Core
The core python API exposes low-level solving logic implemented in rta::core.
Use this API when you need direct control over the solver inputs and outputs, for example:
Running metadata-only IDT/CAT calculations from extracted DNG metadata.
Building a fully spectral pipeline from camera sensitivities, illuminants, observer curves, and training data.
Integrating rawtoaces matrix/white-balance solving into your own tools.
Data model summary
The core bindings expose these data containers and solvers:
rawtoaces.Metadata: container for DNG-style calibration/neutral metadata.rawtoaces.MetadataSolver: solves CAT/IDT usingrawtoaces.Metadata.rawtoaces.Spectrum: one regularly sampled spectral curve.rawtoaces.SpectralData: spectral JSON container/loader.rawtoaces.SpectralSolver: solves WB/IDT using spectral datasets.
Both concrete solvers expose the inherited calculate_transform,
transform_matrix, last_error_message, and verbosity members
directly. The reference lists these members under each solver.
Metadata workflow
Use rawtoaces.MetadataSolver when you already have DNG metadata
values and do not need spectral database lookup.
Minimal example:
import rawtoaces
md = rawtoaces.Metadata()
md.baseline_exposure = 2.4
md.neutral_RGB = [0.6290, 1.0, 0.7904]
c0 = rawtoaces.Metadata.Calibration()
c0.illuminant = 17
c0.XYZ_to_RGB_matrix = [
1.31197, -0.49679, 0.01156,
-0.41723, 1.44237, 0.04528,
0.06723, 0.21710, 0.72651,
]
c1 = rawtoaces.Metadata.Calibration()
c1.illuminant = 21
c1.XYZ_to_RGB_matrix = [
1.00885, -0.27351, -0.08258,
-0.48997, 1.34441, 0.11174,
-0.06406, 0.32997, 0.53917,
]
md.calibration = [c0, c1]
solver = rawtoaces.MetadataSolver(md)
if not solver.calculate_transform():
raise RuntimeError(solver.last_error_message)
idt = solver.transform_matrix # 3x3 list[list[float]]
The transform includes chromatic adaptation; no separate CAT call is needed.
Spectral workflow
Use rawtoaces.SpectralSolver for full spectral solving from camera
and illuminant spectral data.
Typical sequence:
Construct solver with spectral database paths.
Load/find camera data.
Load/find illuminant.
Load observer and training data.
Calculate WB and IDT.
Minimal example using database lookup + file loading:
import rawtoaces
solver = rawtoaces.SpectralSolver([
"/path/to/rawtoaces-data/data"
])
# camera and illuminant
ok = solver.find_camera("nikon", "d200")
if not ok:
raise RuntimeError(solver.last_error_message or "camera not found")
ok = solver.find_illuminant("d55")
if not ok:
raise RuntimeError(solver.last_error_message or "illuminant not found")
# required for IDT solve
if not solver.load_spectral_data("cmf/cmf_1931.json", solver.observer):
raise RuntimeError(solver.last_error_message or "failed to load observer")
if not solver.load_spectral_data(
"training/training_spectral.json", solver.training_data
):
raise RuntimeError(solver.last_error_message or "failed to load training data")
if not solver.calculate_WB():
raise RuntimeError(solver.last_error_message)
if not solver.calculate_transform():
raise RuntimeError(solver.last_error_message)
wb = solver.get_WB_multipliers() # [R, G, B]
idt = solver.transform_matrix # 3x3
Finding a standard illuminant best matching the given white-balancing multipliers:
# Requires camera to be initialized first
if not solver.find_illuminant([1.8, 1.0, 1.4]):
raise RuntimeError(solver.last_error_message)
Spectrum
rawtoaces.Spectrum stores one regularly sampled spectral curve and
corresponds to rta::core::Spectrum. Its nested
Shape describes that sampling in nanometers.
Spectrum.ReferenceShape is the sampling rawtoaces uses internally: 380 nm
through 780 nm in 5 nm steps. Spectrum.EmptyShape allocates no samples.
A shape with a positive step must use finite wavelengths and last >= first;
otherwise construction raises ValueError. Arithmetic is per sample and
requires both curves to share a shape and sample count; a mismatch raises
ValueError. reshape() interpolates onto ReferenceShape. Reading
values returns a new list, and assigning shape leaves the current
samples in place.
import rawtoaces
curve = rawtoaces.Spectrum(0.0, rawtoaces.Spectrum.Shape(380, 400, 10))
curve.values = [10.0, 20.0, 30.0]
curve.reshape()
Spectral Data
The rawtoaces.SpectralData class is a minimal spectral data container exposed
for rawtoaces.SpectralSolver workflows.
Corresponds to rta::core::SpectralData.
Channels in a loaded container are rawtoaces.Spectrum copies.
data["channel"] and data.get(set_name, channel_name) read them, and
data["channel"] = curve replaces a channel that already exists in the
main set. "channel" in data tests for that name. The container is not
iterable.
File format and schema references:
Format description: rawtoaces-data README (JSON Schema for Spectral Datasets)
Current schema: schema_1.0.0.json
Legacy schema (still found in many existing datasets): schema_0.1.0.json
Error handling notes
Most solver methods return
True/Falsefor operational success.On failure,
last_error_messageis populated for state-validation failures (for example, missing camera/illuminant before solving).Input-shape validation at the python binding layer raises
ValueErrorimmediately for invalid arguments (empty required strings, wrong WB vector length, invalid metadata calibration array size).
Data requirements for calculate_transform
Before calling rawtoaces.SpectralSolver.calculate_transform(), ensure:
camerahas 3 channels (R, G, B)illuminanthas 1 channel (power)observerhas 3 channels (X, Y, Z)training_datais non-emptyWhite balance has been calculated with
calculate_WB()or the three-multiplier form offind_illuminant(). The name form only loads illuminant data; the transform solve uses the currently stored multipliers.
Missing camera, illuminant, observer, or training data makes the method return
False, with last_error_message describing the missing prerequisite.
Skipping white balance leaves the current multipliers in use (initially
[1.0, 1.0, 1.0]); this condition does not itself produce an error.
Migration from deprecated methods
The methods below are deprecated since 2.2.0 and scheduled for removal in v3. Use the current APIs in new code.
Deprecated method |
Replacement |
|---|---|
|
|
|
Check |
|
Check |
|
Read |
|
Use |