mirror of
https://github.com/storytold/filmcraft.git
synced 2026-10-24 10:10:05 -06:00
aiongg
0a881266c8
* Tests: one integration-test binary per crate Each crate with several tests/*.rs files keeps them as modules of tests/it/, so cargo links one test executable per crate instead of one per file. Files that change process-wide state or time a workload stay binaries of their own. * Profiles: line tables for workspace crates, no debug info for dependencies * Windows ARM64: nightly and on release pushes instead of every push to main * xtask ci: clippy and tests in the dev profile The release profile's thin LTO and single codegen unit made linking the test binaries take most of the gate. The codec and audio crates stay at opt-level 3 in the dev profile, so their tests run at release speed. * xtask ci: nextest, doctests, no examples, one wasm check Tests run with cargo nextest when it is installed (cargo test otherwise) and build with --lib --bins --tests, so examples aren't linked; doctests run separately. The wasm check keeps going past the first failing crate. VP8 fixture generation locks across processes, since nextest runs each test in its own. * VP9 synthetic fixtures: write aside and rename A test in another process could read a fixture ffmpeg was still writing. * Fuzz tests: a third of each sweep by default, all of it with FILMCRAFT_FUZZ_ITERS Every seed, mutation kind and thread count still runs. Header bytes each get one overwrite value and two bit flips in rotation, so every value and bit index still occurs across the region. FILMCRAFT_FUZZ_ITERS=N runs the whole sweep plus N random rounds per seed, as before. * Platform fallback tests: one failure point per hybrid path The failure-anywhere test injected a failure at four points around every restart point; the hybrid's paths differ only in the first GOP, around the second and last restart points, at the end and never. The replay test needs the first two GOPs. * Export tests: shorter ranges with the same checks The bitrate test measures 0.5–1.5 s, where each preset reaches its own target (on 0–3 s the simple demo left two presets at the same rate). The every-preset test exports three frames per preset. * Audio tests: effects in parallel, a table-driven FFT for the Opus quality metric The extreme-settings test keeps both settings and the 40 s tail for every effect, one thread each. The Opus quality metric's FFT builds its twiddles once and allocates nothing per transform (same algorithm and summation order). * CI: dev-profile gate with nextest xtask ci no longer builds with --release, so the release-profile overrides go; nextest is installed for the test step. * CI: apt packages through the cached install-apt-packages action * Review fixes: fuzz tests with a panic hook in their own binaries, loud fixture lock The fuzz tests of av1, h264, hevc, mpeg2v, vp8 and vp9 count panics through a process-wide hook, so a panic in another test of the same process would fail them; they are binaries of their own again. The VP8 fixture lock fails the test instead of skipping it silently, and the full-sweep doc comments say how many truncation points the full run samples. * Fuzz tests: rotate the default subset per run (FILMCRAFT_FUZZ_SEED replays one) * platform tests: decode-switch tests in their own binaries, one NVENC lock
89 lines
6.1 KiB
Markdown
89 lines
6.1 KiB
Markdown
# filmcraft-dng
|
||
|
||
Clean-room DNG and CinemaDNG camera RAW decoder in pure Rust. Layer L0: depends only on
|
||
`thiserror` and (optional, feature `threads`, default on) `rayon`. Builds for
|
||
`wasm32-unknown-unknown`; no `unsafe`. Implemented from the public specifications below only; the
|
||
source of no other raw decoder (dcraw, LibRaw, rawspeed, darktable, RawTherapee, FFmpeg, the Adobe
|
||
DNG SDK…) was read. LibRaw's `unprocessed_raw` sample program is run as an external test oracle
|
||
when it is installed, never linked.
|
||
|
||
## Specifications
|
||
|
||
| Document | Edition | Used for |
|
||
|---|---|---|
|
||
| Adobe Digital Negative (DNG) Specification | 1.4.0.0 (2012) – 1.7.1.0 (2023) | raw IFD selection (NewSubFileType 0), CFA / LinearRaw data, BitsPerSample packing, LinearizationTable, BlackLevel (+ RepeatDim, DeltaH / DeltaV), WhiteLevel, ActiveArea, DefaultCrop, the colour model of chapter 6 (ColorMatrix, CameraCalibration, AnalogBalance, ForwardMatrix, AsShotNeutral / AsShotWhiteXY, CalibrationIlluminant interpolation, BaselineExposure) |
|
||
| TIFF Revision 6.0 | June 1992 | header, IFDs, field types, strips and tiles, PlanarConfiguration, row padding |
|
||
| TIFF/EP, ISO 12234-2 | 2001 | CFARepeatPatternDim, CFAPattern |
|
||
| TIFF Technical Note 1 (SubIFDs) | 1993 | the SubIFD tree |
|
||
| ITU-T T.81 \| ISO/IEC 10918-1 | 09/1992 | lossless JPEG (process 14, SOF3): Annex B syntax, Annex C Huffman tables, F.2.2.3 decoding, Annex H prediction and point transform |
|
||
| CinemaDNG Image Data Format Specification | 1.1.0.0 (2009) | frames as numbered DNG files, FrameRate, TimeCodes, ReelName tags |
|
||
| SMPTE ST 12-1 | 2014 | time code BCD packing (via the CinemaDNG TimeCodes tag) |
|
||
| CIPA DC-008 (Exif) | 2.3 | LightSource codes → illuminant temperatures |
|
||
| Malvar, He, Cutler, "High-quality linear interpolation for demosaicing of Bayer-patterned color images", IEEE ICASSP | 2004 | the Bayer demosaic filters |
|
||
| McCamy, "Correlated color temperature as an explicit function of chromaticity coordinates", Color Res. Appl. 17(2) | 1992 | white xy → temperature for the calibration interpolation |
|
||
| IEC 61966-2-1 (sRGB) | 1999 | Rec. 709 / sRGB primaries and D65 white |
|
||
|
||
## API
|
||
|
||
```rust
|
||
if filmcraft_dng::sniff(&bytes) {
|
||
let dng = filmcraft_dng::Dng::parse(&bytes)?;
|
||
let info = dng.info()?; // size after crop, bits, CFA or LinearRaw, frame rate, time code, camera, reel
|
||
let raw = dng.raw()?; // the stored samples (u16), bit-exact
|
||
let img = dng.develop()?; // linear Rec. 709 RGBA f32 (alpha 1), info.width × info.height
|
||
}
|
||
let img = filmcraft_dng::decode(&bytes)?; // parse + develop
|
||
```
|
||
|
||
`writer` (feature `writer`, tests only) writes synthetic DNGs: uncompressed at any depth or
|
||
lossless JPEG with any predictor, strips or tiles, either byte order, an optional preview IFD with
|
||
the raw image in a SubIFD, and arbitrary extra tags.
|
||
|
||
## What it decodes
|
||
|
||
- **Container:** little and big-endian TIFF, IFD chains and SubIFDs (at most 64 IFDs, 4 levels,
|
||
cycles end the walk). The main image is the largest NewSubFileType 0 IFD with a CFA or LinearRaw
|
||
photometric interpretation.
|
||
- **Raw data:** 1–16-bit unsigned samples, uncompressed (8 and 16-bit in file byte order, other
|
||
depths packed most significant bit first) or lossless JPEG (all predictors 1–7, 1–4 components,
|
||
point transform, restart intervals of whole lines), in strips or tiles; tiles decode in
|
||
parallel.
|
||
- **Processing:** ActiveArea, LinearizationTable, per-site black levels with row / column deltas,
|
||
per-sample white levels, as-shot white balance (clipped highlights stay neutral), demosaic
|
||
(Malvar–He–Cutler for 2 × 2 Bayer patterns of any phase, bilinear for other patterns up to
|
||
8 × 8), DefaultCrop, the DNG colour model to XYZ D50 and Bradford to linear Rec. 709, and
|
||
BaselineExposure. LinearRaw (3 samples) skips the demosaic; monochrome LinearRaw is grey.
|
||
- **Output:** scene-linear Rec. 709 floats: a white the sensor clipped is 1.0 × 2^BaselineExposure;
|
||
brighter values are kept (FilmCraft's compositor works in linear float). Negative results of the
|
||
colour matrix are clipped to 0. Black levels scale per pixel by (white − black).
|
||
- **White balance without a ForwardMatrix** follows the specification: the camera matrix takes the
|
||
values to XYZ and a Bradford adaptation moves the as-shot white to D50. Decoders in the dcraw
|
||
tradition (LibRaw included) scale the camera channels instead, so under a white far from D65
|
||
their saturated colours differ from ours (greys agree).
|
||
- **Speed:** a 4096 × 2160 12-bit frame develops in about 80–100 ms on 16 threads (raw decode
|
||
~15 ms, the rest demosaic and colour).
|
||
|
||
## Not supported (errors name them)
|
||
|
||
Lossy JPEG and JPEG XL DNG, deflate / floating-point DNG (HDR merges), planar raw data, colour
|
||
filters other than red / green / blue (CMY, RGBE), non-rectangular CFA layouts, opcode lists
|
||
(warp, vignette, bad pixels: ignored), DefaultScale and BestQualityScale (non-square pixels are
|
||
shown square), DNG 1.6 IlluminantData for illuminant 255 (calibration 1 is used), lossless JPEG
|
||
restart intervals that split a line, and MXF-wrapped CinemaDNG.
|
||
|
||
## Tests
|
||
|
||
- `tests/it/roundtrip.rs`: container parsing in both byte orders with and without a preview IFD;
|
||
uncompressed samples bit-exact at 8–16 bits, strips and tiles; lossless JPEG bit-exact for every
|
||
predictor and component count, full-swing 16-bit data (every difference category, SSSS = 16),
|
||
restarts and point transform; developed values against hand-computed ones (black / white,
|
||
white balance, ForwardMatrix, BaselineExposure, ActiveArea, DefaultCrop, LinearRaw); CinemaDNG
|
||
FrameRate / TimeCodes / ReelName; hostile files (every truncation, 12 000 mutations under
|
||
`catch_unwind`, cyclic IFDs, huge sizes, bad offsets, zero denominators).
|
||
- `tests/it/oracle_libraw.rs`: LibRaw's `unprocessed_raw` reads the same samples from our synthetic
|
||
files (uncompressed 8–16-bit in both byte orders, lossless JPEG predictors 1–7 with one and two
|
||
components). Skipped when it is not installed.
|
||
- Unit tests: matrix maths, the published sRGB matrix, McCamy temperatures, calibration
|
||
interpolation, sRGB / ForwardMatrix cameras mapping to themselves, demosaic on flat fields
|
||
(every Bayer phase), ramps and edges, black / white / linearisation maths.
|