Merge pull request #2299 from aiongg/next-sync-1118

Sync main into next (18 Nov)
This commit is contained in:
aiongg authored and GitHub committed 2026-11-18 22:14:22 -05:00
commit 9f234ae3ec
287 files changed
+36228 -881

No files matched your search

+1
View File
@@ -50,6 +50,7 @@ workflows:
- 'actions/checkout@v7.0.1'
- 'dtolnay/rust-toolchain@stable'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/full-validation.yml': []
'.github/workflows/house-rules.yml': []
'.github/workflows/jpeg.yml':
- 'actions/checkout@v7.0.1'
+64
View File
@@ -0,0 +1,64 @@
name: Full validation
# Add full-validation to a PR for uncapped validation of its merge ref. Keep the label across pushes.
# Fast Workspace checks are not substitutes for these six completed native/PDF gate checks.
on:
pull_request:
types: [opened, synchronize, reopened, labeled]
workflow_dispatch:
permissions:
contents: read
concurrency:
# An unrelated label event must not cancel an active full run.
group: full-validation-${{ github.event.action == 'labeled' && github.event.label.name != 'full-validation' && github.run_id || github.event.pull_request.number || github.run_id }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
native:
if: >-
github.event_name == 'workflow_dispatch' ||
(contains(github.event.pull_request.labels.*.name, 'full-validation') &&
(github.event.action != 'labeled' || github.event.label.name == 'full-validation'))
name: Full native
uses: storytold/craft-common-actions/.github/workflows/gate.yml@main
with:
os: '["ubuntu-latest","windows-latest","macos-latest"]'
select-os: '[]'
timeout-minutes: 120
tools: ""
packages: mesa-vulkan-drivers libvulkan1
craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83
linux-env: WGPU_BACKEND=vulkan
windows-env: CRAFT_PRINT_REQUIRE_QUEUE=1
env: CRAFT_PRINT_REQUIRE_QUEUE=0
setup-command: bash scripts/ci-test-inputs.sh
command: |
python scripts/test-full-validation.py
bash scripts/ci-full-validation.sh
pdf-contracts:
if: >-
github.event_name == 'workflow_dispatch' ||
(contains(github.event.pull_request.labels.*.name, 'full-validation') &&
(github.event.action != 'labeled' || github.event.label.name == 'full-validation'))
name: Full PDF contracts
uses: storytold/craft-common-actions/.github/workflows/gate.yml@main
with:
os: '["ubuntu-latest","windows-latest","macos-latest"]'
select-os: '[]'
timeout-minutes: 120
tools: ""
craft-fonts-ref: ""
require-craft-fonts: false
env: RUSTFLAGS=--cfg craft_pdf_unicode_fixtures
setup-command: |
python scripts/test-fetch-pdf-test-fonts.py
python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts"
echo "CRAFT_PDF_TEST_FONT_DIR=$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV"
command: |
unset CRAFT_HOSTILE_DIVISOR PROPTEST_CASES
cargo clippy -p craft-pdf --all-targets --all-features --locked -- -D warnings
cargo test -p craft-pdf --all-features --locked
cargo test --manifest-path crates/pdf/read-only-contract/Cargo.toml --locked
+6 -1
View File
@@ -70,7 +70,12 @@ jobs:
python3 scripts/test-workspace-concurrency.py
python3 scripts/test-workspace-tests.py
fi
cargo fmt --check
# One rustfmt call gets every source root of the workspace, which is longer than
# Windows allows for a command line (os error 206). rustfmt's result is the same on
# every system, so the Linux and macOS legs check it.
if [ "$RUNNER_OS" != Windows ]; then
cargo fmt --check
fi
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
# A push to main builds the gate's test binaries in their own leg and saves the cache right
+12
View File
@@ -146,6 +146,10 @@ Sanitization, animation fitting and numeric output policy remain caller-owned.
`crates/jsonc` is extracted from Craft Anything `crates/formats/src/jsonc.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). The original implementation and hardening by BFlat, newline preservation by NetterSilver, and subsequent RRFZ/Afloat correctness fixes retain separate primary-author port commits with immutable source revisions. Shared API wiring and optional input-byte admission are subsequent changes. Compatibility parsing and all existing formatting/editing tests are retained; application file I/O and policy are not imported.
## XFA XML DOM
`crates/xfa/src/xml.rs` is extracted from PDFCraft at `271e479c53723b1b294c866d5cb2f27604601b29`, originally by Dylan M. Taylor (`eead4541`, `7d44e654`), MIT OR Apache-2.0. The initial extraction changes visibility and module boundaries; subsequent namespace-retention budget hardening intentionally tightens resource admission. PDF/layout/form policy remains in the app.
## Java class inspection
`crates/java-class` extracts Craft Anything `java_class.rs` and `java_ops.rs` at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0), preserving separate primary-author source-history ports by Brandon Thomas, BFlat, Afloat and RRFZ. The checked byte-reader, modified UTF-8 unit decoder, descriptor display helper and synthetic class fixtures come from the same source snapshot. Seven regression files retain their source authors. Neutral error wiring and shared crate integration are subsequent changes. No JAR archive, application I/O or bytecode execution is imported.
@@ -161,6 +165,14 @@ Sanitization, animation fitting and numeric output policy remain caller-owned.
`crates/har` preserves Craft Anything `crates/formats/src/har.rs` from `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the typed reader in `f64ae3bf3c8863a982af1304e06de20653803968`; BFlat added UTF-8 BOM compatibility in `cb0bb9d8fa4536ba44ef2c86f5ed759b879cc2d3`. Both source snapshots retain primary author attribution. Shared wiring, explicit byte admission and its tests are subsequent Dylan M. Taylor changes. Redaction and analysis remain app-owned.
## Dalvik DEX inspection
`crates/dex` extracts Craft Anything `crates/formats/src/dex.rs` and `dex_ops.rs` at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Five source-history ports preserve Brandon Thomas, BFlat and Afloat as primary authors. Five regression imports retain BFlat/Afloat authors and exact source revisions. The checked byte-reader/MUTF-8 subset and synthetic DEX fixture come from that app's `bytes.rs` and `testkit/src/android.rs`; deterministic noise/mutations come from its testkit. No application file I/O, APK logic or execution is imported. Shared neutral errors and workspace wiring are subsequent changes; existing per-file strings, member/handler and bytecode payload budgets are retained.
## EVM bytecode inspection
`crates/evm` extracts Craft Anything `crates/formats/src/evm.rs` at `a31e995858f4312e0f1d59a007112da191ef2d26` (MIT OR Apache-2.0). Eight separate source-history ports preserve Brandon Thomas, Afloat, RRFZ and NetterSilver as primary authors with immutable source references. Synthetic EVM fixtures and deterministic mutation helpers come from the same app source; regression files retain their source provenance. Neutral errors and workspace integration are subsequent changes. No code execution or transaction behavior is imported.
## XFDF field reader
`crates/xfdf` extracts PDFCraft field reading from #5937 refresh `cb564fd827f572818e9ddb0ea5989a432b1f39fd` (MIT OR Apache-2.0). App-side annotation and form policy remains local; source history is retained in the original repository.
Generated
+222 -3
View File
@@ -290,6 +290,17 @@ version = "1.0.104"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
[[package]]
name = "apple-native-keyring-store"
version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2b350bfd03649e07aa05c0a81b3e15934374e585c98204a57e20b9d49f49bb9a"
dependencies = [
"keyring-core",
"log",
"security-framework",
]
[[package]]
name = "arbitrary"
version = "1.5.0"
@@ -1747,6 +1758,7 @@ dependencies = [
"craft-cms",
"craft-codepage",
"craft-color",
"craft-color-transform",
"craft-color-ui",
"craft-control",
"craft-control-protocol",
@@ -1757,6 +1769,9 @@ dependencies = [
"craft-dds",
"craft-deckcraft-format",
"craft-designcraft-format",
"craft-develop",
"craft-develop-model",
"craft-dex",
"craft-dialogs",
"craft-doc",
"craft-doc-binary",
@@ -1772,6 +1787,8 @@ dependencies = [
"craft-elf",
"craft-eps",
"craft-epub",
"craft-esign",
"craft-evm",
"craft-ews",
"craft-exr",
"craft-fcproj-format",
@@ -1790,6 +1807,7 @@ dependencies = [
"craft-frame",
"craft-gainmap",
"craft-gcode",
"craft-geom",
"craft-gif",
"craft-gridcraft-format",
"craft-gzip",
@@ -1882,6 +1900,7 @@ dependencies = [
"craft-stencilcraft-document",
"craft-stencilcraft-format",
"craft-stream-codecs",
"craft-suite-account",
"craft-svg",
"craft-table",
"craft-tar",
@@ -1909,6 +1928,7 @@ dependencies = [
"craft-window",
"craft-wordmodel",
"craft-xcf",
"craft-xfa",
"craft-xfdf",
"craft-xfl",
"craft-xls",
@@ -1966,7 +1986,7 @@ dependencies = [
[[package]]
name = "craft-ai-agents"
version = "0.1.0"
source = "git+https://github.com/storytold/craft-ai-integrations?rev=35e0352666a117407d62230a6c6c2366f3e21a3b#35e0352666a117407d62230a6c6c2366f3e21a3b"
source = "git+https://github.com/storytold/craft-ai-integrations?rev=d94a3593adcff504eaaad9e5aee4c84fd2f07a72#d94a3593adcff504eaaad9e5aee4c84fd2f07a72"
dependencies = [
"dirs",
"serde",
@@ -2128,6 +2148,7 @@ name = "craft-cloud-ui"
version = "0.1.0"
dependencies = [
"craft-cloud",
"craft-esign",
"egui",
"egui_kittest",
"image",
@@ -2158,6 +2179,16 @@ dependencies = [
"serde",
]
[[package]]
name = "craft-color-transform"
version = "0.1.0"
dependencies = [
"craft-cms",
"craft-color",
"serde",
"serde_json",
]
[[package]]
name = "craft-color-ui"
version = "0.1.0"
@@ -2182,10 +2213,15 @@ dependencies = [
name = "craft-control"
version = "0.1.0"
dependencies = [
"craft-ai-agents",
"craft-atomic",
"craft-flags",
"getrandom 0.3.4",
"log",
"proptest",
"serde",
"serde_json",
"tempfile",
]
[[package]]
@@ -2273,6 +2309,36 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-develop"
version = "0.1.0"
dependencies = [
"craft-develop-model",
"proptest",
"serde",
]
[[package]]
name = "craft-develop-model"
version = "0.1.0"
dependencies = [
"craft-geom",
"craft-metadata",
"miniz_oxide 0.9.1",
"proptest",
"serde",
"serde_json",
]
[[package]]
name = "craft-dex"
version = "0.1.0"
dependencies = [
"craft-testkit",
"serde",
"thiserror 2.0.21",
]
[[package]]
name = "craft-dialogs"
version = "0.1.0"
@@ -2321,6 +2387,7 @@ dependencies = [
"craft-wordmodel",
"image",
"log",
"md4",
"miniz_oxide 0.9.1",
"proptest",
"serde_json",
@@ -2462,6 +2529,26 @@ dependencies = [
"zip 9.1.3",
]
[[package]]
name = "craft-esign"
version = "0.1.0"
dependencies = [
"craft-cloud",
"serde",
"serde_json",
"thiserror 2.0.21",
]
[[package]]
name = "craft-evm"
version = "0.1.0"
dependencies = [
"craft-testkit",
"serde",
"serde_json",
"thiserror 2.0.21",
]
[[package]]
name = "craft-ews"
version = "0.1.0"
@@ -2695,6 +2782,14 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-geom"
version = "0.1.0"
dependencies = [
"proptest",
"serde",
]
[[package]]
name = "craft-gif"
version = "0.1.0"
@@ -2825,6 +2920,7 @@ dependencies = [
"craft-dds",
"craft-heif",
"craft-jpeg",
"craft-jxl",
"craft-media-testkit",
"craft-metadata",
"craft-tiff",
@@ -2896,6 +2992,7 @@ dependencies = [
name = "craft-java-class"
version = "0.1.0"
dependencies = [
"craft-testkit",
"serde",
"thiserror 2.0.21",
]
@@ -2938,6 +3035,7 @@ dependencies = [
name = "craft-jxl"
version = "0.1.0"
dependencies = [
"brotli-decompressor 5.0.3",
"craft-cms",
"jixel",
"jxl-oxide",
@@ -3834,6 +3932,21 @@ dependencies = [
"weezl 0.2.1",
]
[[package]]
name = "craft-suite-account"
version = "0.1.0"
dependencies = [
"dirs",
"keyring",
"keyring-core",
"log",
"serde",
"serde_json",
"sha2 0.10.9",
"tempfile",
"zeroize",
]
[[package]]
name = "craft-svg"
version = "0.1.0"
@@ -3842,11 +3955,14 @@ dependencies = [
"craft-xml",
"data-url",
"flate2",
"gif",
"image-webp",
"kurbo",
"quick-xml 0.41.0",
"resvg 0.48.1",
"roxmltree 0.21.2",
"thiserror 2.0.21",
"toml",
"usvg 0.48.1",
"vectorcraft-geom",
"vectorcraft-pathops",
@@ -3876,6 +3992,7 @@ dependencies = [
name = "craft-tar"
version = "0.1.0"
dependencies = [
"craft-testkit",
"serde",
]
@@ -4319,6 +4436,7 @@ dependencies = [
name = "craft-wasm"
version = "0.1.0"
dependencies = [
"craft-testkit",
"serde",
"thiserror 2.0.21",
"wasmparser 0.261.0",
@@ -4413,6 +4531,13 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-xfa"
version = "0.1.0"
dependencies = [
"craft-xml",
]
[[package]]
name = "craft-xfdf"
version = "0.1.0"
@@ -5385,7 +5510,7 @@ dependencies = [
"ff 0.13.1",
"generic-array",
"group 0.13.0",
"hkdf",
"hkdf 0.12.4",
"pem-rfc7468 0.7.0",
"pkcs8 0.10.2",
"rand_core 0.6.4",
@@ -6042,6 +6167,17 @@ dependencies = [
"pin-project-lite",
]
[[package]]
name = "futures-macro"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "futures-sink"
version = "0.3.34"
@@ -6062,6 +6198,7 @@ checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
dependencies = [
"futures-core",
"futures-io",
"futures-macro",
"futures-sink",
"futures-task",
"memchr",
@@ -6709,6 +6846,15 @@ dependencies = [
"hmac 0.12.1",
]
[[package]]
name = "hkdf"
version = "0.13.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4aaa26c720c68b866f2c96ef5c1264b3e6f473fe5d4ce61cd44bbe913e553018"
dependencies = [
"hmac 0.13.0",
]
[[package]]
name = "hmac"
version = "0.12.1"
@@ -7744,6 +7890,27 @@ dependencies = [
"serde",
]
[[package]]
name = "keyring"
version = "4.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2270074a3d26bcac93c1dc5d2845eb4c089e8d761ccf6e0ea266a16004640627"
dependencies = [
"apple-native-keyring-store",
"keyring-core",
"windows-native-keyring-store",
"zbus-secret-service-keyring-store",
]
[[package]]
name = "keyring-core"
version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29fbf4b551298c67925f38cf341a1ada797a75f1837bdf8ae1fc8e2ebc6efb59"
dependencies = [
"log",
]
[[package]]
name = "khronos-egl"
version = "6.0.0"
@@ -8094,6 +8261,15 @@ dependencies = [
"digest 0.11.3",
]
[[package]]
name = "md4"
version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bd76fb0fd6b2e4be62a73f8e0858ca97f81babcb1af322dcaca196f735f17f80"
dependencies = [
"digest 0.11.3",
]
[[package]]
name = "memchr"
version = "2.8.3"
@@ -9447,7 +9623,7 @@ dependencies = [
"generic-array",
"getrandom 0.2.17",
"hex",
"hkdf",
"hkdf 0.12.4",
"idea",
"k256",
"log",
@@ -11033,6 +11209,25 @@ dependencies = [
"zeroize",
]
[[package]]
name = "secret-service"
version = "5.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5107b24b91445dd2aa449a258a1807b63240942157292354dc5bfdbeb8bc6db8"
dependencies = [
"aes 0.9.4",
"cbc",
"futures-util",
"getrandom 0.4.3",
"hkdf 0.13.0",
"hybrid-array",
"num",
"once_cell",
"serde",
"sha2 0.11.1",
"zbus",
]
[[package]]
name = "security-framework"
version = "3.7.0"
@@ -13875,6 +14070,19 @@ version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
[[package]]
name = "windows-native-keyring-store"
version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "063426e76fdec7438d56bb777f67e318a84a25c707b07e575cb8b78e10c028f8"
dependencies = [
"byteorder",
"keyring-core",
"regex",
"windows-sys 0.61.2",
"zeroize",
]
[[package]]
name = "windows-numerics"
version = "0.3.1"
@@ -14502,6 +14710,17 @@ dependencies = [
"zvariant",
]
[[package]]
name = "zbus-secret-service-keyring-store"
version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "74801d001b9e7729adb4f1825b67b398185fed424749aa3d8bacf70417137d9a"
dependencies = [
"keyring-core",
"secret-service",
"zbus",
]
[[package]]
name = "zbus_macros"
version = "5.19.0"
+12 -3
View File
@@ -11,6 +11,8 @@ rust-version = "1.95"
repository = "https://github.com/storytold/craft-libs"
[workspace.dependencies]
craft-xfa = { path = "crates/xfa" }
craft-evm = { path = "crates/evm" }
craft-java-class = { path = "crates/java-class" }
craft-sourcemap = { path = "crates/sourcemap" }
craft-pcap = { path = "crates/pcap" }
@@ -60,6 +62,9 @@ craft-gridcraft-format = { path = "crates/gridcraft-format" }
craft-aaf = { path = "crates/aaf" }
craft-behavior = { path = "crates/behavior" }
craft-atomic = { path = "crates/atomic" }
# The ArtCraft Launcher's app list for AI agents (storytold/craft-ai-integrations, crates/app/ai-agents).
craft-ai-agents = { git = "https://github.com/storytold/craft-ai-integrations", rev = "d94a3593adcff504eaaad9e5aee4c84fd2f07a72" }
craft-dex = { path = "crates/dex" }
craft-xtask = { path = "crates/xtask" }
craft-captions = { path = "crates/captions" }
craft-cfb = { path = "crates/cfb" }
@@ -70,6 +75,7 @@ craft-cloud-local = { path = "crates/cloud-local" }
craft-cloud-ui = { path = "crates/cloud-ui" }
craft-color = { path = "crates/color" }
craft-color-ui = { path = "crates/color-ui" }
craft-color-transform = { path = "crates/color-transform" }
craft-frame = { path = "crates/frame" }
craft-crs = { path = "crates/crs" }
craft-crw = { path = "crates/crw" }
@@ -96,8 +102,6 @@ vectorcraft-doc = { git = "https://github.com/storytold/vectorcraft.git", rev =
vectorcraft-eps = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
vectorcraft-geom = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
vectorcraft-pathops = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
# The ArtCraft Launcher's list of apps AI agents may use, shared with the launcher and the MCP gateway.
craft-ai-agents = { git = "https://github.com/storytold/craft-ai-integrations", rev = "35e0352666a117407d62230a6c6c2366f3e21a3b" }
craft-doc = { path = "crates/doc" }
craft-docpath = { path = "crates/docpath" }
craft-dpx = { path = "crates/dpx" }
@@ -105,6 +109,7 @@ craft-draw = { path = "crates/draw" }
craft-dwg = { path = "crates/dwg" }
craft-fcproj-format = { path = "crates/fcproj-format" }
craft-ecproj-format = { path = "crates/ecproj-format" }
craft-esign = { path = "crates/esign" }
craft-figma-rest = { path = "crates/figma-rest" }
craft-exr = { path = "crates/exr" }
craft-flags = { path = "crates/flags" }
@@ -137,7 +142,7 @@ craft-control = { path = "crates/control" }
craft-control-protocol = { path = "crates/control-protocol" }
craft-jsonrpc = { path = "crates/jsonrpc" }
craft-mcp = { path = "crates/mcp" }
craft-jxl = { path = "crates/jxl" }
craft-jxl = { path = "crates/jxl", default-features = false }
craft-kiwi = { path = "crates/kiwi" }
craft-keymap = { path = "crates/keymap" }
craft-assuan = { path = "crates/assuan" }
@@ -185,6 +190,9 @@ craft-pst = { path = "crates/pst" }
craft-quit = { path = "crates/quit" }
craft-rtf = { path = "crates/rtf" }
craft-raw = { path = "crates/raw" }
craft-geom = { path = "crates/geom" }
craft-develop = { path = "crates/develop" }
craft-develop-model = { path = "crates/develop-model" }
craft-sheet = { path = "crates/sheet" }
craft-sketch = { path = "crates/sketch" }
craft-review = { path = "crates/review" }
@@ -193,6 +201,7 @@ craft-figcraft-format = { path = "crates/figcraft-format" }
craft-scraft-format = { path = "crates/scraft-format" }
craft-time = { path = "crates/time" }
craft-silhouette-studio = { path = "crates/silhouette-studio" }
craft-suite-account = { path = "crates/suite-account" }
craft-svg = { path = "crates/svg" }
craft-stencilcraft-format = { path = "crates/stencilcraft-format" }
craft-stencilcraft-document = { path = "crates/stencilcraft-document" }
+6 -2
View File
@@ -12,9 +12,11 @@ workspace = true
[dependencies]
egui = { workspace = true }
# The vendor-neutral vocabulary the share dialog speaks. No IO and no
# vendor, so this stays buildable for the web.
# The vendor-neutral vocabulary the share and e-sign dialogs speak. No IO and
# no vendor, so this stays buildable for the web.
craft-cloud = { workspace = true, optional = true }
# The e-sign contract the request-signatures dialog states its work through.
craft-esign = { workspace = true, optional = true }
# The control channel's report of the cloud state. One serialiser here
# rather than one per application. No IO and no vendor.
serde_json = { workspace = true, optional = true }
@@ -26,6 +28,8 @@ share = ["dep:craft-cloud"]
# Open and Save against cloud storage. Needs the share dialog, which a
# document's overflow menu and the Share split button both open.
cloud = ["share", "dep:serde_json"]
# Request-signatures dialog.
esign = ["dep:craft-cloud", "dep:craft-esign"]
[dev-dependencies]
image = { version = "0.25", default-features = false, features = ["png"] }
+92
View File
@@ -0,0 +1,92 @@
//! Where the e-sign dialog's work happens, which is never on the frame.
//!
//! Same shape as [`crate::share::ShareBackend`]: the dialog states what it
//! wants, something behind this trait does the waiting, and answers arrive on
//! a channel keyed by sequence number.
use craft_cloud::Contact;
use craft_esign::{CompletedDocument, Envelope, EnvelopeDraft, EsignCapability};
/// One thing the dialog needs done.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Request {
/// What the signing service can actually do, and who is legally responsible.
Capabilities,
/// People matching what has been typed so far (cloud contacts).
Lookup { query: String, limit: usize },
/// Create a draft from a document snapshot, then optionally send it.
Create { draft: Box<EnvelopeDraft>, document: Vec<u8>, idempotency_key: String, send: bool },
/// Current status of one envelope.
Status { envelope: String },
/// Finished document bytes.
Completed { envelope: String },
/// Cancel an in-flight envelope.
Void { envelope: String, reason: String },
/// Nudge one recipient.
Remind { envelope: String, recipient: String },
}
/// What came back.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Answer {
Capabilities {
capabilities: Vec<EsignCapability>,
responsible_party: String,
/// Whether a cloud account is attached so invitations can leave.
linked: bool,
},
Lookup(Vec<Contact>),
Created(Envelope),
Status(Envelope),
Completed(CompletedDocument),
Voided {
envelope: String,
},
Reminded {
envelope: String,
recipient: String,
},
}
/// Where one answer goes.
pub struct Replier {
seq: u64,
tx: std::sync::mpsc::Sender<(u64, Result<Answer, String>)>,
}
impl Replier {
pub(crate) fn new(seq: u64, tx: std::sync::mpsc::Sender<(u64, Result<Answer, String>)>) -> Replier {
Replier { seq, tx }
}
pub fn seq(&self) -> u64 {
self.seq
}
pub fn dup(&self) -> Replier {
Replier { seq: self.seq, tx: self.tx.clone() }
}
pub fn answer(self, answer: Answer) {
self.deliver(Ok(answer));
}
pub fn refuse(self, reason: impl Into<String>) {
self.deliver(Err(reason.into()));
}
fn deliver(self, result: Result<Answer, String>) {
let _ = self.tx.send((self.seq, result));
}
}
impl std::fmt::Debug for Replier {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Replier").field("seq", &self.seq).finish()
}
}
/// Somewhere a [`Request`] can run without blocking a frame.
pub trait EsignBackend {
fn submit(&self, request: Request, reply: Replier);
}
@@ -0,0 +1,216 @@
//! Regression tests for the CodeRabbit findings reviewed on PR #661,
//! reproduced against ef496161 (storytold/craft-libs#661).
//!
//! Reuses `review_repro`'s `Hold` backend and helpers: a test chooses when,
//! and in what order, a held request is answered.
use craft_esign::{Envelope, EnvelopeStatus};
use super::review_repro::{Hold, envelope_for, ready, send, who};
use super::*;
/// Only one capabilities probe is ever outstanding for the current backend.
/// `set_backend` clears `caps_seq`, but a reply already in flight from the
/// backend being replaced keeps its old sequence number: it must not
/// overwrite capabilities, responsible or linked for the new backend when
/// it finally arrives.
#[test]
fn a_capabilities_reply_from_a_replaced_backend_does_not_overwrite_the_new_ones() {
let hold_a = Hold::default();
let mut dialog = EsignDialog::default();
dialog.set_backend(hold_a.clone());
dialog.pump(0.0);
let (_, caps_a) = hold_a.take(|r| matches!(r, Request::Capabilities));
// The backend is replaced before A's capabilities probe answers.
let hold_b = Hold::default();
dialog.set_backend(hold_b.clone());
dialog.pump(0.1);
let (_, caps_b) = hold_b.take(|r| matches!(r, Request::Capabilities));
caps_b.answer(Answer::Capabilities { capabilities: vec![EsignCapability::Envelopes], responsible_party: "B".into(), linked: true });
dialog.pump(0.2);
assert_eq!(dialog.responsible.as_deref(), Some("B"));
// A's reply, from the replaced backend, arrives after B's already installed.
caps_a.answer(Answer::Capabilities { capabilities: vec![EsignCapability::Void], responsible_party: "A".into(), linked: false });
dialog.pump(0.3);
assert_eq!(dialog.responsible.as_deref(), Some("B"), "a stale Capabilities reply from a replaced backend overwrote the new backend's");
assert!(dialog.linked, "a stale Capabilities reply from a replaced backend turned linked back off");
}
/// A document's revision changing is itself a context change: a reply for
/// the bytes under the old `document_etag` must not install under the new
/// one, even though the document id never changed.
#[test]
fn stale_create_reply_for_old_revision_is_dropped_after_reopen_with_new_etag() {
let (mut dialog, hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), Some("etag-1".into()), who("alice"));
send(&mut dialog, b"A bytes etag1");
dialog.open("doc-A".into(), "A.pdf".into(), Some("etag-2".into()), who("alice"));
let (_, create) = hold.take(|r| matches!(r, Request::Create { .. }));
create.answer(Answer::Created(envelope_for("doc-A", "alice")));
dialog.pump(1.0);
assert!(
dialog.envelope.is_none(),
"stale reply for etag-1 installed into the etag-2 opening: {:?}",
dialog.envelope.as_ref().map(|e| e.id.clone())
);
}
/// `take_send_request` already handed the application doc-A's draft; the
/// dialog then reopens for doc-B before the application calls
/// `submit_request`. The reply this produces must still be tagged with
/// doc-A's context, not doc-B's.
#[test]
fn create_reply_for_a_request_taken_before_reopening_does_not_install_in_the_new_document() {
let (mut dialog, hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
dialog.add_email("bob@example.com".into());
dialog.queue_send();
let out = dialog.take_send_request().expect("send produced a request");
// The dialog moves on before the application gets around to submitting
// what it already took.
dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice"));
dialog.submit_request(Request::Create {
draft: Box::new(out.draft),
document: b"A bytes".to_vec(),
idempotency_key: out.idempotency_key,
send: true,
});
let (_, create) = hold.take(|r| matches!(r, Request::Create { .. }));
create.answer(Answer::Created(envelope_for("doc-A", "alice")));
dialog.pump(1.0);
assert!(
dialog.envelope.is_none(),
"doc-A's envelope, submitted after reopening doc-B, installed into doc-B's dialog: {:?}",
dialog.envelope.as_ref().map(|e| e.id.clone())
);
}
/// An untaken `SendRequest` is specific to the context that queued it; it
/// must not survive into a reopened dialog for another document.
#[test]
fn an_untaken_send_request_does_not_survive_reopening_for_another_document() {
let (mut dialog, _hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
dialog.add_email("bob@example.com".into());
dialog.queue_send();
dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice"));
assert!(dialog.take_send_request().is_none(), "doc-B's dialog still held doc-A's untaken send request");
}
/// `note_create_result` is the synchronous twin of `submit_request`: an app
/// that handles create itself, rather than through the backend channel,
/// reports the outcome here. It must drop a result for a context the dialog
/// has already left, exactly as a channel reply would.
#[test]
fn note_create_result_for_a_previous_document_does_not_install_in_the_reopened_dialog() {
let (mut dialog, _hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
dialog.add_email("bob@example.com".into());
dialog.queue_send();
let _out = dialog.take_send_request().expect("send produced a request");
dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice"));
dialog.note_create_result(Ok(envelope_for("doc-A", "alice")));
assert!(
dialog.envelope.is_none(),
"doc-A's result, reported after reopening doc-B, installed into doc-B's dialog: {:?}",
dialog.envelope.as_ref().map(|e| e.id.clone())
);
}
/// `Replier::dup` is the only way a backend can answer one sequence twice.
/// The dialog answers the first reply normally, but a second reply for the
/// same (already resolved) sequence must drop unconditionally, not reach
/// the match arms with no context left to check against.
#[test]
fn a_duplicated_answer_for_an_already_resolved_sequence_is_dropped() {
let (mut dialog, hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
send(&mut dialog, b"A bytes");
let (_, create) = hold.take(|r| matches!(r, Request::Create { .. }));
let dup = create.dup();
create.answer(Answer::Created(envelope_for("doc-A", "alice")));
dialog.pump(1.0);
assert_eq!(dialog.envelope.as_ref().map(|e| e.id.clone()), Some("env-doc-A".to_owned()), "the first answer should have installed normally");
// The dialog moves on; a backend still holding `dup` from the first
// request answers it again.
dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice"));
dup.answer(Answer::Created(envelope_for("doc-A", "alice")));
dialog.pump(2.0);
let shown = dialog.envelope.as_ref().and_then(|e| e.document_id.clone());
assert!(
shown.is_none() || shown.as_deref() == Some("doc-B"),
"a duplicate answer for the first request reinstalled doc-A's envelope into doc-B's dialog: {shown:?}"
);
}
/// `busy` belongs to whichever operation is still pending. A lookup that
/// fails while a create is genuinely in flight must not report the create
/// as finished.
#[test]
fn a_failed_lookup_does_not_clear_busy_for_a_pending_create() {
let (mut dialog, hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
send(&mut dialog, b"A bytes");
assert!(dialog.busy, "queue_send should have left the dialog busy");
dialog.query = "ca".into();
dialog.query_changed_at = 0.0;
dialog.maybe_lookup(1.0);
let (_, lookup) = hold.take(|r| matches!(r, Request::Lookup { .. }));
lookup.refuse("lookup failed");
dialog.pump(2.0);
assert!(dialog.busy, "a failed lookup cleared busy while the create for doc-A was still pending");
}
/// Two "Refresh status" clicks before either reply arrives race two
/// `Request::Status` calls. If the older one answers after the newer one
/// already installed, it must not overwrite the newer status.
#[test]
fn an_older_status_reply_does_not_overwrite_a_newer_one() {
let (mut dialog, hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
send(&mut dialog, b"A bytes");
let (_, create) = hold.take(|r| matches!(r, Request::Create { .. }));
create.answer(Answer::Created(envelope_for("doc-A", "alice")));
dialog.pump(1.0);
let env_id = dialog.envelope.as_ref().expect("created").id.clone();
dialog.busy = true;
let seq1 = dialog.submit_in_context(Request::Status { envelope: env_id.clone() });
dialog.pending_op_seq = Some(seq1);
dialog.status_seq = seq1;
dialog.busy = true;
let seq2 = dialog.submit_in_context(Request::Status { envelope: env_id.clone() });
dialog.pending_op_seq = Some(seq2);
dialog.status_seq = seq2;
let (_, status1) = hold.take(|r| matches!(r, Request::Status { .. }));
let (_, status2) = hold.take(|r| matches!(r, Request::Status { .. }));
// The newer request (seq2) answers first.
status2.answer(Answer::Status(Envelope { status: EnvelopeStatus::Completed, ..envelope_for("doc-A", "alice") }));
dialog.pump(2.0);
assert_eq!(dialog.envelope.as_ref().map(|e| e.status), Some(EnvelopeStatus::Completed));
// The older request (seq1), issued first, answers last.
status1.answer(Answer::Status(Envelope { status: EnvelopeStatus::Sent, ..envelope_for("doc-A", "alice") }));
dialog.pump(3.0);
assert_eq!(dialog.envelope.as_ref().map(|e| e.status), Some(EnvelopeStatus::Completed), "an older status reply overwrote a newer one");
}
@@ -0,0 +1,108 @@
//! Regression tests for CodeRabbit's second review pass on PR #661,
//! reproduced against 1e84947c (storytold/craft-libs#661).
//!
//! Reuses `review_repro`'s `Hold` backend and helpers, the same as
//! `coderabbit_repro`.
use craft_esign::{Envelope, EnvelopeStatus};
use super::review_repro::{Hold, envelope_for, ready, send, who};
use super::*;
/// A host can drive `Request::Status` through the public `submit_request`
/// path directly, not only through `status_panel`'s own "Refresh status"
/// button. That path must register `status_seq` too, or the reply it
/// produces fails the supersession guard added for the button's path and is
/// dropped.
#[test]
fn submit_request_for_a_public_status_submission_registers_status_seq() {
let (mut dialog, hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
send(&mut dialog, b"A bytes");
let (_, create) = hold.take(|r| matches!(r, Request::Create { .. }));
create.answer(Answer::Created(envelope_for("doc-A", "alice")));
dialog.pump(1.0);
let env_id = dialog.envelope.as_ref().expect("created").id.clone();
dialog.submit_request(Request::Status { envelope: env_id });
let (_, status) = hold.take(|r| matches!(r, Request::Status { .. }));
status.answer(Answer::Status(Envelope { status: EnvelopeStatus::Completed, ..envelope_for("doc-A", "alice") }));
dialog.pump(2.0);
assert_eq!(
dialog.envelope.as_ref().map(|e| e.status),
Some(EnvelopeStatus::Completed),
"a Status reply submitted through the public submit_request path was dropped by the status_seq guard"
);
}
/// `available()` stops asking again once the service has reported
/// `Envelopes`, so a backend whose `linked` value changes out of band (the
/// user signs in after the dialog already probed) is never re-asked unless
/// something clears the cached capabilities. `reset_capabilities` is that
/// something, on the same backend instance.
#[test]
fn reset_capabilities_reprobes_the_same_backend_after_an_out_of_band_sign_in() {
let hold = Hold::default();
let mut dialog = EsignDialog::default();
dialog.set_backend(hold.clone());
dialog.pump(0.0);
let (_, caps1) = hold.take(|r| matches!(r, Request::Capabilities));
caps1.answer(Answer::Capabilities { capabilities: vec![EsignCapability::Envelopes], responsible_party: "Stub Signing".into(), linked: false });
dialog.pump(0.1);
assert!(dialog.available());
assert!(!dialog.linked);
// Available is already true, so pump's own retry condition
// (`!available() && ...`) never fires again on its own, no matter how
// much time passes.
for t in 0..5 {
dialog.pump(0.2 + f64::from(t));
}
// The user signs in; nothing about the backend instance changes, so
// only an explicit reset asks again.
dialog.reset_capabilities();
dialog.pump(1.0);
let (_, caps2) = hold.take(|r| matches!(r, Request::Capabilities));
caps2.answer(Answer::Capabilities { capabilities: vec![EsignCapability::Envelopes], responsible_party: "Stub Signing".into(), linked: true });
dialog.pump(1.1);
assert!(dialog.linked, "reset_capabilities did not pick up the backend's new linked state");
}
/// The captured send context belongs only to the create submission that
/// answers a taken [`SendRequest`]. A status refresh submitted for the
/// current document while another document's send is still outstanding must
/// carry the current context, or `pump` drops its reply as belonging to the
/// abandoned send.
#[test]
fn status_for_the_current_document_is_not_consumed_by_an_outstanding_send_from_another() {
let (mut dialog, hold) = ready();
// Document A's send is taken by the app but never submitted: its captured
// context stays pending. The `send` helper would submit the create and
// consume that context, which is exactly what this test must avoid.
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
dialog.add_email("bob@example.com".into());
dialog.queue_send();
let taken = dialog.take_send_request();
assert!(taken.is_some(), "A's send request was taken, leaving its context pending");
// The dialog moves on to document B, which already has an envelope the
// host wants a status for.
dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice"));
dialog.envelope = Some(envelope_for("doc-B", "alice"));
let env_id = dialog.envelope.as_ref().map(|e| e.id.clone()).unwrap_or_default();
dialog.submit_request(Request::Status { envelope: env_id });
let (_, status) = hold.take(|r| matches!(r, Request::Status { .. }));
status.answer(Answer::Status(Envelope { status: EnvelopeStatus::Completed, ..envelope_for("doc-B", "alice") }));
dialog.pump(1.0);
assert_eq!(
dialog.envelope.as_ref().map(|e| e.status),
Some(EnvelopeStatus::Completed),
"B's status reply was dropped because the status request consumed A's outstanding send context"
);
}
File diff suppressed because it is too large. Load diff
+153
View File
@@ -0,0 +1,153 @@
//! Regression tests for the three gate items skylartaylor raised on PR #661,
//! reproduced against 0a937ef (storytold/craft-libs#661):
//! <https://gist.github.com/skylartaylor/c1108ecf20d63c5e3183947408ddab7a>.
//!
//! `Hold` is a backend that keeps every request and its `Replier` so a test
//! chooses when, and in what order, the service answers.
use std::sync::{Arc, Mutex};
use craft_cloud::Identity;
use craft_esign::{Envelope, EnvelopeStatus, EsignCapability};
use super::*;
/// Reused by `coderabbit_repro`, the regression tests for the CodeRabbit
/// findings reviewed on the same pull request.
#[derive(Clone, Default)]
pub(super) struct Hold(Arc<Mutex<Vec<(Request, Replier)>>>);
impl EsignBackend for Hold {
fn submit(&self, request: Request, reply: Replier) {
self.0.lock().unwrap().push((request, reply));
}
}
impl Hold {
/// Takes the oldest held request matching `pick`.
pub(super) fn take(&self, pick: impl Fn(&Request) -> bool) -> (Request, Replier) {
let mut held = self.0.lock().unwrap();
let i = held.iter().position(|(r, _)| pick(r)).expect("request was submitted");
held.remove(i)
}
}
pub(super) fn who(id: &str) -> Identity {
Identity { id: id.into(), display: id.into(), email: Some(format!("{id}@example.com")), avatar: None }
}
pub(super) fn envelope_for(doc: &str, sender: &str) -> Envelope {
Envelope {
id: format!("env-{doc}"),
title: format!("Contract {doc}"),
message: None,
sender: who(sender),
document_id: Some(doc.into()),
document_etag: None,
content_sha256: String::new(),
recipients: Vec::new(),
placements: Vec::new(),
status: EnvelopeStatus::Sent,
expires: None,
created: None,
completed_at: None,
}
}
/// A dialog with a held backend whose capabilities probe has been answered.
pub(super) fn ready() -> (EsignDialog, Hold) {
let hold = Hold::default();
let mut dialog = EsignDialog::default();
dialog.set_backend(hold.clone());
dialog.pump(0.0); // submits Capabilities
let (_, caps) = hold.take(|r| matches!(r, Request::Capabilities));
caps.answer(Answer::Capabilities {
capabilities: vec![EsignCapability::Envelopes, EsignCapability::Void],
responsible_party: "Stub Signing".into(),
linked: true,
});
dialog.pump(0.1);
assert!(dialog.available());
(dialog, hold)
}
/// The app's Send path: queue_send -> take_send_request -> submit Create.
pub(super) fn send(dialog: &mut EsignDialog, doc_bytes: &[u8]) {
dialog.add_email("bob@example.com".into());
dialog.queue_send();
let out = dialog.take_send_request().expect("Send produced a request");
dialog.submit_request(Request::Create {
draft: Box::new(out.draft),
document: doc_bytes.to_vec(),
idempotency_key: out.idempotency_key,
send: true,
});
}
/// Gate item 1 (document variant): the dialog is reopened for document B
/// while document A's create is in flight. A's late reply carries document
/// A's context and must not be installed as document B's envelope.
#[test]
fn review_h5_reply_for_previous_document_is_installed_after_reopen() {
let (mut dialog, hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
send(&mut dialog, b"A bytes");
dialog.open("doc-B".into(), "B.pdf".into(), None, who("alice"));
let (_, create_a) = hold.take(|r| matches!(r, Request::Create { .. }));
create_a.answer(Answer::Created(envelope_for("doc-A", "alice")));
dialog.pump(1.0);
let shown = dialog.envelope.as_ref().and_then(|e| e.document_id.clone());
assert!(
shown.is_none() || shown.as_deref() == Some("doc-B"),
"dialog is open for doc-B but shows the envelope for {shown:?} (status panel: Void/Remind act on it); busy={}",
dialog.busy
);
}
/// Gate item 1 (account variant): reopened for the same document under
/// another signed-in account. Alice's envelope must never render for
/// mallory.
#[test]
fn review_h5_reply_for_previous_account_is_installed_after_account_switch() {
let (mut dialog, hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
send(&mut dialog, b"A bytes");
dialog.open("doc-A".into(), "A.pdf".into(), None, who("mallory"));
let (_, create) = hold.take(|r| matches!(r, Request::Create { .. }));
create.answer(Answer::Created(envelope_for("doc-A", "alice")));
dialog.pump(1.0);
let shown = dialog.envelope.as_ref().map(|e| e.sender.id.clone());
assert!(shown.is_none() || shown.as_deref() == Some("mallory"), "dialog now belongs to mallory but shows alice's envelope: sender={shown:?}");
}
/// Gate item 2: Send is in flight; the user types in the signer search box
/// (a lookup is submitted, which used to bump the old staleness counter).
/// The create reply then arrives for the same context and must still
/// install: typing in a search box is not a context change.
#[test]
fn review_n1_create_reply_dropped_after_a_lookup_leaves_dialog_busy() {
let (mut dialog, hold) = ready();
dialog.open("doc-A".into(), "A.pdf".into(), None, who("alice"));
send(&mut dialog, b"A bytes");
assert!(dialog.busy);
dialog.query = "ca".into(); // typed after pressing Send
dialog.query_changed_at = 1.0;
dialog.maybe_lookup(2.0);
let (_, create) = hold.take(|r| matches!(r, Request::Create { .. }));
create.answer(Answer::Created(envelope_for("doc-A", "alice")));
for t in 0..10 {
dialog.pump(3.0 + f64::from(t));
}
assert!(
!dialog.busy && dialog.envelope.is_some(),
"provider created env-doc-A but dialog busy={} envelope={:?} (reply dropped as stale)",
dialog.busy,
dialog.envelope.as_ref().map(|e| e.id.clone())
);
}
+7 -5
View File
@@ -1,19 +1,21 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
//! The share dialog, the cloud Open and Save pages, the account menu and the presence bar that
//! every Craft app shares.
//! The share dialog, the cloud Open and Save pages, the request-signatures dialog, the account
//! menu and the presence bar that every Craft app shares.
//!
//! This is storytold main's cloud and share UI as main wrote it in craft-ui: raw egui, outside the
//! craft UI library's component contract, themes and tokens. It is to be ported onto the
//! framework's components. Until then the `craft-ui` facade re-exports `account`, `cloud`, `share`
//! and `presence` from here, with the same `share` and `cloud` features, so `craft_ui::…` paths
//! stay as on main.
//! framework's components. Until then the `craft-ui` facade re-exports `account`, `cloud`, `esign`,
//! `share` and `presence` from here, with the same `share`, `cloud` and `esign` features, so
//! `craft_ui::…` paths stay as on main.
#[cfg(feature = "share")]
pub mod account;
mod buttons;
#[cfg(feature = "cloud")]
pub mod cloud;
#[cfg(feature = "esign")]
pub mod esign;
pub mod menu;
pub mod presence;
#[cfg(feature = "share")]
+121 -3
View File
@@ -43,7 +43,9 @@ pub const fn det(m: &Mat3) -> f64 {
+ m[0][2] * (m[1][0] * m[2][1] - m[1][1] * m[2][0])
}
/// Inverse, or `None` when (nearly) singular.
/// Inverse, or `None` when (nearly) singular: the determinant is not finite or is below 1e-12.
/// Profile construction checks its matrices with this rule. [`inverse`] takes the determinant
/// relative to the largest entry instead.
pub const fn invert(m: &Mat3) -> Option<Mat3> {
let d = det(m);
if !d.is_finite() || d.abs() < 1e-12 {
@@ -57,14 +59,66 @@ pub const fn invert(m: &Mat3) -> Option<Mat3> {
])
}
/// Inverse of a matrix at any scale, or `None` when it holds a NaN or an infinite entry, is all
/// zeros, is singular to within rounding (the determinant is at most 1e-12 times the cube of the
/// largest entry), or has an inverse with an entry beyond the range of `f64`.
///
/// The matrix is divided by its largest entry before the determinant is taken, so a matrix whose
/// own determinant overflows or underflows (`diag(1e-200, 1e-200, 1e-200)`) still inverts.
pub const fn inverse(m: &Mat3) -> Option<Mat3> {
let mut scale = 0.0f64;
let mut i = 0;
while i < 9 {
let v = m[i / 3][i % 3];
if v.is_nan() {
return None;
}
if v.abs() > scale {
scale = v.abs();
}
i += 1;
}
if !(scale.is_finite() && scale > 0.0) {
return None;
}
let mut s = [[0.0; 3]; 3];
let mut i = 0;
while i < 9 {
s[i / 3][i % 3] = m[i / 3][i % 3] / scale;
i += 1;
}
let d = det(&s);
if !d.is_finite() || d.abs() <= 1e-12 {
return None;
}
// Each cofactor is divided by the determinant and then by the scale: the reciprocals can
// overflow where the quotients do not.
let c = [
[s[1][1] * s[2][2] - s[1][2] * s[2][1], s[0][2] * s[2][1] - s[0][1] * s[2][2], s[0][1] * s[1][2] - s[0][2] * s[1][1]],
[s[1][2] * s[2][0] - s[1][0] * s[2][2], s[0][0] * s[2][2] - s[0][2] * s[2][0], s[0][2] * s[1][0] - s[0][0] * s[1][2]],
[s[1][0] * s[2][1] - s[1][1] * s[2][0], s[0][1] * s[2][0] - s[0][0] * s[2][1], s[0][0] * s[1][1] - s[0][1] * s[1][0]],
];
let mut inv = [[0.0; 3]; 3];
let mut i = 0;
while i < 9 {
let v = c[i / 3][i % 3] / d / scale;
if !v.is_finite() {
return None;
}
inv[i / 3][i % 3] = v;
i += 1;
}
Some(inv)
}
/// XYZ (Y = 1) of a chromaticity `(x, y)`.
pub const fn xy_to_xyz(xy: [f64; 2]) -> [f64; 3] {
let [x, y] = xy;
[x / y, 1.0, (1.0 - x - y) / y]
}
/// Bradford cone response matrix (Lam 1985).
const BRADFORD: Mat3 = [[0.8951, 0.2664, -0.1614], [-0.7502, 1.7135, 0.0367], [0.0389, -0.0685, 1.0296]];
/// Bradford cone response matrix (Lam 1985): XYZ to sharpened cone responses.
pub const BRADFORD: Mat3 = [[0.8951, 0.2664, -0.1614], [-0.7502, 1.7135, 0.0367], [0.0389, -0.0685, 1.0296]];
/// Inverse of [`BRADFORD`] (determinant ~1.7), computed at compile time.
const BRADFORD_INV: Mat3 = match invert(&BRADFORD) {
@@ -81,6 +135,17 @@ pub fn bradford(src: [f64; 3], dst: [f64; 3]) -> Mat3 {
mul(&inv, &mul(&scale, &BRADFORD))
}
/// [`bradford`], or `None` when a white's cone response is not finite or not above 0, or the
/// response ratios overflow. [`bradford`] divides by the source response without this check.
pub fn bradford_checked(src: [f64; 3], dst: [f64; 3]) -> Option<Mat3> {
let ok = |v: [f64; 3]| v.iter().all(|c| c.is_finite() && *c > 0.0);
if !(ok(apply(&BRADFORD, src)) && ok(apply(&BRADFORD, dst))) {
return None;
}
let m = bradford(src, dst);
m.iter().flatten().all(|v| v.is_finite()).then_some(m)
}
/// RGB → XYZ matrix (relative to `white`, Y = 1) for primaries given as chromaticities, or
/// `None` when the primaries are not independent.
pub const fn rgb_to_xyz_matrix(r: [f64; 2], g: [f64; 2], b: [f64; 2], white: [f64; 3]) -> Option<Mat3> {
@@ -246,4 +311,57 @@ mod tests {
assert!((delta_e2000(b, a) - want).abs() < 1e-4);
}
}
fn close(a: &Mat3, b: &Mat3, tol: f64) {
for i in 0..3 {
for j in 0..3 {
assert!((a[i][j] - b[i][j]).abs() <= tol, "[{i}][{j}] {} vs {}", a[i][j], b[i][j]);
}
}
}
const fn diag(v: f64) -> Mat3 {
[[v, 0.0, 0.0], [0.0, v, 0.0], [0.0, 0.0, v]]
}
#[test]
fn inverse_matches_invert_on_ordinary_matrices() {
let m = [[0.4, 0.3, 0.2], [0.2, 0.7, 0.1], [0.0, 0.1, 0.8]];
close(&inverse(&m).unwrap(), &invert(&m).unwrap(), 1e-12);
assert_eq!(inverse(&BRADFORD).map(|_| ()), Some(()));
}
#[test]
fn inverse_works_at_any_scale_and_rejects_what_has_no_finite_inverse() {
// The determinant, 1e-312, has no finite reciprocal; the inverse itself is finite.
close(&inverse(&diag(1e-104)).unwrap(), &diag(1e104), 1e93);
assert_eq!(invert(&diag(1e-104)), None);
// A determinant beyond f64 in either direction still leaves a finite inverse.
close(&inverse(&diag(1e-200)).unwrap(), &diag(1e200), 1e186);
close(&inverse(&diag(1e110)).unwrap(), &diag(1e-110), 1e-124);
assert_eq!(inverse(&diag(f64::MAX)).map(|m| m[0][0]), Some(1.0 / f64::MAX));
// An inverse with entries beyond f64 is no inverse.
assert_eq!(inverse(&diag(1e-310)), None);
assert_eq!(inverse(&[[0.0; 3]; 3]), None);
assert_eq!(inverse(&[[f64::NAN; 3]; 3]), None);
assert_eq!(inverse(&diag(f64::INFINITY)), None);
let mut one_nan = IDENTITY;
one_nan[1][2] = f64::NAN;
assert_eq!(inverse(&one_nan), None);
// Singular to within rounding relative to the largest entry.
assert_eq!(inverse(&[[1.0, 2.0, 3.0], [2.0, 4.0, 6.0], [0.0, 0.0, 1e9]]), None);
}
#[test]
fn bradford_checked_rejects_whites_with_no_cone_response() {
let d65 = xy_to_xyz(D65_XY);
close(&bradford_checked(d65, D50).unwrap(), &bradford(d65, D50), 0.0);
assert_eq!(bradford_checked([0.0; 3], D50), None);
assert_eq!(bradford_checked(d65, [f64::NAN; 3]), None);
assert_eq!(bradford_checked(d65, [-1.0, -1.0, -1.0]), None);
// Cone responses this small give scale ratios beyond f64.
assert_eq!(bradford_checked([1e-320; 3], d65), None);
// Unchecked, the zero white divides by zero.
assert!(bradford([0.0; 3], D50).iter().flatten().any(|v| !v.is_finite()));
}
}
+21
View File
@@ -0,0 +1,21 @@
[package]
name = "craft-color-transform"
description = "Color transforms for Craft apps: RGB spaces and Bradford adaptation, white balance by temperature and tint, OkLab and OkLCh, monotone tone curves and 1D lookup tables, and BT.2408 PQ tone mapping"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
# PQ (SMPTE ST 2084), the HDR reference white and the color primaries tags.
craft-color = { workspace = true }
# The 3×3 matrix arithmetic and Bradford adaptation (`craft_cms::math`).
craft-cms = { workspace = true }
serde = { workspace = true }
[dev-dependencies]
serde_json = { workspace = true }
+74
View File
@@ -0,0 +1,74 @@
# craft-color-transform
Color transforms for the Craft apps: RGB spaces and chromatic adaptation, white balance by
temperature and tint, OkLab and OkLCh, monotone tone curves and 1D lookup tables, and PQ tone
mapping. It builds on [`craft-color`](../color), which holds the frame color tags, the Y'CbCr
matrices and the sRGB, PQ and HLG transfer functions. It depends on `craft-color`, `craft-cms`
and `serde`, contains no `unsafe` code, and builds for `wasm32-unknown-unknown`. The per-pixel
functions take `f32` and do not allocate.
The matrix arithmetic comes from `craft_cms::math`. `Mat3` wraps its row-major `[[f64; 3]; 3]`
and converts to and from it with `From`. `mul`, `apply` and `determinant` call `math::mul`,
`math::apply` and `math::det`, `Mat3::inverse` calls `math::inverse`, `Xy::to_xyz` calls
`math::xy_to_xyz` after checking the chromaticity, `BRADFORD` is `math::BRADFORD`, and
`bradford_xyz` calls `math::bradford_checked`. `math::inverse` divides the matrix by its largest
entry before taking the determinant. `math::invert`, which `craft-cms` uses to validate ICC
matrices, keeps its absolute determinant floor of 1e-12. `RgbSpace::to_xyz` builds the
normalized primary matrix with `math::inverse` rather than with `math::rgb_to_xyz_matrix`, which
inverts with `math::invert`, and returns the identity when the normalized matrix has no inverse.
Moved from StudioCraft's `craft-color-transform`
([`crates/craft-color-transform`](https://github.com/blamejs/StudioCraft/tree/2abe1824aa0d849faf8d5f91557d68ebe577f495/crates/craft-color-transform)).
Parts of it started in other Craft apps:
- `cct`, `oklab` and `curve` came from LightCraft's `lightcraft-color` (`crates/color/src/cct.rs`,
`perceptual.rs` and `spline.rs`). `MonotoneCurve` now loads a saved curve through its
constructor, so a file cannot give it arrays of different lengths, and it bounds the points it
keeps and the size of their coordinates. `OkLab::for_space` extends the BT.2020-only OkLab
conversion to any `RgbSpace`.
- `tonemap` came from FilmCraft's `filmcraft-color` (`crates/color/src/transform.rs`,
`bt2390_eetf` and its maxRGB operator). It now follows Report ITU-R BT.2408-8 Annex 5 with
the black lift, passes values through when the target peak is at or above the source peak,
and handles a target peak below a third of the source range (see `Eetf`).
License: MIT OR Apache-2.0.
## Contents
| Item | What it does | Source of the formula |
| --- | --- | --- |
| `Mat3`, `Xy`, `RgbSpace` | 3×3 matrices, CIE 1931 chromaticities, RGB spaces from primaries and a white point. `RgbSpace::to_xyz` is the normalized primary matrix. `RgbSpace::from(craft_color::Primaries)` gives the space of a frame tag. | SMPTE RP 177; primaries from ITU-R BT.709, BT.601, BT.2020 and SMPTE EG 432-1 |
| `bradford`, `bradford_xyz` | The Bradford chromatic adaptation matrix between two whites. `RgbSpace::to_space` converts between spaces with it. | The Bradford cone response matrix |
| `cct::temp_tint_to_xy`, `cct::xy_to_temp_tint` | A white at a correlated color temperature and tint, and back. Tint is Duv × 3000 along the locus normal in CIE 1960 (u, v); positive is towards green. | Kim et al., "Design of Advanced Color Temperature Control System for HDTV Applications", Journal of the Korean Physical Society 41 (2002) |
| `cct::wb_matrix`, `cct::white_balance` | The RGB matrix that makes a scene lit by one white look lit by another. | Bradford adaptation |
| `oklab` | OkLab from linear sRGB with the published matrices, from XYZ, and for any `RgbSpace` (`OkLab::for_space`, with `f32` matrices; `oklab::lms_matrices` gives the same matrices in `f64`); OkLCh. | B. Ottosson, "A perceptual color space for image processing" (2020) |
| `curve::MonotoneCurve` | A tone curve through points that does not overshoot between them. It saves as its list of points. `knots` gives each point with its tangent for evaluation in a shader. | Fritsch and Carlson, "Monotone Piecewise Cubic Interpolation", SIAM J. Numer. Anal. 17 (1980) |
| `curve::Lut1` | A 1D lookup table over 0..1 with linear interpolation. | |
| `tonemap::Eetf` | The reference EETF from a mastering display to a target display, with the black lift, on PQ values or nits. When the target peak is below a third of the source range in PQ, where the Annex's knee would be negative, the knee is 0 and the spline starts with a slope of 3 × maxLum. When minLum is above 0.25, where the Annex's lift minLum × (1 − E2)⁴ would make the output fall near black and raise the peak above the target peak, the lift is minLum × (1 − E2 / r)ᵏ with r = max(T, min(1, 2 − 4 minLum)) and k = min(4, r / minLum), where T is the smaller of maxLum and 1. This equals the Annex's lift up to minLum 0.25, keeps the output rising, changes continuously with the target black, and from minLum 0.5 reaches 0 at the top of the output. A target black above the source peak reads as the source peak. Both rules are the crate's own. | Report ITU-R BT.2408-8, Annex 5 |
| `tonemap::ToneMap` | The EETF applied to linear RGB by max(R, G, B) as a ratio, with 1.0 at the 203-nit reference white. | Report ITU-R BT.2408-8, Annex 5 (the maxRGB option) |
## Hostile input
- A chromaticity with `y` at or below 0, or with a coordinate that is not finite, is rejected by
`Xy::to_xyz`. `bradford` then returns the identity, and so does `RgbSpace::to_xyz` for such a
white, for collinear primaries and for a white that gives a primary no weight. `Mat3::inverse`
and `bradford_xyz` return `None` or the identity instead of a matrix with entries beyond
`f64`.
- Temperatures are clamped to 1000 K to 100 000 K, and NaN reads as 6500 K. A tint that is not
finite reads as 0.
- `MonotoneCurve` keeps at most 1024 points and drops points with a coordinate that is not
finite or is beyond ±1e6. A saved curve is read back through the same constructor, so a file
cannot give it mismatched arrays.
- `Lut1::from_fn` and `MonotoneCurve::to_lut` build at most 65 536 entries.
- Luminances are clamped to 0..10 000 nits. A target peak that is NaN or not above 0 gives an
EETF and a `ToneMap` that pass values through.
## Tests
`cargo test -p craft-color-transform` checks the code against published values: the sRGB matrix of
IEC 61966-2-1, the BT.709 and BT.2020 luminance weights, the BT.709 to BT.2020 matrix of
ITU-R BT.2087, the D65 to D50 Bradford matrix as Lindbloom's chromatic adaptation page prints it,
illuminant A and D65 from CIE 15:2004 (temperature, Duv, CIE 1960 coordinates), Ottosson's XYZ to
OkLab table, the OkLab value CSS Color Module Level 4 gives for `#7654CD`, the PQ levels of
BT.2408, and EETF values computed from the BT.2408 Annex 5 equations by a separate
implementation.
+243
View File
@@ -0,0 +1,243 @@
//! Correlated color temperature, tint and white balance.
//!
//! The Planckian locus is the cubic approximation of Kim et al., "Design of Advanced Color
//! Temperature Control System for HDTV Applications", Journal of the Korean Physical Society 41
//! (2002), over 1667 K to 25000 K. Outside that range the locus continues as a straight line in
//! mired (10⁶ / K) from the end of the approximation. Temperatures are clamped to
//! [`MIN_TEMPERATURE`] to [`MAX_TEMPERATURE`].
//!
//! Tint is a signed distance from the locus in CIE 1960 (u, v), along the locus normal, in units
//! of 1/[`TINT_SCALE`] of Duv. A positive tint is a white above the locus (towards green), so the
//! correction that removes it adds magenta; a negative tint is a white below the locus.
use crate::{Mat3, RgbSpace, Xy, bradford};
/// Tint units per unit of Duv.
pub const TINT_SCALE: f64 = 3000.0;
/// The lowest temperature the approximation covers, in kelvin.
pub const KIM_MIN: f64 = 1667.0;
/// The highest temperature the approximation covers, in kelvin.
pub const KIM_MAX: f64 = 25000.0;
/// The lowest temperature the functions here take.
pub const MIN_TEMPERATURE: f64 = 1000.0;
/// The highest temperature the functions here take.
pub const MAX_TEMPERATURE: f64 = 100_000.0;
fn kim_xy(t: f64) -> Xy {
let t = t.clamp(KIM_MIN, KIM_MAX);
let (t2, t3) = (t * t, t * t * t);
let x = if t <= 4000.0 {
-0.2661239e9 / t3 - 0.2343589e6 / t2 + 0.8776956e3 / t + 0.179910
} else {
-3.0258469e9 / t3 + 2.1070379e6 / t2 + 0.2226347e3 / t + 0.240390
};
let (x2, x3) = (x * x, x * x * x);
let y = if t <= 2222.0 {
-1.1063814 * x3 - 1.34811020 * x2 + 2.18555832 * x - 0.20219683
} else if t <= 4000.0 {
-0.9549476 * x3 - 1.37418593 * x2 + 2.09137015 * x - 0.16748867
} else {
3.0817580 * x3 - 5.87338670 * x2 + 3.75112997 * x - 0.37001483
};
Xy::new(x, y)
}
/// CIE 1931 xy to CIE 1960 (u, v).
pub fn xy_to_uv(p: Xy) -> (f64, f64) {
let d = -2.0 * p.x + 12.0 * p.y + 3.0;
(4.0 * p.x / d, 6.0 * p.y / d)
}
/// CIE 1960 (u, v) to CIE 1931 xy.
pub fn uv_to_xy(u: f64, v: f64) -> Xy {
let d = 2.0 * u - 8.0 * v + 4.0;
Xy::new(3.0 * u / d, 2.0 * v / d)
}
/// A temperature in range: NaN reads as 6500 K.
fn sane_temperature(t: f64) -> f64 {
if t.is_nan() { 6500.0 } else { t.clamp(MIN_TEMPERATURE, MAX_TEMPERATURE) }
}
/// The locus in (u, v) at `t` kelvin.
fn locus_uv(t: f64) -> (f64, f64) {
if (KIM_MIN..=KIM_MAX).contains(&t) {
return xy_to_uv(kim_xy(t));
}
let (a, b) = if t < KIM_MIN { (KIM_MIN, KIM_MIN + 50.0) } else { (KIM_MAX - 500.0, KIM_MAX) };
let (ua, va) = xy_to_uv(kim_xy(a));
let (ub, vb) = xy_to_uv(kim_xy(b));
let (ma, mb, m) = (1e6 / a, 1e6 / b, 1e6 / t);
let s = (m - ma) / (mb - ma);
(ua + (ub - ua) * s, va + (vb - va) * s)
}
/// The unit normal of the locus at `t`, pointing towards green (increasing v).
fn locus_normal(t: f64) -> (f64, f64) {
let m = 1e6 / t;
let (u0, v0) = locus_uv(1e6 / (m + 1.0));
let (u1, v1) = locus_uv(1e6 / (m - 1.0).max(1.0));
let (du, dv) = (u1 - u0, v1 - v0);
let l = du.hypot(dv).max(1e-12);
let (nx, ny) = (-dv / l, du / l);
if ny < 0.0 { (-nx, -ny) } else { (nx, ny) }
}
/// The chromaticity of a white at temperature `t` (kelvin) and `tint`. A NaN tint reads as 0.
pub fn temp_tint_to_xy(t: f64, tint: f64) -> Xy {
let t = sane_temperature(t);
let tint = if tint.is_finite() { tint } else { 0.0 };
let (u, v) = locus_uv(t);
let (nu, nv) = locus_normal(t);
let duv = tint / TINT_SCALE;
uv_to_xy(u + nu * duv, v + nv * duv)
}
/// The temperature and tint of a white: the nearest point on the locus, searched in mired, and
/// the signed distance from it. The inverse of [`temp_tint_to_xy`] over its range. A
/// chromaticity with no (u, v) coordinates (NaN, or on the line where their denominator is 0)
/// reads as 6500 K with no tint.
pub fn xy_to_temp_tint(p: Xy) -> (f64, f64) {
let (u, v) = xy_to_uv(p);
if !(u.is_finite() && v.is_finite()) {
return (6500.0, 0.0);
}
let dist = |m: f64| {
let (lu, lv) = locus_uv(1e6 / m);
(u - lu).powi(2) + (v - lv).powi(2)
};
let (lo, hi) = (1e6 / MAX_TEMPERATURE, 1e6 / MIN_TEMPERATURE);
// A scan every 5 mired, then a golden-section search around the best step.
let mut best = lo;
let mut best_d = f64::MAX;
let mut m = lo;
while m <= hi {
let d = dist(m);
if d < best_d {
best_d = d;
best = m;
}
m += 5.0;
}
let (mut a, mut b) = ((best - 5.0).max(lo), (best + 5.0).min(hi));
let g = 0.618_033_988_75;
for _ in 0..60 {
let c = b - g * (b - a);
let d = a + g * (b - a);
if dist(c) < dist(d) { b = d } else { a = c }
}
let t = 1e6 / ((a + b) / 2.0);
let (lu, lv) = locus_uv(t);
let (nu, nv) = locus_normal(t);
(t, ((u - lu) * nu + (v - lv) * nv) * TINT_SCALE)
}
/// The matrix (linear RGB in `space` to the same space) that makes a scene lit by a white at
/// `src` look as if it were lit by the space's own white (Bradford adaptation).
pub fn wb_matrix(space: &RgbSpace, src: Xy) -> Mat3 {
space.from_xyz().mul(&bradford(src, space.white)).mul(&space.to_xyz())
}
/// The matrix (linear RGB in `space` to the same space) that makes a scene lit by a white at
/// temperature and tint `from` look as if it were lit by the white at `to`. Equal settings give
/// the identity. A lower `from` temperature than `to` cools the picture.
pub fn white_balance(space: &RgbSpace, from: (f64, f64), to: (f64, f64)) -> Mat3 {
let (src, dst) = (temp_tint_to_xy(from.0, from.1), temp_tint_to_xy(to.0, to.1));
if src == dst {
return Mat3::IDENTITY;
}
space.from_xyz().mul(&bradford(src, dst)).mul(&space.to_xyz())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::{D65, REC2020, SRGB};
/// CIE 15:2004 gives illuminant A (a Planckian radiator at 2856 K) as x = 0.44757,
/// y = 0.40745. The cubic approximation lands within 0.001 Duv of it.
#[test]
fn illuminant_a_lies_on_the_locus() {
let (u, v) = xy_to_uv(temp_tint_to_xy(2856.0, 0.0));
let (ua, va) = xy_to_uv(Xy::new(0.44757, 0.40745));
assert!((u - ua).hypot(v - va) < 1e-3, "{u} {v}");
let (t, _) = xy_to_temp_tint(Xy::new(0.44757, 0.40745));
assert!((t - 2856.0).abs() < 15.0, "{t}");
}
/// CIE 15:2004 gives D65 a correlated color temperature of 6504 K; it lies above the locus
/// by a Duv of about 0.0032.
#[test]
fn d65_reads_as_6504_k_above_the_locus() {
let (t, tint) = xy_to_temp_tint(D65);
assert!((t - 6504.0).abs() < 15.0, "{t}");
assert!((tint / TINT_SCALE - 0.0032).abs() < 3e-4, "{tint}");
}
/// D65 in CIE 1960 UCS is (0.1978, 0.3122).
#[test]
fn uv_matches_cie_1960_for_d65() {
let (u, v) = xy_to_uv(D65);
assert!((u - 0.1978).abs() < 1e-4 && (v - 0.3122).abs() < 1e-4, "{u} {v}");
let back = uv_to_xy(u, v);
assert!((back.x - D65.x).abs() < 1e-12 && (back.y - D65.y).abs() < 1e-12);
}
#[test]
fn temperature_and_tint_round_trip() {
for t in [1200.0, 2000.0, 2856.0, 4000.0, 5003.0, 6500.0, 9000.0, 15000.0, 30000.0, 50000.0] {
for tint in [-100.0, -20.0, 0.0, 35.0, 150.0] {
let (t2, tint2) = xy_to_temp_tint(temp_tint_to_xy(t, tint));
assert!((t2 - t).abs() / t < 0.01, "{t} {tint} -> {t2}");
assert!((tint2 - tint).abs() < 1.0, "{t} {tint} -> {tint2}");
}
}
}
#[test]
fn warmer_whites_are_redder_and_positive_tint_is_greener() {
assert!(temp_tint_to_xy(3000.0, 0.0).x > temp_tint_to_xy(9000.0, 0.0).x);
let (_, v0) = xy_to_uv(temp_tint_to_xy(5000.0, 0.0));
let (_, v1) = xy_to_uv(temp_tint_to_xy(5000.0, 50.0));
assert!(v1 > v0);
}
#[test]
fn wb_matrix_maps_the_source_white_to_neutral() {
let src = temp_tint_to_xy(3200.0, 10.0);
let m = wb_matrix(&REC2020, src);
let out = m.apply(REC2020.from_xyz().apply(src.to_xyz().unwrap()));
assert!((out[0] - out[1]).abs() < 1e-9 && (out[1] - out[2]).abs() < 1e-9, "{out:?}");
}
#[test]
fn white_balance_is_the_identity_for_equal_settings_and_cools_a_warm_light() {
assert_eq!(white_balance(&SRGB, (6500.0, 0.0), (6500.0, 0.0)), Mat3::IDENTITY);
// Light at 3200 K made to look like 6500 K: a white surface lit by it turns neutral.
let m = white_balance(&SRGB, (3200.0, 0.0), (6500.0, 0.0));
let gray = m.apply([1.0, 1.0, 1.0]);
assert!(gray[2] > gray[0], "{gray:?}");
let lit = SRGB.from_xyz().apply(temp_tint_to_xy(3200.0, 0.0).to_xyz().unwrap());
let lit6500 = SRGB.from_xyz().apply(temp_tint_to_xy(6500.0, 0.0).to_xyz().unwrap());
let out = m.apply(lit);
for i in 0..3 {
assert!((out[i] - lit6500[i]).abs() < 1e-9, "{out:?} {lit6500:?}");
}
}
#[test]
fn hostile_temperatures_stay_finite() {
for t in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, 0.0, -5.0, 1e300] {
for tint in [f64::NAN, f64::INFINITY, 0.0] {
let p = temp_tint_to_xy(t, tint);
assert!(p.x.is_finite() && p.y.is_finite(), "{t} {tint} {p:?}");
let m = white_balance(&SRGB, (t, tint), (6500.0, 0.0));
assert!(m.0.iter().flatten().all(|v| v.is_finite()), "{t} {tint}");
}
}
// -2x + 12y + 3 = 0 at (1.5, 0): the (u, v) denominator.
for p in [Xy::new(f64::NAN, f64::NAN), Xy::new(1.5, 0.0), Xy::new(f64::INFINITY, 0.3)] {
assert_eq!(xy_to_temp_tint(p), (6500.0, 0.0), "{p:?}");
}
}
}
+421
View File
@@ -0,0 +1,421 @@
//! Tone curves: monotone cubic Hermite splines and 1D lookup tables.
//!
//! [`MonotoneCurve`] interpolates its points with the tangents of F. N. Fritsch and R. E.
//! Carlson, "Monotone Piecewise Cubic Interpolation", SIAM Journal on Numerical Analysis 17
//! (1980): between two points the curve does not overshoot, so a curve whose points rise never
//! falls.
use std::fmt;
use serde::de::{IgnoredAny, SeqAccess, Visitor};
use serde::{Deserialize, Deserializer, Serialize};
/// The most points a [`MonotoneCurve`] keeps; points past it are ignored.
pub const MAX_POINTS: usize = 1024;
/// The largest coordinate a [`MonotoneCurve`] point may have; points farther out are dropped.
pub const MAX_COORDINATE: f64 = 1e6;
/// A curve through points in `0..1 × 0..1` (any finite values work). It is saved as its points.
#[derive(Clone, Debug, PartialEq, Serialize)]
#[serde(into = "Vec<(f64, f64)>")]
pub struct MonotoneCurve {
xs: Vec<f64>,
ys: Vec<f64>,
ms: Vec<f64>,
}
impl From<Vec<(f64, f64)>> for MonotoneCurve {
fn from(points: Vec<(f64, f64)>) -> MonotoneCurve {
MonotoneCurve::new(&points)
}
}
/// Reads a saved list of points, keeping the first [`MAX_POINTS`] and skipping the rest
/// without storing them.
impl<'de> Deserialize<'de> for MonotoneCurve {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<MonotoneCurve, D::Error> {
struct Points;
impl<'de> Visitor<'de> for Points {
type Value = MonotoneCurve;
fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
f.write_str("a list of [x, y] points")
}
fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<MonotoneCurve, A::Error> {
let mut p = Vec::with_capacity(seq.size_hint().unwrap_or(0).min(MAX_POINTS));
while p.len() < MAX_POINTS {
match seq.next_element::<(f64, f64)>()? {
Some(q) => p.push(q),
None => return Ok(MonotoneCurve::new(&p)),
}
}
while seq.next_element::<IgnoredAny>()?.is_some() {}
Ok(MonotoneCurve::new(&p))
}
}
d.deserialize_seq(Points)
}
}
impl From<MonotoneCurve> for Vec<(f64, f64)> {
fn from(c: MonotoneCurve) -> Vec<(f64, f64)> {
c.points()
}
}
impl MonotoneCurve {
/// A curve through `points`, sorted by x. Points with a coordinate that is not finite or is
/// beyond ±[`MAX_COORDINATE`] are dropped, and of points closer than 1e-9 in x the first is
/// kept. Fewer than two points give the identity.
pub fn new(points: &[(f64, f64)]) -> MonotoneCurve {
let ok = |v: f64| v.is_finite() && v.abs() <= MAX_COORDINATE;
let mut p: Vec<(f64, f64)> = points.iter().take(MAX_POINTS).copied().filter(|(x, y)| ok(*x) && ok(*y)).collect();
p.sort_by(|a, b| a.0.total_cmp(&b.0));
p.dedup_by(|a, b| (a.0 - b.0).abs() < 1e-9);
if p.len() < 2 {
p = vec![(0.0, 0.0), (1.0, 1.0)];
}
let n = p.len();
let xs: Vec<f64> = p.iter().map(|q| q.0).collect();
let ys: Vec<f64> = p.iter().map(|q| q.1).collect();
let d: Vec<f64> = xs.windows(2).zip(ys.windows(2)).map(|(x, y)| (y[1] - y[0]) / (x[1] - x[0])).collect();
let mut ms = vec![0.0; n];
ms[0] = d[0];
ms[n - 1] = d[n - 2];
for i in 1..n - 1 {
ms[i] = if d[i - 1] * d[i] <= 0.0 { 0.0 } else { (d[i - 1] + d[i]) / 2.0 };
}
// The Fritsch–Carlson limit: tangents inside the circle of radius 3 keep each segment
// monotone. The length of (m₀, m₁) is compared with 3·|d|, which stays finite when the
// secant d is subnormal.
for i in 0..n - 1 {
if d[i] == 0.0 {
ms[i] = 0.0;
ms[i + 1] = 0.0;
continue;
}
let r = ms[i].hypot(ms[i + 1]);
let limit = 3.0 * d[i].abs();
if r > limit {
ms[i] = ms[i] / r * limit;
ms[i + 1] = ms[i + 1] / r * limit;
}
}
MonotoneCurve { xs, ys, ms }
}
pub fn identity() -> MonotoneCurve {
MonotoneCurve::new(&[(0.0, 0.0), (1.0, 1.0)])
}
/// Whether the curve maps every value in `0..1` to itself. A curve whose points do not
/// reach 0 and 1 is not the identity, since it clamps outside them.
pub fn is_identity(&self) -> bool {
let covers = self.xs.first().is_some_and(|x| *x <= 0.0) && self.xs.last().is_some_and(|x| *x >= 1.0);
covers && self.xs.iter().zip(&self.ys).all(|(x, y)| x == y) && self.ms.iter().all(|m| *m == 1.0)
}
/// The curve at `x`. Below the first point it is the first point's y, above the last the
/// last's. NaN gives NaN.
pub fn eval(&self, x: f64) -> f64 {
if x.is_nan() {
return x;
}
let n = self.xs.len();
if x <= self.xs[0] {
return self.ys[0];
}
if x >= self.xs[n - 1] {
return self.ys[n - 1];
}
let i = match self.xs.binary_search_by(|v| v.total_cmp(&x)) {
Ok(i) => return self.ys[i],
Err(i) => i - 1,
};
hermite(self.xs[i], self.ys[i], self.ms[i], self.xs[i + 1], self.ys[i + 1], self.ms[i + 1], x)
}
/// The curve sampled at `n` evenly spaced points over `0..1` (at least 2).
pub fn to_lut(&self, n: usize) -> Lut1 {
let n = n.clamp(2, MAX_LUT);
Lut1 { v: (0..n).map(|i| self.eval(i as f64 / (n - 1) as f64) as f32).collect() }
}
/// The points, sorted by x.
pub fn points(&self) -> Vec<(f64, f64)> {
self.xs.iter().copied().zip(self.ys.iter().copied()).collect()
}
/// Each point as `[x, y, tangent]`, for code that evaluates the same spline elsewhere (a
/// GPU pass): between points `k` and `k + 1`, with `h = x₁ − x₀` and `t = (x − x₀) / h`,
/// the curve is `(2t³ − 3t² + 1) y₀ + (t³ − 2t² + t) h m₀ + (−2t³ + 3t²) y₁ + (t³ − t²) h m₁`.
pub fn knots(&self) -> impl ExactSizeIterator<Item = [f64; 3]> + '_ {
self.xs.iter().zip(&self.ys).zip(&self.ms).map(|((x, y), m)| [*x, *y, *m])
}
}
fn hermite(x0: f64, y0: f64, m0: f64, x1: f64, y1: f64, m1: f64, x: f64) -> f64 {
let h = x1 - x0;
let t = (x - x0) / h;
let (t2, t3) = (t * t, t * t * t);
(2.0 * t3 - 3.0 * t2 + 1.0) * y0 + (t3 - 2.0 * t2 + t) * h * m0 + (-2.0 * t3 + 3.0 * t2) * y1 + (t3 - t2) * h * m1
}
/// The most entries [`Lut1::from_fn`] and [`MonotoneCurve::to_lut`] build.
pub const MAX_LUT: usize = 1 << 16;
/// A 1D lookup table over `0..1` with linear interpolation. Inputs outside `0..1` clamp.
#[derive(Clone, Debug, PartialEq)]
pub struct Lut1 {
pub v: Vec<f32>,
}
impl Lut1 {
/// The identity with `n` entries (2 to [`MAX_LUT`]).
pub fn identity(n: usize) -> Lut1 {
Lut1::from_fn(n, |x| x)
}
/// `f` sampled at `n` evenly spaced points over `0..1` (2 to [`MAX_LUT`]).
pub fn from_fn(n: usize, f: impl Fn(f32) -> f32) -> Lut1 {
let n = n.clamp(2, MAX_LUT);
Lut1 { v: (0..n).map(|i| f(i as f32 / (n - 1) as f32)).collect() }
}
/// The table at `x`. `v` is public, so a table of 1 entry reads as that constant and an
/// empty one as the identity.
#[inline]
pub fn eval(&self, x: f32) -> f32 {
let x = x.clamp(0.0, 1.0);
let n = self.v.len();
if n < 2 {
return self.v.first().copied().unwrap_or(x);
}
let f = x * (n - 1) as f32;
let i = (f as usize).min(n - 2);
let t = f64::from(f - i as f32);
// Weighted in f64, so entries as far apart as ±f32::MAX do not overflow, and t = 0 and
// t = 1 give the entries exactly.
(f64::from(self.v[i]) * (1.0 - t) + f64::from(self.v[i + 1]) * t) as f32
}
/// `self ∘ inner`: `inner` applies first. An empty `inner` is the identity, so the result
/// is `self`. The result is sampled on the densest grid of at most [`MAX_LUT`] entries that
/// holds the sample points of both tables. Between two grid points it differs from
/// `self.eval(inner.eval(x))` by at most one grid step times the product of the two
/// tables' steepest slopes. When no grid of that size holds both tables' points, the result
/// uses the longer table's grid, with the same bound for that grid's step: a table whose
/// slope is near its entry count can then lose the other table's knots between two samples.
pub fn compose(&self, inner: &Lut1) -> Lut1 {
if inner.v.is_empty() {
return self.clone();
}
let on_inner = || Lut1 { v: inner.v.iter().map(|&x| self.eval(x)).collect() };
let resampled = |n: usize| Lut1::from_fn(n, |x| self.eval(inner.eval(x)));
let (a, b) = (inner.v.len() - 1, self.v.len().saturating_sub(1));
if a == 0 || b == 0 {
return on_inner();
}
let common = (a / gcd(a, b)).checked_mul(b).filter(|l| *l < MAX_LUT);
let steps = common.map(|l| (MAX_LUT - 1) / l * l);
match steps {
Some(s) if s == a => on_inner(),
Some(s) => resampled(s + 1),
None if inner.v.len() >= self.v.len() => on_inner(),
None => resampled(self.v.len()),
}
}
pub fn is_identity(&self) -> bool {
let n = self.v.len();
n >= 2 && self.v.iter().enumerate().all(|(i, &y)| (y - i as f32 / (n - 1) as f32).abs() < 1e-6)
}
}
fn gcd(mut a: usize, mut b: usize) -> usize {
while b != 0 {
(a, b) = (b, a % b);
}
a
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_identity_curve_maps_every_value_to_itself() {
let c = MonotoneCurve::identity();
assert!(c.is_identity());
for i in 0..=10 {
let x = i as f64 / 10.0;
assert!((c.eval(x) - x).abs() < 1e-12);
}
assert!(c.to_lut(256).is_identity());
assert!(!MonotoneCurve::new(&[(0.0, 0.0), (0.5, 0.6), (1.0, 1.0)]).is_identity());
// These points lie on the diagonal, but the curve clamps below 0.2 and above 0.8.
let inner = MonotoneCurve::new(&[(0.2, 0.2), (0.8, 0.8)]);
assert_eq!(inner.eval(0.0), 0.2);
assert!(!inner.is_identity());
assert!(MonotoneCurve::new(&[(-1.0, -1.0), (2.0, 2.0)]).is_identity());
}
#[test]
fn the_curve_passes_through_its_points_and_rises_with_them() {
let pts = [(0.0, 0.0), (0.25, 0.15), (0.5, 0.5), (0.75, 0.88), (1.0, 1.0)];
let c = MonotoneCurve::new(&pts);
for (x, y) in pts {
assert!((c.eval(x) - y).abs() < 1e-12);
}
let mut prev = -1.0;
for i in 0..=1000 {
let y = c.eval(i as f64 / 1000.0);
assert!(y >= prev - 1e-12);
prev = y;
}
}
/// Data that rise, then stay level: a natural cubic spline overshoots the level part, and
/// this curve stays on it.
#[test]
fn the_curve_does_not_overshoot_a_level_run() {
let c = MonotoneCurve::new(&[(0.0, 0.0), (0.4, 0.5), (0.6, 0.5), (1.0, 1.0)]);
for i in 400..=600 {
let y = c.eval(i as f64 / 1000.0);
assert!((y - 0.5).abs() < 1e-9, "{y}");
}
}
/// Steep and shallow neighbors: the unlimited average tangent overshoots, the limited one
/// keeps the segment within its end values.
#[test]
fn steep_steps_stay_monotone() {
let c = MonotoneCurve::new(&[(0.0, 0.0), (0.1, 0.0), (0.2, 1.0), (1.0, 1.0)]);
let mut prev = -1.0;
for i in 0..=1000 {
let y = c.eval(i as f64 / 1000.0);
assert!((0.0..=1.0).contains(&y) && y >= prev - 1e-12, "{i} {y}");
prev = y;
}
}
#[test]
fn the_knots_evaluate_to_the_same_curve() {
let c = MonotoneCurve::new(&[(0.0, 0.1), (0.3, 0.2), (0.7, 0.9), (1.0, 0.95)]);
let k: Vec<[f64; 3]> = c.knots().collect();
assert_eq!(k.len(), 4);
for i in 0..=100 {
let x = i as f64 / 100.0;
let seg = k.windows(2).find(|w| x >= w[0][0] && x <= w[1][0]).unwrap();
let y = hermite(seg[0][0], seg[0][1], seg[0][2], seg[1][0], seg[1][1], seg[1][2], x);
assert!((y - c.eval(x)).abs() < 1e-12, "{x}");
}
}
#[test]
fn luts_compose() {
let a = Lut1::from_fn(1024, |x| x * x);
let b = Lut1::from_fn(1024, f32::sqrt);
assert!((a.compose(&b).eval(0.3) - 0.3).abs() < 2e-3);
assert_eq!(a.compose(&Lut1 { v: vec![] }), a);
}
/// A short `inner` does not drop the outer table's points between its own.
#[test]
fn composing_with_a_short_table_keeps_the_outer_curve() {
let peak = Lut1 { v: vec![0.0, 1.0, 0.0] };
let c = peak.compose(&Lut1::identity(2));
assert_eq!(c.eval(0.5), 1.0);
assert_eq!(c.eval(0.0), 0.0);
assert_eq!(c.eval(1.0), 0.0);
assert_eq!(peak.compose(&Lut1 { v: vec![0.5] }).eval(0.2), 1.0);
// Grids that do not hold each other's points, and inner tables that cross the outer
// peak between their own points.
let cases = [
(Lut1::identity(4), peak.clone()),
(Lut1 { v: vec![0.0, 1.0, 0.0, 1.0] }, peak.clone()),
(peak.clone(), Lut1::identity(4)),
(peak.clone(), peak.clone()),
(peak.clone(), Lut1 { v: vec![0.0, 0.75] }),
(Lut1::from_fn(17, |x| (x * 9.0).sin().abs()), Lut1::from_fn(9, |x| x * x)),
];
for (outer, inner) in &cases {
let c = outer.compose(inner);
for i in 0..=3000 {
let x = i as f32 / 3000.0;
let want = outer.eval(inner.eval(x));
assert!((c.eval(x) - want).abs() < 1e-3, "{outer:?} {inner:?} {x}");
}
}
assert!((peak.compose(&Lut1 { v: vec![0.0, 0.75] }).eval(2.0 / 3.0) - 1.0).abs() < 1e-3);
// A grid beyond MAX_LUT entries falls back to the longer table's grid.
let big = Lut1::identity(MAX_LUT - 1).compose(&Lut1::identity(MAX_LUT));
assert_eq!(big.v.len(), MAX_LUT);
}
/// Entries this far apart overflow a difference taken between them.
#[test]
fn far_apart_entries_interpolate_without_overflow() {
let wide = Lut1 { v: vec![-f32::MAX, f32::MAX] };
assert_eq!(wide.eval(0.0), -f32::MAX);
assert_eq!(wide.eval(1.0), f32::MAX);
assert_eq!(wide.eval(0.5), 0.0);
assert!(wide.eval(0.25).is_finite());
let high = Lut1 { v: vec![f32::MAX, f32::MAX] };
assert_eq!(high.eval(0.3), f32::MAX);
}
#[test]
fn a_curve_saves_as_its_points_and_a_hostile_file_does_not_break_it() {
let c = MonotoneCurve::new(&[(0.0, 0.0), (0.5, 0.7), (1.0, 1.0)]);
let json = serde_json::to_string(&c).unwrap();
assert_eq!(json, "[[0.0,0.0],[0.5,0.7],[1.0,1.0]]");
assert_eq!(serde_json::from_str::<MonotoneCurve>(&json).unwrap(), c);
// A single point, unsorted points and duplicates load as a working curve.
assert!(serde_json::from_str::<MonotoneCurve>("[[0.5,0.5]]").unwrap().is_identity());
let messy: MonotoneCurve = serde_json::from_str("[[1.0,1.0],[0.0,0.0],[0.0,0.3],[0.5,0.2]]").unwrap();
assert_eq!(messy.points(), vec![(0.0, 0.0), (0.5, 0.2), (1.0, 1.0)]);
// The fields are not read from a file, so their lengths always agree.
assert!(serde_json::from_str::<MonotoneCurve>(r#"{"xs":[0.0],"ys":[],"ms":[]}"#).is_err());
// A long list keeps its first MAX_POINTS points.
let long: Vec<(f64, f64)> = (0..3000).map(|i| (f64::from(i) / 3000.0, f64::from(i) / 3000.0)).collect();
let loaded: MonotoneCurve = serde_json::from_str(&serde_json::to_string(&long).unwrap()).unwrap();
assert_eq!(loaded.points().len(), MAX_POINTS);
assert_eq!(loaded.points()[MAX_POINTS - 1], long[MAX_POINTS - 1]);
}
#[test]
fn nan_input_and_short_or_huge_tables_do_not_panic() {
let c = MonotoneCurve::new(&[(0.0, 0.0), (0.5, 0.6), (1.0, 1.0)]);
assert!(c.eval(f64::NAN).is_nan());
assert!(c.eval(-f64::NAN).is_nan());
assert_eq!(c.eval(-3.0), 0.0);
assert_eq!(c.eval(9.0), 1.0);
for n in [0, 1] {
assert_eq!(c.to_lut(n).v.len(), 2, "{n}");
assert!(Lut1::identity(n).is_identity(), "{n}");
}
assert_eq!(Lut1::from_fn(usize::MAX, |x| x).v.len(), MAX_LUT);
assert_eq!(Lut1 { v: vec![] }.eval(0.3), 0.3);
assert_eq!(Lut1 { v: vec![] }.eval(-1.0), 0.0);
assert_eq!(Lut1 { v: vec![0.7] }.eval(0.3), 0.7);
assert!(!Lut1 { v: vec![0.0] }.is_identity());
let many: Vec<(f64, f64)> = (0..5000).map(|i| (i as f64, i as f64)).collect();
assert_eq!(MonotoneCurve::new(&many).points().len(), MAX_POINTS);
let bad = MonotoneCurve::new(&[(f64::NAN, 0.0), (0.2, f64::INFINITY), (0.5, 0.5)]);
assert!(bad.is_identity());
// Differences between these would overflow to infinity and give NaN slopes.
let far = MonotoneCurve::new(&[(-1e308, -1e308), (0.5, 0.25), (1e308, 1e308)]);
assert!(far.is_identity());
let wide = MonotoneCurve::new(&[(-1e6, -1e6), (1e6, 1e6), (0.0, 0.5)]);
assert!(wide.eval(3.0).is_finite());
// A subnormal secant next to a normal one: the tangent over that secant overflows.
let flat_then_steep = MonotoneCurve::new(&[(0.0, 0.0), (0.5, 1e-310), (1.0, 1.0)]);
assert!(flat_then_steep.knots().flatten().all(f64::is_finite));
let mut prev = -1.0;
for i in 0..=1000 {
let y = flat_then_steep.eval(f64::from(i) / 1000.0);
assert!(y.is_finite() && y >= prev, "{i} {y}");
prev = y;
}
}
}
+21
View File
@@ -0,0 +1,21 @@
//! Color transforms for the Craft apps.
//!
//! - [`Mat3`], CIE [`Xy`] chromaticities and RGB spaces defined by primaries and a white point
//! ([`RgbSpace`]), with Bradford chromatic adaptation ([`bradford`]).
//! - White balance by correlated color temperature and tint ([`cct`]).
//! - OkLab and OkLCh ([`oklab`]).
//! - Monotone tone curves and 1D lookup tables ([`curve`]).
//! - PQ tone mapping with the reference EETF of Report ITU-R BT.2408 Annex 5 ([`tonemap`]).
//!
//! Frame color tags, Y'CbCr matrices and the transfer functions (sRGB, PQ, HLG) are in
//! `craft-color`; this crate builds on them. Every function that runs per pixel works on `f32`
//! without allocating, and builds for `wasm32-unknown-unknown`.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
pub mod cct;
pub mod curve;
pub mod oklab;
mod space;
pub mod tonemap;
pub use space::{BRADFORD, D50, D65, DISPLAY_P3, Mat3, REC601_525, REC601_625, REC2020, RgbSpace, SRGB, Xy, bradford, bradford_xyz};
+246
View File
@@ -0,0 +1,246 @@
//! OkLab and OkLCh, as Björn Ottosson defined them in "A perceptual color space for image
//! processing" (2020).
//!
//! [`from_linear_srgb`] and [`to_linear_srgb`] use the published linear sRGB matrices.
//! [`OkLab::for_space`] builds the conversion for any [`RgbSpace`] from the published XYZ
//! matrix, adapting the space's white to D65 first (Bradford).
use crate::{D65, Mat3, RgbSpace, bradford};
/// XYZ (D65) to approximate cone responses (the published M1).
pub const XYZ_TO_LMS: Mat3 =
Mat3([[0.8189330101, 0.3618667424, -0.1288597137], [0.0329845436, 0.9293118715, 0.0361456387], [0.0482003018, 0.2643662691, 0.6338517070]]);
/// Cube-rooted cone responses to Lab (the published M2).
pub const LMS_TO_LAB: Mat3 =
Mat3([[0.2104542553, 0.7936177850, -0.0040720468], [1.9779984951, -2.4285922050, 0.4505937099], [0.0259040371, 0.7827717662, -0.8086757660]]);
/// Linear sRGB to cone responses (published with the linear sRGB conversion).
pub const SRGB_TO_LMS: Mat3 =
Mat3([[0.4122214708, 0.5363325363, 0.0514459929], [0.2119034982, 0.6806995451, 0.1073969566], [0.0883024619, 0.2817188376, 0.6299787005]]);
/// Cone responses to linear sRGB (published with the linear sRGB conversion).
pub const LMS_TO_SRGB: Mat3 =
Mat3([[4.0767416621, -3.3077115913, 0.2309699292], [-1.2684380046, 2.6097574011, -0.3413193965], [-0.0041960863, -0.7034186147, 1.7076147010]]);
/// Lab to cube-rooted cone responses (published with the linear sRGB conversion).
pub const LAB_TO_LMS: Mat3 = Mat3([[1.0, 0.3963377774, 0.2158037573], [1.0, -0.1055613458, -0.0638541728], [1.0, -0.0894841775, -1.2914855480]]);
const fn f32s(m: &Mat3) -> [[f32; 3]; 3] {
let m = &m.0;
[
[m[0][0] as f32, m[0][1] as f32, m[0][2] as f32],
[m[1][0] as f32, m[1][1] as f32, m[1][2] as f32],
[m[2][0] as f32, m[2][1] as f32, m[2][2] as f32],
]
}
const SRGB_LMS: [[f32; 3]; 3] = f32s(&SRGB_TO_LMS);
const LMS_SRGB: [[f32; 3]; 3] = f32s(&LMS_TO_SRGB);
const LAB: [[f32; 3]; 3] = f32s(&LMS_TO_LAB);
const LAB_INV: [[f32; 3]; 3] = f32s(&LAB_TO_LMS);
#[inline]
fn mul(m: &[[f32; 3]; 3], v: [f32; 3]) -> [f32; 3] {
[
m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2],
m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2],
m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2],
]
}
/// Linear sRGB (BT.709 primaries, D65) to OkLab `[L, a, b]`.
#[inline]
pub fn from_linear_srgb(rgb: [f32; 3]) -> [f32; 3] {
mul(&LAB, mul(&SRGB_LMS, rgb).map(f32::cbrt))
}
/// OkLab to linear sRGB.
#[inline]
pub fn to_linear_srgb(lab: [f32; 3]) -> [f32; 3] {
mul(&LMS_SRGB, mul(&LAB_INV, lab).map(|v| v * v * v))
}
/// XYZ (D65, white Y = 1) to OkLab.
pub fn from_xyz(xyz: [f64; 3]) -> [f64; 3] {
LMS_TO_LAB.apply(XYZ_TO_LMS.apply(xyz).map(f64::cbrt))
}
/// The `f64` matrices [`OkLab::for_space`] starts from: linear RGB in `space` to cone responses
/// (the white adapted to D65 by Bradford), and back. `None` when the first has no inverse. Code
/// that builds its matrices once per render in `f64` uses these with [`LMS_TO_LAB`] and
/// [`LAB_TO_LMS`].
pub fn lms_matrices(space: &RgbSpace) -> Option<(Mat3, Mat3)> {
let to_lms = XYZ_TO_LMS.mul(&bradford(space.white, D65)).mul(&space.to_xyz());
to_lms.inverse().map(|from_lms| (to_lms, from_lms))
}
/// OkLab to OkLCh `[L, C, h]`, with the hue in radians from −π to π.
#[inline]
pub fn lab_to_lch(lab: [f32; 3]) -> [f32; 3] {
[lab[0], lab[1].hypot(lab[2]), lab[2].atan2(lab[1])]
}
/// OkLCh to OkLab.
#[inline]
pub fn lch_to_lab(lch: [f32; 3]) -> [f32; 3] {
let (s, c) = lch[2].sin_cos();
[lch[0], lch[1] * c, lch[1] * s]
}
/// The OkLab conversion for one RGB space, with its matrices precomputed in `f32`.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct OkLab {
to_lms: [[f32; 3]; 3],
from_lms: [[f32; 3]; 3],
}
impl OkLab {
/// The conversion for linear RGB in `space`.
pub fn for_space(space: &RgbSpace) -> OkLab {
let pair = lms_matrices(space).map(|(to_lms, from_lms)| (to_lms.to_f32(), from_lms.to_f32()));
let finite = |m: &[[f32; 3]; 3]| m.iter().flatten().all(|v| v.is_finite());
match pair {
Some((to_lms, from_lms)) if finite(&to_lms) && finite(&from_lms) => OkLab { to_lms, from_lms },
// A matrix with no inverse or with an entry beyond f32 falls back to XYZ_TO_LMS
// alone, the matrix a space gets when its primaries and its white are both rejected.
_ => OkLab { to_lms: f32s(&XYZ_TO_LMS), from_lms: XYZ_TO_LMS.inverse().unwrap_or(Mat3::IDENTITY).to_f32() },
}
}
/// The `f32` matrices, row-major: linear RGB to cone responses, and back. GPU passes that
/// convert to OkLab use these with [`LMS_TO_LAB`].
pub fn matrices(&self) -> ([[f32; 3]; 3], [[f32; 3]; 3]) {
(self.to_lms, self.from_lms)
}
/// Linear RGB to OkLab.
#[inline]
pub fn from_rgb(&self, rgb: [f32; 3]) -> [f32; 3] {
mul(&LAB, mul(&self.to_lms, rgb).map(f32::cbrt))
}
/// OkLab to linear RGB.
#[inline]
pub fn to_rgb(&self, lab: [f32; 3]) -> [f32; 3] {
mul(&self.from_lms, mul(&LAB_INV, lab).map(|v| v * v * v))
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::{D50, REC2020, SRGB, Xy};
/// The table of XYZ values and their OkLab coordinates in Ottosson's definition, rounded
/// to three decimals.
#[test]
fn xyz_matches_the_published_table() {
let table = [
([0.950, 1.000, 1.089], [1.000, 0.000, 0.000]),
([1.000, 0.000, 0.000], [0.450, 1.236, -0.019]),
([0.000, 1.000, 0.000], [0.922, -0.671, 0.263]),
([0.000, 0.000, 1.000], [0.153, -1.415, -0.449]),
];
for (xyz, want) in table {
let lab = from_xyz(xyz);
for i in 0..3 {
assert!((lab[i] - want[i]).abs() < 6e-4, "{xyz:?} -> {lab:?}");
}
}
}
/// CSS Color Module Level 4 (section 2, "These are exactly equivalent") gives #7654CD as
/// oklab(54.43237% 0.0681665 -0.1656703).
#[test]
fn an_srgb_color_matches_css_color_4() {
let rgb = [0x76, 0x54, 0xCD].map(|v: u8| craft_color::srgb_to_linear(f32::from(v) / 255.0));
let lab = from_linear_srgb(rgb);
let want = [0.5443237, 0.0681665, -0.1656703];
for i in 0..3 {
assert!((lab[i] - want[i]).abs() < 2e-4, "{lab:?}");
}
}
#[test]
fn the_srgb_matrices_and_the_space_built_from_xyz_agree() {
let srgb = OkLab::for_space(&SRGB);
for c in [[0.1, 0.5, 0.9], [1.0, 0.0, 0.0], [0.02, 0.03, 0.01], [1.0, 1.0, 1.0]] {
let a = from_linear_srgb(c);
let b = srgb.from_rgb(c);
for i in 0..3 {
assert!((a[i] - b[i]).abs() < 2e-4, "{c:?} {a:?} {b:?}");
}
}
}
#[test]
fn white_is_l1_and_grays_have_no_chroma_in_every_space() {
let d50 = crate::RgbSpace { white: D50, ..SRGB };
for space in [SRGB, REC2020, d50] {
let ok = OkLab::for_space(&space);
let w = ok.from_rgb([1.0, 1.0, 1.0]);
assert!((w[0] - 1.0).abs() < 2e-4 && w[1].abs() < 2e-4 && w[2].abs() < 2e-4, "{space:?} {w:?}");
let g = ok.from_rgb([0.18, 0.18, 0.18]);
assert!(g[1].abs() < 2e-4 && g[2].abs() < 2e-4, "{space:?} {g:?}");
}
}
#[test]
fn conversions_round_trip() {
let ok = OkLab::for_space(&REC2020);
for c in [[0.1, 0.5, 0.9], [1.0, 0.0, 0.0], [0.02, 0.03, 0.01], [2.0, 1.5, 0.3], [-0.1, 0.4, 0.2]] {
let a = to_linear_srgb(from_linear_srgb(c));
let b = ok.to_rgb(ok.from_rgb(c));
for i in 0..3 {
assert!((a[i] - c[i]).abs() < 1e-4 * c[i].abs().max(1.0), "{c:?} {a:?}");
assert!((b[i] - c[i]).abs() < 1e-4 * c[i].abs().max(1.0), "{c:?} {b:?}");
}
}
let lab = lch_to_lab(lab_to_lch([0.5, 0.1, -0.05]));
assert!((lab[1] - 0.1).abs() < 1e-6 && (lab[2] + 0.05).abs() < 1e-6);
}
#[test]
fn a_space_that_does_not_exist_does_not_produce_nan() {
let bad = crate::RgbSpace { r: Xy::new(0.3, 0.0), ..SRGB };
let ok = OkLab::for_space(&bad);
assert!(ok.from_rgb([0.5, 0.5, 0.5]).iter().all(|v| v.is_finite()));
}
#[test]
fn the_f64_matrices_match_the_published_xyz_conversion() {
let (to, from) = lms_matrices(&SRGB).unwrap();
let p = to.mul(&from);
for i in 0..3 {
for j in 0..3 {
assert!((p.0[i][j] - if i == j { 1.0 } else { 0.0 }).abs() < 1e-12, "{p:?}");
}
}
// The published linear sRGB matrix and the one built from XYZ differ by at most 3.1e-4.
for i in 0..3 {
for j in 0..3 {
assert!((to.0[i][j] - SRGB_TO_LMS.0[i][j]).abs() < 5e-4, "{to:?}");
}
}
for c in [[0.1, 0.5, 0.9], [1.0, 1.0, 1.0]] {
let lab = LMS_TO_LAB.apply(to.apply(c).map(f64::cbrt));
let f = OkLab::for_space(&SRGB).from_rgb(c.map(|v| v as f32));
for i in 0..3 {
assert!((lab[i] - f64::from(f[i])).abs() < 1e-5, "{c:?} {lab:?} {f:?}");
}
}
let bad = crate::RgbSpace { r: Xy::new(0.3, 0.0), ..SRGB };
assert!(lms_matrices(&bad).is_some_and(|(t, _)| t.0.iter().flatten().all(|v| v.is_finite())));
}
/// A white this close to y = 0 gives `f64` matrices with entries beyond `f32`.
#[test]
fn a_space_whose_matrices_overflow_f32_does_not_produce_nan() {
let far = crate::RgbSpace { white: Xy::new(0.5, 1e-40), ..SRGB };
let ok = OkLab::for_space(&far);
let (to, from) = ok.matrices();
assert!(to.iter().chain(from.iter()).flatten().all(|v| v.is_finite()), "{to:?} {from:?}");
for c in [[0.0; 3], [0.5, 0.5, 0.5], [1.0, 0.0, 0.0]] {
assert!(ok.from_rgb(c).iter().all(|v| v.is_finite()), "{c:?}");
assert!(ok.to_rgb(ok.from_rgb(c)).iter().all(|v| v.is_finite()), "{c:?}");
}
}
}
+295
View File
@@ -0,0 +1,295 @@
//! 3×3 matrices, chromaticities, RGB spaces and Bradford chromatic adaptation.
use craft_cms::math;
use craft_color::Primaries;
use serde::{Deserialize, Serialize};
/// A row-major 3×3 matrix.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
pub struct Mat3(pub [[f64; 3]; 3]);
impl Mat3 {
pub const IDENTITY: Mat3 = Mat3([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]);
pub const fn diag(a: f64, b: f64, c: f64) -> Mat3 {
Mat3([[a, 0.0, 0.0], [0.0, b, 0.0], [0.0, 0.0, c]])
}
/// `self × o`: applying the product applies `o` first ([`math::mul`]).
pub fn mul(&self, o: &Mat3) -> Mat3 {
Mat3(math::mul(&self.0, &o.0))
}
/// [`math::apply`].
pub fn apply(&self, v: [f64; 3]) -> [f64; 3] {
math::apply(&self.0, v)
}
/// [`math::det`].
pub fn determinant(&self) -> f64 {
math::det(&self.0)
}
/// The inverse, or `None` when the matrix holds a non-finite value, is singular to within
/// rounding (the determinant is at most 1e-12 times the cube of the largest entry), or has an
/// inverse with an entry beyond the range of `f64` ([`math::inverse`]).
pub fn inverse(&self) -> Option<Mat3> {
math::inverse(&self.0).map(Mat3)
}
pub fn transpose(&self) -> Mat3 {
let m = &self.0;
Mat3([[m[0][0], m[1][0], m[2][0]], [m[0][1], m[1][1], m[2][1]], [m[0][2], m[1][2], m[2][2]]])
}
/// The matrix as `f32`, row-major, for per-pixel code and GPU uniforms.
pub fn to_f32(&self) -> [[f32; 3]; 3] {
self.0.map(|r| r.map(|v| v as f32))
}
}
/// A row-major array, the form `craft_cms::math::Mat3` takes.
impl From<[[f64; 3]; 3]> for Mat3 {
fn from(m: [[f64; 3]; 3]) -> Mat3 {
Mat3(m)
}
}
impl From<Mat3> for [[f64; 3]; 3] {
fn from(m: Mat3) -> [[f64; 3]; 3] {
m.0
}
}
/// A CIE 1931 xy chromaticity.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
pub struct Xy {
pub x: f64,
pub y: f64,
}
impl Xy {
pub const fn new(x: f64, y: f64) -> Xy {
Xy { x, y }
}
/// XYZ with Y = 1, or `None` when `y` is not above 0, a coordinate is not finite, or `y` is
/// so small that X or Z overflows.
pub fn to_xyz(self) -> Option<[f64; 3]> {
if !(self.x.is_finite() && self.y.is_finite() && self.y > 0.0) {
return None;
}
let xyz = math::xy_to_xyz([self.x, self.y]);
xyz.iter().all(|v| v.is_finite()).then_some(xyz)
}
/// The chromaticity of an XYZ triple, or `None` when X + Y + Z is not above 0.
pub fn from_xyz(v: [f64; 3]) -> Option<Xy> {
let s = v[0] + v[1] + v[2];
if !(s.is_finite() && s > 0.0) {
return None;
}
Some(Xy::new(v[0] / s, v[1] / s))
}
}
/// CIE standard illuminant D65, as ITU-R BT.709 and BT.2020 give it.
pub const D65: Xy = Xy::new(0.3127, 0.3290);
/// CIE illuminant D50, the ICC profile connection space white.
pub const D50: Xy = Xy::new(0.3457, 0.3585);
/// An RGB color space: three primaries and a white point. A space read at run time (from a
/// file's primaries or a stream's mastering metadata) is built with a struct literal.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
pub struct RgbSpace {
pub r: Xy,
pub g: Xy,
pub b: Xy,
pub white: Xy,
}
/// The ITU-R BT.709 primaries, which sRGB (IEC 61966-2-1) shares.
pub const SRGB: RgbSpace = RgbSpace { r: Xy::new(0.64, 0.33), g: Xy::new(0.30, 0.60), b: Xy::new(0.15, 0.06), white: D65 };
/// ITU-R BT.601, 625-line systems.
pub const REC601_625: RgbSpace = RgbSpace { r: Xy::new(0.64, 0.33), g: Xy::new(0.29, 0.60), b: Xy::new(0.15, 0.06), white: D65 };
/// ITU-R BT.601, 525-line systems.
pub const REC601_525: RgbSpace = RgbSpace { r: Xy::new(0.630, 0.340), g: Xy::new(0.310, 0.595), b: Xy::new(0.155, 0.070), white: D65 };
/// ITU-R BT.2020 (and BT.2100).
pub const REC2020: RgbSpace = RgbSpace { r: Xy::new(0.708, 0.292), g: Xy::new(0.170, 0.797), b: Xy::new(0.131, 0.046), white: D65 };
/// The DCI-P3 primaries with a D65 white (SMPTE EG 432-1).
pub const DISPLAY_P3: RgbSpace = RgbSpace { r: Xy::new(0.680, 0.320), g: Xy::new(0.265, 0.690), b: Xy::new(0.150, 0.060), white: D65 };
impl From<Primaries> for RgbSpace {
fn from(p: Primaries) -> RgbSpace {
match p {
Primaries::Bt709 => SRGB,
Primaries::Bt601_625 => REC601_625,
Primaries::Bt601_525 => REC601_525,
Primaries::Bt2020 => REC2020,
Primaries::P3D65 => DISPLAY_P3,
}
}
}
impl RgbSpace {
/// Linear RGB in this space to XYZ, with the space's white at Y = 1 (the normalized primary
/// matrix of SMPTE RP 177). Primaries or a white that do not define a space (collinear
/// primaries, a `y` of 0, a white on a primary or on the line between two) give the identity.
pub fn to_xyz(&self) -> Mat3 {
let (Some(r), Some(g), Some(b), Some(w)) = (self.r.to_xyz(), self.g.to_xyz(), self.b.to_xyz(), self.white.to_xyz()) else {
return Mat3::IDENTITY;
};
let m = Mat3([[r[0], g[0], b[0]], [r[1], g[1], b[1]], [r[2], g[2], b[2]]]);
let Some(inv) = m.inverse() else { return Mat3::IDENTITY };
let s = inv.apply(w);
let npm = m.mul(&Mat3::diag(s[0], s[1], s[2]));
// A white that gives a primary no weight leaves a matrix with no inverse.
if npm.inverse().is_none() { Mat3::IDENTITY } else { npm }
}
/// XYZ to linear RGB in this space: the inverse of [`to_xyz`](Self::to_xyz).
pub fn from_xyz(&self) -> Mat3 {
self.to_xyz().inverse().unwrap_or(Mat3::IDENTITY)
}
/// The luminance weights of R, G and B (the Y row of [`to_xyz`](Self::to_xyz)).
pub fn luma(&self) -> [f64; 3] {
self.to_xyz().0[1]
}
/// Linear RGB in `self` to linear RGB in `dst`, Bradford-adapting between the white points.
pub fn to_space(&self, dst: &RgbSpace) -> Mat3 {
dst.from_xyz().mul(&bradford(self.white, dst.white)).mul(&self.to_xyz())
}
}
/// The Bradford cone response matrix (XYZ to sharpened cone responses).
pub const BRADFORD: Mat3 = Mat3(math::BRADFORD);
/// The Bradford chromatic adaptation matrix (XYZ to XYZ) from white `src` to white `dst`. A
/// white that [`Xy::to_xyz`] rejects gives the identity.
pub fn bradford(src: Xy, dst: Xy) -> Mat3 {
if src == dst {
return Mat3::IDENTITY;
}
match (src.to_xyz(), dst.to_xyz()) {
(Some(s), Some(d)) => bradford_xyz(s, d),
_ => Mat3::IDENTITY,
}
}
/// [`bradford`] for whites given as XYZ. A white with a cone response that is not above 0 or
/// not finite, or a pair whose response ratios overflow, gives the identity.
pub fn bradford_xyz(src: [f64; 3], dst: [f64; 3]) -> Mat3 {
math::bradford_checked(src, dst).map_or(Mat3::IDENTITY, Mat3)
}
#[cfg(test)]
mod tests {
use super::*;
fn close(a: &Mat3, b: &[[f64; 3]; 3], tol: f64) {
for i in 0..3 {
for j in 0..3 {
assert!((a.0[i][j] - b[i][j]).abs() < tol, "[{i}][{j}] {} vs {}", a.0[i][j], b[i][j]);
}
}
}
/// IEC 61966-2-1 gives the sRGB RGB to XYZ matrix to four decimals.
#[test]
fn srgb_matrix_matches_iec_61966_2_1() {
close(&SRGB.to_xyz(), &[[0.4124, 0.3576, 0.1805], [0.2126, 0.7152, 0.0722], [0.0193, 0.1192, 0.9505]], 1e-4);
}
/// ITU-R BT.2020 and BT.709 give the luminance coefficients.
#[test]
fn luminance_weights_match_bt709_and_bt2020() {
for (space, want) in [(SRGB, [0.2126, 0.7152, 0.0722]), (REC2020, [0.2627, 0.6780, 0.0593])] {
let l = space.luma();
for i in 0..3 {
assert!((l[i] - want[i]).abs() < 1e-4, "{space:?} {l:?}");
}
}
}
/// The Bradford matrix from D65 to D50 as Lindbloom's chromatic adaptation tables print it,
/// with his reference whites.
#[test]
fn bradford_d65_to_d50_matches_the_published_matrix() {
let m = bradford_xyz([0.95047, 1.0, 1.08883], [0.96422, 1.0, 0.82521]);
let want = [[1.0478112, 0.0228866, -0.0501270], [0.0295424, 0.9904844, -0.0170491], [-0.0092345, 0.0150436, 0.7521316]];
close(&m, &want, 1e-6);
}
#[test]
fn adaptation_maps_white_to_white_and_round_trips() {
let m = bradford(D65, D50);
let w = m.apply(D65.to_xyz().unwrap());
let d50 = D50.to_xyz().unwrap();
for i in 0..3 {
assert!((w[i] - d50[i]).abs() < 1e-12);
}
let back = bradford(D50, D65).mul(&m);
close(&back, &Mat3::IDENTITY.0, 1e-12);
let v = SRGB.to_space(&REC2020).apply([1.0, 1.0, 1.0]);
assert!(v.iter().all(|c| (c - 1.0).abs() < 1e-9), "{v:?}");
}
/// The BT.709 to BT.2020 conversion matrix of Report ITU-R BT.2087 (equation 2).
#[test]
fn bt709_to_bt2020_matches_bt2087() {
let want = [[0.6274, 0.3293, 0.0433], [0.0691, 0.9195, 0.0114], [0.0164, 0.0880, 0.8956]];
close(&SRGB.to_space(&REC2020), &want, 1e-4);
}
#[test]
fn primaries_tags_map_to_spaces() {
assert_eq!(RgbSpace::from(Primaries::Bt2020), REC2020);
assert_eq!(RgbSpace::from(Primaries::default()), SRGB);
}
#[test]
fn hostile_whites_and_primaries_do_not_produce_nan() {
assert_eq!(Xy::new(0.3, 0.0).to_xyz(), None);
assert_eq!(Xy::new(f64::NAN, 0.3).to_xyz(), None);
assert_eq!(Xy::new(0.3, 1e-320).to_xyz(), None);
assert_eq!(bradford(Xy::new(0.3, 1e-320), D65), Mat3::IDENTITY);
assert_eq!(Xy::from_xyz([0.0, 0.0, 0.0]), None);
assert_eq!(bradford(Xy::new(0.3, 0.0), D65), Mat3::IDENTITY);
assert_eq!(bradford(D65, Xy::new(f64::INFINITY, 0.3)), Mat3::IDENTITY);
assert_eq!(bradford_xyz([-1.0, 1.0, 1.0], [0.95, 1.0, 1.09]), Mat3::IDENTITY);
let flat = RgbSpace { r: Xy::new(0.2, 0.2), g: Xy::new(0.3, 0.3), b: Xy::new(0.4, 0.4), white: D65 };
assert_eq!(flat.to_xyz(), Mat3::IDENTITY);
assert_eq!(Mat3([[f64::NAN; 3]; 3]).inverse(), None);
// The determinant, 1e-312, has no finite reciprocal; the inverse itself is finite.
let tiny = Mat3::diag(1e-104, 1e-104, 1e-104).inverse().unwrap();
close(&tiny, &[[1e104, 0.0, 0.0], [0.0, 1e104, 0.0], [0.0, 0.0, 1e104]], 1e93);
// A determinant beyond f64 in either direction still leaves a finite inverse.
let small = Mat3::diag(1e-200, 1e-200, 1e-200).inverse().unwrap();
close(&small, &Mat3::diag(1e200, 1e200, 1e200).0, 1e186);
let large = Mat3::diag(1e110, 1e110, 1e110).inverse().unwrap();
close(&large, &Mat3::diag(1e-110, 1e-110, 1e-110).0, 1e-124);
// An inverse with entries beyond f64 is no inverse.
assert_eq!(Mat3::diag(1e-310, 1e-310, 1e-310).inverse(), None);
assert_eq!(Mat3([[0.0; 3]; 3]).inverse(), None);
assert_eq!(Mat3::diag(f64::MAX, f64::MAX, f64::MAX).inverse().map(|m| m.0[0][0]), Some(1.0 / f64::MAX));
// A white on a primary leaves two primaries with no weight: no space.
let on_red = RgbSpace { white: SRGB.r, ..SRGB };
assert_eq!(on_red.to_xyz(), Mat3::IDENTITY);
assert_eq!(on_red.from_xyz(), Mat3::IDENTITY);
// Cone responses this small give scale ratios beyond f64.
assert_eq!(bradford_xyz([1e-320; 3], D65.to_xyz().unwrap()), Mat3::IDENTITY);
}
/// A space built from primaries read at run time saves and loads, and its matrix converts
/// to and from a plain array.
#[test]
fn spaces_save_and_load() {
let read = RgbSpace { r: Xy::new(0.7, 0.29), g: Xy::new(0.16, 0.8), b: Xy::new(0.13, 0.05), white: D50 };
let json = serde_json::to_string(&read).unwrap();
assert_eq!(serde_json::from_str::<RgbSpace>(&json).unwrap(), read);
let m: [[f64; 3]; 3] = read.to_xyz().into();
assert_eq!(Mat3::from(m), read.to_xyz());
}
}
+406
View File
@@ -0,0 +1,406 @@
//! PQ tone mapping with the reference EETF of Report ITU-R BT.2408-8, Annex 5 ("Displaying
//! PQ: calculating the EETF"), which Report ITU-R BT.2390 described before it.
//!
//! The EETF works on PQ (SMPTE ST 2084) values: it keeps the range below a knee 1:1, rolls off
//! the range above it with a Hermite spline so the source peak lands on the target peak, and
//! lifts the target black with a tapered offset. [`ToneMap`] applies it to RGB by max(R, G, B),
//! the "maxRGB" option of the Annex, as a ratio, so hue and saturation are kept.
use craft_color::{REFERENCE_WHITE_NITS, pq_eotf, pq_inverse_eotf};
/// PQ code value (0..1) of `nits`.
fn pq(nits: f64) -> f64 {
f64::from(pq_inverse_eotf((nits / 10_000.0).clamp(0.0, 1.0) as f32))
}
/// Luminance in nits of the PQ value `e`.
fn nits(e: f64) -> f64 {
f64::from(pq_eotf(e.clamp(0.0, 1.0) as f32)) * 10_000.0
}
/// A luminance in nits: NaN, negative values and infinity read as 0, 0 and 10 000.
fn sane(n: f64) -> f64 {
if n.is_nan() { 0.0 } else { n.clamp(0.0, 10_000.0) }
}
/// The reference EETF from a mastering display (black `src_black`, peak `src_peak`) to a
/// target display (black `dst_black`, peak `dst_peak`), all in nits.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Eetf {
pb: f64,
span: f64,
min_lum: f64,
max_lum: f64,
ks: f64,
/// The spline's slope at the knee: 1 within the Annex's range.
slope: f64,
/// The black lift's exponent: 4 within the Annex's range.
lift: f64,
/// The E2 at which the black lift reaches 0: 1 within the Annex's range.
reach: f64,
}
impl Eetf {
/// Luminances are clamped to 0..10 000 nits. A target black below the source black adds no
/// lift. When the source range is empty the EETF passes values through.
///
/// When the target peak sits below a third of the source range in PQ, the Annex's knee
/// (KS = 1.5 maxLum − 0.5) is negative. The knee is then 0 and the spline starts with a
/// slope of 3 maxLum, the steepest that keeps it rising.
///
/// The Annex's black lift, minLum × (1 − E2)⁴, makes the output fall near black when minLum
/// is above 0.25, and lifts the peak well above the target peak. The lift here is
/// minLum × (1 − E2 / r)ᵏ with r = max(T, min(1, 2 − 4 minLum)) and k = min(4, r / minLum),
/// where T, the top of the output, is the smaller of maxLum and 1. Up to minLum 0.25 this is
/// the Annex's lift. Above it, k is the largest exponent that keeps the output rising, r moves
/// continuously from 1 down to T, and from minLum 0.5 the lift reaches 0 at the top of the
/// output. A target black above the source peak reads as the source peak.
///
/// A target peak at or below the source black would put every output at the source black
/// or above it; the source black then reads as 0. A target black above the target peak
/// reads as the target peak. A target peak that is NaN or not above 0 names no display, and
/// the EETF then passes values through.
pub fn new(src_black: f64, src_peak: f64, dst_black: f64, dst_peak: f64) -> Eetf {
let pb = pq(sane(src_black));
let pass = Eetf { pb, span: 0.0, min_lum: 0.0, max_lum: 1.0, ks: 1.0, slope: 1.0, lift: 4.0, reach: 1.0 };
if dst_peak.is_nan() || dst_peak <= 0.0 {
return pass;
}
let (dst_peak, pw) = (sane(dst_peak), pq(sane(src_peak)));
let dst_black = sane(dst_black).min(dst_peak);
if pw <= pb {
return pass;
}
let pb = if pq(dst_peak) <= pb { 0.0 } else { pb };
let span = pw - pb;
// Step 2.
let min_lum = ((pq(dst_black) - pb) / span).max(0.0);
let max_lum = ((pq(dst_peak) - pb) / span).max(0.0);
let ks = 1.5 * max_lum - 0.5;
let (ks, slope) = if ks >= 0.0 { (ks, 1.0) } else { (0.0, 3.0 * max_lum) };
// E2 ends at `top`. The output's slope at E2 = 0 is 1 − lift × minLum / reach, so the
// exponent is at most reach / minLum. Up to minLum 0.25 this gives the Annex's (1, 4); both
// change continuously above it, and reach is `top` from minLum 0.5. A target black above
// the source peak (minLum above `top`) reads as the source peak.
let top = max_lum.min(1.0);
let min_lum = min_lum.min(top);
let reach = top.max((2.0 - 4.0 * min_lum).min(1.0));
let lift = if min_lum > 0.0 { (reach / min_lum).min(4.0) } else { 4.0 };
Eetf { pb, span, min_lum, max_lum, ks, slope, lift, reach }
}
/// Whether the EETF passes every value through unchanged.
pub fn is_identity(&self) -> bool {
self.span <= 0.0 || (self.max_lum >= 1.0 && self.min_lum <= 0.0)
}
/// The EETF on a PQ value (0..1): steps 1 to 5 of the Annex. Unless the EETF is the
/// identity, values above the source peak map as the peak does.
pub fn apply_pq(&self, e: f64) -> f64 {
if self.is_identity() || e.is_nan() {
return e;
}
// Step 1.
let e1 = ((e - self.pb) / self.span).clamp(0.0, 1.0);
// Steps 3 and 4: 1:1 below the knee, the Hermite spline above it.
let e2 = if e1 < self.ks || self.max_lum >= 1.0 {
e1
} else {
let t = (e1 - self.ks) / (1.0 - self.ks);
let (t2, t3) = (t * t, t * t * t);
(2.0 * t3 - 3.0 * t2 + 1.0) * self.ks + (t3 - 2.0 * t2 + t) * (1.0 - self.ks) * self.slope + (-2.0 * t3 + 3.0 * t2) * self.max_lum
};
let e3 = if self.reach == 1.0 && self.lift == 4.0 {
e2 + self.min_lum * (1.0 - e2).powi(4)
} else {
e2 + self.min_lum * (1.0 - e2 / self.reach).max(0.0).powf(self.lift)
};
// Step 5.
e3 * self.span + self.pb
}
/// The EETF on a luminance in nits.
pub fn apply_nits(&self, n: f64) -> f64 {
nits(self.apply_pq(pq(sane(n))))
}
}
/// The BT.2408 EETF from a display of peak `src_peak` to one of peak `dst_peak` (nits), with
/// black at 0.
pub fn eetf(n: f64, src_peak: f64, dst_peak: f64) -> f64 {
Eetf::new(0.0, src_peak, 0.0, dst_peak).apply_nits(n)
}
/// Entries in [`ToneMap`]'s table.
const TABLE: usize = 4096;
/// Tone mapping of linear RGB, where 1.0 is reference white, from a source peak to a target
/// peak. It applies the EETF (black at 0) to max(R, G, B) and scales the three channels by the
/// same ratio. The ratios are tabulated on a PQ axis once, so [`apply`](Self::apply) does not
/// allocate.
#[derive(Clone, Debug, PartialEq)]
pub struct ToneMap {
src_peak: f32,
dst_peak: f32,
white: f32,
identity: bool,
/// Output nits over input nits, at PQ values `i / (TABLE − 1)`.
ratio: Vec<f32>,
}
impl ToneMap {
/// Tone mapping with reference white at `craft_color::REFERENCE_WHITE_NITS` (203 nits,
/// Report ITU-R BT.2408).
pub fn new(src_peak_nits: f64, dst_peak_nits: f64) -> ToneMap {
ToneMap::with_reference_white(src_peak_nits, dst_peak_nits, REFERENCE_WHITE_NITS)
}
/// Tone mapping where 1.0 is `white_nits`. A white that is not above 0 or not finite reads
/// as 203 nits, and one above 10 000 nits as 10 000.
pub fn with_reference_white(src_peak_nits: f64, dst_peak_nits: f64, white_nits: f64) -> ToneMap {
let (s, d) = (sane(src_peak_nits), sane(dst_peak_nits));
let white = if white_nits.is_finite() && white_nits > 0.0 { white_nits.min(10_000.0) } else { REFERENCE_WHITE_NITS };
let curve = Eetf::new(0.0, s, 0.0, d);
let identity = curve.is_identity();
let ratio = if identity {
Vec::new()
} else {
(0..TABLE)
.map(|i| {
let e = i as f64 / (TABLE - 1) as f64;
let n = nits(e);
if n <= 1e-6 { 1.0 } else { (curve.apply_nits(n) / n) as f32 }
})
.collect()
};
ToneMap { src_peak: s as f32, dst_peak: d as f32, white: white as f32, identity, ratio }
}
/// Whether [`apply`](Self::apply) returns its input (the target peak is at or above the
/// source peak).
pub fn is_identity(&self) -> bool {
self.identity
}
/// One pixel of linear RGB, 1.0 = reference white.
#[inline]
pub fn apply(&self, c: [f32; 3]) -> [f32; 3] {
if self.identity {
return c;
}
let m = c[0].max(c[1]).max(c[2]);
// NaN (all three channels NaN) and values at or below 0 pass through.
if m.is_nan() || m <= 0.0 {
return c;
}
let n = m * self.white;
if n >= self.src_peak {
// The brightest channel lands on the target peak. Dividing by m first keeps an
// infinite channel (or an n that overflows) from giving infinity times 0.
let peak = self.dst_peak / self.white;
return c.map(|v| if v >= m { peak } else { v / m * peak });
}
let k = self.lookup(pq_inverse_eotf(n / 10_000.0));
c.map(|v| v * k)
}
#[inline]
fn lookup(&self, e: f32) -> f32 {
let last = self.ratio.len().saturating_sub(1);
let p = e.clamp(0.0, 1.0) * last as f32;
let i = (p as usize).min(last.saturating_sub(1));
let (Some(a), Some(b)) = (self.ratio.get(i), self.ratio.get(i + 1)) else { return 1.0 };
a + (b - a) * (p - i as f32)
}
}
#[cfg(test)]
mod tests {
use super::*;
/// Report ITU-R BT.2408 lists 203 nits (HDR reference white) at 58 % PQ and 1000 nits at
/// 75 %; these check the PQ functions the EETF stands on.
#[test]
fn pq_reference_levels() {
assert!((pq(203.0) - 0.58).abs() < 0.005, "{}", pq(203.0));
assert!((pq(1000.0) - 0.75).abs() < 0.005, "{}", pq(1000.0));
assert!((nits(pq(100.0)) - 100.0).abs() < 0.05);
}
/// Values computed from the Annex 5 equations and the ST 2084 constants by a separate
/// implementation, 1000 nits to 100 nits.
#[test]
fn matches_an_independent_evaluation_of_the_annex() {
let curve = Eetf::new(0.0, 1000.0, 0.0, 100.0);
for (input, want) in ORACLE_1000_TO_100 {
let got = curve.apply_nits(input);
assert!((got - want).abs() <= want * 2e-4 + 1e-4, "{input} nits: {got} vs {want}");
}
let lifted = Eetf::new(0.0, 1000.0, 0.1, 100.0);
for (input, want) in ORACLE_1000_TO_100_BLACK_01 {
let got = lifted.apply_nits(input);
assert!((got - want).abs() <= want * 2e-4 + 1e-4, "{input} nits: {got} vs {want}");
}
}
const ORACLE_1000_TO_100: [(f64, f64); 9] = [
(0.0, 0.000000),
(1.0, 1.000000),
(10.0, 10.000000),
(50.0, 46.142955),
(100.0, 69.454403),
(203.0, 88.243641),
(400.0, 97.598409),
(700.0, 99.854805),
(1000.0, 100.000000),
];
const ORACLE_1000_TO_100_BLACK_01: [(f64, f64); 9] = [
(0.0, 0.100000),
(1.0, 1.608558),
(10.0, 11.080978),
(50.0, 47.142334),
(100.0, 70.309850),
(203.0, 88.992667),
(400.0, 98.298831),
(700.0, 100.543945),
(1000.0, 100.688420),
];
#[test]
fn the_knee_keeps_low_values_and_lands_the_peak_on_the_target() {
let curve = Eetf::new(0.0, 1000.0, 0.0, 100.0);
assert!((curve.apply_nits(1000.0) - 100.0).abs() < 0.05);
assert!((curve.apply_nits(5000.0) - 100.0).abs() < 0.05, "above the source peak");
// Below the knee (KS = 1.5 maxLum − 0.5) the EETF is 1:1.
let below = nits(curve.ks * pq(1000.0) * 0.99);
assert!((curve.apply_nits(below) - below).abs() < below * 1e-4, "{below}");
let mut prev = 0.0;
for i in 0..=1000 {
let out = curve.apply_pq(f64::from(i) / 1000.0 * pq(1000.0));
assert!(out >= prev - 1e-12, "monotone");
prev = out;
}
assert!(Eetf::new(0.0, 100.0, 0.0, 1000.0).is_identity());
assert_eq!(eetf(400.0, 100.0, 1000.0) as f32, nits(pq(400.0)) as f32);
}
/// 10 000 nits to 1 nit puts the target peak below a third of the source range: the curve
/// still rises from 0 to the target peak and keeps shadows apart.
#[test]
fn a_deep_reduction_keeps_rising_without_crushing_shadows() {
let curve = Eetf::new(0.0, 10_000.0, 0.0, 1.0);
let mut prev = -1.0;
for i in 0..=2000 {
let out = curve.apply_pq(f64::from(i) / 2000.0);
assert!(out > prev || i == 0, "{i}: {out} after {prev}");
assert!(out >= 0.0);
prev = out;
}
assert!((curve.apply_nits(10_000.0) - 1.0).abs() < 1e-3);
assert!(curve.apply_nits(0.01) > 0.0 && curve.apply_nits(0.01) < curve.apply_nits(0.1));
}
#[test]
fn the_black_lift_raises_black_to_the_target_black() {
let curve = Eetf::new(0.0, 1000.0, 0.1, 100.0);
assert!((curve.apply_nits(0.0) - 0.1).abs() < 1e-3, "{}", curve.apply_nits(0.0));
// The taper (1 − E2)⁴ is small but not 0 at the target peak, so the peak rises a little.
let peak = curve.apply_nits(1000.0);
assert!(peak > 100.0 && peak < 101.0, "{peak}");
}
#[test]
fn a_high_target_black_keeps_the_output_rising_and_lands_the_peak() {
let cases = [(100.0, 100.0), (50.0, 100.0), (10.0, 100.0), (1.0, 100.0), (0.1, 1000.0), (40.0, 4000.0), (2000.0, 4000.0)];
for (black, peak) in cases {
let curve = Eetf::new(0.0, 1000.0, black, peak);
// A target black above the 1000-nit source peak reads as the source peak.
let want = f64::min(black, 1000.0);
assert!((curve.apply_nits(0.0) - want).abs() < 1e-2 * want.max(1.0), "{black} {peak}: {}", curve.apply_nits(0.0));
// From minLum 0.5 the lift reaches 0 at the top of the output.
let top = curve.apply_nits(1000.0);
if curve.min_lum >= 0.5 {
assert!((top - f64::min(peak, 1000.0)).abs() < 1e-2 * peak, "{black} {peak}: {top}");
}
let mut last = curve.apply_pq(0.0);
for i in 1..=1000 {
let out = curve.apply_pq(f64::from(i) / 1000.0);
assert!(out >= last - 1e-12, "{black} {peak} at {i}: {out} < {last}");
last = out;
}
}
}
#[test]
fn the_output_changes_continuously_with_the_target_black() {
for peak in [100.0, 300.0, 4000.0] {
let at = |black: f64, n: f64| Eetf::new(0.0, 1000.0, black, peak).apply_pq(pq(n));
// Target blacks 1/20 000 of the target peak's PQ value apart.
let black = |i: u32| nits(f64::from(i) / 20_000.0 * pq(peak));
for n in [0.0, 1.0, 100.0, 1000.0] {
let mut last = at(0.0, n);
for i in 1..=20_000 {
let out = at(black(i), n);
assert!((out - last).abs() < 1e-3, "peak {peak}, input {n}, black {}: {last} to {out}", black(i));
last = out;
}
}
}
}
#[test]
fn tone_map_keeps_hue_and_maps_the_peak() {
let tm = ToneMap::new(1000.0, 203.0);
let peak = 1000.0 / 203.0;
let out = tm.apply([peak, peak * 0.5, peak * 0.25]);
assert!((out[0] - 1.0).abs() < 1e-3, "{out:?}");
assert!((out[1] / out[0] - 0.5).abs() < 1e-6 && (out[2] / out[0] - 0.25).abs() < 1e-6);
let low = tm.apply([0.02, 0.01, 0.0]);
assert!((low[0] - 0.02).abs() < 1e-4, "{low:?}");
assert_eq!(tm.apply([0.0, 0.0, 0.0]), [0.0, 0.0, 0.0]);
assert_eq!(tm.apply([-1.0, -2.0, -0.5]), [-1.0, -2.0, -0.5]);
}
/// With a target peak above the source peak nothing changes, highlights above the source
/// peak included (they are not raised to the target peak).
#[test]
fn a_brighter_target_leaves_colors_alone() {
let tm = ToneMap::new(1000.0, 4000.0);
assert!(tm.is_identity());
let hot = [1200.0 / 203.0, 0.5, 0.1];
assert_eq!(tm.apply(hot), hot);
}
#[test]
fn hostile_values_do_not_panic_or_spread() {
let tm = ToneMap::new(f64::NAN, f64::INFINITY);
assert!(tm.is_identity());
let huge = ToneMap::with_reference_white(1000.0, 100.0, 1e100);
assert!((huge.apply([1.0, 1.0, 1.0])[0] - 100.0 / 10_000.0).abs() < 1e-4, "{:?}", huge.apply([1.0, 1.0, 1.0]));
let tm = ToneMap::with_reference_white(1000.0, 100.0, -3.0);
// max() skips NaN, so the other channels are mapped by their own maximum.
assert!(tm.apply([f32::NAN, 0.5, 0.5]).iter().skip(1).all(|v| v.is_finite()));
assert_eq!(tm.apply([f32::INFINITY, 0.5, 0.0]), [100.0 / 203.0, 0.0, 0.0]);
assert_eq!(tm.apply([f32::MAX, f32::MAX, 0.0]), [100.0 / 203.0, 100.0 / 203.0, 0.0]);
// A target peak below the source black: the peak still lands on the target peak.
let dim = Eetf::new(100.0, 1000.0, 0.0, 50.0);
assert!((dim.apply_nits(1000.0) - 50.0).abs() < 0.05, "{}", dim.apply_nits(1000.0));
assert!(Eetf::new(0.0, 1000.0, 500.0, 100.0).apply_nits(0.0) <= 100.0 + 0.05);
let e = Eetf::new(500.0, 100.0, 0.0, 50.0);
assert!(e.is_identity());
assert_eq!(e.apply_pq(0.3), 0.3);
assert!(Eetf::new(0.0, 1000.0, 0.0, 100.0).apply_pq(f64::NAN).is_nan());
}
/// A target peak that is NaN, 0 or negative passes the picture through instead of turning it
/// black.
#[test]
fn a_missing_target_peak_passes_values_through() {
for peak in [f64::NAN, 0.0, -100.0, f64::NEG_INFINITY] {
let tm = ToneMap::new(1000.0, peak);
assert!(tm.is_identity(), "{peak}");
assert_eq!(tm.apply([0.8, 0.5, 0.1]), [0.8, 0.5, 0.1], "{peak}");
assert!(Eetf::new(0.0, 1000.0, 0.0, peak).is_identity(), "{peak}");
}
}
}
+16
View File
@@ -10,6 +10,12 @@ repository.workspace = true
[lints]
workspace = true
[features]
default = []
# AI agents in the open window (desktop): the ArtCraft Launcher's switch, the connection file and
# the `<id>-cli mcp` side that finds the open window. The agent settings build without it.
agents = ["dep:craft-ai-agents", "dep:craft-atomic", "dep:craft-flags", "dep:log"]
[dependencies]
serde = { workspace = true }
serde_json = { workspace = true }
@@ -18,6 +24,16 @@ serde_json = { workspace = true }
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
# The per-launch control token: 32 random bytes from the operating system (MIT OR Apache-2.0).
getrandom = "0.3"
# The launcher's app list, read in one place for the launcher, the gateway and every app (MIT OR Apache-2.0, ours).
craft-ai-agents = { workspace = true, optional = true }
craft-atomic = { workspace = true, optional = true }
craft-flags = { workspace = true, optional = true }
log = { workspace = true, optional = true }
[dev-dependencies]
proptest = { workspace = true }
tempfile = "3"
[[test]]
name = "agents"
required-features = ["agents"]
+115
View File
@@ -0,0 +1,115 @@
//! The connection file: where an app's control server listens for agents.
use std::net::{SocketAddr, TcpStream};
use std::path::{Path, PathBuf};
use std::time::Duration;
use serde::{Deserialize, Serialize};
/// The connection file in the app's settings folder, present while the app accepts agents.
pub const CONNECTION_FILE: &str = "agent-connection.json";
/// The token file the app keeps in its settings folder for agent connections.
pub const TOKEN_FILE: &str = "agent-control.token";
/// How long [`probe`] waits for a connection to be accepted.
pub const PROBE_TIMEOUT: Duration = Duration::from_millis(500);
/// The version of the [`Connection`] file format.
const CONNECTION_VERSION: u32 = 1;
/// The largest connection file read; anything bigger is not one.
const MAX_CONNECTION_BYTES: u64 = 1 << 20;
/// What an app publishes in [`CONNECTION_FILE`]: `{"version", "pid", "port", "tokenFile", "app"}`.
/// Holds no secret: the token stays in its own owner-only file.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Connection {
/// The file format's version (1).
pub version: u32,
/// The app's process id: only that process removes the file.
pub pid: u32,
/// The loopback port of the control server.
pub port: u16,
/// The file holding the token.
pub token_file: PathBuf,
/// The app's version, for diagnostics.
pub app: String,
}
impl Connection {
/// This process's connection on `port`, naming `app` (the app's version string).
pub fn new(port: u16, token_file: PathBuf, app: impl Into<String>) -> Self {
Self { version: CONNECTION_VERSION, pid: std::process::id(), port, token_file, app: app.into() }
}
/// `127.0.0.1:<port>`.
pub fn addr(&self) -> String {
format!("127.0.0.1:{}", self.port)
}
}
fn io_error(path: &Path, e: impl std::fmt::Display) -> std::io::Error {
std::io::Error::other(format!("{}: {e}", path.display()))
}
/// Publishes `c` in `dir` (made if missing), written atomically so a reader never sees half a
/// file.
pub fn write_connection(dir: &Path, c: &Connection) -> std::io::Result<()> {
std::fs::create_dir_all(dir).map_err(|e| io_error(dir, e))?;
let path = dir.join(CONNECTION_FILE);
let text = serde_json::to_string_pretty(c).map_err(|e| io_error(&path, e))?;
craft_atomic::atomic_write(&path, text.as_bytes()).map_err(|e| io_error(&path, e))
}
/// The connection published in `dir`, if any. A file of another version, with port 0, or one
/// that does not parse (invalid UTF-8 included) counts as none: the app rewrites it when it next
/// starts listening. Anything but a regular file (a FIFO would block the read) or a file over
/// 1 MiB is an error, and left alone.
pub fn read_connection(dir: &Path) -> std::io::Result<Option<Connection>> {
let path = dir.join(CONNECTION_FILE);
let meta = match std::fs::metadata(&path) {
Ok(m) => m,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(io_error(&path, e)),
};
if !meta.is_file() {
return Err(io_error(&path, "not a regular file"));
}
if meta.len() > MAX_CONNECTION_BYTES {
return Err(io_error(&path, format!("larger than {MAX_CONNECTION_BYTES} bytes")));
}
let bytes = match std::fs::read(&path) {
Ok(b) => b,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(io_error(&path, e)),
};
Ok(serde_json::from_slice::<Connection>(&bytes).ok().filter(|c| c.version == CONNECTION_VERSION && c.port != 0))
}
/// Removes the connection file in `dir` if process `pid` wrote it (another instance may have
/// published its own since). Errors are ignored: a stale file only fails [`probe`].
pub fn remove_connection(dir: &Path, pid: u32) {
if let Ok(Some(c)) = read_connection(dir)
&& c.pid == pid
{
let _ = std::fs::remove_file(dir.join(CONNECTION_FILE));
}
}
/// Removes the connection file in `dir` when nothing listens on its port any more (an app that
/// crashed or quit without removing it), or when it does not read as a connection. A live
/// instance's file is kept, and so is anything but a regular file. Errors are ignored.
pub fn remove_stale_connection(dir: &Path) {
let path = dir.join(CONNECTION_FILE);
let stale = match read_connection(dir) {
Ok(Some(c)) => !probe(c.port, PROBE_TIMEOUT),
Ok(None) => path.is_file(),
Err(_) => false,
};
if stale {
let _ = std::fs::remove_file(path);
}
}
/// Whether something accepts connections on loopback `port` within `timeout`; port 0 never does.
pub fn probe(port: u16, timeout: Duration) -> bool {
port != 0 && TcpStream::connect_timeout(&SocketAddr::from(([127, 0, 0, 1], port)), timeout).is_ok()
}
+601
View File
@@ -0,0 +1,601 @@
//! The other end of the link: where an app's `<id>-cli mcp` sends each tool call.
//!
//! [`Live::resolve`] runs before every tool call. It reads the connection file the app publishes
//! while it accepts agents ([`super::write_connection`]), so the app may start, quit or move to another port
//! while the MCP client stays connected, and the client's configuration holds no port and no
//! token:
//!
//! - An app that accepts agents: the call goes to its open window ([`Route::Window`]). The same
//! port, token and process id keep the window client the app made; any change makes a new one.
//! - No app accepts agents, and the person doesn't let agents use it ([`Consent::allowed`] off, or
//! [`AgentSettings::allow_agent_control`] off, under which the app doesn't listen either): a
//! session without a window with only the folders given to the command
//! ([`LiveConfig::read_roots`], [`LiveConfig::write_root`]), as `mcp` always worked. The app's own
//! folders are for agents the person let in.
//! - No app accepts agents, but agents are allowed: the closed-app choice decides
//! ([`LiveConfig::when_closed`], otherwise [`AgentSettings::when_app_closed`]): start the app and
//! wait until it accepts agents, a headless session with the app's agent folders (the command's
//! folders win), or an error that says what to do.
//!
//! Once headless, the session stays headless: documents don't move under the agent. Only a session
//! made with the app's agent folders ends when the person stops letting agents in; the next call
//! gets one with the command's folders. A window route is dropped as soon as no app accepts agents.
//! Lookups are
//! serialised, so concurrent calls start the app once: calls that queued while a start was under
//! way and found no window get that start's error rather than starting the app again; a call made
//! after it tries again.
//!
//! The crate has no async runtime: `resolve` blocks (file reads, a loopback probe, and while an
//! app starts, polling), so an async MCP server calls it from its blocking pool. What a window
//! client and a headless session are stays the app's ([`LiveConfig::new`]'s `connect` and
//! `headless`), and so do the tools and the transport. Errors are the tool call's result: words
//! for the agent, and through it the person, naming the app.
use std::ffi::{OsStr, OsString};
use std::fmt;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Mutex, PoisonError};
use std::time::{Duration, Instant};
use super::{AgentSettings, Connection, PROBE_TIMEOUT, WhenAppClosed, probe, read_connection};
/// Starts the desktop app; see [`launcher`].
pub type LaunchFn = Box<dyn Fn() -> Result<(), String> + Send + Sync>;
/// What the person allows now, read from the app's settings folder before every call.
pub type ConsentFn = Box<dyn Fn(&Path) -> Consent + Send + Sync>;
/// Makes the app's client for its open window.
pub type ConnectFn<W> = Box<dyn Fn(&Window) -> Result<W, String> + Send + Sync>;
/// Makes the app's headless session with these folders.
pub type HeadlessFn<H> = Box<dyn Fn(&HeadlessFolders) -> Result<H, String> + Send + Sync>;
/// How long a started app gets to accept agents. A first start can take a while (GPU shader
/// caches, a font scan), but MCP clients give a tool call about a minute.
pub const LAUNCH_TIMEOUT: Duration = Duration::from_secs(45);
/// How often a starting app's connection file is looked for.
pub const LAUNCH_POLL: Duration = Duration::from_millis(250);
/// The longest [`LiveConfig::launch_timeout`] used; a longer one is cut to this.
const MAX_LAUNCH_TIMEOUT: Duration = Duration::from_secs(600);
/// The range [`LiveConfig::poll`] is kept in.
const POLL_RANGE: (Duration, Duration) = (Duration::from_millis(1), Duration::from_secs(1));
/// The open window a call goes to: from the connection file, with the token from its token file.
#[derive(Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct Window {
/// The loopback port of the app's control server.
pub port: u16,
/// The app's process id.
pub pid: u32,
/// The control token, as its token file holds it (trimmed).
pub token: String,
}
impl Window {
/// `127.0.0.1:<port>`.
pub fn addr(&self) -> String {
format!("127.0.0.1:{}", self.port)
}
}
impl fmt::Debug for Window {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// Never the token: Debug output ends up in logs.
f.debug_struct("Window").field("port", &self.port).field("pid", &self.pid).finish_non_exhaustive()
}
}
/// Whether the person lets agents use the app now, and its agent settings.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct Consent {
/// Agents may use the app: `agents_allowed(mcp_flag(), launcher_allows("<id>"), legacy)`
/// ([`super::agents_allowed`]), with the suite's `AI-MCP` flag the ArtCraft Launcher's switch.
/// [`Live`] also requires [`AgentSettings::allow_agent_control`].
pub allowed: bool,
/// The app's agent settings (closed-app choice, folders).
pub settings: AgentSettings,
}
impl Consent {
/// `allowed` with these settings.
pub fn new(allowed: bool, settings: AgentSettings) -> Self {
Self { allowed, settings }
}
}
/// The folders a headless session may open from and save to.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct HeadlessFolders {
/// Folders files may be opened from.
pub read: Vec<PathBuf>,
/// The folder files may be saved to.
pub write: Option<PathBuf>,
}
/// Where a tool call goes: the app's window client or its headless session.
#[derive(Clone, Debug)]
pub enum Route<W, H> {
/// The open window.
Window(W),
/// A session without a window.
Headless(H),
}
/// What [`Live`] needs from the app.
#[non_exhaustive]
pub struct LiveConfig<W, H> {
/// The app's name in messages (`"PhotoCraft"`).
pub app_name: String,
/// The app's settings folder: connection file, token file and settings.
pub config_dir: PathBuf,
/// Overrides the app's closed-app choice (the CLI's `--when-closed`).
pub when_closed: Option<WhenAppClosed>,
/// Folders a headless session may open from (the CLI's read roots); while agents are allowed
/// they replace the app's read folder.
pub read_roots: Vec<PathBuf>,
/// The folder a headless session may save to (the CLI's write root); while agents are allowed
/// it replaces the app's write folder.
pub write_root: Option<PathBuf>,
/// Starts the app; `None` when this install can't ([`launcher`] found nothing to start).
pub launch: Option<LaunchFn>,
/// How long a started app gets to accept agents ([`LAUNCH_TIMEOUT`]; at most 10 minutes).
pub launch_timeout: Duration,
/// How often a starting app is looked for ([`LAUNCH_POLL`]; kept between 1 ms and 1 s).
pub poll: Duration,
consent: ConsentFn,
connect: ConnectFn<W>,
headless: HeadlessFn<H>,
}
impl<W, H> LiveConfig<W, H> {
/// The app `app_name` with its settings in `config_dir`: `consent` reads whether agents may
/// use it, `connect` makes a client for its open window, `headless` a session without one.
pub fn new(
app_name: impl Into<String>,
config_dir: PathBuf,
consent: impl Fn(&Path) -> Consent + Send + Sync + 'static,
connect: impl Fn(&Window) -> Result<W, String> + Send + Sync + 'static,
headless: impl Fn(&HeadlessFolders) -> Result<H, String> + Send + Sync + 'static,
) -> Self {
Self {
app_name: app_name.into(),
config_dir,
when_closed: None,
read_roots: Vec::new(),
write_root: None,
launch: None,
launch_timeout: LAUNCH_TIMEOUT,
poll: LAUNCH_POLL,
consent: Box::new(consent),
connect: Box::new(connect),
headless: Box::new(headless),
}
}
}
/// The port, token and process id a window client was made for: a restarted app may keep its
/// port and token, but its old socket is gone.
type WindowKey = (u16, String, u32);
/// The route the last call took.
struct Current<W, H> {
route: Route<W, H>,
/// For a window, the key its client was made for.
key: Option<WindowKey>,
/// A headless session that holds folders of the app's agent settings: it lasts only while
/// the person lets agents in.
app_folders: bool,
}
/// Resolves each tool call of one MCP session; see the module docs.
pub struct Live<W, H> {
cfg: LiveConfig<W, H>,
/// Serialises lookups, so concurrent calls start the app once; holds the last start's error.
lookup: Mutex<Option<String>>,
/// How many starts have finished, read before a call queues for `lookup`.
finished: AtomicU64,
current: Mutex<Option<Current<W, H>>>,
}
impl<W: Clone, H: Clone> Live<W, H> {
/// A session that has not resolved anything yet.
pub fn new(cfg: LiveConfig<W, H>) -> Self {
Self { cfg, lookup: Mutex::new(None), finished: AtomicU64::new(0), current: Mutex::new(None) }
}
/// The route the last [`Self::resolve`] chose, if any.
pub fn current(&self) -> Option<Route<W, H>> {
self.current.lock().unwrap_or_else(PoisonError::into_inner).as_ref().map(|c| c.route.clone())
}
fn set(&self, route: Route<W, H>, key: Option<WindowKey>, app_folders: bool) -> Route<W, H> {
*self.current.lock().unwrap_or_else(PoisonError::into_inner) = Some(Current { route: route.clone(), key, app_folders });
route
}
/// The headless session to keep using, if any: one made with the app's folders only while
/// agents are still `allowed`. A route that may not be kept is dropped.
fn sticky_headless(&self, allowed: bool) -> Option<Route<W, H>> {
let mut current = self.current.lock().unwrap_or_else(PoisonError::into_inner);
match current.as_ref() {
Some(c) if matches!(c.route, Route::Headless(_)) && (allowed || !c.app_folders) => Some(c.route.clone()),
Some(c) if matches!(c.route, Route::Headless(_)) => {
*current = None;
None
}
_ => None,
}
}
/// Forgets a window route: no app accepts agents any more, so its client is for a socket
/// that is gone.
fn drop_window(&self) {
let mut current = self.current.lock().unwrap_or_else(PoisonError::into_inner);
if current.as_ref().is_some_and(|c| matches!(c.route, Route::Window(_))) {
*current = None;
}
}
/// Where the next tool call goes. Blocks; see the module docs. The error is the tool call's
/// result.
pub fn resolve(&self) -> Result<Route<W, H>, String> {
let queued_at = self.finished.load(Ordering::Acquire);
let mut last_failure = self.lookup.lock().unwrap_or_else(PoisonError::into_inner);
let consent = (self.cfg.consent)(&self.cfg.config_dir);
// Allow Agent Control off refuses agents, as the app does: it doesn't listen then.
let allowed = consent.allowed && consent.settings.allow_agent_control;
if let Some(route) = self.sticky_headless(allowed) {
return Ok(route);
}
if let Some(window) = self.find_app()? {
return self.use_window(window);
}
self.drop_window();
let app = &self.cfg.app_name;
if !allowed {
let folders = HeadlessFolders { read: self.cfg.read_roots.clone(), write: self.cfg.write_root.clone() };
return self.headless(&folders, false, &format!("{app} can't use the automation roots"));
}
match self.cfg.when_closed.unwrap_or(consent.settings.when_app_closed) {
WhenAppClosed::Error => Err(format!("{app} isn't running: open it, then try again.")),
WhenAppClosed::Headless => {
let app_read = self.cfg.read_roots.is_empty() && consent.settings.read_folder().is_some();
let app_write = self.cfg.write_root.is_none() && consent.settings.write_folder().is_some();
let read =
if self.cfg.read_roots.is_empty() { consent.settings.read_folder().into_iter().collect() } else { self.cfg.read_roots.clone() };
let write = self.cfg.write_root.clone().or_else(|| consent.settings.write_folder());
let why = format!("{app} isn't running and its agent folders can't be used");
self.headless(&HeadlessFolders { read, write }, app_read || app_write, &why)
}
WhenAppClosed::Launch => {
// A start finished while this call waited and the app still isn't there: its answer
// is this call's too, rather than a second start of an app that may be opening.
if self.finished.load(Ordering::Acquire) != queued_at
&& let Some(failure) = last_failure.as_ref()
{
return Err(failure.clone());
}
let started = self.launch_and_wait();
*last_failure = started.as_ref().err().cloned();
self.finished.fetch_add(1, Ordering::AcqRel);
started
}
}
}
/// A headless session with `folders` from now on; `app_folders` when some of them are the
/// app's agent folders. `why` leads its error.
fn headless(&self, folders: &HeadlessFolders, app_folders: bool, why: &str) -> Result<Route<W, H>, String> {
let session = (self.cfg.headless)(folders).map_err(|e| format!("{why}: {e}"))?;
Ok(self.set(Route::Headless(session), None, app_folders))
}
/// Starts the app and waits until it accepts agents, at most the launch timeout.
fn launch_and_wait(&self) -> Result<Route<W, H>, String> {
let app = &self.cfg.app_name;
let Some(launch) = &self.cfg.launch else {
return Err(format!("{app} isn't running, and this install can't start it from here: open {app}, then try again."));
};
launch().map_err(|e| format!("couldn't start {app}: {e}"))?;
let timeout = self.cfg.launch_timeout.min(MAX_LAUNCH_TIMEOUT);
let started = Instant::now();
let deadline = started.checked_add(timeout).unwrap_or(started);
let poll = self.cfg.poll.clamp(POLL_RANGE.0, POLL_RANGE.1);
loop {
std::thread::sleep(poll);
if let Some(window) = self.find_app()? {
return self.use_window(window);
}
if Instant::now() >= deadline {
return Err(format!(
"{app} didn't accept agents within {} s of starting. If it's still opening, try again in a moment; otherwise check that AI agents are on in ArtCraft Launcher › Settings › AI agents.",
timeout.as_secs()
));
}
}
}
/// The client for `window`: the one made for the same port, token and process, or a new one.
fn use_window(&self, window: Window) -> Result<Route<W, H>, String> {
let key: WindowKey = (window.port, window.token.clone(), window.pid);
{
let current = self.current.lock().unwrap_or_else(PoisonError::into_inner);
if let Some(c) = current.as_ref()
&& c.key.as_ref() == Some(&key)
{
return Ok(c.route.clone());
}
}
let client = (self.cfg.connect)(&window).map_err(|e| format!("couldn't reach {}'s window: {e}", self.cfg.app_name))?;
Ok(self.set(Route::Window(client), Some(key), false))
}
/// The app accepting agents now: `None` when there is no connection file, or one left by an
/// app that crashed (nothing listens on its port).
fn find_app(&self) -> Result<Option<Window>, String> {
find_window(&self.cfg.config_dir, &self.cfg.app_name)
}
}
/// The window accepting agents with its settings in `dir`, with the token from its token file;
/// `None` when no app accepts agents there. `app_name` names the app in errors.
pub fn find_window(dir: &Path, app_name: &str) -> Result<Option<Window>, String> {
let Some(c): Option<Connection> = read_connection(dir).map_err(|e| e.to_string())? else { return Ok(None) };
if !probe(c.port, PROBE_TIMEOUT) {
return Ok(None);
}
let token = read_token(&c.token_file).map_err(|e| format!("{app_name}'s agent token: {e}"))?;
Ok(Some(Window { port: c.port, pid: c.pid, token }))
}
/// The largest token file read; a token is far shorter.
const MAX_TOKEN_FILE: u64 = 4096;
/// The token in the token file at `path`, trimmed and otherwise as written: the app's server
/// compares it exactly ([`crate::auth::tokens_match`]). The file must be a regular file of at most
/// [`MAX_TOKEN_FILE`] bytes holding one token (no spaces or control characters in it), and on Unix
/// readable by its owner only: a token others could read is refused rather than used.
fn read_token(path: &Path) -> Result<String, String> {
use std::io::Read;
let shown = |e: &dyn fmt::Display| format!("{}: {e}", path.display());
// Before opening: opening a FIFO for reading blocks until something writes to it.
if !std::fs::metadata(path).map_err(|e| shown(&e))?.is_file() {
return Err(shown(&"not a regular file"));
}
let file = std::fs::File::open(path).map_err(|e| shown(&e))?;
let meta = file.metadata().map_err(|e| shown(&e))?;
if !meta.is_file() {
return Err(shown(&"not a regular file"));
}
#[cfg(unix)]
{
use std::os::unix::fs::MetadataExt;
if meta.mode() & 0o077 != 0 {
return Err(shown(&format!("readable by group or others (mode {:o}); restrict it to its owner", meta.mode() & 0o777)));
}
}
let mut text = String::new();
file.take(MAX_TOKEN_FILE + 1).read_to_string(&mut text).map_err(|e| shown(&e))?;
if text.len() as u64 > MAX_TOKEN_FILE {
return Err(shown(&format!("larger than {MAX_TOKEN_FILE} bytes")));
}
let token = text.trim();
if token.is_empty() || token.chars().any(|c| c.is_whitespace() || c.is_control()) {
return Err(shown(&"not a control token"));
}
Ok(token.to_owned())
}
/// How to start the desktop app `exe` (its file name without `.exe`) that ships beside the CLI at
/// `cli`: detached and with no standard streams, since the CLI's carry the MCP protocol and the
/// app must outlive the MCP client. `None` where this install can't start it: inside a Flatpak,
/// or with no app beside the CLI.
pub fn launcher(cli: &Path, exe: &str) -> Option<LaunchFn> {
use std::process::{Command, Stdio};
let env = |name: &str| std::env::var_os(name).filter(|v| !v.is_empty());
// Both sides resolved, so a mount reached through a symlink (`$TMPDIR`) still matches.
let resolved = |p: &Path| std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf());
let install = Install {
platform: Platform::current(),
flatpak: env("FLATPAK_ID").is_some(),
appimage: env("APPIMAGE"),
appdir: env("APPDIR").map(|d| resolved(Path::new(&d)).into_os_string()),
system_root: env("SystemRoot"),
};
let (program, args) = launch_command(&resolved(cli), exe, &install, &|p| p.is_file())?;
let mut command = Command::new(program);
command.args(args);
let command = Mutex::new(command);
Some(Box::new(move || {
let mut c = command.lock().unwrap_or_else(PoisonError::into_inner);
c.stdin(Stdio::null()).stdout(Stdio::null()).stderr(Stdio::null());
detach(&mut c);
let child = c.spawn().map_err(|e| e.to_string())?;
reap(child);
Ok(())
}))
}
/// Waits for `child` on a thread of its own, so a start helper that exits (`open`, Explorer) or an
/// app that quits before the CLI does is reaped rather than left a zombie until the MCP client
/// ends; the app keeps running on its own either way. Without a thread the child is dropped, as
/// before.
fn reap(mut child: std::process::Child) {
let _ = std::thread::Builder::new().name("app-start-reaper".into()).spawn(move || {
let _ = child.wait();
});
}
/// What [`launch_command`] needs to know about the install, from the environment.
#[derive(Clone, Debug, Default)]
struct Install {
platform: Platform,
/// Inside a Flatpak (`FLATPAK_ID`).
flatpak: bool,
/// The AppImage the running image set (`APPIMAGE`).
appimage: Option<OsString>,
/// That image's mount point (`APPDIR`).
appdir: Option<OsString>,
/// `%SystemRoot%` (Windows).
system_root: Option<OsString>,
}
/// The platform [`launch_command`] plans for.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
enum Platform {
Windows,
MacOs,
#[default]
Other,
}
impl Platform {
/// The platform this build runs on.
fn current() -> Self {
if cfg!(windows) {
Self::Windows
} else if cfg!(target_os = "macos") {
Self::MacOs
} else {
Self::Other
}
}
}
/// The program and arguments that start the app; see [`launcher`].
fn launch_command(cli: &Path, exe: &str, install: &Install, is_file: &dyn Fn(&Path) -> bool) -> Option<(PathBuf, Vec<OsString>)> {
let platform = install.platform;
if install.flatpak {
return None;
}
// Only when this CLI runs from that image's mount: a process started from another AppImage
// (an MCP client packaged as one) inherits its `APPIMAGE` too.
if let (Some(image), Some(mount)) = (&install.appimage, &install.appdir)
&& cli.starts_with(mount)
{
// The AppImage's mount point goes away with the CLI; the image itself stays.
return Some((PathBuf::from(image), Vec::new()));
}
let dir = cli.parent()?;
if platform == Platform::MacOs
&& dir.ends_with("Contents/MacOS")
&& let Some(bundle) = dir.parent().and_then(Path::parent)
{
// A macOS app bundle: LaunchServices starts (or brings forward) the app.
return Some((PathBuf::from("/usr/bin/open"), vec![OsString::from("-a"), bundle.as_os_str().to_os_string()]));
}
let app = dir.join(if platform == Platform::Windows { format!("{exe}.exe") } else { exe.to_owned() });
if !is_file(&app) {
return None;
}
Some(if platform == Platform::Windows { windows_launch(&app, install.system_root.as_deref()) } else { (app, Vec::new()) })
}
/// How Windows starts the app at `app`: through Explorer, as a double-click would. The app is then
/// no child of the CLI, so it outlives the MCP client ending the CLI's process tree (Claude Code
/// does on Windows), and it runs outside the container of a Microsoft Store client (Claude
/// Desktop): there, new files under `%APPDATA%` land in the client's package, where the app
/// started from the Start menu would never see them. Explorer reads a comma as a separator, so
/// such a path is started directly. (`%WINDIR%` can be empty under a Store client, hence
/// `%SystemRoot%`.)
fn windows_launch(app: &Path, system_root: Option<&OsStr>) -> (PathBuf, Vec<OsString>) {
if app.to_string_lossy().contains(',') {
return (app.to_path_buf(), Vec::new());
}
let root = system_root.filter(|r| !r.is_empty()).map_or_else(|| PathBuf::from(r"C:\Windows"), PathBuf::from);
(root.join("explorer.exe"), vec![app.as_os_str().to_os_string()])
}
/// Keeps the app running when the MCP client stops the CLI (and its process group).
fn detach(c: &mut std::process::Command) {
#[cfg(unix)]
{
use std::os::unix::process::CommandExt;
c.process_group(0);
}
#[cfg(windows)]
{
use std::os::windows::process::CommandExt;
const DETACHED_PROCESS: u32 = 0x0000_0008;
const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
c.creation_flags(DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP);
}
#[cfg(not(any(unix, windows)))]
let _ = c;
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
fn plan(
cli: &str,
platform: Platform,
flatpak: bool,
appimage: Option<&str>,
root: Option<&str>,
exists: bool,
) -> Option<(PathBuf, Vec<OsString>)> {
// An AppImage's mount is where its CLI runs from.
let appdir = appimage.map(|_| OsString::from("/tmp/.mount"));
let install = Install { platform, flatpak, appimage: appimage.map(OsString::from), appdir, system_root: root.map(OsString::from) };
launch_command(Path::new(cli), "photocraft", &install, &|_| exists)
}
#[test]
fn windows_starts_the_app_through_explorer() {
let app = Path::new(r"C:\Program Files\PhotoCraft\photocraft.exe");
let (program, args) = windows_launch(app, Some(OsStr::new(r"D:\Win")));
assert_eq!(program, Path::new(r"D:\Win").join("explorer.exe"));
assert_eq!(args, [app.as_os_str()]);
// No usable %SystemRoot%: the default Windows folder.
let default = Path::new(r"C:\Windows").join("explorer.exe");
assert_eq!(windows_launch(app, Some(OsStr::new(""))).0, default);
assert_eq!(windows_launch(app, None).0, default);
// Explorer would split this path at the comma.
let comma = Path::new(r"C:\Apps, tools\photocraft.exe");
assert_eq!(windows_launch(comma, None), (comma.to_path_buf(), Vec::new()));
}
#[test]
fn the_launch_command_fits_the_install() {
// Flatpak: the sandbox can't start the app.
assert_eq!(plan("/app/bin/photocraft-cli", Platform::Other, true, Some("/x.AppImage"), None, true), None);
// An AppImage starts its image, not the mount point the CLI runs from.
assert_eq!(
plan("/tmp/.mount/usr/bin/photocraft-cli", Platform::Other, false, Some("/home/a/P.AppImage"), None, false),
Some((PathBuf::from("/home/a/P.AppImage"), Vec::new()))
);
// Another AppImage's variables (an MCP client packaged as one): the app beside the CLI.
let client = plan("/opt/pc/photocraft-cli", Platform::Other, false, Some("/home/a/Client.AppImage"), None, true);
assert_eq!(client, Some((PathBuf::from("/opt/pc/photocraft"), Vec::new())));
let no_mount = Install { appimage: Some("/home/a/P.AppImage".into()), ..Install::default() };
assert_eq!(
launch_command(Path::new("/tmp/.mount/usr/bin/photocraft-cli"), "photocraft", &no_mount, &|_| false),
None,
"APPIMAGE without APPDIR"
);
// A macOS bundle opens through LaunchServices.
let (program, args) = plan("/Applications/PhotoCraft.app/Contents/MacOS/photocraft-cli", Platform::MacOs, false, None, None, false).unwrap();
assert_eq!(program, Path::new("/usr/bin/open"));
assert_eq!(args, [OsString::from("-a"), OsString::from("/Applications/PhotoCraft.app")]);
// Beside the CLI, by the app's file name.
assert_eq!(plan("/opt/pc/photocraft-cli", Platform::Other, false, None, None, true), Some((PathBuf::from("/opt/pc/photocraft"), Vec::new())));
let (program, args) = plan(r"C:\PC\photocraft-cli.exe", Platform::Windows, false, None, Some(r"C:\Win"), true).unwrap();
assert_eq!(program, Path::new(r"C:\Win").join("explorer.exe"));
// The app beside the CLI (on a non-Windows host the backslashes are no separators).
assert_eq!(args, [Path::new(r"C:\PC\photocraft-cli.exe").parent().unwrap().join("photocraft.exe").into_os_string()]);
// No app beside the CLI: nothing to start.
assert_eq!(plan("/opt/pc/photocraft-cli", Platform::Other, false, None, None, false), None);
assert_eq!(plan("photocraft-cli", Platform::Other, false, None, None, true).map(|p| p.0), Some(PathBuf::from("photocraft")));
}
#[test]
fn a_window_never_shows_its_token() {
let w = Window { port: 7, pid: 9, token: "ab".repeat(32) };
assert!(!format!("{w:?}").contains("abab"));
assert_eq!(w.addr(), "127.0.0.1:7");
}
}
+78
View File
@@ -0,0 +1,78 @@
//! AI agents in the open window, with no UI toolkit: whether the person lets agents use the app,
//! how the app tells its own `<id>-cli mcp` where it listens, and where that CLI sends each tool
//! call.
//!
//! One switch serves every Craft app: the ArtCraft Launcher's *Settings › AI agents › Let AI agents
//! use Craft apps*, which writes the launcher's app list (`craft_ai_agents`). With the suite's
//! `AI-MCP` flag on, an app lets agents in when that list names it ([`AgentSwitch`]); without the
//! flag, the app's own earlier consent decides ([`agents_allowed`]). Apps have no agents switch of
//! their own.
//!
//! While agents may connect, the app serves its control channel on loopback with a token
//! ([`crate::server`], [`crate::auth`], or its own) and publishes where in its settings folder
//! ([`CONNECTION_FILE`]): the port, its process id and the token file. The app's `<id>-cli mcp`
//! reads that file before every tool call ([`Live`]), so an MCP client's configuration never holds
//! a port or a token. The file holds no secret. A crashed app can leave it behind; nothing then
//! listens on its port ([`probe`]), and the app's next launch removes it
//! ([`remove_stale_connection`]). An app that quits removes its own ([`remove_connection`]).
//!
//! | Part | Names | Builds |
//! |---|---|---|
//! | Settings | [`AgentSettings`], [`WhenAppClosed`], [`agents_allowed`], [`folder`] | every target |
//! | The launcher's switch | [`AgentSwitch`], [`mcp_flag`], [`launcher_allows`], [`POLL`] | desktop, feature `agents` |
//! | The connection file | [`Connection`], [`write_connection`], [`read_connection`], [`remove_connection`], [`remove_stale_connection`], [`probe`] | desktop, feature `agents` |
//! | The CLI's side | [`Live`], [`LiveConfig`], [`Route`], [`Window`], [`Consent`], [`HeadlessFolders`], [`find_window`], [`launcher`] | desktop, feature `agents` |
//!
//! The same formats as `craft_automation::agents` on the shared UI library's branch (`next`),
//! which adds the egui link host and the Agents page of Preferences.
//!
//! # Adding an app
//!
//! The app (its id is the one in the ArtCraft Launcher's catalog, `"gridcraft"`):
//!
//! 1. At start, [`remove_stale_connection`] in its settings folder, then
//! `AgentSwitch::watch("gridcraft", wake)`, where `wake` asks the UI for a frame.
//! 2. Agents may connect while `settings.allow_agent_control && switch.allows(legacy)`
//! ([`AgentSettings::allow_agent_control`], [`AgentSwitch::allows`]); check it again when the
//! launcher's switch wakes the app and when the person changes the setting. When it turns true,
//! listen on loopback with a token, the token in an owner-only file
//! ([`crate::auth::App::write_token_file`]), and [`write_connection`] with [`Connection::new`];
//! when it turns false, and when the app quits, stop listening and [`remove_connection`] with
//! the app's process id. No restart, no agents switch of its own. There is one connection file
//! per settings folder: an app that runs more than one process on one folder lets only one of
//! them accept agents.
//!
//! Its `gridcraft-cli mcp`:
//!
//! 1. A [`LiveConfig`] with the app's settings folder; `consent` reads its saved
//! [`AgentSettings`] and answers `agents_allowed(mcp_flag(), launcher_allows("gridcraft"), legacy)`
//! ([`agents_allowed`], [`mcp_flag`], [`launcher_allows`]); `connect` makes the app's client for a
//! [`Window`] (its address and token); `headless` makes its session without a window for
//! [`HeadlessFolders`]. [`launcher`] starts the app beside the CLI.
//! 2. Before every tool call, [`Live::resolve`] (from a blocking thread in an async server), then
//! the call goes to the [`Route`] it returns. `--headless` skips [`Live`] altogether.
// The links above name items of the `agents` feature; without it they have nothing to point at,
// and the docs of the settings alone still build.
#![cfg_attr(not(all(feature = "agents", not(target_arch = "wasm32"))), allow(rustdoc::broken_intra_doc_links))]
mod settings;
pub use settings::{AgentSettings, WhenAppClosed, agents_allowed, folder};
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
mod connection;
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
mod live;
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
mod switch;
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
pub use connection::{
CONNECTION_FILE, Connection, PROBE_TIMEOUT, TOKEN_FILE, probe, read_connection, remove_connection, remove_stale_connection, write_connection,
};
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
pub use live::{
ConnectFn, Consent, ConsentFn, HeadlessFn, HeadlessFolders, LAUNCH_POLL, LAUNCH_TIMEOUT, LaunchFn, Live, LiveConfig, Route, Window, find_window,
launcher,
};
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
pub use switch::{AgentSwitch, POLL, launcher_allows, mcp_flag};
+124
View File
@@ -0,0 +1,124 @@
//! The agent settings an app saves in its preferences, and who decides that agents may connect.
use std::path::PathBuf;
use serde::{Deserialize, Serialize};
/// The agent settings of an app's Preferences (its `integrations` section in PhotoCraft). Saved in
/// camelCase: `allowAgentControl`, `controlPort`, `readRoot`, `writeRoot`, `whenAppClosed`.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
#[non_exhaustive]
pub struct AgentSettings {
/// Off refuses every control server, `--control` included.
pub allow_agent_control: bool,
/// The loopback port agents connect to; 0 is any free port, published in the connection file.
pub control_port: u32,
/// The folder agents may open from; empty is none. Applied at once while agents are connected.
pub read_root: String,
/// The folder agents may save to; empty is none. Applied at once while agents are connected.
pub write_root: String,
/// What the app's `<id>-cli mcp` does while agents may use the app but it is closed.
pub when_app_closed: WhenAppClosed,
}
impl Default for AgentSettings {
fn default() -> Self {
Self {
allow_agent_control: true,
control_port: 0,
read_root: String::new(),
write_root: String::new(),
when_app_closed: WhenAppClosed::Launch,
}
}
}
impl AgentSettings {
/// [`Self::read_root`] as a path ([`folder`]).
pub fn read_folder(&self) -> Option<PathBuf> {
folder(&self.read_root)
}
/// [`Self::write_root`] as a path ([`folder`]).
pub fn write_folder(&self) -> Option<PathBuf> {
folder(&self.write_root)
}
}
/// A folder setting as a path, trimmed; empty or blank is `None`.
pub fn folder(pref: &str) -> Option<PathBuf> {
let pref = pref.trim();
(!pref.is_empty()).then(|| PathBuf::from(pref))
}
/// What an app's `<id>-cli mcp` does when an agent calls a tool while the app is closed.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum WhenAppClosed {
/// Open the app and wait for it.
#[default]
Launch,
/// Run the tool without a window.
Headless,
/// Answer with an error that asks to open the app.
Error,
}
impl WhenAppClosed {
/// The saved names, in [`Self::ALL`] order.
pub const NAMES: &'static [&'static str] = &["launch", "headless", "error"];
/// Every choice, in the order a menu lists them.
pub const ALL: [Self; 3] = [Self::Launch, Self::Headless, Self::Error];
/// The saved name.
pub fn name(self) -> &'static str {
match self {
Self::Launch => "launch",
Self::Headless => "headless",
Self::Error => "error",
}
}
/// The choice a saved name means; `None` for any other text.
pub fn parse(name: &str) -> Option<Self> {
Self::ALL.into_iter().find(|c| c.name() == name)
}
}
/// Whether agents may use the open window. With the suite's `AI-MCP` flag only the launcher's
/// switch decides: one switch for every Craft app, none in the app. Without the flag the app's own
/// earlier consent decides (`legacy`; PhotoCraft's is a Control Port saved before the switch).
/// Allow Agent Control off still refuses agents either way ([`AgentSettings::allow_agent_control`]).
pub fn agents_allowed(mcp_flag: bool, launcher: bool, legacy: bool) -> bool {
if mcp_flag { launcher } else { legacy }
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
// The saved names read back as the same choice, and nothing else reads as one.
#[test]
fn when_app_closed_names_round_trip() {
for choice in WhenAppClosed::ALL {
assert_eq!(WhenAppClosed::parse(choice.name()), Some(choice));
assert_eq!(serde_json::to_value(choice).unwrap(), serde_json::json!(choice.name()));
}
assert_eq!(WhenAppClosed::NAMES, WhenAppClosed::ALL.map(WhenAppClosed::name));
assert_eq!(WhenAppClosed::parse("Launch"), None);
let settings: AgentSettings = serde_json::from_str(r#"{"whenAppClosed": "headless", "controlPort": 7878}"#).unwrap();
assert_eq!((settings.when_app_closed, settings.control_port, settings.allow_agent_control), (WhenAppClosed::Headless, 7878, true));
}
// A folder setting is trimmed; empty or blank means no folder.
#[test]
fn folder_preferences_are_trimmed() {
assert_eq!(folder(""), None);
assert_eq!(folder(" "), None);
assert_eq!(folder(" /work/project "), Some(PathBuf::from("/work/project")));
let settings = AgentSettings { read_root: " /in ".into(), ..AgentSettings::default() };
assert_eq!((settings.read_folder(), settings.write_folder()), (Some(PathBuf::from("/in")), None));
}
}
+94
View File
@@ -0,0 +1,94 @@
//! The ArtCraft Launcher's switch for one app, behind the suite's `AI-MCP` flag.
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Weak};
use std::time::Duration;
use super::agents_allowed;
/// How often [`AgentSwitch::watch`] reads the launcher's app list.
pub const POLL: Duration = Duration::from_secs(2);
/// The suite's `AI-MCP` flag (`ArtCraft/flags.toml` or `CRAFT_FLAGS`). Reads the flags file;
/// what could not be read is logged.
pub fn mcp_flag() -> bool {
let flags = craft_flags::load();
for problem in &flags.problems {
log::warn!("flags: {problem}");
}
flags.enabled(&craft_flags::AI_MCP)
}
/// The launcher's switch (Settings › AI agents › *Let AI agents use Craft apps*) lets agents use
/// the app `app_id`: the `AI-MCP` flag is on and the launcher's app list names the app. Reads two
/// small files; ask from a timer or a command, not every frame ([`AgentSwitch`] does that).
pub fn launcher_allows(app_id: &str) -> bool {
mcp_flag() && craft_ai_agents::allowed(app_id)
}
/// The launcher's switch for one app, watched on a thread so a frame can ask without touching the
/// disk. The `AI-MCP` flag is read once, at [`Self::watch`]; the launcher's list every [`POLL`].
/// Clones share one watch; the thread ends after the last clone is dropped.
#[derive(Clone, Debug)]
pub struct AgentSwitch {
mcp_flag: bool,
on: Arc<AtomicBool>,
}
impl AgentSwitch {
/// Watches the launcher's list for `app_id`; a change logs `agents on/off` and calls `wake` (the
/// app asks for a frame there).
/// Without the `AI-MCP` flag nothing is watched: the launcher's list means nothing then.
pub fn watch(app_id: &'static str, wake: impl Fn() + Send + 'static) -> Self {
let flag = mcp_flag();
if !flag {
return Self::fixed(false, false);
}
Self::watch_with(flag, move || craft_ai_agents::allowed(app_id), POLL, wake)
}
/// A switch that never changes: tests, the web, an app without agents.
pub fn fixed(mcp_flag: bool, launcher: bool) -> Self {
Self { mcp_flag, on: Arc::new(AtomicBool::new(launcher)) }
}
/// [`Self::watch`] with the flag given, `probe` asked once now and then every `poll`.
#[doc(hidden)]
pub fn watch_with(mcp_flag: bool, probe: impl Fn() -> bool + Send + 'static, poll: Duration, wake: impl Fn() + Send + 'static) -> Self {
let on = Arc::new(AtomicBool::new(probe()));
let seen: Weak<AtomicBool> = Arc::downgrade(&on);
let started = std::thread::Builder::new().name("launcher-agents".into()).spawn(move || {
loop {
std::thread::sleep(poll);
let now = probe();
let Some(seen) = seen.upgrade() else { return };
if seen.swap(now, Ordering::Relaxed) != now {
log::info!("ArtCraft Launcher: agents {}", if now { "on" } else { "off" });
wake();
}
}
});
// Without a thread a later "off" in the launcher would never be seen: agents stay out.
if let Err(e) = started {
log::warn!("couldn't watch the ArtCraft Launcher's agents switch, so agents stay off: {e}");
on.store(false, Ordering::Relaxed);
}
Self { mcp_flag, on }
}
/// The `AI-MCP` flag as it was when the watch started.
pub fn mcp_flag(&self) -> bool {
self.mcp_flag
}
/// Whether the launcher's list named the app at the last poll.
pub fn launcher(&self) -> bool {
self.on.load(Ordering::Relaxed)
}
/// Whether agents may use the open window ([`agents_allowed`]); `legacy` is the app's own
/// earlier consent, which counts only without the flag.
pub fn allows(&self, legacy: bool) -> bool {
agents_allowed(self.mcp_flag, self.launcher(), legacy)
}
}
+4 -1
View File
@@ -2,12 +2,15 @@
//! files ([`auth`]), the loopback server that admits a connection by the token and hands each
//! request to the window ([`server`]), the client that talks to it ([`client`]), the request the
//! window answers ([`ControlRequest`]), the document watch subscribed connections wait on
//! ([`DocumentWatch`]), and what a request still running does when it finishes ([`Effect`]). It
//! ([`DocumentWatch`]), what a request still running does when it finishes ([`Effect`]), and AI
//! agents in the open window behind the ArtCraft Launcher's switch ([`agents`]: its settings on
//! every target, the switch, the connection file and the CLI's side with feature `agents`). It
//! needs no UI toolkit; the window's own requests over egui (`ui.screenshot`, `ui.resize`) are
//! `craft-control-egui`.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
pub mod agents;
pub mod auth;
mod cancel;
#[cfg(not(target_arch = "wasm32"))]
+572
View File
@@ -0,0 +1,572 @@
//! AI agents in the open window: the launcher's switch, the connection file, and where an app's
//! `<id>-cli mcp` sends each tool call.
// Unwrapping, expecting and panicking on failure is fine in tests, unlike in shipped code.
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use std::net::TcpListener;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
use craft_control::agents::{
AgentSettings, AgentSwitch, CONNECTION_FILE, Connection, Consent, HeadlessFolders, Live, LiveConfig, Route, TOKEN_FILE, WhenAppClosed, Window,
agents_allowed, find_window, read_connection, remove_connection, remove_stale_connection, write_connection,
};
fn temp_dir(tag: &str) -> tempfile::TempDir {
tempfile::Builder::new().prefix(&format!("craft-agents-{tag}-")).tempdir().expect("a temp dir")
}
/// Waits up to five seconds for `done`.
fn wait_for(mut done: impl FnMut() -> bool) -> bool {
let started = Instant::now();
while !done() {
if started.elapsed() > Duration::from_secs(5) {
return false;
}
std::thread::sleep(Duration::from_millis(5));
}
true
}
const TOKEN: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
/// Writes `text` as an owner-only token file, as an app's own token writer does.
fn write_token(path: &Path, text: &str) {
std::fs::write(path, text).unwrap();
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600)).unwrap();
}
}
/// An app accepting agents in `dir`: a listener on a free loopback port, its token file and its
/// connection file. Dropping the listener leaves the file behind, as a crashed app would.
fn publish(dir: &Path) -> (TcpListener, Connection) {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
write_token(&dir.join(TOKEN_FILE), &format!("{}\n", TOKEN.to_ascii_uppercase()));
let c = Connection::new(listener.local_addr().unwrap().port(), dir.join(TOKEN_FILE), "Test 1.0");
write_connection(dir, &c).unwrap();
(listener, c)
}
// ---- The launcher's switch ----------------------------------------------------------------------
/// With the `AI-MCP` flag only the launcher's switch decides; without it the app's earlier consent.
#[test]
fn with_the_flag_only_the_launchers_switch_lets_agents_in() {
assert!(agents_allowed(false, false, true), "without the flag, the app's earlier consent");
assert!(!agents_allowed(false, true, false), "the launcher's list means nothing without the flag");
assert!(agents_allowed(true, true, false));
assert!(!agents_allowed(true, false, true), "no second switch in the app");
assert!(AgentSwitch::fixed(true, true).allows(false));
assert!(!AgentSwitch::fixed(false, true).allows(false));
}
/// The switch follows the launcher's list within a poll, wakes the app once per change rather than
/// once per poll, and its thread ends once the last clone is dropped.
#[test]
fn the_switch_wakes_once_per_change() {
let launcher = Arc::new(AtomicBool::new(false));
let probes = Arc::new(AtomicUsize::new(0));
let wakes = Arc::new(AtomicUsize::new(0));
// Held by the watch thread through its probe: gone once the thread has ended.
let alive = Arc::new(());
let probe = {
let (launcher, probes, alive) = (launcher.clone(), probes.clone(), alive.clone());
move || {
let _ = &alive;
probes.fetch_add(1, Ordering::Relaxed);
launcher.load(Ordering::Relaxed)
}
};
let wake = {
let wakes = wakes.clone();
move || {
wakes.fetch_add(1, Ordering::Relaxed);
}
};
let switch = AgentSwitch::watch_with(true, probe, Duration::from_millis(5), wake);
let clone = switch.clone();
assert!(!switch.launcher());
launcher.store(true, Ordering::Relaxed);
assert!(wait_for(|| clone.launcher()), "the switch follows the launcher");
assert!(switch.allows(false));
let polled = probes.load(Ordering::Relaxed);
assert!(wait_for(|| probes.load(Ordering::Relaxed) > polled + 10));
launcher.store(false, Ordering::Relaxed);
assert!(wait_for(|| !switch.launcher()));
assert!(wait_for(|| wakes.load(Ordering::Relaxed) == 2));
assert_eq!(wakes.load(Ordering::Relaxed), 2, "one wake per change, not per poll");
drop(switch);
drop(clone);
assert!(wait_for(|| Arc::strong_count(&alive) == 1), "the watch ended with the last switch");
let after_end = probes.load(Ordering::Relaxed);
std::thread::sleep(Duration::from_millis(20));
assert_eq!(probes.load(Ordering::Relaxed), after_end, "nothing probes after the watch ended");
}
// ---- The connection file ------------------------------------------------------------------------
/// A published connection reads back in its documented shape, and only the process that wrote it
/// removes it.
#[test]
fn a_published_connection_reads_back_and_only_its_writer_removes_it() {
let dir = temp_dir("conn");
let dir = dir.path();
assert_eq!(read_connection(dir).unwrap(), None, "no file");
let c = Connection::new(7878, dir.join(TOKEN_FILE), "MyApp 1.2.3");
write_connection(dir, &c).unwrap();
assert_eq!(read_connection(dir).unwrap(), Some(c.clone()));
assert_eq!(c.addr(), "127.0.0.1:7878");
let v: serde_json::Value = serde_json::from_str(&std::fs::read_to_string(dir.join(CONNECTION_FILE)).unwrap()).unwrap();
let mut keys: Vec<_> = v.as_object().unwrap().keys().cloned().collect();
keys.sort();
assert_eq!(keys, ["app", "pid", "port", "tokenFile", "version"]);
assert_eq!((v["version"].as_u64(), v["port"].as_u64(), v["app"].as_str()), (Some(1), Some(7878), Some("MyApp 1.2.3")));
remove_connection(dir, c.pid.wrapping_add(1));
assert!(dir.join(CONNECTION_FILE).is_file(), "another process's file stays");
remove_connection(dir, c.pid);
assert!(!dir.join(CONNECTION_FILE).exists());
}
/// A damaged, foreign or port-0 file reads as none; a directory in its place is an error and is
/// left alone; a file nobody listens on is removed as stale and a live one kept.
#[test]
fn a_damaged_foreign_or_stale_connection_file_counts_as_none() {
let dir = temp_dir("bad-conn");
let dir = dir.path();
for text in [
&b""[..],
b"{not json",
b"[]",
br#"{"version":2,"pid":1,"port":7878,"tokenFile":"t","app":"x"}"#,
br#"{"version":1,"pid":1,"port":0,"tokenFile":"t","app":"x"}"#,
b"\xff\xfe not utf-8",
] {
std::fs::write(dir.join(CONNECTION_FILE), text).unwrap();
assert_eq!(read_connection(dir).unwrap(), None, "{}", String::from_utf8_lossy(text));
remove_stale_connection(dir);
assert!(!dir.join(CONNECTION_FILE).exists(), "an unreadable file is not a connection");
}
std::fs::create_dir(dir.join(CONNECTION_FILE)).unwrap();
assert!(read_connection(dir).is_err());
remove_stale_connection(dir);
assert!(dir.join(CONNECTION_FILE).is_dir(), "anything but a regular file is left alone");
std::fs::remove_dir(dir.join(CONNECTION_FILE)).unwrap();
let live = TcpListener::bind("127.0.0.1:0").unwrap();
let live_port = live.local_addr().unwrap().port();
write_connection(dir, &Connection { pid: 1, ..Connection::new(live_port, dir.join(TOKEN_FILE), "x") }).unwrap();
remove_stale_connection(dir);
assert!(dir.join(CONNECTION_FILE).is_file(), "something listens on {live_port}");
drop(live);
let closed = TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port();
write_connection(dir, &Connection { pid: 1, ..Connection::new(closed, dir.join(TOKEN_FILE), "x") }).unwrap();
remove_stale_connection(dir);
assert!(!dir.join(CONNECTION_FILE).exists(), "nothing listens on {closed}");
}
// ---- The CLI's side -----------------------------------------------------------------------------
/// What the stand-in app made: a window client (its window) or a headless session (its folders),
/// with counts of each.
#[derive(Default)]
struct Made {
connects: AtomicUsize,
sessions: AtomicUsize,
}
type TestLive = Live<Window, HeadlessFolders>;
fn config(dir: &Path, consent: Consent, made: &Arc<Made>) -> LiveConfig<Window, HeadlessFolders> {
let (a, b) = (made.clone(), made.clone());
let mut cfg = LiveConfig::new(
"Test",
dir.to_path_buf(),
move |_: &Path| consent.clone(),
move |w: &Window| {
a.connects.fetch_add(1, Ordering::Relaxed);
Ok(w.clone())
},
move |f: &HeadlessFolders| {
b.sessions.fetch_add(1, Ordering::Relaxed);
Ok(f.clone())
},
);
cfg.poll = Duration::from_millis(5);
cfg
}
fn settings(when: WhenAppClosed, read: &str, write: &str) -> AgentSettings {
let mut s = AgentSettings::default();
s.when_app_closed = when;
s.read_root = read.into();
s.write_root = write.into();
s
}
fn allowed(when: WhenAppClosed) -> Consent {
Consent::new(true, settings(when, "/app-in", "/app-out"))
}
fn headless_folders(route: Result<Route<Window, HeadlessFolders>, String>) -> HeadlessFolders {
match route {
Ok(Route::Headless(f)) => f,
Ok(Route::Window(w)) => panic!("expected headless, got the window {w:?}"),
Err(e) => panic!("expected headless, got the error {e}"),
}
}
fn window(route: Result<Route<Window, HeadlessFolders>, String>) -> Window {
match route {
Ok(Route::Window(w)) => w,
Ok(Route::Headless(f)) => panic!("expected the window, went headless with {f:?}"),
Err(e) => panic!("expected the window, got the error {e}"),
}
}
fn paths(p: &[&str]) -> Vec<PathBuf> {
p.iter().map(PathBuf::from).collect()
}
/// An app accepting agents takes the call; the same port, token and process keep the client, a
/// restarted app (another process on the same port and token) gets a new one.
#[test]
fn an_open_app_takes_the_call_and_keeps_its_client_until_it_restarts() {
let dir = temp_dir("window");
let (_listener, c) = publish(dir.path());
let made = Arc::new(Made::default());
// Even without consent: an app publishes its connection only while it accepts agents.
let live = TestLive::new(config(dir.path(), Consent::default(), &made));
let w = window(live.resolve());
assert_eq!(
(w.port, w.pid, w.token.as_str(), w.addr()),
(c.port, c.pid, TOKEN.to_ascii_uppercase().as_str(), c.addr()),
"the token is trimmed, otherwise as written"
);
window(live.resolve());
assert_eq!(made.connects.load(Ordering::Relaxed), 1, "the same window keeps its client");
assert!(matches!(live.current(), Some(Route::Window(_))));
write_connection(dir.path(), &Connection { pid: c.pid.wrapping_add(1), ..c.clone() }).unwrap();
assert_eq!(window(live.resolve()).pid, c.pid.wrapping_add(1));
assert_eq!(made.connects.load(Ordering::Relaxed), 2, "a restarted app gets a new client");
assert_eq!(made.sessions.load(Ordering::Relaxed), 0);
}
/// No app accepts agents and the person doesn't let them use it: headless with only the command's
/// folders, never the app's.
#[test]
fn without_consent_a_closed_app_runs_headless_with_the_commands_folders_only() {
let dir = temp_dir("no-consent");
let made = Arc::new(Made::default());
let consent = Consent::new(false, settings(WhenAppClosed::Launch, "/app-in", "/app-out"));
let live = TestLive::new(config(dir.path(), consent.clone(), &made));
assert_eq!(headless_folders(live.resolve()), HeadlessFolders::default(), "no folders given, none used");
let mut cfg = config(dir.path(), consent, &made);
cfg.read_roots = paths(&["/cli-in"]);
cfg.write_root = Some(PathBuf::from("/cli-out"));
let f = headless_folders(TestLive::new(cfg).resolve());
assert_eq!((f.read, f.write), (paths(&["/cli-in"]), Some(PathBuf::from("/cli-out"))));
}
/// Agents allowed, app closed, "headless": the app's agent folders, each replaced by the command's.
#[test]
fn allowed_and_closed_runs_headless_with_the_apps_folders_unless_the_command_gives_its_own() {
let dir = temp_dir("headless");
let made = Arc::new(Made::default());
let f = headless_folders(TestLive::new(config(dir.path(), allowed(WhenAppClosed::Headless), &made)).resolve());
assert_eq!((f.read, f.write), (paths(&["/app-in"]), Some(PathBuf::from("/app-out"))));
let mut cfg = config(dir.path(), allowed(WhenAppClosed::Headless), &made);
cfg.read_roots = paths(&["/cli-a", "/cli-b"]);
let f = headless_folders(TestLive::new(cfg).resolve());
assert_eq!((f.read, f.write), (paths(&["/cli-a", "/cli-b"]), Some(PathBuf::from("/app-out"))));
let mut cfg = config(dir.path(), allowed(WhenAppClosed::Headless), &made);
cfg.write_root = Some(PathBuf::from("/cli-out"));
let f = headless_folders(TestLive::new(cfg).resolve());
assert_eq!((f.read, f.write), (paths(&["/app-in"]), Some(PathBuf::from("/cli-out"))));
}
/// Agents allowed, app closed, "error": the call fails with words that name the app; the command's
/// choice wins over the app's.
#[test]
fn the_closed_app_choice_decides_and_the_command_overrides_it() {
let dir = temp_dir("error");
let made = Arc::new(Made::default());
let err = TestLive::new(config(dir.path(), allowed(WhenAppClosed::Error), &made)).resolve().err().unwrap();
assert_eq!(err, "Test isn't running: open it, then try again.");
let mut cfg = config(dir.path(), allowed(WhenAppClosed::Error), &made);
cfg.when_closed = Some(WhenAppClosed::Headless);
headless_folders(TestLive::new(cfg).resolve());
let mut cfg = config(dir.path(), allowed(WhenAppClosed::Headless), &made);
cfg.when_closed = Some(WhenAppClosed::Error);
assert!(TestLive::new(cfg).resolve().is_err());
}
/// Once headless, the session stays headless even when the app starts, so documents don't move
/// under the agent.
#[test]
fn a_headless_session_stays_headless() {
let dir = temp_dir("sticky");
let made = Arc::new(Made::default());
let live = TestLive::new(config(dir.path(), Consent::default(), &made));
headless_folders(live.resolve());
let _app = publish(dir.path());
headless_folders(live.resolve());
assert_eq!((made.sessions.load(Ordering::Relaxed), made.connects.load(Ordering::Relaxed)), (1, 0), "one session, no window");
}
/// A connection file left by an app that crashed counts as a closed app.
#[test]
fn a_crashed_apps_connection_file_counts_as_closed() {
let dir = temp_dir("crashed");
drop(publish(dir.path()).0);
let made = Arc::new(Made::default());
headless_folders(TestLive::new(config(dir.path(), Consent::default(), &made)).resolve());
assert_eq!(find_window(dir.path(), "Test").unwrap(), None);
}
/// A token file that isn't a token, is too big, is missing, isn't a regular file or (on Unix)
/// others can read fails the call and names the app; nothing is sent to the window.
#[test]
fn a_bad_token_file_fails_the_call() {
let dir = temp_dir("token");
let (_listener, _c) = publish(dir.path());
let made = Arc::new(Made::default());
for bad in ["", " \n", "not a token", &"a".repeat(5000)] {
write_token(&dir.path().join(TOKEN_FILE), bad);
let err = TestLive::new(config(dir.path(), Consent::default(), &made)).resolve().err().unwrap();
assert!(err.starts_with("Test's agent token: "), "{err}");
}
// Any token the app's server accepts is passed on: upper case, dashes.
write_token(&dir.path().join(TOKEN_FILE), "AB12-cd34-EF56-0000-1111-2222-3333-4444");
assert_eq!(find_window(dir.path(), "Test").unwrap().unwrap().token, "AB12-cd34-EF56-0000-1111-2222-3333-4444");
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
let token = dir.path().join(TOKEN_FILE);
write_token(&token, TOKEN);
std::fs::set_permissions(&token, std::fs::Permissions::from_mode(0o644)).unwrap();
let err = find_window(dir.path(), "Test").err().unwrap();
assert!(err.contains("readable by group or others"), "{err}");
// A FIFO would block a plain open until something writes to it.
std::fs::remove_file(&token).unwrap();
assert!(std::process::Command::new("mkfifo").arg(&token).status().unwrap().success());
let err = find_window(dir.path(), "Test").err().unwrap();
assert!(err.contains("not a regular file"), "{err}");
}
std::fs::remove_file(dir.path().join(TOKEN_FILE)).unwrap();
assert!(find_window(dir.path(), "Test").is_err());
assert_eq!(made.connects.load(Ordering::Relaxed), 0);
}
/// The app's own errors reach the agent with what was being done.
#[test]
fn the_apps_errors_reach_the_agent() {
let dir = temp_dir("app-errors");
let consent = Consent::default();
let cfg: LiveConfig<Window, HeadlessFolders> = LiveConfig::new(
"Test",
dir.path().to_path_buf(),
move |_: &Path| consent.clone(),
|w: &Window| Ok(w.clone()),
|_: &HeadlessFolders| Err("no such folder".into()),
);
assert_eq!(TestLive::new(cfg).resolve().err().unwrap(), "Test can't use the automation roots: no such folder");
let (_listener, _c) = publish(dir.path());
let cfg: LiveConfig<Window, HeadlessFolders> = LiveConfig::new(
"Test",
dir.path().to_path_buf(),
|_: &Path| Consent::default(),
|_: &Window| Err("refused".into()),
|f: &HeadlessFolders| Ok(f.clone()),
);
let live = TestLive::new(cfg);
assert_eq!(live.resolve().err().unwrap(), "couldn't reach Test's window: refused");
assert!(live.current().is_none(), "a failed connect leaves no route");
}
/// "Launch" without a way to start the app, a start that fails, and an app that never accepts
/// agents each end with words that say what to do.
#[test]
fn a_launch_that_cannot_happen_or_never_finishes_says_what_to_do() {
let dir = temp_dir("launch-fails");
let made = Arc::new(Made::default());
let err = TestLive::new(config(dir.path(), allowed(WhenAppClosed::Launch), &made)).resolve().err().unwrap();
assert_eq!(err, "Test isn't running, and this install can't start it from here: open Test, then try again.");
let mut cfg = config(dir.path(), allowed(WhenAppClosed::Launch), &made);
cfg.launch = Some(Box::new(|| Err("boom".into())));
assert_eq!(TestLive::new(cfg).resolve().err().unwrap(), "couldn't start Test: boom");
let mut cfg = config(dir.path(), allowed(WhenAppClosed::Launch), &made);
cfg.launch = Some(Box::new(|| Ok(())));
cfg.launch_timeout = Duration::from_millis(40);
let err = TestLive::new(cfg).resolve().err().unwrap();
assert!(err.starts_with("Test didn't accept agents within 0 s of starting."), "{err}");
}
/// "Launch" starts the app once, also for calls that arrive together, and the calls go to its
/// window once it accepts agents.
#[test]
fn a_started_app_takes_the_call_and_concurrent_calls_start_it_once() {
let dir = temp_dir("launch");
let made = Arc::new(Made::default());
let launches = Arc::new(AtomicUsize::new(0));
let app: Arc<Mutex<Option<TcpListener>>> = Arc::new(Mutex::new(None));
let mut cfg = config(dir.path(), allowed(WhenAppClosed::Launch), &made);
let (d, n, slot) = (dir.path().to_path_buf(), launches.clone(), app.clone());
cfg.launch = Some(Box::new(move || {
n.fetch_add(1, Ordering::Relaxed);
let (d, slot) = (d.clone(), slot.clone());
// The app takes a moment before it accepts agents.
std::thread::spawn(move || {
std::thread::sleep(Duration::from_millis(60));
*slot.lock().unwrap() = Some(publish(&d).0);
});
Ok(())
}));
let live = Arc::new(TestLive::new(cfg));
let calls: Vec<_> = (0..4)
.map(|_| {
let live = live.clone();
std::thread::spawn(move || window(live.resolve()))
})
.collect();
let ports: Vec<u16> = calls.into_iter().map(|c| c.join().unwrap().port).collect();
assert_eq!(launches.load(Ordering::Relaxed), 1, "one start for every call");
assert!(ports.windows(2).all(|p| p[0] == p[1]), "{ports:?}");
assert_eq!(made.connects.load(Ordering::Relaxed), 1);
}
/// Calls that queued while a start was under way get its error when the app still isn't there,
/// rather than starting it again; a call made afterwards tries again.
#[test]
fn calls_queued_behind_a_failed_start_share_its_error() {
let dir = temp_dir("launch-shared");
let made = Arc::new(Made::default());
let launches = Arc::new(AtomicUsize::new(0));
let mut cfg = config(dir.path(), allowed(WhenAppClosed::Launch), &made);
let entered = Arc::new(AtomicUsize::new(0));
let (n, e) = (launches.clone(), entered.clone());
// The app is started but never accepts agents within the timeout. The start waits until every
// call is under way and then a while longer, so a call that hasn't reached its lookup by the
// time the start ends is very unlikely (there is no hook between the two).
cfg.launch = Some(Box::new(move || {
n.fetch_add(1, Ordering::Relaxed);
assert!(wait_for(|| e.load(Ordering::Relaxed) == 4), "every call starts");
std::thread::sleep(Duration::from_millis(250));
Ok(())
}));
cfg.launch_timeout = Duration::from_millis(150);
let live = Arc::new(TestLive::new(cfg));
let calls: Vec<_> = (0..4)
.map(|_| {
let (live, entered) = (live.clone(), entered.clone());
std::thread::spawn(move || {
entered.fetch_add(1, Ordering::Relaxed);
live.resolve()
})
})
.collect();
let answers: Vec<_> = calls.into_iter().map(|c| c.join().unwrap()).collect();
assert_eq!(launches.load(Ordering::Relaxed), 1, "one start for the calls that came together");
for answer in &answers {
let err = answer.as_ref().err().unwrap();
assert!(err.starts_with("Test didn't accept agents within"), "{err}");
}
assert!(live.resolve().is_err());
assert_eq!(launches.load(Ordering::Relaxed), 2, "a later call starts the app again");
}
/// Allow Agent Control off refuses agents on the CLI's side too, as the app does by not
/// listening: no start, and only the command's folders.
#[test]
fn allow_agent_control_off_counts_as_not_allowed() {
let dir = temp_dir("aac-off");
let made = Arc::new(Made::default());
let mut s = settings(WhenAppClosed::Launch, "/app-in", "/app-out");
s.allow_agent_control = false;
let mut cfg = config(dir.path(), Consent::new(true, s), &made);
cfg.launch = Some(Box::new(|| panic!("nothing may start the app")));
cfg.read_roots = paths(&["/cli-in"]);
let f = headless_folders(TestLive::new(cfg).resolve());
assert_eq!((f.read, f.write), (paths(&["/cli-in"]), None));
}
/// A window route is dropped once no app accepts agents, so a dead client isn't kept or handed
/// back.
#[test]
fn a_window_that_went_away_is_forgotten() {
let dir = temp_dir("gone");
let made = Arc::new(Made::default());
let live = TestLive::new(config(dir.path(), allowed(WhenAppClosed::Error), &made));
let (listener, c) = publish(dir.path());
window(live.resolve());
drop(listener);
remove_connection(dir.path(), c.pid);
assert!(live.resolve().is_err(), "the app is closed and the choice is an error");
assert!(live.current().is_none(), "the dead window is gone");
}
/// A headless session with the app's agent folders ends when the person stops letting agents in;
/// one with only the command's folders stays.
#[test]
fn a_headless_session_with_the_apps_folders_ends_with_consent() {
let dir = temp_dir("revoke");
let made = Arc::new(Made::default());
let on = Arc::new(AtomicBool::new(true));
let gate = on.clone();
let (b, c) = (made.clone(), made.clone());
let cfg: LiveConfig<Window, HeadlessFolders> = LiveConfig::new(
"Test",
dir.path().to_path_buf(),
move |_: &Path| Consent::new(gate.load(Ordering::Relaxed), settings(WhenAppClosed::Headless, "/app-in", "/app-out")),
move |w: &Window| {
b.connects.fetch_add(1, Ordering::Relaxed);
Ok(w.clone())
},
move |f: &HeadlessFolders| {
c.sessions.fetch_add(1, Ordering::Relaxed);
Ok(f.clone())
},
);
let live = TestLive::new(cfg);
assert_eq!(headless_folders(live.resolve()).read, paths(&["/app-in"]));
on.store(false, Ordering::Relaxed);
assert_eq!(headless_folders(live.resolve()), HeadlessFolders::default(), "the app's folders went with the consent");
on.store(true, Ordering::Relaxed);
assert_eq!(headless_folders(live.resolve()), HeadlessFolders::default(), "a session without the app's folders stays");
assert_eq!(made.sessions.load(Ordering::Relaxed), 2);
}
/// A huge launch timeout or poll is cut down rather than overflowing the deadline or blocking.
#[test]
fn a_huge_launch_timeout_or_poll_neither_panics_nor_hangs() {
let dir = temp_dir("huge");
let made = Arc::new(Made::default());
let mut cfg = config(dir.path(), allowed(WhenAppClosed::Launch), &made);
let (d, app) = (dir.path().to_path_buf(), Arc::new(Mutex::new(None)));
let slot = app.clone();
cfg.launch = Some(Box::new(move || {
*slot.lock().unwrap() = Some(publish(&d).0);
Ok(())
}));
cfg.launch_timeout = Duration::MAX;
cfg.poll = Duration::MAX;
let started = Instant::now();
window(TestLive::new(cfg).resolve());
assert!(started.elapsed() < Duration::from_secs(5), "{:?}", started.elapsed());
}
+31
View File
@@ -204,6 +204,15 @@ craft-pcap = { workspace = true, optional = true }
craft-sourcemap = { workspace = true, optional = true }
craft-wasm = { workspace = true, optional = true }
craft-xfdf = { workspace = true, optional = true }
craft-color-transform = { workspace = true, optional = true }
craft-develop = { workspace = true, optional = true }
craft-develop-model = { workspace = true, optional = true }
craft-dex = { workspace = true, optional = true }
craft-esign = { workspace = true, optional = true }
craft-evm = { workspace = true, optional = true }
craft-geom = { workspace = true, optional = true }
craft-suite-account = { workspace = true, optional = true }
craft-xfa = { workspace = true, optional = true }
[features]
ui = [
@@ -324,6 +333,7 @@ cloud-local = ["dep:craft-cloud-local"]
cloud-ui = ["dep:craft-cloud-ui"]
cloud-ui-cloud = ["cloud-ui", "craft-cloud-ui/cloud"]
cloud-ui-esign = ["cloud-ui", "craft-cloud-ui/esign"]
cloud-ui-share = ["cloud-ui", "craft-cloud-ui/share"]
cms = ["dep:craft-cms"]
@@ -332,9 +342,12 @@ codepage = ["dep:craft-codepage"]
color = ["dep:craft-color"]
color-transform = ["dep:craft-color-transform"]
color-ui = ["dep:craft-color-ui", "keymap", "settings", "window", "platform"]
control = ["dep:craft-control"]
control-agents = ["control", "craft-control/agents"]
control-protocol = ["dep:craft-control-protocol"]
@@ -353,6 +366,12 @@ deckcraft-format = ["dep:craft-deckcraft-format"]
designcraft-format = ["dep:craft-designcraft-format"]
develop = ["dep:craft-develop"]
develop-model = ["dep:craft-develop-model"]
dex = ["dep:craft-dex"]
dialogs = ["dep:craft-dialogs"] # native only: rfd's folder picker and file paths
doc = ["dep:craft-doc"]
@@ -386,6 +405,10 @@ eps-paths = ["eps", "craft-eps/paths"]
epub = ["dep:craft-epub"]
esign = ["dep:craft-esign"]
evm = ["dep:craft-evm"]
ews = ["dep:craft-ews"]
exr = ["dep:craft-exr"]
@@ -443,6 +466,8 @@ gainmap = ["dep:craft-gainmap"]
gcode = ["dep:craft-gcode"]
geom = ["dep:craft-geom"]
gif = ["dep:craft-gif"]
gif-frames = ["gif", "craft-gif/frames"]
@@ -476,6 +501,7 @@ image-codecs-avif = ["image-codecs", "craft-image-codecs/avif"]
image-codecs-avif-decode = ["image-codecs", "craft-image-codecs/avif-decode"]
image-codecs-corpus = ["image-codecs", "craft-image-codecs/corpus"]
image-codecs-heif = ["image-codecs", "craft-image-codecs/heif"]
image-codecs-jxl = ["image-codecs", "craft-image-codecs/jxl"]
image-codecs-sgi = ["image-codecs", "craft-image-codecs/sgi"]
image-codecs-sunraster = ["image-codecs", "craft-image-codecs/sunraster"]
image-codecs-threads = ["image-codecs", "craft-image-codecs/threads"]
@@ -719,6 +745,8 @@ stencilcraft-format = ["dep:craft-stencilcraft-format"]
stream-codecs = ["dep:craft-stream-codecs"]
suite-account = ["dep:craft-suite-account"]
svg = ["dep:craft-svg"]
svg-draw = ["svg", "craft-svg/draw"]
svg-paths = ["svg", "craft-svg/paths"]
@@ -820,6 +848,7 @@ timeline-xml = ["timeline", "craft-timeline/xml"]
ui-app = ["ui", "craft-ui/app"]
ui-cloud = ["ui", "craft-ui/cloud"]
ui-color_fonts = ["ui", "craft-ui/color_fonts"]
ui-esign = ["ui", "craft-ui/esign"]
ui-share = ["ui", "craft-ui/share"]
ui-snapshot = ["ui", "craft-ui/snapshot"]
ui-system_fonts = ["ui", "craft-ui/system_fonts"]
@@ -889,6 +918,8 @@ wordmodel-test-support = ["wordmodel", "craft-wordmodel/test-support"]
xcf = ["dep:craft-xcf"]
xfa = ["dep:craft-xfa"]
xfdf = ["dep:craft-xfdf"]
xfl = ["dep:craft-xfl"]
+18
View File
@@ -47,6 +47,8 @@ pub use craft_cms as cms;
pub use craft_codepage as codepage;
#[cfg(feature = "color")]
pub use craft_color as color;
#[cfg(feature = "color-transform")]
pub use craft_color_transform as color_transform;
#[cfg(feature = "color-ui")]
pub use craft_color_ui as color_ui;
#[cfg(feature = "control")]
@@ -67,6 +69,12 @@ pub use craft_dds as dds;
pub use craft_deckcraft_format as deckcraft_format;
#[cfg(feature = "designcraft-format")]
pub use craft_designcraft_format as designcraft_format;
#[cfg(feature = "develop")]
pub use craft_develop as develop;
#[cfg(feature = "develop-model")]
pub use craft_develop_model as develop_model;
#[cfg(feature = "dex")]
pub use craft_dex as dex;
#[cfg(feature = "dialogs")]
pub use craft_dialogs as dialogs;
#[cfg(feature = "doc")]
@@ -97,6 +105,10 @@ pub use craft_elf as elf;
pub use craft_eps as eps;
#[cfg(feature = "epub")]
pub use craft_epub as epub;
#[cfg(feature = "esign")]
pub use craft_esign as esign;
#[cfg(feature = "evm")]
pub use craft_evm as evm;
#[cfg(feature = "ews")]
pub use craft_ews as ews;
#[cfg(feature = "exr")]
@@ -133,6 +145,8 @@ pub use craft_frame as frame;
pub use craft_gainmap as gainmap;
#[cfg(feature = "gcode")]
pub use craft_gcode as gcode;
#[cfg(feature = "geom")]
pub use craft_geom as geom;
#[cfg(feature = "gif")]
pub use craft_gif as gif;
#[cfg(feature = "gridcraft-format")]
@@ -315,6 +329,8 @@ pub use craft_stencilcraft_document as stencilcraft_document;
pub use craft_stencilcraft_format as stencilcraft_format;
#[cfg(feature = "stream-codecs")]
pub use craft_stream_codecs as stream_codecs;
#[cfg(feature = "suite-account")]
pub use craft_suite_account as suite_account;
#[cfg(feature = "svg")]
pub use craft_svg as svg;
#[cfg(feature = "table")]
@@ -368,6 +384,8 @@ pub use craft_window as window;
pub use craft_wordmodel as wordmodel;
#[cfg(feature = "xcf")]
pub use craft_xcf as xcf;
#[cfg(feature = "xfa")]
pub use craft_xfa as xfa;
#[cfg(feature = "xfdf")]
pub use craft_xfdf as xfdf;
#[cfg(feature = "xfl")]
+1 -1
View File
@@ -11,7 +11,7 @@ mapping a SYLK sheet onto a document are the caller's work.
| Function | What it does |
|---|---|
| `decode_text(bytes)` | UTF-8 and UTF-16 byte order marks; without one, valid UTF-8 is kept; other bytes are Windows-1256 when they read as Arabic, else Windows-1252 |
| `sniff_delimiter(text, quote)` | comma, semicolon or tab: the one with the most consistent field count over the first 20 non-blank records in a 64 KiB sample; when no candidate finds coherent complete records with a delimiter in each, a candidate that finds no complete record counts the delimiters of the first record up to the end of the sample, or up to a quoted field still open there, and a quote inside a field that does not start with one makes that record incoherent; quote boundaries must be coherent, and ties prefer tab, comma, then semicolon |
| `sniff_delimiter(text, quote)` | comma, semicolon or tab: the one with the most consistent field count over the first 20 records with other text in a 64 KiB sample; when none separates those records, the candidates whose records hold only their delimiters and whitespace (rows of empty cells) are compared the same way, leaving out any candidate that found a record with other text; when no candidate finds coherent complete records with a delimiter in each, a candidate that finds no complete record with other text counts the delimiters of the first such record up to the end of the sample, or up to a quoted field still open there (after its rows of empty cells, a record without its delimiter is left out), and a quote inside a field that does not start with one makes that record incoherent; quote boundaries must be coherent, and ties prefer tab, comma, then semicolon |
| `parse_records(text, delim, quote, max_fields, on_record)` | records of fields, one callback per record (return `false` to stop); CR, LF and CRLF line ends; quoted fields with doubled quotes and line breaks; a quote in the middle of a field is text |
| `records(text, delim, quote, max_records, max_fields)` | the same, collected |
| `push_field(out, field, delim)`, `field_len(field, delim)` | one field as written, quoted only when it holds the delimiter, a quote or a line break; its exact length, to enforce a size cap before writing |
+109 -13
View File
@@ -33,13 +33,17 @@ pub use decode::{decode_text, decode_utf8};
/// Picks comma, semicolon or tab by consistent field counts in the first non-blank records.
/// Quotes start only at a candidate field boundary; candidates with incoherent quoted fields
/// are discarded when another coherent candidate separates the records. Ties prefer tab,
/// then comma, then semicolon. Comma is the fallback when no candidate separates the text.
/// then comma, then semicolon. When no candidate separates the records that hold other text,
/// the same rules pick among the candidates whose records hold only their delimiters and
/// whitespace, such as an exported row of empty cells; a candidate that finds a record with
/// other text is left out of that pick. Comma is the fallback when neither pick finds one.
/// Only the first 64 KiB are read. A record cut off at the end of that sample is left out,
/// except when no candidate finds coherent complete records with a delimiter in each. Then a candidate
/// that finds no complete record counts the delimiters read so far in the first record, and that
/// record is incoherent when it has a quote inside a field that does not start with one. When one
/// of those candidates ends the sample inside a quoted field, each of them counts only up to that
/// field's opening quote.
/// that finds no complete record with other text counts the delimiters read so far in the first
/// such record, unless it found rows of its empty cells and that record has none of its
/// delimiters. That record is incoherent when it has a quote inside a field that does not start
/// with one. When one of those candidates ends the sample inside a quoted field, each of them
/// counts only up to that field's opening quote.
pub fn sniff_delimiter(text: &str, quote: char) -> u8 {
const SAMPLE_BYTES: usize = 64 * 1024;
let mut sample_end = text.len().min(SAMPLE_BYTES);
@@ -64,7 +68,15 @@ pub fn sniff_delimiter(text: &str, quote: char) -> u8 {
(scan.count, scan.record_has_content, scan.record_coherent, scan.record_bare_quote) =
(before_cut.count, before_cut.record_has_content, before_cut.record_coherent, before_cut.record_bare_quote);
}
if scan.record_has_content {
if scan.delimiter_only_counts.is_empty() {
if scan.record_has_content {
scan.coherent &= scan.record_coherent && !scan.record_bare_quote;
scan.counts.push(scan.count);
} else {
scan.push_delimiter_only_record();
}
} else if scan.record_has_content && scan.count > 0 {
// After rows of empty cells, a cut record without this delimiter is left out.
scan.coherent &= scan.record_coherent && !scan.record_bare_quote;
scan.counts.push(scan.count);
}
@@ -79,6 +91,8 @@ pub fn sniff_delimiter(text: &str, quote: char) -> u8 {
} else if scan.record_has_content {
scan.coherent &= scan.record_coherent;
scan.counts.push(scan.count);
} else {
scan.push_delimiter_only_record();
}
}
}
@@ -86,23 +100,34 @@ pub fn sniff_delimiter(text: &str, quote: char) -> u8 {
}
fn pick_delimiter(scans: [DelimiterScan; 3]) -> u8 {
let candidates =
scans.map(|scan| (scan.delimiter, scan.counts.iter().copied().min().unwrap_or(0), scan.counts.iter().sum::<usize>(), scan.coherent));
let with_text = scans.each_ref().map(|scan| (scan.delimiter, scan.counts.as_slice(), scan.coherent));
// Records of delimiters alone have no quotes, so they are coherent.
let delimiters_only =
scans.each_ref().map(|scan| (scan.delimiter, if scan.counts.is_empty() { scan.delimiter_only_counts.as_slice() } else { &[] }, true));
best_delimiter(with_text).or_else(|| best_delimiter(delimiters_only)).unwrap_or(b',')
}
fn best_delimiter(candidates: [(u8, &[usize], bool); 3]) -> Option<u8> {
let candidates = candidates
.map(|(delimiter, counts, coherent)| (delimiter, counts.iter().copied().min().unwrap_or(0), counts.iter().sum::<usize>(), coherent));
let prefer_coherent = candidates.iter().any(|(_, min, _, coherent)| *min > 0 && *coherent);
let mut best = (b',', 0usize, 0usize);
let mut best: Option<(u8, usize, usize)> = None;
for (delimiter, min, total, coherent) in candidates {
if min > 0 && (!prefer_coherent || coherent) && (min, total) > (best.1, best.2) {
best = (delimiter, min, total);
if min > 0 && (!prefer_coherent || coherent) && best.is_none_or(|(_, best_min, best_total)| (min, total) > (best_min, best_total)) {
best = Some((delimiter, min, total));
}
}
best.0
best.map(|(delimiter, _, _)| delimiter)
}
/// One candidate delimiter's pass over the sample in [`sniff_delimiter`].
struct DelimiterScan {
delimiter: u8,
/// Delimiter counts of the complete non-blank records, at most 20.
/// Delimiter counts of the complete records that hold other text, at most 20.
counts: Vec<usize>,
/// Delimiter counts of the complete records that hold only this candidate's delimiters and
/// whitespace, at most 20. They do not count toward the 20 records above.
delimiter_only_counts: Vec<usize>,
/// Whether every counted record had coherent quoted fields.
coherent: bool,
reached_record_limit: bool,
@@ -117,10 +142,21 @@ struct DelimiterScan {
open_quote: Option<usize>,
}
impl DelimiterScan {
/// Keeps the open record's delimiter count when the record has no other text and at least
/// one delimiter.
fn push_delimiter_only_record(&mut self) {
if !self.record_has_content && self.count > 0 && self.delimiter_only_counts.len() < 20 {
self.delimiter_only_counts.push(self.count);
}
}
}
fn scan_delimiter(sample: &str, delimiter: u8, quote: char) -> DelimiterScan {
let mut scan = DelimiterScan {
delimiter,
counts: Vec::new(),
delimiter_only_counts: Vec::new(),
coherent: true,
reached_record_limit: false,
count: 0,
@@ -158,6 +194,8 @@ fn scan_delimiter(sample: &str, delimiter: u8, quote: char) -> DelimiterScan {
scan.reached_record_limit = true;
break;
}
} else {
scan.push_delimiter_only_record();
}
scan.count = 0;
after_quote = false;
@@ -403,6 +441,64 @@ mod tests {
assert_eq!(sniff_delimiter(&format!("a,b,c;\"hello,\";d\n{}", "x;y;z\n".repeat(12_000)), '"'), b';');
}
// A sheet whose only value is far down exports rows of empty cells that fill the whole sample.
#[test]
fn delimiter_sniffing_reads_a_sparse_semicolon_export() {
assert_eq!(sniff_delimiter(&format!("{};7\n", ";\n".repeat(40_000)), '"'), b';');
}
#[test]
fn delimiter_sniffing_reads_a_sparse_semicolon_export_with_crlf() {
assert_eq!(sniff_delimiter(&format!("{};7\r\n", ";\r\n".repeat(40_000)), '"'), b';');
}
#[test]
fn delimiter_sniffing_reads_a_sparse_tab_export() {
assert_eq!(sniff_delimiter(&format!("{}\t7\r\n", "\t\r\n".repeat(40_000)), '"'), b'\t');
}
#[test]
fn delimiter_sniffing_reads_a_short_file_of_empty_semicolon_cells() {
assert_eq!(sniff_delimiter(";;\n;;\n", '"'), b';');
assert_eq!(sniff_delimiter(";;\r\n;;", '"'), b';');
}
#[test]
fn delimiter_sniffing_reads_empty_semicolon_cells_padded_with_whitespace() {
assert_eq!(sniff_delimiter(&"; ; \n".repeat(20_000), '"'), b';');
}
#[test]
fn delimiter_sniffing_reads_a_first_record_of_empty_cells_longer_than_the_sample() {
assert_eq!(sniff_delimiter(&format!("{}\n1;2\n", ";".repeat(70_000)), '"'), b';');
}
#[test]
fn delimiter_sniffing_leaves_out_a_cut_record_after_a_row_of_empty_cells() {
assert_eq!(sniff_delimiter(&format!(";\n{};7\n", "x".repeat(70_000)), '"'), b';');
}
#[test]
fn delimiter_sniffing_counts_a_long_record_after_a_row_of_empty_cells() {
// Delimiters inside the long record's quoted field are text for every candidate.
assert_eq!(sniff_delimiter(&format!("\t\nname\t\"{}\"\n", "x,y".repeat(30_000)), '"'), b'\t');
assert_eq!(sniff_delimiter(&format!(";\nname;\"{}\"\n", "x,y\t".repeat(20_000)), '"'), b';');
}
#[test]
fn delimiter_sniffing_lets_records_with_text_outweigh_records_of_delimiters_alone() {
// Rows of tabs alone are blank to the other candidates and do not outweigh them.
assert_eq!(sniff_delimiter(&format!("{}a;b\nc;d\n", "\t\n".repeat(25)), '"'), b';');
assert_eq!(sniff_delimiter(&format!("{}a;b\nc;d\n", "\t\t\n".repeat(25)), '"'), b';');
// The same holds for a record with text cut off at the end of the sample.
assert_eq!(sniff_delimiter(&format!("\t\n{}", "x;".repeat(40_000)), '"'), b';');
// A candidate with a record of other text is judged on those records alone.
assert_eq!(sniff_delimiter(&format!("title\n{}", ";\n".repeat(25)), '"'), b',');
// Rows of empty cells in a comma file; comma is also the fallback.
assert_eq!(sniff_delimiter("a,b,c,d\n,,,\n,,,\n1,2,3,4\n", '"'), b',');
assert_eq!(sniff_delimiter(&format!("{}x;y\n", ",,,\n".repeat(20_000)), '"'), b',');
}
#[test]
fn parser_stops_collecting_fields_at_the_cap() {
let (max, extra) = (16_384usize, 50);
+11 -10
View File
@@ -23,21 +23,22 @@ in part.
Pixels are 8 bits per channel (`encode`, `Texture::decode`) or 16 bits per channel (`encode16`,
`Texture::decode16`), interleaved and top row first, in one of four `Layout`s (`Gray`,
`GrayA`, `Rgb`, `Rgba`). BC1 to BC3 are written from RGBA, BC4 from gray and BC5 from RGB
(`DdsCompression::layout` names it). BC4 reads back as gray. BC5 stores red and green only, so it
reads back as RGB with blue 0: for a tangent-space normal map, X and Y, with Z left to the
renderer. ATI2 files are read as Microsoft's tools read them (red in the first block), not with
the two blocks swapped as FFmpeg does.
(`DdsCompression::layout` names it). BC4 reads back as gray. BC5 and `R16G16_UNORM` store red
and green only, so they read as RGB with blue 0: for a tangent-space normal map, X and Y, with Z
left to the renderer. ATI2 files are read as Microsoft's tools read them (red in the first block),
not with the two blocks swapped as FFmpeg does.
From 16-bit pixels, uncompressed textures keep 16 bits per channel: gray as `R16_UNORM`, gray
and alpha (or any two channels, such as a normal map's X and Y) as `R16G16_UNORM`, RGB (alpha
65535) and RGBA as `R16G16B16A16_UNORM`, all with the DX10 header; they read back as gray, gray
and alpha, and RGBA. BC4 and BC5 keep 8-bit endpoints, as the formats store them, but pick them
and the indices against the 16-bit values, so a smooth height or normal map has less error than
when its 8-bit rounding is compressed. BC1 to BC3 round the pixels to 8 bits first.
65535) and RGBA as `R16G16B16A16_UNORM`, all with the DX10 header; they read back as gray, RGB
with blue 0 (red and green holding the two channels), and RGBA. BC4 and BC5 keep 8-bit
endpoints, as the formats store them, but pick them and the indices against the 16-bit values,
so a smooth height or normal map has less error than when its 8-bit rounding is compressed. BC1 to BC3 round the pixels to 8 bits first.
`Texture::decode` rounds 16-bit formats to 8 bits; `Texture::decode16` returns them exactly,
rescales channel-mask fields from their own width (a 16-bit luminance field exactly),
interpolates BC4 and BC5 at 16 bits, and scales BC1 to BC3 by 257. `craft-image-codecs` still
reads DDS at 8 bits.
interpolates BC4 and BC5 at 16 bits, and scales BC1 to BC3 by 257. `Texture::bits_per_channel`
gives the widest stored channel; `craft-image-codecs` reads a texture through `decode16` when it
is wider than 8 bits.
```rust
use craft_dds::{DdsCompression, DdsOptions, Layout, Texture};
+99 -22
View File
@@ -5,9 +5,10 @@
//! described by channel masks, RGB or luminance, or 16 bits per channel: `R16_UNORM`,
//! `R16G16_UNORM`, `R16G16B16A16_UNORM`) or block-compressed BC1/BC2/BC3
//! (DXT1/DXT3/DXT5) or unsigned BC4/BC5 (ATI1/ATI2), with or without the DX10 header. BC4 opens
//! as gray and BC5 as RGB with blue 0: BC5 stores only red and green, and a normal map's Z is
//! left for the caller to reconstruct. Cubemaps, texture arrays and volume textures are refused
//! rather than flattened to one face or slice, and signed (SNORM) BC4/BC5 is refused too.
//! as gray, and BC5 and `R16G16_UNORM` as RGB with blue 0: they store only red and green, and a
//! normal map's Z is left for the caller to reconstruct. Cubemaps, texture arrays and volume
//! textures are refused rather than flattened to one face or slice, and signed (SNORM) BC4/BC5 is
//! refused too.
//!
//! Writing: a 2D texture, uncompressed (BGRA or BGRX, luminance with or without alpha),
//! BC1/BC2/BC3 or BC4/BC5, optionally with its full mip chain. The legacy header describes all
@@ -18,7 +19,7 @@
//! Pixels are 8 bits per channel ([`encode`], [`Texture::decode`]) or 16 bits per channel
//! ([`encode16`], [`Texture::decode16`]), interleaved, top row first, in one of the [`Layout`]s.
//! Uncompressed 16-bit pixels are written with the DX10 header as `R16_UNORM` (gray),
//! `R16G16_UNORM` (gray and alpha, or any two channels such as a normal map's X and Y) or
//! `R16G16_UNORM` (two channels, such as a normal map's X and Y, read back as red and green) or
//! `R16G16B16A16_UNORM` (RGB, with alpha 65535, and RGBA). BC4 and BC5 fit their 8-bit endpoints
//! and their indices to the 16-bit values; BC1 to BC3 round the pixels to 8 bits first. The
//! crate has no dependencies; the `parallel` feature encodes and decodes rows of blocks (and mip
@@ -269,7 +270,8 @@ enum Encoding {
Bc1,
Bc2,
Bc3,
/// 16 bits per channel, little-endian: gray, gray and alpha (or red and green), or RGBA.
/// 16 bits per channel, little-endian: gray, red and green (read as RGB with blue 0), or
/// RGBA.
Unorm16 {
channels: usize,
},
@@ -301,7 +303,7 @@ impl Encoding {
Encoding::Masks { gray: true, .. } => Layout::Gray,
Encoding::Masks { fields, .. } if fields[3].is_none() => Layout::Rgb,
Encoding::Unorm16 { channels: 1 } => Layout::Gray,
Encoding::Unorm16 { channels: 2 } => Layout::GrayA,
Encoding::Unorm16 { channels: 2 } => Layout::Rgb,
Encoding::Bc4 => Layout::Gray,
Encoding::Bc5 => Layout::Rgb,
_ => Layout::Rgba,
@@ -479,6 +481,17 @@ impl<'a> Texture<'a> {
self.levels
}
/// Bits in the widest channel the file stores: 16 for the 16-bit formats, the widest mask
/// field for other uncompressed pixels, 8 for block compressions. Above 8,
/// [`Texture::decode`] rounds samples that [`Texture::decode16`] keeps.
pub fn bits_per_channel(&self) -> u32 {
match self.encoding {
Encoding::Unorm16 { .. } => 16,
Encoding::Masks { fields, .. } => fields.iter().flatten().map(|f| u32::BITS - f.max.leading_zeros()).max().unwrap_or(0),
Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 | Encoding::Bc4 | Encoding::Bc5 => 8,
}
}
/// The encoding named by the header, including unsigned BC4 and BC5.
pub fn compression(&self) -> DdsCompression {
match self.encoding {
@@ -534,11 +547,8 @@ impl<'a> Texture<'a> {
match encoding {
Encoding::Masks { bytes, gray, fields } => decode_masks(Masks { bytes, gray, fields }, data, row_pitch, &mut pixels, row_size),
// Each 16-bit sample rounded to the nearest 8-bit level.
Encoding::Unorm16 { .. } => rows(&mut pixels, row_size, |y, dst| {
let src = data.get(y * row_pitch..).unwrap_or_default();
for (d, s) in dst.iter_mut().zip(src.as_chunks::<2>().0) {
*d = to8(u16::from_le_bytes(*s));
}
Encoding::Unorm16 { channels: stored } => rows(&mut pixels, row_size, |y, dst| {
unorm16_row(data.get(y * row_pitch..).unwrap_or_default(), stored, dst, to8);
}),
Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 | Encoding::Bc4 | Encoding::Bc5 => {
decode_blocks(encoding, data, (w, channels), &mut pixels)
@@ -565,11 +575,8 @@ impl<'a> Texture<'a> {
let mut pixels = alloc_zeroed(total / 2)?;
match encoding {
Encoding::Masks { bytes, gray, fields } => decode_masks16(Masks { bytes, gray, fields }, data, row_pitch, &mut pixels, row_size),
Encoding::Unorm16 { .. } => rows(&mut pixels, row_size, |y, dst| {
let src = data.get(y * row_pitch..).unwrap_or_default();
for (d, s) in dst.iter_mut().zip(src.as_chunks::<2>().0) {
*d = u16::from_le_bytes(*s);
}
Encoding::Unorm16 { channels: stored } => rows(&mut pixels, row_size, |y, dst| {
unorm16_row(data.get(y * row_pitch..).unwrap_or_default(), stored, dst, |v| v);
}),
Encoding::Bc4 | Encoding::Bc5 => decode_value_blocks16(encoding, data, (w, channels), &mut pixels),
Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 => {
@@ -603,6 +610,21 @@ impl<'a> Texture<'a> {
}
}
/// One row of 16-bit samples, `stored` a pixel and little-endian, into `dst` through `convert`.
/// Two stored channels are red and green: they fill RGB pixels with blue 0.
fn unorm16_row<T: Copy + Default>(src: &[u8], stored: usize, dst: &mut [T], convert: impl Fn(u16) -> T) {
let src = src.as_chunks::<2>().0;
if stored == 2 {
for (d, s) in dst.as_chunks_mut::<3>().0.iter_mut().zip(src.as_chunks::<2>().0) {
*d = [convert(u16::from_le_bytes(s[0])), convert(u16::from_le_bytes(s[1])), T::default()];
}
} else {
for (d, s) in dst.iter_mut().zip(src) {
*d = convert(u16::from_le_bytes(*s));
}
}
}
/// A 16-bit sample rounded to the nearest 8-bit level.
fn to8(v: u16) -> u8 {
((u32::from(v) + 128) / 257) as u8
@@ -946,7 +968,8 @@ pub fn encode(width: u32, height: u32, layout: Layout, pixels: &[u8], options: D
/// [`encode`] for 16-bit pixels. Uncompressed, they keep 16 bits per channel: gray as
/// `R16_UNORM`, gray and alpha (or any two channels, such as a normal map's X and Y) as
/// `R16G16_UNORM`, RGB (with alpha 65535) and RGBA as `R16G16B16A16_UNORM`, all with the DX10
/// header. BC4 and BC5 pick their endpoints and indices against the 16-bit values; BC1 to BC3
/// header. `R16G16_UNORM` holds red and green, so two channels read back as RGB with blue 0. BC4
/// and BC5 pick their endpoints and indices against the 16-bit values; BC1 to BC3
/// round the pixels to 8 bits and write what [`encode`] writes from them.
pub fn encode16(width: u32, height: u32, layout: Layout, pixels: &[u16], options: DdsOptions) -> Result<Vec<u8>, DdsError> {
if width == 0 || height == 0 {
@@ -1293,6 +1316,24 @@ mod tests {
assert_eq!(Texture::parse(&file).and_then(|t| t.decode()), Ok(vec![7; 64]));
}
#[test]
fn bits_per_channel_is_the_widest_stored_channel() {
let options = |compression| DdsOptions { compression, mipmaps: false };
let gray = encode(4, 4, Layout::Gray, &[7; 16], options(DdsCompression::None)).unwrap();
let bc4 = encode(4, 4, Layout::Gray, &[7; 16], options(DdsCompression::Bc4)).unwrap();
let r16 = encode16(4, 4, Layout::Gray, &[7; 16], options(DdsCompression::None)).unwrap();
let bits = |file: &[u8]| Texture::parse(file).unwrap().bits_per_channel();
assert_eq!((bits(&gray), bits(&bc4), bits(&r16)), (8, 8, 16));
// A2R10G10B10 as masks: 10 bits.
let mut a2r10 = gray[..HEADER].to_vec();
a2r10[80..84].copy_from_slice(&(DDPF_RGB | DDPF_ALPHAPIXELS).to_le_bytes());
a2r10[88..92].copy_from_slice(&32u32.to_le_bytes());
for (i, mask) in [0x3ff0_0000u32, 0xf_fc00, 0x3ff, 0xc000_0000].into_iter().enumerate() {
a2r10[92 + 4 * i..96 + 4 * i].copy_from_slice(&mask.to_le_bytes());
}
assert_eq!(bits(&a2r10), 10);
}
/// Samples spread over the whole 16-bit range, `channels` a pixel.
fn spread16(width: usize, height: usize, channels: usize) -> Vec<u16> {
(0..width * height * channels).map(|i| (i as u32 * 7919 % 65536) as u16).collect()
@@ -1303,13 +1344,17 @@ mod tests {
let (w, h) = (7, 5);
for (layout, dxgi, read_as, pixel_bytes) in [
(Layout::Gray, 56, Layout::Gray, 2),
(Layout::GrayA, 35, Layout::GrayA, 4),
(Layout::GrayA, 35, Layout::Rgb, 4),
(Layout::Rgb, 11, Layout::Rgba, 8),
(Layout::Rgba, 11, Layout::Rgba, 8),
] {
let pixels = spread16(w, h, layout.channels());
let want: Vec<u16> =
if layout == Layout::Rgb { pixels.chunks(3).flat_map(|p| [p[0], p[1], p[2], 65535]).collect() } else { pixels.clone() };
let want: Vec<u16> = match layout {
// R16G16 holds red and green: the two channels read back with blue 0.
Layout::GrayA => pixels.chunks(2).flat_map(|p| [p[0], p[1], 0]).collect(),
Layout::Rgb => pixels.chunks(3).flat_map(|p| [p[0], p[1], p[2], 65535]).collect(),
_ => pixels.clone(),
};
for mipmaps in [false, true] {
let file = encode16(w as u32, h as u32, layout, &pixels, DdsOptions { compression: DdsCompression::None, mipmaps }).unwrap();
assert_eq!(le32(&file, HEADER).unwrap(), dxgi, "{layout:?}");
@@ -1358,6 +1403,7 @@ mod tests {
let texture = Texture::parse(&l16).unwrap();
assert_eq!(texture.decode16().unwrap(), [300, 65000]);
assert_eq!(texture.decode().unwrap(), [1, 253]);
assert_eq!(texture.bits_per_channel(), 16);
// G16R16 as masks (red low, green high) reads as RGB at 16 bits, blue 0.
let mut g16r16 = l16[..HEADER].to_vec();
g16r16[80..84].copy_from_slice(&DDPF_RGB.to_le_bytes());
@@ -1369,6 +1415,36 @@ mod tests {
assert_eq!((texture.layout(), texture.decode16().unwrap()), (Layout::Rgb, vec![300, 40000, 0, 65535, 7, 0]));
}
/// A DX10 `R16G16` file (DXGI 35, or 33 typeless) of `levels` levels: red then green,
/// little-endian, each level packed after the one above.
fn rg16_file(width: u32, height: u32, dxgi: u32, levels: u32, samples: &[u16]) -> Vec<u8> {
let mut file = header(width, height, Store::R16, levels, 0).unwrap().to_vec();
file[HEADER..HEADER + 4].copy_from_slice(&dxgi.to_le_bytes());
file[20..24].copy_from_slice(&(width * 4).to_le_bytes());
file.extend(samples.iter().flat_map(|v| v.to_le_bytes()));
file
}
#[test]
fn r16g16_textures_read_as_red_and_green_with_blue_0() {
// R16G16 stores red and green and no alpha: blue is 0, as for BC5 and G16R16 masks.
let (w, h) = (3, 2);
let top = spread16(w, h, 2);
let rgb: Vec<u16> = top.chunks(2).flat_map(|p| [p[0], p[1], 0]).collect();
for dxgi in [35, 33] {
// 3×2, then 1×1 with red 11 and green 22.
let file = rg16_file(w as u32, h as u32, dxgi, 2, &[top.clone(), vec![11, 22]].concat());
let texture = Texture::parse(&file).unwrap();
assert_eq!((texture.layout(), texture.bits_per_channel()), (Layout::Rgb, 16), "DXGI {dxgi}");
assert_eq!(texture.decode16().unwrap(), rgb, "DXGI {dxgi}");
assert_eq!(texture.decode().unwrap(), rgb.iter().map(|&v| to8(v)).collect::<Vec<_>>(), "DXGI {dxgi}");
let level = texture.mip_level(1).unwrap();
assert_eq!(level.decode16().unwrap(), [11, 22, 0]);
assert!(matches!(level.decode16_with_limit(5), Err(DdsError::LimitExceeded { required: 6, limit: 5 })));
assert!(Texture::parse(&file[..file.len() - 5]).unwrap().decode16().is_err());
}
}
#[test]
fn typeless_and_padded_16_bit_textures_are_read() {
// Rows padded to 8 bytes, as other writers may store them: the padding is skipped.
@@ -1380,8 +1456,9 @@ mod tests {
padded.extend_from_slice(&[0xee, 0xee]);
}
assert_eq!(Texture::parse(&padded).unwrap().decode16().unwrap(), [1, 2, 3, 4, 5, 6]);
// The typeless forms read as the UNORM ones; typeless RGBA refuses premultiplied alpha too.
for (unorm, typeless, layout) in [(56u32, 53u32, Layout::Gray), (35, 33, Layout::GrayA), (11, 9, Layout::Rgba)] {
// The typeless forms read as the UNORM ones (R16G16's in its own test); typeless RGBA
// refuses premultiplied alpha too.
for (unorm, typeless, layout) in [(56u32, 53u32, Layout::Gray), (11, 9, Layout::Rgba)] {
let pixels = spread16(3, 2, layout.channels());
let file = encode16(3, 2, layout, &pixels, DdsOptions::default()).unwrap();
assert_eq!(le32(&file, HEADER).unwrap(), unorm);
+5 -2
View File
@@ -74,14 +74,17 @@ fn mip_views_reuse_shared_decoders_and_keep_their_bounds() {
#[test]
fn sixteen_bit_mip_views_preserve_samples_and_stored_offsets() {
for (layout, channels) in [(Layout::Gray, 1), (Layout::GrayA, 2), (Layout::Rgba, 4)] {
// Two channels are stored as R16G16 and read back as red and green with blue 0.
let read =
|samples: Vec<u16>| -> Vec<u16> { if channels == 2 { samples.chunks(2).flat_map(|p| [p[0], p[1], 0]).collect() } else { samples } };
let pixels: Vec<u16> = (0..16).flat_map(|p| (0..channels).map(move |c| (p * 400 + c * 31 + 7) as u16)).collect();
let bytes = craft_dds::encode16(4, 4, layout, &pixels, DdsOptions { compression: DdsCompression::None, mipmaps: true }).unwrap();
let texture = Texture::parse(&bytes).unwrap();
assert_eq!(texture.compression(), DdsCompression::None);
assert_eq!(texture.levels(), 3);
assert_eq!(texture.decode16().unwrap(), pixels);
assert_eq!(texture.decode16().unwrap(), read(pixels));
for (index, averages) in [(1, vec![1000, 1800, 4200, 5000]), (2, vec![3000])] {
let expected: Vec<u16> = averages.iter().flat_map(|p| (0..channels).map(move |c| (p + c * 31 + 7) as u16)).collect();
let expected = read(averages.iter().flat_map(|p| (0..channels).map(move |c| (p + c * 31 + 7) as u16)).collect());
let level = texture.mip_level(index).unwrap();
let budget = (expected.len() * 2) as u64;
assert!(matches!(level.decode16_with_limit(budget - 1), Err(craft_dds::DdsError::LimitExceeded { .. })));
+3 -2
View File
@@ -127,9 +127,10 @@ pub fn starts_designcraft(prefix: &[u8]) -> bool {
craft_document_bundle::starts_with_mimetype(prefix, BUNDLE)
}
/// Read the first-page PNG preview from a ZIP package, with a fixed 4 MiB cap.
/// Read the first-page PNG preview from an unprefixed native ZIP package, with a fixed 4 MiB cap.
/// Nonmatching signatures are rejected after at most four bytes read.
pub fn read_preview<R: Read + Seek>(reader: R) -> Option<Vec<u8>> {
craft_document_bundle::read_preview_from(reader, PREVIEW)
craft_document_bundle::read_unprefixed_preview_from(reader, PREVIEW)
}
fn is_linked(document: &Value, id: &str) -> bool {
+34
View File
@@ -167,3 +167,37 @@ fn bytes_supplied_for_a_linked_asset_are_not_written() -> Result<(), Box<dyn std
assert_eq!(load::<Value>(&bytes)?.assets, [("8".to_owned(), b"kept".to_vec())]);
Ok(())
}
#[test]
fn preview_uses_the_strict_signature_path_without_losing_cursor_independence() -> Result<(), Box<dyn std::error::Error>> {
struct Counted {
cursor: std::io::Cursor<Vec<u8>>,
bytes_read: usize,
}
impl std::io::Read for Counted {
fn read(&mut self, out: &mut [u8]) -> std::io::Result<usize> {
let n = self.cursor.read(out)?;
self.bytes_read += n;
Ok(n)
}
}
impl std::io::Seek for Counted {
fn seek(&mut self, position: std::io::SeekFrom) -> std::io::Result<u64> {
self.cursor.seek(position)
}
}
let mut non_zip = Counted { cursor: std::io::Cursor::new(vec![0x42; 1 << 20]), bytes_read: 0 };
non_zip.cursor.set_position(100);
assert_eq!(read_preview(&mut non_zip), None);
assert!(non_zip.bytes_read <= 4);
let bytes = save(&json!({}), "DesignCraft test", Some(b"png"), &[], &[])?;
let mut cursor = std::io::Cursor::new(&bytes);
cursor.set_position(bytes.len() as u64);
assert_eq!(read_preview(cursor), Some(b"png".to_vec()));
let mut prefixed = b"MZsynthetic-prefix".to_vec();
prefixed.extend(bytes);
assert_eq!(craft_document_bundle::read_preview_from(std::io::Cursor::new(&prefixed), PREVIEW), Some(b"png".to_vec()));
assert_eq!(read_preview(std::io::Cursor::new(prefixed)), None);
Ok(())
}
+21
View File
@@ -0,0 +1,21 @@
[package]
name = "craft-develop-model"
description = "Raw develop settings as data: the non-destructive edit model (white balance, tone, colour, detail, optics, geometry, masks), control specs with ranges and defaults, process versions, presets, and the mapping to and from Camera Raw's crs: settings."
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-geom = { workspace = true }
craft-metadata = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
miniz_oxide = "0.9"
[dev-dependencies]
proptest = { workspace = true }
+51
View File
@@ -0,0 +1,51 @@
# craft-develop-model
Raw develop settings as data: the second of the three crates planned in craft-libs#587
(`craft-raw`, `craft-develop-model`, `craft-develop`). No rendering, no GPU, no I/O. An app can
store, copy, merge, migrate and serialise a photo's edits without depending on the pipeline.
```toml
craft-develop-model = { git = "https://github.com/storytold/craft-libs", rev = "<commit>" }
```
The base is LightCraft's `lightcraft-develop` and the `crs:` import from `lightcraft-engine`
(`crs.rs`, `crs_masks.rs`) at `a75497d6`. Issue numbers in comments are LightCraft's
(`storytold/lightcraft#N`).
## What is here
| Module | Contents |
|---|---|
| `settings` | `DevelopSettings`, the complete, serialisable description of a photo's look: white balance (Kelvin or relative scale), light, tone curve, HSL / mixer / point colour, B&W mix, colour grading, calibration, effects (vignette, grain), detail, optics (lens profile, embedded corrections, defringe), geometry and Upright, crop, masks (brush, linear, radial, range, AI segmentation), spots, red eye, lens blur, enhance, HDR. `ProcessVersion` / `Process`: which formulas an edit renders with, so later formula changes leave existing edits alone ([process versions](docs/process-versions.md)). |
| `controls` | `CONTROLS`: every numeric slider by id, with its label, section, range, default, step and track gradient. UIs and agents address sliders through it. |
| `presets` | `Preset`, `SettingsGroup` (the groups a copy, paste, sync or preset covers), `extract_groups`, `apply_partial` (a partial settings object merged at an amount), `deep_merge`. |
| `segmask` | `SegMask`: a compressed AI segmentation mask stored inside the settings. |
| `crs`, `crs_masks` | Camera Raw / Lightroom `crs:` properties (from `craft_metadata::parse_xmp`) mapped to a *partial* `DevelopSettings` JSON object, which is merged like a preset: global adjustments, tone curves, white balance (`Target` decides how a `crs:` temperature is read), crop, Upright, local corrections and retouch spots, with a report of what was read and what was left out. `preset_from_xmp` reads an XMP preset. The field table is in [xmp-interop](docs/xmp-interop.md). |
Reading the `crs:` packet itself (names, structures, Camera Raw's number formats) is
[`craft-crs`](../crs/README.md)'s job; this crate decides what those settings mean for the edit
model. The mapping is a best-effort approximation of the other application's look, not a pixel match.
## Different from LightCraft
Fixes made here that LightCraft `a75497d6` does not have. It gets them when it switches to this crate.
- `to_json_for_merge` states every setting the stored JSON leaves out at its default (HDR, the profile and its camera
local tone, the curve, Lens Blur's and Denoise's optional settings), not only Remove Hot Pixels. Copying a group
turns them off on the target, and a preset at an amount starts from them.
- `reset_section` resets the sliders of point colours and red eyes, Upright with its guides, and the lens profile and
Remove Chromatic Aberration switches. Settings from outside the app keep those sliders in range.
- `is_unedited` counts a chosen white balance as an edit. As shot, the numbers stay the photo's own.
- A preset at no amount adds no mask, and its Lens Blur focus mask follows its mask to the id the photo gives it.
- `crs:` import: a brush dab that is not a finite number is dropped, brush runs that differ in `crs:MaskInverted` stay
two components, `crs:RetouchInfo` is read only without `crs:RetouchAreas`, and an XMP preset keeps its masks.
- `Homography::from_quads` (`craft-geom`) solves a mapping that sends the origin to infinity.
## Not here yet
- Writing `crs:` back from `DevelopSettings`. LightCraft writes its own `lc:settings` in a sidecar; PhotoCraft's
Camera Raw writes `crs:`. That comes with the PhotoCraft switch, together with the migration of PhotoCraft's
current Camera Raw settings.
- The tests that render a mask or a spot to check its sense (inside or outside a radial, where a spot lands)
need the pipeline. They come back with `craft-develop`. The mapping half of each is kept here.
- LightCraft-only paths: `Target` from a catalog photo, and `.lrtemplate` (Lua) presets.
@@ -0,0 +1,132 @@
# Process versions
> **Changes:** [revision history](#revision-history)
Every photo's develop settings record the **rendering process** they are interpreted by
(`DevelopSettings::process`, a `ProcessVersion` in `crates/develop/src/settings.rs`). Lightroom calls
this the process version. It lets the look of LightCraft improve (a new default tone curve, issue #146;
stronger Light sliders, issue #196) without changing a single photo someone has already edited.
| Process | What it changes |
|---|---|
| **V1** | LightCraft's rendering from before process versions existed. Frozen. |
| **V2** | Highlights and Shadows keep fine detail (issue #632): their base layer (`local::tone_base`) is the edge-aware filter of a separable median of log luminance (radius 0.15 % of the long edge, at most 24 px, `local::BASE_DETAIL`) instead of log luminance itself, so twigs, lines and texture take their surroundings' shift and keep their contrast; region edges stay sharp. CPU (`local::prepare`) and GPU prepare branch on `local::tone_base_detail` (0 = no median under V1); the base plane is cached per process (`local::BaseKey`). Renders without Highlights or Shadows (global or local) are the same as V1's. Tone map unchanged. |
| **V3** | Pixel-scale sharpening (issue #757): Radius uses the original photo’s pixels, Detail controls halo damping, and downsized sources retain a response-matched sharpening band. V1 and V2 keep texture-band sharpening exactly. The sharpen plane is keyed by radius and process and invalidated after noise-reduction changes. The Highlights/Shadows base and tone map are unchanged from V2. |
| **V4** | V3 plus calibrated global Contrast (per channel) and Blacks (per-channel/luminance mix) on raws with a camera tone curve. Whites behaves exactly as V2, both signs; its calibration is a planned follow-up. Other sources and local adjustments retain V2 operators. See [calibrated Light operators](https://github.com/storytold/lightcraft/blob/a75497d6/docs/light-v3.md). |
| **V5** | V4 plus: a raw's tone curve rolls off into white in stops instead of reaching it within about a stop of the sensor's white, so raising Exposure keeps the highlights the sensor recorded (issue #1632). **Camera curve** (the look fitted to the embedded JPEG, or a DNG's `ProfileToneCurve`; `CameraTone`): past its last knot `CameraTone::apply_rolloff` closes the gap to white by `gap / (1 + c·(2^t − 1))` at `t` stops past the knot, with `c` matching the curve's slope there and the gap halving every stop in the end (`tone::ROLLOFF_STOPS`); `ToneMap::camera_rolloff_hdr` builds the table from it. Under V1 to V4 the curve past its last knot (fitted only to camera JPEG tones below 0.85, so 1 to 3 stops below the sensor's white on most photos) closes on white exponentially in linear light: the sensor's white renders at 8-bit 246 to 254 at Exposure 0 and 254 to 255 from Exposure +1. On the 11 CC0 corpus files with a fitted look (8 Sony, 2 Nikon, 1 Fujifilm) it now renders at 239 to 250 at Exposure 0 and 247 to 253 at +1. A DNG curve that reaches white at the sensor's white renders as before. **Generic curve** (raws without a camera curve, `ToneMap::rolloff_hdr`): from half a stop below its white point (`tone::GENERIC_KNEE_STOPS`) the same shoulder takes over, with the extended Reinhard curve's value and slope at the join, where V1 to V4 clip at the white point (scene 1.18 at default settings, ¼ stop above the sensor's white). The sensor's white renders at about 235, 248 and 252 at Exposure 0, +1 and +2 (V1 to V4: 239, 255, 255; the CC0 Canon R8 file and 6 CC0 DNGs without a camera curve). Content past the old clip point, such as a clipped sky, now renders up to 15 codes below white at Exposure 0 and reaches 255 about 5 stops past the sensor's white. Below the last knot or the join, JPEGs and other display-referred sources, and the camera fit itself are unchanged; CPU and GPU share the tone LUT. |
| **V6** | V5 plus: colour noise reduction filters the linear colour differences R−Y and B−Y with the joint method (issue #815, `docs/nr-color-joint.md`): edge-aware weights from a denoised guide shared by both differences, anisotropic diffusion over scales, a brake for isolated colour specks; Y is kept exactly. V1 to V5 keep the blurred chromaticity (`local::denoise`). CPU (`local::denoise`) and GPU (`render::denoise`) branch on `local::joint_colour_nr`. Renders with Color 0 are the same as V2's. |
| **V7** | V6 plus: film grain from crystal layers ([grain.md](https://github.com/storytold/lightcraft/blob/a75497d6/docs/grain.md), `crates/pipeline/src/crystal.rs`), after Aurélien Pierre's model: resolution independent (a preview is the export's grain box-downscaled), fading out at black and white, calibrated to Lightroom Classic's strength and width at mid grey. V1 to V6 keep their two-octave value noise exactly (`finish::ValueGrain`; on the GPU `F_GRAIN_MODEL` 0); `finish::GrainModel::new` picks the model per process. Renders without grain don't depend on this. |
| **V8** (the latest) | V7 plus: Highlights and Shadows take their edge-aware filter of log luminance without its fine detail (`local::detail_free`: each value clamped between its separable median at the V2 radius and the median of a 3× wider neighbourhood) instead of V2's plain median (`local::base_keeps_gaps`), so the gaps in dark lettering on a bright panel are not lifted into bright blocks (issue #3460). CPU (`local::tone_base`) and GPU (`render::tone_base`) branch on it; the base plane is keyed by process. Renders without Highlights or Shadows (global or local) are the same as V7's. |
## The rule
**A change that alters how existing settings render ships as a new process. V1 is frozen.**
- A deliberate change of look (tone model, slider response, default curve, how a stage interprets a
value) goes into a new process. Photos stay on the process they have until someone runs Update to
Current Process (or Reset).
- Bug fixes that make output correct where it was broken (a crash, NaN or black output, a decoder
error, CPU and GPU disagreeing) are not looks and can land in place, as before.
- Changes to how a file is decoded or which camera colour it gets change the source, not how settings
are interpreted; the process doesn't reach that stage today.
**Neutral display tone map** (JPEG, PNG and other display-referred sources with Contrast, Whites and
Blacks at 0) is the identity up to white: the SDR shoulder no longer pulls 1.0 down to 0.9875 (8-bit
255 to 254, issue #1945). It landed in place as a bug fix, since the tone map promised identity at
neutral settings; edited curves keep the shoulder and their V1 look.
**AI mask edges** (Object and Describe selections stored as a model's grid) follow the photo's edges
when they are enlarged to the output (issue #3272): the plain enlargement spilled 1–2 px onto the
background, which a raised Exposure turned into a bright outline around the subject in previews and
exports. Existing AI masks become 1–2 px tighter at a subject's edges, on every process; their
inside, their outside and edges without contrast in the photo are unchanged. It landed in place as
a bug fix: the outline is output that isn't in the photo nor in the edit, not a look anyone chose.
**A mask whose first component is Intersect** starts from that component, on the CPU and the GPU
(issue #1889). It used to start from nothing, so alone it selected nothing, with a later Add it gave
only what was added, and with the mask's Invert it gave the whole photo. Such masks now include the
first component, on every process. It landed in place as a bug fix: intersecting with nothing is not
a look anyone chose.
**Lettering under Highlights and Shadows** (V8) no longer grows blocks of the wrong tone. V2's base
is the edge-aware filter of a separable median alone. Dark lettering on a bright panel (a bus
number, a sign) has strokes and gaps about as wide as the median's radius, so each row and column
window was close to half letter and half panel, and the median picked one tone or the other in
rectangles: it filled the gaps between the letters and their counters with the letters' tone.
Shadows then lifted those patches of panel by over 1 EV, into bright blocks beside the letters. From V8 each
value moves toward that median only as far as the median of a 3× wider neighbourhood agrees
(`local::detail_free`). A twig against a wall has both medians on the wall's side and takes its tone,
as before (#632); the gap between two strokes sits in a wider neighbourhood that is mostly panel, the
two medians disagree, and the gap keeps its own tone. The letters themselves count as fine dark detail
on the panel and keep their contrast, as twigs do. V8 differs from V7 under Highlights or Shadows only in detail
about as fine as the radius, mostly where it is packed closely (lettering, grilles). V2 to V7
are released and keep the blocks (`tests_legacy` locks V1 and V2); Update to Current Process moves a photo past them.
## Adding a process
1. Add a variant to `Process` (`V2`), append it to `Process::ALL` (oldest first), give it its number in
`Process::version` and make it `Process::LATEST`.
2. The compiler then points at every `match` on `Process`. The base tone map is chosen in one place,
`lightcraft_pipeline::finish::base_tone` (both the CPU and the GPU renderer take it from there): give
V2 its own arm and leave V1's alone. A process that changes another stage branches there the same
way, on `s.process.process()`; if that stage is cached (`Plan::lin_key`, the planes in `local.rs`),
add the process to its key.
3. Keep `settings_saved_before_process_versions_load_as_v1` (`crates/develop/src/tests_process.rs`)
passing: settings saved without the field must stay V1, not become the new latest. That is the
field's `#[serde(default = "ProcessVersion::legacy")]`; the struct-level `Default` gives new
settings the latest instead.
4. Render a few procedural scenes on both processes and compare, and update `docs/parity-checklist.md`.
## What gets which process
| | Process |
|---|---|
| A newly imported, merged or Lightroom-imported photo | the latest |
| Settings saved without the field (catalogs and their snapshots, versions and history, `lc:settings` in XMP sidecars, browser libraries: everything from before process versions), or with a damaged value | V1 |
| Reset (`develop.reset`) | the latest |
| Reset of a section or a slider | unchanged |
| Update to Current Process (`develop.updateProcess`) | the latest, for photos on an older one; one undo step. The menu item follows the selection; a call with `ids` / `id` acts on those photos whatever is selected |
| Virtual copy, duplicate | the source's |
| Copy / paste / sync / Auto Sync / presets | unchanged (see below) |
| `crs:` edits (XMP from other raw developers, Lightroom catalogs, imported presets) | unchanged; a new photo has the latest |
| Restoring a version or history step | the one it had |
**Copy, paste, sync and presets** never carry the process: it is in no settings group, so the photos
they change keep their own and interpret the pasted values with it. (Lightroom offers the process
version as a separate checkbox when syncing; LightCraft's groups are coarser and keep it out.) Partial
settings JSON that names `process` itself (`develop.merge`, a hand-written preset) sets it.
**Lightroom edits** are re-interpreted by LightCraft's mapper (`crates/engine/src/crs.rs`), which is
written against the current rendering. `crs:ProcessVersion` numbers Adobe's renderer, not ours, and is
ignored; a photo imported with Lightroom edits is on LightCraft's latest process, and an existing
LightCraft photo that receives them keeps its own.
**A number above this build's latest** (a library or sidecar written by a newer LightCraft) loads, is
kept when saved, and renders with the newest process this build has. Update to Current Process never
moves a photo to an older process; Reset does move it to this build's latest.
**A damaged value** (anything but a whole number from 0 to 2^32 - 1; `2.0` counts as 2) reads as V1,
like a missing field, and costs nothing else: the rest of the settings load from the catalog, a
snapshot, the op log or an `lc:settings` sidecar as usual. The damaged value isn't kept: the photo is
saved as V1.
## Storage
The process is saved as `"process": <number>` in the settings JSON, except V1, which is left out.
Settings made before process versions existed are therefore saved exactly as before, and their
preview-cache keys (`DevelopSettings::hash64`) don't change. `develop.get` (MCP `get_develop`) always
states the process.
From process V3 on, persistent thumbnail, view-render and variant keys also include the
resolved rendering process. A future number can keep the same settings hash across builds
while resolving to different operators, so those keys must differ. V1 and V2 omit this
extra field and retain their existing cached renders. No cache-version bump is needed.
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-11-08 | minor | V8: the Highlights/Shadows base keeps the gaps in dark lettering (#3460) |
| 2026-11-07 | minor | V7: film grain from crystal layers ([grain.md](https://github.com/storytold/lightcraft/blob/a75497d6/docs/grain.md)); V1 to V6 keep their value noise |
| 2026-11-05 | minor | V5: a raw's tone curve rolls off into white in stops, so raising Exposure keeps recorded highlights (#1632) |
| 2026-10-12 | minor | Calibrated Contrast and Blacks, V2 Whites, resolved-process cache keys and number coordination |
+342
View File
@@ -0,0 +1,342 @@
# XMP sidecars and interchange
LightCraft keeps its catalog as the source of truth, and can also store each photo's metadata and develop settings in
an XMP sidecar next to the original. Sidecars let edits travel with the files (backups, another LightCraft library,
other tools), and let LightCraft pick up edits made elsewhere.
## Sidecar files
| | |
|---|---|
| Name | `<stem>.xmp` by default (`IMG_0001.CR3` → `IMG_0001.xmp`); `<file>.xmp` (`IMG_0001.CR3.xmp`) with `naming: "full"`. Reading accepts either (preferred first) and `.XMP`. With stem naming, files sharing a stem don't share a sidecar: see *Shared names* below. |
| Write | `photo.saveMetadataToFile {ids?}` (Photo ▸ Save Metadata to File, ⌘S), or automatically after every change with `library.xmpPreferences {autoWrite: true}` (File ▸ Automatically Write Changes into XMP). Slider drags are written once, when the drag ends; undo/redo rewrite the sidecar. An existing sidecar is **merged into, never replaced** (see *Saving into an existing sidecar*). Written atomically (temp file, fsync, rename). The result lists `written`, `merged` and `backups`. |
| Read | On import (`library.import`, the report counts `sidecars`), and `photo.readMetadataFromFile {ids?}` (one undo step). Manual rereading uses embedded XMP in raw/DNG and JPEG files when no sidecar exists. A discovered sidecar that cannot be read or parsed is reported in `failed`, without applying embedded values. `photo.readMetadataFromFile` never writes the sidecar, even with auto-write on: writing back what it has just read would add `lc:settings`, which later reads prefer over another app's `crs:` edits (issue #934). A file arriving in an import is ranked as if it were catalogued already: it reads its own `<file>.xmp` when another file of its stem (a raw first) owns the shared stem sidecar (issue #1905). |
| Preferences | `library.xmpPreferences {autoWrite?, naming?: stem\|full}`, stored in the library's `prefs.json`. |
What we write (standard namespaces, so other tools can read the metadata):
| Field | XMP property |
|---|---|
| Rating 0–5 | `xmp:Rating` |
| Colour label | `xmp:Label` (`Red`, `Yellow`, `Green`, `Blue`, `Purple`) |
| Title / caption / copyright / creator | `dc:title` / `dc:description` / `dc:rights` / `dc:creator` |
| Copyright status | `xmpRights:Marked` (`True` copyrighted, `False` public domain, absent = unknown) |
| Rights usage terms / copyright info URL | `xmpRights:UsageTerms` / `xmpRights:WebStatement` |
| Keywords | `dc:subject` (names: `Places`, `Italy`, `Rome`) and, when any keyword has levels, `lr:hierarchicalSubject` (paths: `Places\|Italy\|Rome`, with the flat keywords too) |
| Capture time, GPS | `exif:DateTimeOriginal`, `photoshop:DateCreated`, `exif:GPSLatitude`/`GPSLongitude` |
| Pick / reject flag | `lc:flag` (`pick`, `reject`, `none`) |
| Location | `lc:location` |
| Develop settings | `lc:settings` — our complete `DevelopSettings` as JSON (exact round trip, incl. masks, spots, crop and the rendering process; settings without `process` are V1, see [process-versions.md](process-versions.md)) |
`lc:` is `http://ns.lightcraft.app/lc/1.0/`.
Reading merges into the catalog with the **sidecar winning** for every field it states; fields it doesn't state are
kept. The one exception is the **capture time**: a valid time embedded in the file (EXIF/IPTC) wins. Invalid EXIF
clock values are skipped, allowing DateTimeDigitized, IFD0 DateTime or embedded XMP to supply the time. If the file
has no valid capture time, the sidecar's `exif:DateTimeOriginal`, else `photoshop:DateCreated`, else `xmp:CreateDate`
(ISO 8601) is used — on import (it then also files a copied photo in its date folder) and by
`photo.readMetadataFromFile` (undoable). An incomplete or malformed XMP timestamp is not projected as a capture time,
remains available in the raw property map, and does not prevent the next valid capture-time property from being used.
`xmp:Rating="-1"` (the XMP convention for rejected) sets the reject flag. Develop settings come from
`lc:settings` when present (exact); otherwise from the `crs:` fields below (approximate).
When foreign `crs:` settings are only partly transferable, `library.import` includes per-photo `warnings` in its
report. Warnings identify unsupported profile names, saved Upright geometry that will be recalculated, and other
unmapped adjustments; they do not change the source packet or become catalog edits.
Manual rereading and undo leave the JPEG original unchanged. Manual rereading also leaves sidecar files unchanged,
even with automatic XMP writing on. With automatic XMP writing off (the default), undo/redo leave sidecars unchanged;
with it enabled, subsequent edits and undo/redo can trigger the existing sidecar writer. `photo.allMetadata` uses
its already loaded file bytes for embedded XMP, with an existing sidecar taking precedence.
Manual JPEG rereading uses the first standard XMP APP1 before the first SOS (scan) or EOI (end) marker.
Scanning is limited to a 16 MiB header span, including SOI, segment headers and skipped payloads, and 4096
marker/fill steps after SOI. Non-APP1 payloads are skipped without loading them. Each APP1 payload must be
complete and is at most 65,533 bytes. Header extraction succeeds for the first complete
standard XMP packet within both limits, including a packet ending exactly at either limit; otherwise it
fails without a whole-file fallback, including on I/O errors or an incomplete APP1 whose available bytes
form parseable XMP. A valid JPEG with
XMP beyond those limits therefore cannot be manually reread through this path. Extended XMP assembly and
packets between scans are not supported by manual JPEG rereading.
Packet completeness is stricter than the shared best-effort JPEG extractor; it is not strict whole-JPEG
validation. A complete early XMP packet can be returned without examining the remaining file. Import and
`photo.allMetadata` retain their existing extraction paths. Command regressions in
`crates/engine/src/tests/xmp.rs` cover metadata/undo and sidecar precedence, an over-nested XMP packet and a
truncated APP1 without an XMP signature. Separate reader cases in `sidecar::jpeg_header_tests` use small
counted readers and injected limits for span/step boundaries, complete versus truncated APP1, early stopping,
short reads and I/O errors.
## Saving into an existing sidecar
A sidecar may already hold another application's data — e.g. its `crs:` develop settings and `xmpMM:History` — often
the only copy of those edits outside that application's catalog. Saving never drops it:
- LightCraft **owns** the properties in the table above: `xmp:Rating`, `xmp:Label`, `dc:title`, `dc:description`,
`dc:rights`, `dc:creator`, `dc:subject`, `lr:hierarchicalSubject`, `Iptc4xmpCore:Location`, `Iptc4xmpCore:AltTextAccessibility`,
`Iptc4xmpCore:ExtDescrAccessibility`, `photoshop:City`/`State`/`Country`, `xmpRights:Marked`/`UsageTerms`/
`WebStatement` and everything in `lc:`. They are replaced on every save, and removed when LightCraft has no value
(clearing a title in LightCraft clears it in the file). All of them are read back on import, so the library starts
from what the sidecar said.
- The **capture time** (`exif:DateTimeOriginal`, `photoshop:DateCreated`) and **GPS** (`exif:GPSLatitude`,
`exif:GPSLongitude`) are replaced only when LightCraft has a value; otherwise the file's stay.
- **Everything else is kept byte for byte**: other namespaces (`crs:`, `xmpMM:`, the rest of `lr:`, unknown
ones), `xmp:CreatorTool`, comments, the packet wrapper and padding. LightCraft's properties go into one
`rdf:Description` of their own; owned properties written by another application (in attribute or element form) are
removed from its description, which otherwise stays as it was.
- Ownership follows the namespace URI, not the prefix spelling. A foreign namespace bound to `lc:` or `xmp:`
stays foreign: its properties are preserved and do not become LightCraft settings or ratings. Genuine namespace
aliases remain interchangeable, including namespace declarations containing XML character references.
- A sidecar that can't be read as XMP (not well-formed, not UTF-8, no `rdf:RDF`) is first copied to
`<name>.xmp.bak-<date><time>` (`-1`, `-2`… if taken — a backup is never overwritten), then replaced. A sidecar that
can't be read at all (permissions) is left alone and the save fails.
Keywords are written the way Lightroom Classic and darktable write them, so other applications can search them: names
in `dc:subject`, paths in `lr:hierarchicalSubject` (`keywords::to_file`; read back by `keywords::from_file`, which gives
the same keywords). No export option applies to a sidecar, so no keyword is left out and no synonym added. Sidecars
from LightCraft 0.13 and older have paths in `dc:subject`; they still read as paths, and the next save writes them this
way.
Limits: LightCraft doesn't write `crs:`: the other application's
develop settings stay as that application left them, next to LightCraft's own (`lc:settings`, which LightCraft reads
first).
## Shared names
With stem naming, `IMG_0001.CR3` and `IMG_0001.JPG` map to the same `IMG_0001.xmp`. When two or more files in the
library share a stem, the stem sidecar belongs to one of them — a raw first, otherwise the first by file name — and
the others write and read `<file>.xmp` (`IMG_0001.JPG.xmp`), falling back to the stem sidecar for reading when they
have none. So saving one photo never overwrites the other's metadata (`Session::sidecar_naming`).
An import ranks the files it is adding the same way, before they are catalogued: a TIFF or JPEG arriving beside a
raw of its stem reads its own `<file>.xmp` and takes nothing from the raw's `IMG_0001.xmp`, whether it arrives
with the raw or after it (issue #1905).
## Face regions (MWG)
LightCraft reads face, pet, focus and barcode regions in the Metadata Working Group's region schema
(`mwg-rs:Regions`, `http://www.metadataworkinggroup.com/schemas/regions/`), as Lightroom, digiKam, Picasa and others
write them, from sidecars and from XMP embedded in the file. Named faces become people in the People view
(LR-LIB-PEOPLE in [`parity-checklist.md`](parity-checklist.md)), and every region is drawn as a box in the loupe.
- **Read only.** LightCraft never writes `mwg-rs:Regions`; saving a sidecar keeps another application's regions byte
for byte. Removing or resizing a box in the loupe changes the library only.
- **Areas**: `stArea:x`/`y` are the box's centre, `w`/`h` its size, normalized to the photo (`stArea:unit="pixel"`
areas are divided by `mwg-rs:AppliedToDimensions`, and dropped without it). Boxes are clipped to the photo; one
that misses it entirely, or has a non-finite, zero or negative size, is skipped (the rest of the list is kept).
- **Orientation**: regions are stored on the upright (EXIF-oriented) photo. A `mwg-rs:Rotation` of −π/2, +π/2 or ±π
(how Lightroom marks a box given in the sensor's frame for Exif orientation 6, 8 or 3) is turned back into the
upright frame; MWG can't say "mirrored", so Lightroom's boxes on mirrored photos (orientations 2, 4, 5, 7) are
taken as written. Other applications mark boxes drawn on the photo as stored only by their size: when
`mwg-rs:AppliedToDimensions` has the shape of the photo as stored rather than upright (a photo that Exif orientation
5–8 turns a quarter turn, and no `mwg-rs:Rotation`), the boxes are turned with the file's own Exif orientation,
mirror included, when imported and when read again (#2674). The image's own pixel size decides, not a size the
metadata states, and the orientation is found wherever the file keeps its Exif (WebP after the image data, for
one). The exception is a raw with a sidecar that has no `mwg-rs:Regions`: its boxes come from the file and the size
its Exif states decides, and with no such size they are taken as written. A square photo or size looks the same both
ways and is taken as written. Boxes follow LightCraft's own Rotate Left/Right and flips.
- **Re-reading**: a sidecar that has `mwg-rs:Regions` — even with an empty list — replaces the photo's regions, so
regions removed in another application go away here too. A sidecar without `mwg-rs:Regions` (an application that
doesn't do regions) leaves the photo's regions as they are.
## Reading `crs:` develop fields
Many raw developers store edits as `crs:` properties (`http://ns.adobe.com/camera-raw-settings/1.0/`) in sidecars, in
DNG files and in XMP presets. LightCraft reads the common ones and maps them to its own controls. We implemented this
from the public XMP specification and by observing what each field does; no third-party code or preset files were used.
Our pipeline renders differently, so **values carry over but the look is approximate**.
We read these fields; we never write them. Only fields in the packet are applied: the result is a partial settings
object that gets merged like a preset, so everything else keeps its current or default value. Packets marked
`crs:AlreadyApplied="True"` are skipped, because those pixels already contain the edit. Process-version 2012+ field
names are read (e.g. `Exposure2012`). A packet with none of them has its older (process version 2010) fields, such as
`Exposure`, `Contrast` and `FillLight`, approximated with today's sliders; beside any field whose name ends in `2012` those older sliders are ignored. The older `ToneCurve` is separate: it is read whenever the packet has no `ToneCurvePV2012`. `crs:ProcessVersion` itself numbers the other
application's renderer and is ignored: the photo keeps LightCraft's own process, the latest for a newly imported photo
([process-versions.md](process-versions.md)).
| `crs:` field(s) | LightCraft control | Notes |
|---|---|---|
| `Exposure2012` | `light.exposure` | EV, 1:1 |
| `Contrast2012`, `Highlights2012`, `Shadows2012`, `Whites2012`, `Blacks2012` | `light.contrast` … `light.blacks` | −100..100, 1:1 |
| `HDREditMode` | `hdr.enabled` | `1` / `True` = HDR editing on, `0` / `False` off |
| `WhiteBalance` | `wb.mode` | `As Shot`, `Auto`, `Daylight`, `Cloudy`, `Shade`, `Tungsten`, `Fluorescent`, `Flash`; other names → custom |
| `Temperature`, `Tint` | `wb.temp`, `wb.tint` (+ `wb.scale: kelvin`) | Kelvin / tint as written for raws with colour matrices — in the file (DNG) or measured for the camera (`lightcraft_raw::spectral`: ILCE-7M3, D850, EOS 5D Mark III…, issue #730) or read from its white-balance presets (`lightcraft_raw::kelvin_presets`: ILCA-99M2, ILCA-77M2…) — and for presets; the mapped settings say `"scale": "kelvin"` so the value stays Kelvin wherever it lands. Raws LightCraft develops relative to their as-shot look (ARW, NEF, RW2, RAF, CR3, CR2, PEF, SRW of other cameras: 6500 K / 0 means as shot) take the same mired shift from the packet's `AsShotTemperature` / `AsShotTint` instead; without that reference a custom Kelvin stays As Shot and is reported (`Temperature, Tint (custom white balance without AsShotTemperature: kept As Shot)`), because read on the relative scale it would be a large colour cast (issue #510). Note that LightCraft's Kelvin for a camera comes from its measured matrices, Lightroom's from Adobe's: the two scales differ (about 7–10 % on the ILCE-7M3), so the number is carried over, not the exact look |
| `IncrementalTemperature`, `IncrementalTint` | `wb.temp`, `wb.tint` | rendered files: −100..100 on our relative scale (mired shift around 6500 K, same as the Temp slider); a rendered file with only `Temperature` shifts from `AsShotTemperature` like the raws above when it is present |
| `Vibrance`, `Saturation` | `color.vibrance`, `color.saturation` | 1:1 |
| `Texture`, `Clarity2012`, `Dehaze` | `effects.texture`, `effects.clarity`, `effects.dehaze` | 1:1 |
| `HueAdjustment<Band>`, `SaturationAdjustment<Band>`, `LuminanceAdjustment<Band>` | `mixer.<band>.hue/sat/lum` | bands Red, Orange, Yellow, Green, Aqua, Blue, Purple, Magenta |
| `ConvertToGrayscale` | `treatment` | `True` → B&W |
| `GrayMixer<Band>` | `bw_mix.<band>` | |
| `ParametricShadows`, `ParametricDarks`, `ParametricLights`, `ParametricHighlights` | `curve.shadows/darks/lights/highlights` | |
| `ParametricShadowSplit`, `ParametricMidtoneSplit`, `ParametricHighlightSplit` | `curve.split_shadows/split_mid/split_highlights` | |
| `CurveRefineSaturation` | `curve.refine_saturation` | 0..100 (100 = curve saturation unchanged) |
| `ToneCurvePV2012`, `ToneCurvePV2012Red/Green/Blue` | `curve.master/red/green/blue` | `"x, y"` points in 0..255 → 0..1; a straight 0→255 line = no curve; the red / green / blue curves are read only when `ToneCurvePV2012` and all three channel curves are present (Lightroom Classic ignores them otherwise: a master + red-only packet renders without the red curve) |
| `SplitToningShadowHue/Saturation`, `SplitToningHighlightHue/Saturation` | `grading.shadows/highlights.hue/sat` | |
| `ColorGradeShadowLum`, `ColorGradeHighlightLum` | `grading.shadows/highlights.lum` | |
| `ColorGradeMidtoneHue/Sat/Lum`, `ColorGradeGlobalHue/Sat/Lum` | `grading.midtones/global.*` | |
| `ColorGradeBlending`, `SplitToningBalance` | `grading.blending`, `grading.balance` | |
| `Sharpness`, `SharpenRadius`, `SharpenDetail`, `SharpenEdgeMasking` | `detail.sharpen_*` | |
| `LuminanceSmoothing`, `LuminanceNoiseReductionDetail`, `LuminanceNoiseReductionContrast` | `detail.nr_luminance/nr_detail/nr_contrast` | |
| `ColorNoiseReduction`, `ColorNoiseReductionDetail`, `ColorNoiseReductionSmoothness` | `detail.nr_color/nr_color_detail/nr_color_smoothness` | |
| `PostCropVignetteAmount/Midpoint/Roundness/Feather/HighlightContrast` | `vignette.amount/midpoint/roundness/feather/highlights` | |
| `PostCropVignetteStyle` | `vignette.style` | 1 highlight priority, 2 colour priority, 3 paint overlay |
| `GrainAmount`, `GrainSize`, `GrainFrequency` | `grain.amount`, `grain.size`, `grain.roughness` | |
| `LensProfileEnable`, `AutoLateralCA` | `optics.lens_profile`, `optics.remove_ca` | lens profiles are the file's own (DNG-embedded) corrections, which Lightroom applies whatever its profile switch says (our inference): only `LensProfileEnable=1` carries over, `0` leaves the switch as it is |
| `LensManualDistortionAmount`, `VignetteAmount`, `VignetteMidpoint` | `optics.distortion`, `optics.vignetting`, `optics.vignetting_midpoint` | |
| `DefringePurple/GreenAmount/HueLo/HueHi` | `optics.defringe_*` | |
| `ShadowTint`, `RedHue/Saturation`, `GreenHue/Saturation`, `BlueHue/Saturation` | `calibration.shadows_tint`, `calibration.red_hue/red_sat`, … | Calibration panel, 1:1 |
| `PerspectiveVertical/Horizontal/Rotate/Scale/Aspect/X/Y` | `geometry.vertical/horizontal/rotate/scale/aspect/offset_x/offset_y` | |
| `PerspectiveUpright` | `geometry.upright` | 0 off, 1 auto, 2 level, 3 vertical, 4 full, 5 guided; saved `UprightTransform_*` matrices are not imported, so photo import reports that Lightroom geometry was not preserved and the selected mode will be recalculated |
| `HasCrop`, `CropLeft/Top/Right/Bottom`, `CropAngle` | `crop.geometry` | normalized edges → rect; angle in degrees; `HasCrop="False"` → no crop |
Values pass through our control specs, so anything outside our slider ranges gets clamped.
`crs:CameraProfile` is kept as the selected name in the photo's import warning and the active profile is left as it is: the name carries no rendering data and never selects an Adobe profile. Import reports such a profile as not applied (colours may differ from Lightroom), except Lightroom's default profiles (`Adobe Standard`, `Adobe Color`), which every sidecar names and which LightCraft's own starting look stands in for.
**Profiles named by presets (`Look`, issue #1001).** A preset keeps the profile it names (`crs:Look`: `Name`, `Group`,
`UUID`, `Amount`; in `.lrtemplate` files the `Look` table) as `profile.look` in its settings. When the user has imported
a profile of that name (`profile.import`; the name compared ignoring case and repeated spaces, the group breaking
ties), applying the preset selects it at the look's amount (`Amount` 1 = 100 %). Lightroom's basic profiles map to our
own (`Adobe Color` → Color, `Adobe Neutral`, `Adobe Vivid`, `Adobe Landscape`, `Adobe Portrait`, `Adobe Monochrome`
→ Monochrome). Any other `Adobe …` / `Camera …` profile and the numbered creative ones (`Artistic 01`, `B&W 05`,
`Modern 10`, `Vintage 02`) can't be used here, and a third-party profile not imported yet leaves the photo's profile as it
is; import reports either per preset (`Profile “Name” (Lightroom's own)` / `(not imported yet)` in `unmapped`).
References are resolved again whenever profiles are imported or deleted, so a pack's profiles and presets can come in
either order. The look's embedded `Parameters` are not read.
**Not mapped:** camera profiles (`CameraProfile`; we have our own profile set), red eye, lens blur,
process-version 2010 field names, and AI features. Local adjustments and spot removal are read as described below.
## Spot removal
Heal and clone spots stored as `crs:RetouchAreas` (one structure per spot, a mask component inside) and the older
`crs:RetouchInfo` list (one `key = value, …` line per spot; read on its own when it is all a packet has) become our
spots (`crates/engine/src/crs_masks.rs`, `spots`). Implemented from the public data model and by observing what a
sidecar written for a healed photo contains.
| Field | Ours | Notes |
|---|---|---|
| `SpotType` | `mode` | `heal` (default) or `clone`; the removal method (`Method`) is ours |
| `Masks` → `Mask/Ellipse` (`X`, `Y`, `SizeX`) | a circle spot | centre in image fractions; `SizeX` is a fraction of the width, our size of the long edge |
| `Masks` → `Mask/CircularGradient` (`Top/Left/Bottom/Right`) | a circle spot | the box's centre and half-width |
| `Masks` → `Mask/Paint` (`Dabs`, `Radius`) | a brushed spot | the dabs are the path |
| `SourceX`, `OffsetY` | `source_offset` | the source's **absolute** x and y (despite the name); ours is the offset from the target. Only with `SourceState="sourceSetExplicitly"` (or no state); anything else leaves the source automatic |
| `Opacity`, `Feather` | `opacity`, `feather` | 0..1 → 0..100 |
A spot whose mask is any other kind is reported as `Spot: <kind>`. Sizes are clamped to our spot range. A sidecar's
spots replace the photo's, as its masks do.
## Local corrections (masks)
Masks stored as `crs:` structures are read from sidecars, DNG-embedded XMP, XMP presets and `.lrtemplate` files
(`crates/engine/src/crs_masks.rs`). Four containers hold them: `MaskGroupBasedCorrections` (current) and the older
`GradientBasedCorrections`, `CircularGradientBasedCorrections` and `PaintBasedCorrections`. Each correction becomes one
mask: `CorrectionName` → name, `CorrectionAmount` → Amount, inactive corrections are skipped.
| Field | Ours | Notes |
|---|---|---|
| `LocalExposure2012` | `adjust.exposure` | stored as a fraction, ×4 EV |
| `LocalContrast2012`, `LocalHighlights2012`, `LocalShadows2012`, `LocalWhites2012`, `LocalBlacks2012`, `LocalClarity2012`, `LocalTexture`, `LocalDehaze`, `LocalTemperature`, `LocalTint`, `LocalSaturation`, `LocalHue`, `LocalSharpness`, `LocalLuminanceNoise`, `LocalMoire`, `LocalDefringe`, `LocalToningSaturation` | the matching `adjust.*` | stored −1..1, ×100 |
| `LocalToningHue` | `adjust.color_hue` | degrees |
| other `Local*` sliders (`LocalGrain`…) | — | no counterpart in our masks: reported as `Mask: LocalGrain` when set (`LocalCurveRefineSaturation` 100 is neutral) |
| `Mask/Gradient` (`FullX/Y`, `ZeroX/Y`) | linear gradient | full effect at the Full point |
| `Mask/CircularGradient` (`Top/Left/Bottom/Right`, `Angle`, `Feather`, `Flipped`) | radial gradient | box fractions → long-edge radii (presets assume 3:2; sidecars use the photo's shape). `Flipped="true"` means effect inside: in `MaskGroupBasedCorrections` with `Version` 2 (what Lightroom writes for an ordinary radial) and in the legacy `CircularGradientBasedCorrections` Radial Filter, whose default (no `Flipped`) is outside. A `MaskGroupBasedCorrections` radial without `Version` is inside whatever `Flipped` says, and its `Feather` is halved (Lightroom rescales it that way when it upgrades one). Inverting is `MaskInverted` |
| `Mask/Paint` (`Dabs` "d x y", `Radius`, `Flow`, `CenterWeight`, `MaskValue`) | brush | one brush component per correction; `MaskValue` ≤ 0 erases |
| `Mask/Image` `MaskSubType` 1 / 2 | Subject / Sky | other AI selections are reported, not guessed |
| `Mask/RangeMask` `Type` 2 / 3 (`LumRange`, `DepthRange`) | luminance / depth range | lightness converted to our range scale; a range at full strength at white (third `LumRange` value 1) stays open above our scene white; colour ranges are reported |
| `MaskBlendMode` 0 / 1 / 2, `MaskInverted` | add / subtract / intersect, invert | |
Applying a preset adds its masks to the photo's own (masks the photo already has are not added twice), and the Amount
slider scales them. A sidecar's masks replace the photo's, because a sidecar holds the whole edit. Components we can't
carry over are listed in `preset.import`'s `unmapped` as `Mask: <kind>`.
## Local adjustment presets (mask effects)
`mask.importEffects {path | paths, group?, dryRun?}` (and `preset.import`, File ▸ Import Profiles & Presets…, drag & drop)
reads these into the Masking panel's Effect menu (`crates/engine/src/cmd/mask_effect_files.rs`):
| File | How it is read |
|---|---|
| Lightroom Classic `.lrtemplate` (`%APPDATA%\Adobe\Lightroom\Local Adjustment Presets`, `~/Library/Application Support/Adobe/Lightroom/Local Adjustment Presets`) | a Lua table with `type = "LocalizedAdjustmentPreset"`; `title` (else `internalName`, else the file name) → name; `value` holds the `Local*` field names in lower camel case: `exposure2012` → `LocalExposure2012`, mapped as in the table above (`exposure`, `contrast`, `clarity` are the older process version's; the 2012 fields win); `luminanceNoise` → Noise, `toningHue` / `toningSaturation` → Color |
| Camera Raw local-correction `.xmp` (`CameraRaw/LocalCorrections`) | top-level `crs:Local*` properties (or, in a file with `crs:PresetType="Local"` without them, its first correction's); `crs:Name` → name, `crs:Group` → group. Develop presets (no `crs:Local*`) stay develop presets |
| `.lceffect` | ours: `{"format": "lightcraft.maskEffects", "version": 2, "effects": [{name, adjust, group?, favorite?, fields?, with_amount?, brush?, extra?}]}` (a bare array or one effect also reads); `mask.exportEffects {path, names?, group?}` writes it |
| `.zip` | the presets above inside it; its folders give groups |
Groups: a file's folder (relative to the imported folder; names that only say "local adjustment presets" don't count)
names its group, unless the file names one. Lightroom users mark sections of the flat preset menu with **divider
presets**: presets that set nothing, named like `10 ----- DETAIL ENHANCERS ----- 10` (a run of three or more `-`, `=`,
`_`, `*`, `#`, `~`, `—`, `.`). These become groups instead of effects: a preset whose name starts with a number goes to
the divider with the largest number not above it (`12 Sky` under `10 ----- DETAIL ENHANCERS ----- 10` → *Detail
Enhancers*); presets without a number keep their folder's group. An earlier import's divider effects are removed.
Same-named effects are replaced (a star is kept).
Settings with no local slider here are listed per preset in `unmapped` (and the toast) and **kept** with the effect in
`extra` (an `.lceffect` export carries them), but not applied: `grain` (Grain; LightCraft has no local grain),
`pointColors` (Point Color: `SrcHue/Sat/Lum`, `HueShift`, `SatScale`, `LumScale`, `RangeAmount`, `Hue/Sat/LumRange`
`{LowerNone, LowerFull, UpperFull, UpperNone}`; there is global Point Color only), `toningLuminance`. Zero values aren't
listed (`refineSaturation = 0` in most files). Lightroom keeps brush size, feather, flow and density per brush, not in
presets, so there is nothing to import for them; an effect saved here can carry them (`brush`).
Applying (`mask.applyEffect {name, id? | ids? | all?, photos?: "selected"}`) sets the sliders the effect carries —
all of them for an imported preset (unnamed ones to 0, as Lightroom does), or only the ones chosen when it was saved
(`mask.saveEffect {fields: "changed" | [..]}`) — and Amount only if it carries it. The effect is remembered for the
mask's kind: the next brush / linear / radial / … mask starts with it (`mask.toolEffect`).
## Preset files
| | |
|---|---|
| Ours: `.lcpreset` | JSON `{"format": "lightcraft.preset", "version": 1, "presets": [{id, name, group, settings}]}`, where `settings` is a partial develop-settings object (only the groups the preset includes). A file can hold one preset or many, and every preset keeps its group. Import also accepts a bare preset object or an array of them. |
| Export | `preset.export {path, ids?, group?}`: all user presets by default, or the given ids or one group. In the app: File ▸ Export Presets…, Presets panel ▸ ⋯ ▸ Export User Presets…, or right-click a group ▸ Export Group…. |
| Import | `preset.import {paths, group?, dryRun?}`: files or folders (recursive): `.lcpreset`, `.xmp`, classic `.lrtemplate` (a Lua table: `value.settings` holds the same field names as `crs:`), photos that carry their edits in XMP ("DNG presets" from mobile apps; their crop, geometry and custom white balance are left out) and `.zip` bundles of any of these. Local adjustment (brush) presets — Lightroom Classic's `.lrtemplate` with `type = "LocalizedAdjustmentPreset"`, Camera Raw's local-correction `.xmp`, our `.lceffect`, also inside zips — become mask effects (`mask.effects`) instead (see *Local adjustment presets* below); the result lists them under `effects`, and divider presets under `effectDividers`. Presets in a folder (or a folder inside a zip) go to a group named after it, unless the file names its own group. The result lists, per preset, the settings that couldn't be carried over (`unmapped`, e.g. `CameraProfile`, a profile named by `Look` that isn't imported, local masks), and the app's toast names them; fields that only describe the preset or the photo (`Cluster`, `SortName`, `Description`, `SupportsAmount2`, `RequiresRGBTables`, `CropConstrainToWarp`, `OverrideLookVignette`, `AsShotTemperature` / `AsShotTint`, empty `PointColors` slots) aren't listed. Older (process version 2010) fields — `Exposure`, `Contrast`, `FillLight`, `HighlightRecovery`, `Shadows`, `Brightness`, `Clarity`, `ToneCurve` — are approximated with today's sliders when a preset has no 2012-era fields. Dropping preset files on the window imports them too. In the app: File ▸ Import Presets…, or Presets panel ▸ ⋯ ▸ Import Presets…. A preset that's already there (same name, group and settings) is skipped. If an id clashes, the import gets a fresh `user.*` id, and built-in presets are never replaced. |
| XMP presets | Read with the `crs:` table above, with `crs:Name` as the name (falling back to the file name) and `crs:Group` as the group (falling back to "Imported Presets"). Only the fields the preset sets are included, so applying it leaves everything else alone and the Amount slider scales it like any other preset. We only read XMP presets; we don't write them. |
LightCraft ships no third-party presets. Its built-in presets are its own values (`crates/engine/src/presets.rs`).
## Luminar looks (`.lmp`, `.mplumpack`)
`preset.import` (and drag & drop, File ▸ Import Profiles & Presets…) also reads Luminar looks: an `.lmp` file is an
XML property list of adjustment layers (each with effects and named sliders, mostly on a −100..100 scale); newer looks
may be a bundle folder `Name.lmp/Contents/preset.lmp`. An `.mplumpack` collection is a zip of `.lmp` files whose
`PresetsInfo.plist` names the group (`GroupName`); the pack's file name is the fallback. Looks get their own name
(`Name`) or their file / bundle name. The sliders with a clear counterpart are carried over; everything else (AI tools,
Orton, glow, LUT layers, colour balance…) is listed in `unmapped` as `Tool.Slider` (e.g. `OrtonFilter.Amount`).
Disabled layers are ignored, layer opacity scales the sliders (and fades curves toward a straight line), and layers
with a blend mode other than Normal or with a mask are reported, not applied. Binary property lists are not read.
| Luminar tool.slider | Ours |
|---|---|
| Develop / Light / Exposure `Exposure` (±100) | `light.exposure` (±4 EV — the scale is our reading, not documented) |
| `Contrast`, `Highlights`, `Shadows`, `Whites`, `Blacks` | `light.*` (same scale) |
| `Temperature`, `Tint` (relative) | white balance shift as `crs:IncrementalTemperature` / `IncrementalTint`; values above 1000 as Kelvin |
| `Saturation`, `Vibrance` | `color.saturation`, `color.vibrance` |
| Clarity `Clarity`, Structure / AI Structure `Amount` | `effects.clarity` (summed) |
| Dehaze `Amount` | `effects.dehaze` |
| HSL (`MIPLChannelsEffect`) `h`/`s`/`l` + Red…Magenta | `mixer.<band>.hue / sat / lum` |
| Curves `RGB` / `Red` / `Green` / `Blue` (x, y points in 0..1) | `curve.master / red / green / blue` |
| Vignette `Amount`, `Vignette Size` | `vignette.amount`, `vignette.midpoint` |
| Grain `Amount` | `grain.amount` |
## Profiles: 3D LUTs (`.cube`)
`profile.import {paths}` (File ▸ Import Profiles & Presets…, drag & drop) reads `.cube` 3D LUTs — single files, folders
or `.zip` bundles — as creative profiles: they appear in the profile browser under their folder's (or zip's) name and
take the Amount slider (0–200 %) like the built-in looks. The LUT is applied to the finished, display-encoded colour
(trilinear; `DOMAIN_MIN` / `DOMAIN_MAX` honoured; 1D LUTs are not supported); photos with a LUT profile render on the
CPU. A library on disk keeps a copy of each file in its `Profiles/` folder. XMP camera/creative profiles with embedded
tables are not read.
## Profiles: camera profiles (`.dcp`)
The same command (and File ▸ Import Profiles & Presets…, drag & drop) reads DNG Camera Profiles — the user's own `.dcp`
files, e.g. made with a colour-checker tool — as camera profiles (`dcp:<camera>-<file>` ids, group *Camera Profiles*,
listed by `profiles.camera`). Read per DNG specification chapter 6 (`crates/raw/src/dcp.rs`): `ProfileName`,
`UniqueCameraModel`, `CalibrationIlluminant1/2`, `ColorMatrix1/2`, `ForwardMatrix1/2`, `ProfileHueSatMap*`,
`ProfileLookTable*`, `ProfileToneCurve` and `BaselineExposureOffset`. Choosing one (`develop.profile {id}`) replaces a raw
file's colour model when it is decoded — the file's own white balance, analog balance and baseline exposure stay, and a
profile without a `ProfileToneCurve` (most chart-made ones) keeps the photo's own contrast: the DNG's tone curve, else the
tone of the look fitted to its camera JPEG — so the
photo's source is decoded again when its profile changes; rendered (non-raw) photos ignore it. Smart previews and the
web build's render worker keep the file's own colour. A library on disk keeps a copy of each file in `Profiles/`;
`profile.deleteCamera` (or `profile.deleteImported`) removes one. No profile ships with LightCraft, and the repository
holds none: tests build theirs in memory (`lightcraft_raw::dcp::write_dcp`).
+632
View File
@@ -0,0 +1,632 @@
//! Control specs: one table describes every numeric develop slider — id, label, section, range,
//! default, step, display precision and track style. The UI builds panels from it, MCP exposes it as
//! a schema, and `get`/`set` address settings by id (e.g. `light.exposure`, `mixer.red.hue`).
//!
//! Settings that come in lists (Point Color samples) are *indexed* controls: one template spec in
//! [`INDEXED`] (`pointColor.hueShift`) addresses every element as `pointColor.<i>.hueShift`.
use serde::{Deserialize, Serialize};
use crate::settings::DevelopSettings;
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum Section {
Light,
Curve,
Color,
Mixer,
BwMix,
Grading,
Effects,
Vignette,
Grain,
Detail,
Optics,
Geometry,
Profile,
Calibration,
PointColor,
RedEye,
LensBlur,
}
impl Section {
pub fn label(self) -> &'static str {
match self {
Section::Light => "Light",
Section::Curve => "Tone Curve",
Section::Color => "Color",
Section::Mixer => "Color Mixer",
Section::BwMix => "B&W Mixer",
Section::Grading => "Color Grading",
Section::Effects => "Effects",
Section::Vignette => "Vignette",
Section::Grain => "Grain",
Section::Detail => "Detail",
Section::Optics => "Optics",
Section::Geometry => "Geometry",
Section::Profile => "Profile",
Section::Calibration => "Calibration",
Section::PointColor => "Point Color",
Section::RedEye => "Red Eye",
Section::LensBlur => "Lens Blur",
}
}
}
/// How the slider track is drawn.
#[derive(Clone, Copy, Debug, PartialEq, Serialize)]
#[serde(rename_all = "camelCase", tag = "kind")]
pub enum Track {
/// Plain grey track, fill from the minimum.
Plain,
/// Grey track, zero in the middle.
Centered,
/// Blue → yellow (white balance temperature).
Temp,
/// Green → magenta (tint).
Tint,
/// A two-colour gradient (sRGB hex strings).
Gradient { from: &'static str, to: &'static str },
/// Hue shift for a mixer band: gradient from the neighbouring hues through the band colour.
Hue { band: u8 },
/// Saturation for a band: grey → band colour.
Sat { band: u8 },
/// Luminance for a band: dark → light band colour.
Lum { band: u8 },
/// Full hue rainbow.
Rainbow,
}
#[derive(Clone, Copy, Debug, Serialize)]
pub struct ControlSpec {
pub id: &'static str,
pub label: &'static str,
pub section: Section,
pub min: f64,
pub max: f64,
pub default: f64,
pub step: f64,
/// Decimal places shown.
pub decimals: u8,
pub track: Track,
}
impl ControlSpec {
pub fn clamp(&self, v: f64) -> f64 {
if v.is_finite() { v.clamp(self.min, self.max) } else { self.default }
}
pub fn format(&self, v: f64) -> String {
let s = format!("{:.*}", self.decimals as usize, v);
if v.is_finite() && !s.bytes().any(|b| matches!(b, b'1'..=b'9')) {
// Rounds to zero: no sign.
return s.trim_start_matches('-').to_string();
}
if v > 0.0 && self.min < 0.0 { format!("+{s}") } else { s }
}
/// Where `v` sits on the slider track, from 0 (left end) to 1 (right end). Linear, except for the Kelvin
/// temperature, which follows Lightroom's scale: 2000–7000 K fill the left half evenly (100 K per 1 %), and
/// the right half grows logarithmically up to 50000 K, so everyday temperatures aren't crowded into the
/// left sixth of the track. The relative temperature of rendered files (−100…+100, already in mireds) stays
/// linear.
pub fn position(&self, v: f64) -> f64 {
let v = self.clamp(v);
let p = match self.kelvin_scale() {
Some((centre, right)) if v > centre => 0.5 + 0.5 * (1.0 + (v - centre) / KELVIN_KNEE).ln() / right,
Some((centre, _)) => 0.5 * (v - self.min) / (centre - self.min),
None => (v - self.min) / (self.max - self.min).max(1e-9),
};
if p.is_finite() { p.clamp(0.0, 1.0) } else { 0.0 }
}
/// The value at track position `p` (0…1): the inverse of [`ControlSpec::position`], not yet on the steps.
pub fn value_at(&self, p: f64) -> f64 {
let p = if p.is_finite() { p.clamp(0.0, 1.0) } else { 0.0 };
let v = match self.kelvin_scale() {
Some(_) if p >= 1.0 => self.max,
Some((centre, right)) if p > 0.5 => centre + KELVIN_KNEE * (((2.0 * p - 1.0) * right).exp() - 1.0),
Some((centre, _)) => self.min + 2.0 * p * (centre - self.min),
None => self.min + p * (self.max - self.min),
};
self.clamp(v)
}
/// The Kelvin temperature's track centre and `ln` of its right half's span (see [`ControlSpec::position`]);
/// `None` for every other control, or a range the centre isn't inside.
fn kelvin_scale(&self) -> Option<(f64, f64)> {
let centre = KELVIN_CENTRE;
(self.id == "wb.temp" && self.min < centre && centre < self.max).then(|| (centre, (1.0 + (self.max - centre) / KELVIN_KNEE).ln()))
}
}
/// The Kelvin temperature at the middle of its track, as in Lightroom.
const KELVIN_CENTRE: f64 = 7000.0;
/// Where the right half of the Kelvin track turns logarithmic: 1000 K gives it close to the left half's slope
/// just past the centre (76 K against 100 K per 1 % of the track), so the thumb moves evenly across it.
const KELVIN_KNEE: f64 = 1000.0;
macro_rules! controls {
($( $id:literal => $($field:ident).+ , $label:literal, $section:ident, $min:expr, $max:expr, $def:expr, $step:expr, $dec:expr, $track:expr; )*) => {
/// All numeric develop controls, in panel order.
pub static CONTROLS: &[ControlSpec] = &[
$( ControlSpec { id: $id, label: $label, section: Section::$section, min: $min as f64, max: $max as f64, default: $def as f64, step: $step as f64, decimals: $dec, track: $track }, )*
];
/// Read a control value by id.
pub fn get(s: &DevelopSettings, id: &str) -> Option<f64> {
match id {
$( $id => Some(s.$($field).+ as f64), )*
_ => indexed_get(s, id),
}
}
/// Write a control value by id (clamped to the spec range). Returns false for unknown ids.
pub fn set(s: &mut DevelopSettings, id: &str, v: f64) -> bool {
let Some(spec) = find(id) else { return false };
let v = spec.clamp(v);
match id {
$( $id => { s.$($field).+ = v as _; true } )*
_ => indexed_set(s, id, v),
}
}
};
}
use Track::*;
controls! {
"profile.amount" => profile.amount, "Amount", Profile, 0, 200, 100, 1, 0, Plain;
"wb.temp" => wb.temp, "Temp", Color, 2000, 50000, 6500, 50, 0, Temp;
"wb.tint" => wb.tint, "Tint", Color, -150, 150, 0, 1, 0, Tint;
"light.exposure" => light.exposure, "Exposure", Light, -5, 5, 0, 0.01, 2, Centered;
"light.contrast" => light.contrast, "Contrast", Light, -100, 100, 0, 1, 0, Centered;
"light.highlights" => light.highlights, "Highlights", Light, -100, 100, 0, 1, 0, Centered;
"light.shadows" => light.shadows, "Shadows", Light, -100, 100, 0, 1, 0, Centered;
"light.whites" => light.whites, "Whites", Light, -100, 100, 0, 1, 0, Centered;
"light.blacks" => light.blacks, "Blacks", Light, -100, 100, 0, 1, 0, Centered;
"hdr.maxEv" => hdr.max_ev, "HDR Headroom", Light, 0, 5, 3, 0.1, 1, Plain;
"hdr.sdrBrightness" => hdr.sdr_brightness, "SDR Brightness", Light, -100, 100, 0, 1, 0, Centered;
"hdr.sdrContrast" => hdr.sdr_contrast, "SDR Contrast", Light, -100, 100, 0, 1, 0, Centered;
"hdr.sdrHighlights" => hdr.sdr_highlights, "SDR Highlights", Light, -100, 100, 0, 1, 0, Centered;
"hdr.sdrShadows" => hdr.sdr_shadows, "SDR Shadows", Light, -100, 100, 0, 1, 0, Centered;
"hdr.sdrWhites" => hdr.sdr_whites, "SDR Whites", Light, -100, 100, 0, 1, 0, Centered;
"hdr.sdrClarity" => hdr.sdr_clarity, "SDR Clarity", Light, -100, 100, 0, 1, 0, Centered;
"curve.highlights" => curve.highlights, "Highlights", Curve, -100, 100, 0, 1, 0, Centered;
"curve.lights" => curve.lights, "Lights", Curve, -100, 100, 0, 1, 0, Centered;
"curve.darks" => curve.darks, "Darks", Curve, -100, 100, 0, 1, 0, Centered;
"curve.shadows" => curve.shadows, "Shadows", Curve, -100, 100, 0, 1, 0, Centered;
"curve.splitShadows" => curve.split_shadows, "Shadows split", Curve, 10, 70, 25, 1, 0, Plain;
"curve.splitMid" => curve.split_mid, "Midtones split", Curve, 20, 80, 50, 1, 0, Plain;
"curve.splitHighlights" => curve.split_highlights, "Highlights split", Curve, 30, 90, 75, 1, 0, Plain;
"curve.refineSaturation" => curve.refine_saturation, "Refine Saturation", Curve, 0, 100, 100, 1, 0, Gradient { from: "#7a7a7a", to: "#d85a3a" };
"color.vibrance" => color.vibrance, "Vibrance", Color, -100, 100, 0, 1, 0, Gradient { from: "#7a7a7a", to: "#d8406a" };
"color.saturation" => color.saturation, "Saturation", Color, -100, 100, 0, 1, 0, Gradient { from: "#7a7a7a", to: "#e04a3a" };
"mixer.red.hue" => mixer.red.hue, "Red Hue", Mixer, -100, 100, 0, 1, 0, Hue { band: 0 };
"mixer.red.sat" => mixer.red.sat, "Red Saturation", Mixer, -100, 100, 0, 1, 0, Sat { band: 0 };
"mixer.red.lum" => mixer.red.lum, "Red Luminance", Mixer, -100, 100, 0, 1, 0, Lum { band: 0 };
"mixer.orange.hue" => mixer.orange.hue, "Orange Hue", Mixer, -100, 100, 0, 1, 0, Hue { band: 1 };
"mixer.orange.sat" => mixer.orange.sat, "Orange Saturation", Mixer, -100, 100, 0, 1, 0, Sat { band: 1 };
"mixer.orange.lum" => mixer.orange.lum, "Orange Luminance", Mixer, -100, 100, 0, 1, 0, Lum { band: 1 };
"mixer.yellow.hue" => mixer.yellow.hue, "Yellow Hue", Mixer, -100, 100, 0, 1, 0, Hue { band: 2 };
"mixer.yellow.sat" => mixer.yellow.sat, "Yellow Saturation", Mixer, -100, 100, 0, 1, 0, Sat { band: 2 };
"mixer.yellow.lum" => mixer.yellow.lum, "Yellow Luminance", Mixer, -100, 100, 0, 1, 0, Lum { band: 2 };
"mixer.green.hue" => mixer.green.hue, "Green Hue", Mixer, -100, 100, 0, 1, 0, Hue { band: 3 };
"mixer.green.sat" => mixer.green.sat, "Green Saturation", Mixer, -100, 100, 0, 1, 0, Sat { band: 3 };
"mixer.green.lum" => mixer.green.lum, "Green Luminance", Mixer, -100, 100, 0, 1, 0, Lum { band: 3 };
"mixer.aqua.hue" => mixer.aqua.hue, "Aqua Hue", Mixer, -100, 100, 0, 1, 0, Hue { band: 4 };
"mixer.aqua.sat" => mixer.aqua.sat, "Aqua Saturation", Mixer, -100, 100, 0, 1, 0, Sat { band: 4 };
"mixer.aqua.lum" => mixer.aqua.lum, "Aqua Luminance", Mixer, -100, 100, 0, 1, 0, Lum { band: 4 };
"mixer.blue.hue" => mixer.blue.hue, "Blue Hue", Mixer, -100, 100, 0, 1, 0, Hue { band: 5 };
"mixer.blue.sat" => mixer.blue.sat, "Blue Saturation", Mixer, -100, 100, 0, 1, 0, Sat { band: 5 };
"mixer.blue.lum" => mixer.blue.lum, "Blue Luminance", Mixer, -100, 100, 0, 1, 0, Lum { band: 5 };
"mixer.purple.hue" => mixer.purple.hue, "Purple Hue", Mixer, -100, 100, 0, 1, 0, Hue { band: 6 };
"mixer.purple.sat" => mixer.purple.sat, "Purple Saturation", Mixer, -100, 100, 0, 1, 0, Sat { band: 6 };
"mixer.purple.lum" => mixer.purple.lum, "Purple Luminance", Mixer, -100, 100, 0, 1, 0, Lum { band: 6 };
"mixer.magenta.hue" => mixer.magenta.hue, "Magenta Hue", Mixer, -100, 100, 0, 1, 0, Hue { band: 7 };
"mixer.magenta.sat" => mixer.magenta.sat, "Magenta Saturation", Mixer, -100, 100, 0, 1, 0, Sat { band: 7 };
"mixer.magenta.lum" => mixer.magenta.lum, "Magenta Luminance", Mixer, -100, 100, 0, 1, 0, Lum { band: 7 };
"bw.red" => bw_mix.red, "Red", BwMix, -100, 100, 0, 1, 0, Lum { band: 0 };
"bw.orange" => bw_mix.orange, "Orange", BwMix, -100, 100, 0, 1, 0, Lum { band: 1 };
"bw.yellow" => bw_mix.yellow, "Yellow", BwMix, -100, 100, 0, 1, 0, Lum { band: 2 };
"bw.green" => bw_mix.green, "Green", BwMix, -100, 100, 0, 1, 0, Lum { band: 3 };
"bw.aqua" => bw_mix.aqua, "Aqua", BwMix, -100, 100, 0, 1, 0, Lum { band: 4 };
"bw.blue" => bw_mix.blue, "Blue", BwMix, -100, 100, 0, 1, 0, Lum { band: 5 };
"bw.purple" => bw_mix.purple, "Purple", BwMix, -100, 100, 0, 1, 0, Lum { band: 6 };
"bw.magenta" => bw_mix.magenta, "Magenta", BwMix, -100, 100, 0, 1, 0, Lum { band: 7 };
"grading.shadows.hue" => grading.shadows.hue, "Shadows Hue", Grading, 0, 360, 0, 1, 0, Rainbow;
"grading.shadows.sat" => grading.shadows.sat, "Shadows Saturation", Grading, 0, 100, 0, 1, 0, Plain;
"grading.shadows.lum" => grading.shadows.lum, "Shadows Luminance", Grading, -100, 100, 0, 1, 0, Centered;
"grading.midtones.hue" => grading.midtones.hue, "Midtones Hue", Grading, 0, 360, 0, 1, 0, Rainbow;
"grading.midtones.sat" => grading.midtones.sat, "Midtones Saturation", Grading, 0, 100, 0, 1, 0, Plain;
"grading.midtones.lum" => grading.midtones.lum, "Midtones Luminance", Grading, -100, 100, 0, 1, 0, Centered;
"grading.highlights.hue" => grading.highlights.hue, "Highlights Hue", Grading, 0, 360, 0, 1, 0, Rainbow;
"grading.highlights.sat" => grading.highlights.sat, "Highlights Saturation", Grading, 0, 100, 0, 1, 0, Plain;
"grading.highlights.lum" => grading.highlights.lum, "Highlights Luminance", Grading, -100, 100, 0, 1, 0, Centered;
"grading.global.hue" => grading.global.hue, "Global Hue", Grading, 0, 360, 0, 1, 0, Rainbow;
"grading.global.sat" => grading.global.sat, "Global Saturation", Grading, 0, 100, 0, 1, 0, Plain;
"grading.global.lum" => grading.global.lum, "Global Luminance", Grading, -100, 100, 0, 1, 0, Centered;
"grading.blending" => grading.blending, "Blending", Grading, 0, 100, 50, 1, 0, Plain;
"grading.balance" => grading.balance, "Balance", Grading, -100, 100, 0, 1, 0, Centered;
"effects.texture" => effects.texture, "Texture", Effects, -100, 100, 0, 1, 0, Centered;
"effects.clarity" => effects.clarity, "Clarity", Effects, -100, 100, 0, 1, 0, Centered;
"effects.dehaze" => effects.dehaze, "Dehaze", Effects, -100, 100, 0, 1, 0, Centered;
"vignette.amount" => vignette.amount, "Vignette", Vignette, -100, 100, 0, 1, 0, Gradient { from: "#101010", to: "#f0f0f0" };
"vignette.midpoint" => vignette.midpoint, "Midpoint", Vignette, 0, 100, 50, 1, 0, Plain;
"vignette.roundness" => vignette.roundness, "Roundness", Vignette, -100, 100, 0, 1, 0, Centered;
"vignette.feather" => vignette.feather, "Feather", Vignette, 0, 100, 50, 1, 0, Plain;
"vignette.highlights" => vignette.highlights, "Highlights", Vignette, 0, 100, 0, 1, 0, Plain;
"grain.amount" => grain.amount, "Grain", Grain, 0, 100, 0, 1, 0, Plain;
"grain.size" => grain.size, "Size", Grain, 0, 100, 25, 1, 0, Plain;
"grain.roughness" => grain.roughness, "Roughness", Grain, 0, 100, 50, 1, 0, Plain;
"enhance.denoise" => enhance.denoise, "Amount", Detail, 0, 100, 0, 1, 0, Plain;
"detail.sharpenAmount" => detail.sharpen_amount, "Sharpening", Detail, 0, 150, 0, 1, 0, Plain;
"detail.sharpenRadius" => detail.sharpen_radius, "Radius", Detail, 0.5, 3, 1, 0.1, 1, Plain;
"detail.sharpenDetail" => detail.sharpen_detail, "Detail", Detail, 0, 100, 25, 1, 0, Plain;
"detail.sharpenMasking" => detail.sharpen_masking, "Masking", Detail, 0, 100, 0, 1, 0, Plain;
"detail.nrLuminance" => detail.nr_luminance, "Noise Reduction", Detail, 0, 100, 0, 1, 0, Plain;
"detail.nrDetail" => detail.nr_detail, "Detail", Detail, 0, 100, 50, 1, 0, Plain;
"detail.nrContrast" => detail.nr_contrast, "Contrast", Detail, 0, 100, 0, 1, 0, Plain;
"detail.nrColor" => detail.nr_color, "Color Noise Reduction", Detail, 0, 100, 0, 1, 0, Plain;
"detail.nrColorDetail" => detail.nr_color_detail, "Detail", Detail, 0, 100, 50, 1, 0, Plain;
"detail.nrColorSmoothness" => detail.nr_color_smoothness, "Smoothness", Detail, 0, 100, 50, 1, 0, Plain;
"optics.distortion" => optics.distortion, "Distortion", Optics, -100, 100, 0, 1, 0, Centered;
"optics.vignetting" => optics.vignetting, "Vignetting", Optics, -100, 100, 0, 1, 0, Centered;
"optics.vignettingMidpoint" => optics.vignetting_midpoint, "Midpoint", Optics, 0, 100, 50, 1, 0, Plain;
"optics.profileDistortion" => optics.profile_distortion, "Profile Distortion", Optics, 0, 200, 100, 1, 0, Plain;
"optics.profileVignetting" => optics.profile_vignetting, "Profile Vignetting", Optics, 0, 200, 100, 1, 0, Plain;
"optics.defringePurple" => optics.defringe_purple_amount, "Purple Amount", Optics, 0, 20, 0, 1, 0, Gradient { from: "#7a7a7a", to: "#a040d0" };
"optics.defringePurpleHueLo" => optics.defringe_purple_hue_lo, "Purple Hue Low", Optics, 0, 90, 30, 1, 0, Gradient { from: "#6040e0", to: "#d040b0" };
"optics.defringePurpleHueHi" => optics.defringe_purple_hue_hi, "Purple Hue High", Optics, 10, 100, 70, 1, 0, Gradient { from: "#6040e0", to: "#d040b0" };
"optics.defringeGreen" => optics.defringe_green_amount, "Green Amount", Optics, 0, 20, 0, 1, 0, Gradient { from: "#7a7a7a", to: "#40c040" };
"optics.defringeGreenHueLo" => optics.defringe_green_hue_lo, "Green Hue Low", Optics, 0, 90, 40, 1, 0, Gradient { from: "#c0d030", to: "#30c0b0" };
"optics.defringeGreenHueHi" => optics.defringe_green_hue_hi, "Green Hue High", Optics, 10, 100, 60, 1, 0, Gradient { from: "#c0d030", to: "#30c0b0" };
"optics.caRed" => optics.ca_red, "Red/Cyan Fringe", Optics, -100, 100, 0, 1, 0, Gradient { from: "#30c0c0", to: "#e04040" };
"optics.caBlue" => optics.ca_blue, "Blue/Yellow Fringe", Optics, -100, 100, 0, 1, 0, Gradient { from: "#d0c030", to: "#4060e0" };
"geometry.vertical" => geometry.vertical, "Vertical", Geometry, -100, 100, 0, 1, 0, Centered;
"geometry.horizontal" => geometry.horizontal, "Horizontal", Geometry, -100, 100, 0, 1, 0, Centered;
"geometry.rotate" => geometry.rotate, "Rotate", Geometry, -10, 10, 0, 0.1, 1, Centered;
"geometry.aspect" => geometry.aspect, "Aspect", Geometry, -100, 100, 0, 1, 0, Centered;
"geometry.scale" => geometry.scale, "Scale", Geometry, 50, 150, 100, 1, 0, Plain;
"geometry.offsetX" => geometry.offset_x, "Offset X", Geometry, -100, 100, 0, 0.1, 1, Centered;
"geometry.offsetY" => geometry.offset_y, "Offset Y", Geometry, -100, 100, 0, 0.1, 1, Centered;
"lensBlur.amount" => lens_blur.amount, "Blur Amount", LensBlur, 0, 100, 0, 1, 0, Plain;
"lensBlur.boost" => lens_blur.boost, "Boost", LensBlur, 0, 100, 0, 1, 0, Plain;
"lensBlur.transition" => lens_blur.transition, "Transition", LensBlur, 0, 100, 50, 1, 0, Plain;
"calibration.shadowsTint" => calibration.shadows_tint, "Shadows Tint", Calibration, -100, 100, 0, 1, 0, Tint;
"calibration.redHue" => calibration.red_hue, "Red Hue", Calibration, -100, 100, 0, 1, 0, Gradient { from: "#e0306a", to: "#e08a30" };
"calibration.redSat" => calibration.red_sat, "Red Saturation", Calibration, -100, 100, 0, 1, 0, Gradient { from: "#7a7a7a", to: "#e03a3a" };
"calibration.greenHue" => calibration.green_hue, "Green Hue", Calibration, -100, 100, 0, 1, 0, Gradient { from: "#b0c030", to: "#30c08a" };
"calibration.greenSat" => calibration.green_sat, "Green Saturation", Calibration, -100, 100, 0, 1, 0, Gradient { from: "#7a7a7a", to: "#40b050" };
"calibration.blueHue" => calibration.blue_hue, "Blue Hue", Calibration, -100, 100, 0, 1, 0, Gradient { from: "#30a0d0", to: "#8040d0" };
"calibration.blueSat" => calibration.blue_sat, "Blue Saturation", Calibration, -100, 100, 0, 1, 0, Gradient { from: "#7a7a7a", to: "#3a60e0" };
"crop.angle" => crop.geometry.angle, "Straighten", Geometry, -45, 45, 0, 0.01, 2, Centered;
}
/// Template specs of the indexed controls (`<family>.<field>`; addressed as `<family>.<i>.<field>`).
pub static INDEXED: &[ControlSpec] = &[
ControlSpec {
id: "pointColor.hueShift",
label: "Hue",
section: Section::PointColor,
min: -100.0,
max: 100.0,
default: 0.0,
step: 1.0,
decimals: 0,
track: Rainbow,
},
ControlSpec {
id: "pointColor.satShift",
label: "Saturation",
section: Section::PointColor,
min: -100.0,
max: 100.0,
default: 0.0,
step: 1.0,
decimals: 0,
track: Gradient { from: "#7a7a7a", to: "#e04a3a" },
},
ControlSpec {
id: "pointColor.lumShift",
label: "Luminance",
section: Section::PointColor,
min: -100.0,
max: 100.0,
default: 0.0,
step: 1.0,
decimals: 0,
track: Gradient { from: "#202020", to: "#f0f0f0" },
},
ControlSpec {
id: "pointColor.variance",
label: "Variance",
section: Section::PointColor,
min: -100.0,
max: 100.0,
default: 0.0,
step: 1.0,
decimals: 0,
track: Centered,
},
ControlSpec {
id: "pointColor.range",
label: "Range",
section: Section::PointColor,
min: 0.0,
max: 100.0,
default: 50.0,
step: 1.0,
decimals: 0,
track: Plain,
},
ControlSpec {
id: "pointColor.hueRange",
label: "Hue Range",
section: Section::PointColor,
min: 0.0,
max: 100.0,
default: 50.0,
step: 1.0,
decimals: 0,
track: Rainbow,
},
ControlSpec {
id: "pointColor.satRange",
label: "Saturation Range",
section: Section::PointColor,
min: 0.0,
max: 100.0,
default: 50.0,
step: 1.0,
decimals: 0,
track: Gradient { from: "#7a7a7a", to: "#e04a3a" },
},
ControlSpec {
id: "pointColor.lumRange",
label: "Luminance Range",
section: Section::PointColor,
min: 0.0,
max: 100.0,
default: 50.0,
step: 1.0,
decimals: 0,
track: Gradient { from: "#202020", to: "#f0f0f0" },
},
ControlSpec {
id: "redEye.pupilSize",
label: "Pupil Size",
section: Section::RedEye,
min: 0.0,
max: 100.0,
default: 50.0,
step: 1.0,
decimals: 0,
track: Plain,
},
ControlSpec {
id: "redEye.darken",
label: "Darken",
section: Section::RedEye,
min: 0.0,
max: 100.0,
default: 50.0,
step: 1.0,
decimals: 0,
track: Gradient { from: "#d0d0d0", to: "#101010" },
},
];
/// `pointColor.3.hueShift` → (`pointColor`, 3, `hueShift`).
fn split_indexed(id: &str) -> Option<(&str, usize, &str)> {
let mut it = id.splitn(3, '.');
let (fam, i, field) = (it.next()?, it.next()?, it.next()?);
if i.is_empty() || !i.bytes().all(|b| b.is_ascii_digit()) {
return None;
}
Some((fam, i.parse().ok()?, field))
}
fn indexed_field<'a>(s: &'a mut DevelopSettings, id: &str) -> Option<&'a mut f64> {
let (fam, i, field) = split_indexed(id)?;
match fam {
"pointColor" => {
let p = s.point_colors.get_mut(i)?;
Some(match field {
"hueShift" => &mut p.hue_shift,
"satShift" => &mut p.sat_shift,
"lumShift" => &mut p.lum_shift,
"variance" => &mut p.variance,
"range" => &mut p.range,
"hueRange" => &mut p.hue_range,
"satRange" => &mut p.sat_range,
"lumRange" => &mut p.lum_range,
_ => return None,
})
}
"redEye" => {
let e = s.red_eye.get_mut(i)?;
Some(match field {
"pupilSize" => &mut e.pupil_size,
"darken" => &mut e.darken,
_ => return None,
})
}
_ => None,
}
}
fn indexed_get(s: &DevelopSettings, id: &str) -> Option<f64> {
// one accessor for get and set: a copy of the one element read (never of the lists, which a
// read of every indexed control would copy once per control)
let (fam, i, field) = split_indexed(id)?;
let mut c = DevelopSettings::default();
match fam {
"pointColor" => c.point_colors.push(*s.point_colors.get(i)?),
"redEye" => c.red_eye.push(*s.red_eye.get(i)?),
_ => return None,
}
indexed_field(&mut c, &format!("{fam}.0.{field}")).map(|v| *v)
}
fn indexed_set(s: &mut DevelopSettings, id: &str, v: f64) -> bool {
match indexed_field(s, id) {
Some(f) => {
*f = v;
true
}
None => false,
}
}
/// The spec of a control id, including indexed ids (`pointColor.0.hueShift` → the
/// `pointColor.hueShift` template).
pub fn find(id: &str) -> Option<&'static ControlSpec> {
if let Some(c) = CONTROLS.iter().find(|c| c.id == id) {
return Some(c);
}
let (fam, _, field) = split_indexed(id)?;
INDEXED.iter().find(|c| c.id.strip_prefix(fam).and_then(|r| r.strip_prefix('.')) == Some(field))
}
/// Every indexed control that exists in `s` (id, template spec), e.g. `pointColor.0.hueShift`.
pub fn indexed_instances(s: &DevelopSettings) -> Vec<(String, &'static ControlSpec)> {
let mut out = Vec::new();
for spec in INDEXED {
let Some((fam, field)) = spec.id.split_once('.') else { continue };
let n = match fam {
"pointColor" => s.point_colors.len(),
"redEye" => s.red_eye.len(),
_ => 0,
};
for i in 0..n {
out.push((format!("{fam}.{i}.{field}"), spec));
}
}
out
}
pub fn in_section(section: Section) -> impl Iterator<Item = &'static ControlSpec> {
CONTROLS.iter().filter(move |c| c.section == section)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn format_shows_no_sign_on_a_value_that_rounds_to_zero() {
let e = find("light.exposure").unwrap();
assert_eq!(e.format(0.004), "0.00");
assert_eq!(e.format(-0.004), "0.00");
assert_eq!(e.format(0.5), "+0.50");
assert_eq!(e.format(-0.5), "-0.50");
assert_eq!(e.format(f64::INFINITY), "+inf");
assert_eq!(e.format(f64::NEG_INFINITY), "-inf");
}
#[test]
fn every_control_reads_its_default() {
let s = DevelopSettings::default();
for c in CONTROLS {
let v = get(&s, c.id).unwrap_or_else(|| panic!("no getter for {}", c.id));
assert_eq!(v, c.default, "{}", c.id);
assert!(c.min <= c.default && c.default <= c.max, "{}", c.id);
}
}
#[test]
fn ids_unique_and_settable() {
let mut seen = std::collections::HashSet::new();
let mut s = DevelopSettings::default();
for c in CONTROLS {
assert!(seen.insert(c.id), "duplicate {}", c.id);
assert!(set(&mut s, c.id, c.max + 1000.0));
assert_eq!(get(&s, c.id), Some(c.max), "{}", c.id);
assert!(set(&mut s, c.id, f64::NAN));
assert_eq!(get(&s, c.id), Some(c.default));
}
assert!(!set(&mut s, "nope", 1.0));
assert_eq!(get(&s, "nope"), None);
}
#[test]
fn indexed_controls_address_list_elements() {
let mut s = DevelopSettings::default();
assert_eq!(get(&s, "pointColor.0.hueShift"), None);
assert!(!set(&mut s, "pointColor.0.hueShift", 10.0), "no sample yet");
s.point_colors.push(Default::default());
s.point_colors.push(Default::default());
assert!(set(&mut s, "pointColor.1.hueShift", 250.0));
assert_eq!(s.point_colors[1].hue_shift, 100.0, "clamped by the template spec");
assert_eq!(get(&s, "pointColor.1.range"), Some(50.0));
assert_eq!(find("pointColor.7.lumRange").map(|c| c.id), Some("pointColor.lumRange"));
assert!(find("pointColor.x.lumRange").is_none() && find("pointColor.0.nope").is_none());
let ids: Vec<String> = indexed_instances(&s).into_iter().map(|(id, _)| id).collect();
assert_eq!(ids.len(), 2 * INDEXED.iter().filter(|c| c.id.starts_with("pointColor.")).count());
for (id, spec) in indexed_instances(&s) {
assert!(get(&s, &id).is_some(), "{id}");
assert!(spec.min <= spec.default && spec.default <= spec.max);
}
}
#[test]
fn signed_indexes_are_unknown_ids() {
let mut s = DevelopSettings::default();
s.point_colors.push(Default::default());
let before = s.point_colors[0].hue_shift;
assert!(!set(&mut s, "pointColor.+0.hueShift", 10.0), "signed index");
assert_eq!(s.point_colors[0].hue_shift, before);
assert_eq!(get(&s, "pointColor.+0.hueShift"), None);
assert!(find("pointColor.+0.hueShift").is_none());
assert!(find("redEye.+0.darken").is_none());
}
#[test]
fn formatting() {
let e = find("light.exposure").unwrap();
assert_eq!(e.format(0.5), "+0.50");
assert_eq!(e.format(-1.0), "-1.00");
assert_eq!(find("wb.temp").unwrap().format(5500.0), "5500");
}
/// The Kelvin temperature's track follows Lightroom's (positions measured in Lightroom Classic against
/// the linear Tint slider; the model is within 2 % of them); every other control stays linear.
#[test]
fn the_kelvin_track_is_lightrooms_and_others_stay_linear() {
let temp = find("wb.temp").unwrap();
for (k, lightroom, model) in [
(2000.0, 0.0, 0.0),
(3650.0, 0.167, 0.165),
(5400.0, 0.333, 0.34),
(7000.0, 0.5, 0.5),
(15000.0, 0.79, 0.79),
(20000.0, 0.853, 0.849),
(30000.0, 0.90, 0.92),
(50000.0, 1.0, 1.0),
] {
let p = temp.position(k);
assert!((p - model).abs() < 0.001, "{k} K at {p}, the model says {model}");
assert!((p - lightroom).abs() <= 0.021, "{k} K at {p}, Lightroom at {lightroom}");
}
// every 50 K step survives value → position → value, and the track never runs backwards
let mut last = -1.0;
for k in (2000..=50000).step_by(50).map(f64::from) {
let p = temp.position(k);
assert!(p > last, "{k} K");
last = p;
let back = (temp.value_at(p) / temp.step).round() * temp.step;
assert_eq!(back, k, "{k} K → {p} → {back}");
}
assert_eq!((temp.value_at(-1.0), temp.value_at(2.0), temp.value_at(f64::NAN)), (2000.0, 50000.0, 2000.0));
assert_eq!((temp.position(1.0), temp.position(1e9), temp.position(f64::NAN)), (0.0, 1.0, temp.position(temp.default)));
let exposure = find("light.exposure").unwrap();
for (v, p) in [(-5.0, 0.0), (-2.5, 0.25), (0.0, 0.5), (1.0, 0.6), (5.0, 1.0)] {
assert!((exposure.position(v) - p).abs() < 1e-12 && (exposure.value_at(p) - v).abs() < 1e-12, "{v}");
}
// the relative temperature of rendered files (its own spec, centred on 0) isn't a Kelvin scale
let relative = ControlSpec { id: "wb.tempRel", min: -100.0, max: 100.0, default: 0.0, step: 1.0, ..*temp };
assert_eq!((relative.position(-50.0), relative.value_at(0.75)), (0.25, 50.0));
// a Kelvin range that doesn't contain the centre falls back to linear rather than dividing by zero
let narrow = ControlSpec { min: 7000.0, max: 9000.0, ..*temp };
assert_eq!((narrow.position(8000.0), narrow.value_at(0.5)), (0.5, 8000.0));
}
}
+543
View File
@@ -0,0 +1,543 @@
//! Interchange: camera-raw-settings (`crs:`) develop fields from XMP → our develop settings.
//!
//! Other raw developers store their edits as `crs:` properties in XMP sidecars, in DNG-embedded
//! XMP and in XMP preset files. This module maps the commonly used, documented-by-observation
//! fields to a *partial* [`DevelopSettings`](crate::DevelopSettings) JSON object
//! (only the fields present in the packet), which is then merged like a preset. Our pipeline is
//! not theirs, so the result is a best-effort approximation of the look, not a pixel match.
//! The full table is in `docs/xmp-interop.md`.
//!
//! Implemented from the public XMP specification (ISO 16684-1) and black-box observation of what
//! each field means; no third-party code or preset content was used.
use std::collections::BTreeMap;
use crate::{MIXER_BANDS, Preset};
use serde_json::{Map, Value, json};
/// Properties keyed `prefix:name` (as produced by [`craft_metadata::parse_xmp`]).
pub type Props = BTreeMap<String, Vec<String>>;
/// What the mapped settings will develop. It decides how a `crs:` white balance is read: a raw
/// with a Kelvin scale (colour matrices in the file, or measured for its camera) takes `Temperature`
/// as Kelvin; everything developed relative to its as-shot look (rendered files, and raws without
/// matrices anywhere) needs a shift from the other app's as-shot white instead, because on that scale 6500 K / 0 means *as shot* (issue storytold/lightcraft#510).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Target {
/// A preset: raw or rendered unknown. Absolute Kelvin first, else the relative scale.
Any,
/// A rendered photo (or a raw shown from its embedded preview): `Incremental*` fields on our
/// relative scale.
Rendered,
/// A raw developed with an absolute white balance (DNG and other files with matrices, and raws
/// whose camera has measured matrices): Kelvin as written.
RawAbsolute,
/// A raw developed relative to its as-shot look.
RawRelative,
}
/// Band names as they appear in `crs:` field names, in our mixer order.
const CRS_BANDS: [&str; 8] = ["Red", "Orange", "Yellow", "Green", "Aqua", "Blue", "Purple", "Magenta"];
/// `crs:` fields that describe the packet rather than an adjustment.
const NON_ADJUSTMENT: &[&str] = &[
"crs:Version",
"crs:ProcessVersion",
"crs:Name",
"crs:ShortName",
"crs:Group",
"crs:UUID",
"crs:PresetType",
"crs:SupportsAmount",
"crs:SupportsColor",
"crs:SupportsMonochrome",
"crs:SupportsHighDynamicRange",
"crs:SupportsNormalDynamicRange",
"crs:SupportsSceneReferred",
"crs:SupportsOutputReferred",
"crs:CameraModelRestriction",
"crs:Copyright",
"crs:ContactInfo",
"crs:HasSettings",
"crs:AlreadyApplied",
"crs:RawFileName",
"crs:HasCrop",
// preset/library bookkeeping and tool options that don't change the rendering
"crs:Cluster",
"crs:SupportsAmount2",
"crs:RequiresRGBTables",
"crs:SortName",
"crs:Description",
"crs:CropConstrainToWarp",
"crs:OverrideLookVignette",
// the file's as-shot white, recorded next to the edit (ours comes from the file itself)
"crs:AsShotTemperature",
"crs:AsShotTint",
// which Lightroom version may read the edit, and checksums of the profiles it names
"crs:CompatibleVersion",
"crs:CameraProfileDigest",
"crs:LensProfileDigest",
// the lens profile Lightroom picked: ours is the file's own, only `LensProfileEnable` carries over
"crs:LensProfileName",
"crs:LensProfileFilename",
"crs:LensProfileIsEmbedded",
"crs:LensProfileSetup",
// a crop tool option (keep the crop inside the photo), not the crop itself
"crs:CropConstrainToUnitSquare",
];
/// True if the packet carries any `crs:` adjustment (not just bookkeeping fields).
pub fn has_adjustments(props: &Props) -> bool {
if props.get("crs:AlreadyApplied").and_then(|v| v.first()).is_some_and(|s| s.eq_ignore_ascii_case("true")) {
// The pixels already contain these settings (e.g. an exported/rendered file).
return false;
}
props.keys().any(|k| k.starts_with("crs:") && !NON_ADJUSTMENT.contains(&k.split('/').next().unwrap_or(k)))
}
thread_local! {
/// Keys read by [`to_partial`] while [`to_partial_report`] runs.
static READ: std::cell::RefCell<Option<std::collections::BTreeSet<String>>> = const { std::cell::RefCell::new(None) };
/// Adjustments [`to_partial`] read but deliberately left out, for the report.
static SKIPPED: std::cell::RefCell<Option<Vec<String>>> = const { std::cell::RefCell::new(None) };
}
fn note(k: &str) {
READ.with(|r| {
if let Some(s) = r.borrow_mut().as_mut() {
s.insert(k.to_string());
}
});
}
fn skipped(what: &str) {
SKIPPED.with(|r| {
if let Some(s) = r.borrow_mut().as_mut() {
s.push(what.to_string());
}
});
}
fn first<'a>(props: &'a Props, k: &str) -> Option<&'a str> {
note(k);
props.get(k).and_then(|v| v.first()).map(|s| s.trim()).filter(|s| !s.is_empty())
}
fn num(props: &Props, k: &str) -> Option<f64> {
let s = first(props, k)?;
let s = s.strip_prefix('+').unwrap_or(s);
if let Some((n, d)) = s.split_once('/') {
let (n, d) = (n.trim().parse::<f64>().ok()?, d.trim().parse::<f64>().ok()?);
return (d != 0.0).then_some(n / d).filter(|v| v.is_finite());
}
s.parse::<f64>().ok().filter(|v| v.is_finite())
}
fn boolean(props: &Props, k: &str) -> Option<bool> {
first(props, k).map(|s| s.eq_ignore_ascii_case("true") || s == "1")
}
/// Insert `v` at the dotted `path` of a JSON object, creating intermediate objects.
fn put(out: &mut Value, path: &str, v: Value) {
let mut cur = out;
let mut parts = path.split('.').peekable();
while let Some(p) = parts.next() {
let Value::Object(m) = cur else { return };
if parts.peek().is_none() {
m.insert(p.to_string(), v);
return;
}
cur = m.entry(p.to_string()).or_insert_with(|| Value::Object(Map::new()));
}
}
/// Relative temperature (−100..100, used for rendered files) → Kelvin, matching the UI's scale
/// (a mired shift around 6500 K).
pub fn rel_to_kelvin(r: f64) -> f64 {
1e6 / (1e6 / 6500.0 - r.clamp(-100.0, 100.0) * 0.8)
}
/// Parse a point curve stored as an `rdf:Seq` of `"x, y"` strings in 0..255.
fn curve(props: &Props, k: &str) -> Option<Value> {
note(k);
let items = props.get(k)?;
let mut pts = Vec::new();
for it in items {
let (x, y) = it.split_once(',')?;
// (`parse` reads "NaN" and "inf" too: a curve with such a point is not a curve)
let (x, y) = (x.trim().parse::<f64>().ok().filter(|v| v.is_finite())?, y.trim().parse::<f64>().ok().filter(|v| v.is_finite())?);
pts.push(json!({"x": (x / 255.0).clamp(0.0, 1.0), "y": (y / 255.0).clamp(0.0, 1.0)}));
}
if pts.len() < 2 {
return None;
}
// A straight 0,0 → 255,255 line is the identity: store it as "no curve".
let identity = pts.len() == 2 && items.iter().all(|it| it.split(',').map(|v| v.trim()).collect::<Vec<_>>().windows(2).all(|w| w[0] == w[1]));
Some(if identity { json!([]) } else { Value::Array(pts) })
}
/// Map the `crs:` fields of an XMP packet to a partial develop-settings JSON object.
///
/// `target` decides how the white balance is read (see [`Target`]).
pub fn to_partial(props: &Props, target: Target) -> Value {
let mut out = Value::Object(Map::new());
let o = &mut out;
let n = |o: &mut Value, crs: &str, path: &str| {
if let Some(v) = num(props, &format!("crs:{crs}")) {
put(o, path, json!(v));
}
};
// ---- Light (process version 2012+ names)
n(o, "Exposure2012", "light.exposure");
n(o, "Contrast2012", "light.contrast");
n(o, "Highlights2012", "light.highlights");
n(o, "Shadows2012", "light.shadows");
n(o, "Whites2012", "light.whites");
n(o, "Blacks2012", "light.blacks");
// Lightroom's Light panel "HDR" button
if let Some(on) = boolean(props, "crs:HDREditMode") {
put(o, "hdr.enabled", json!(on));
}
// older process versions (most `.lrtemplate` presets): approximate the 2012 sliders from the
// earlier ones, relative to their defaults (contrast 25, blacks 5, brightness 50)
let has = |o: &Value, path: &str| path.split('.').try_fold(o, |v, k| v.get(k)).is_some();
// presets written by newer versions keep the old fields at their defaults: ignore them there
let pv2012 = props.keys().any(|k| k.ends_with("2012"));
let old = |o: &mut Value, crs: &str, path: &str, f: &dyn Fn(f64) -> f64| {
let v = num(props, &format!("crs:{crs}"));
if !pv2012
&& !has(o, path)
&& let Some(v) = v
{
put(o, path, json!(f(v).clamp(-100.0, 100.0)));
}
};
old(o, "Exposure", "light.exposure", &|v| v);
old(o, "Contrast", "light.contrast", &|v| v - 25.0);
old(o, "HighlightRecovery", "light.highlights", &|v| -v);
old(o, "FillLight", "light.shadows", &|v| v);
old(o, "Shadows", "light.blacks", &|v| -(v - 5.0) * 4.0);
old(o, "Brightness", "light.whites", &|v| (v - 50.0) * 0.6);
// ---- Presence
n(o, "Texture", "effects.texture");
n(o, "Clarity2012", "effects.clarity");
old(o, "Clarity", "effects.clarity", &|v| v);
n(o, "Dehaze", "effects.dehaze");
n(o, "Vibrance", "color.vibrance");
n(o, "Saturation", "color.saturation");
// ---- White balance
let mode = first(props, "crs:WhiteBalance").map(|m| match m.to_ascii_lowercase().replace(' ', "").as_str() {
"asshot" => "asShot",
"auto" => "auto",
"daylight" => "daylight",
"cloudy" => "cloudy",
"shade" => "shade",
"tungsten" => "tungsten",
"fluorescent" => "fluorescent",
"flash" => "flash",
_ => "custom",
});
let abs = num(props, "crs:Temperature").map(|t| (t, num(props, "crs:Tint")));
let rel = num(props, "crs:IncrementalTemperature")
.or(num(props, "crs:IncrementalTint").map(|_| 0.0))
.map(|t| (rel_to_kelvin(t), num(props, "crs:IncrementalTint")));
// A Kelvin value for something we develop relative to its as-shot look: the other app's
// as-shot white (`AsShotTemperature` / `AsShotTint`, written next to the edit) is the
// reference, so the edit is the same mired shift from ours (issue storytold/lightcraft#510).
let shifted = || {
let (t, tint) = abs?;
let as_shot = num(props, "crs:AsShotTemperature").filter(|k| *k > 0.0)?;
if t <= 0.0 {
return None;
}
let r = (1e6 / as_shot - 1e6 / t) / 0.8;
let tint = tint.map(|v| v - num(props, "crs:AsShotTint").unwrap_or(0.0));
Some((rel_to_kelvin(r), tint))
};
let wb = match target {
Target::RawAbsolute => abs,
Target::Any => abs.or(rel),
Target::Rendered => rel.or_else(shifted).or(abs),
Target::RawRelative => rel.or_else(shifted),
};
match (mode, wb) {
(Some(m), _) if m != "custom" => put(o, "wb.mode", json!(m)),
(m, Some((t, tint))) => {
put(o, "wb.mode", json!(m.unwrap_or("custom")));
put(o, "wb.temp", json!(t));
if let Some(tint) = tint {
put(o, "wb.tint", json!(tint));
}
// Kelvin as the other app wrote it: say so, so the value stays Kelvin on a raw with that scale (a
// preset's Kelvin is read as the relative scale on the files that have only that, as before)
if wb == abs && matches!(target, Target::RawAbsolute | Target::Any) {
put(o, "wb.scale", json!("kelvin"));
}
}
// a custom Kelvin with nothing to shift it from: read on the relative scale it would be a
// large colour shift (ΔE 22 against Lightroom's export on the photos of issue storytold/lightcraft#510), so
// the photo stays As Shot (ΔE 12 there) and the report says so
(_, None) if target == Target::RawRelative && abs.is_some() => {
put(o, "wb.mode", json!("asShot"));
skipped("Temperature, Tint (custom white balance without AsShotTemperature: kept As Shot)");
}
(Some(m), None) => put(o, "wb.mode", json!(m)),
(None, None) => {}
}
// ---- Treatment + B&W mix
if let Some(bw) = boolean(props, "crs:ConvertToGrayscale") {
put(o, "treatment", json!(if bw { "bw" } else { "color" }));
}
for (band, crs) in MIXER_BANDS.iter().zip(CRS_BANDS) {
n(o, &format!("HueAdjustment{crs}"), &format!("mixer.{band}.hue"));
n(o, &format!("SaturationAdjustment{crs}"), &format!("mixer.{band}.sat"));
n(o, &format!("LuminanceAdjustment{crs}"), &format!("mixer.{band}.lum"));
n(o, &format!("GrayMixer{crs}"), &format!("bw_mix.{band}"));
}
// ---- Tone curve: parametric regions + point curves
n(o, "ParametricShadows", "curve.shadows");
n(o, "ParametricDarks", "curve.darks");
n(o, "ParametricLights", "curve.lights");
n(o, "ParametricHighlights", "curve.highlights");
n(o, "ParametricShadowSplit", "curve.split_shadows");
n(o, "ParametricMidtoneSplit", "curve.split_mid");
n(o, "ParametricHighlightSplit", "curve.split_highlights");
n(o, "CurveRefineSaturation", "curve.refine_saturation");
if let Some(c) = curve(props, "crs:ToneCurve") {
// the older single curve, used when no 2012 curve is present; a straight one says "no curve", which has to
// be said for it to replace a curve the photo has
if !props.contains_key("crs:ToneCurvePV2012") {
put(o, "curve.master", c);
}
}
// Lightroom Classic reads the red / green / blue curves only when the packet holds the master
// 2012 curve and all three channel curves (as its own packets always do): a packet missing any
// of them imports without channel curves (master + red, master + red + green, or red / green /
// blue without the master all leave the photo's channels unchanged there)
if let Some(c) = curve(props, "crs:ToneCurvePV2012") {
put(o, "curve.master", c);
let channels = [("ToneCurvePV2012Red", "red"), ("ToneCurvePV2012Green", "green"), ("ToneCurvePV2012Blue", "blue")]
.map(|(crs, ch)| (curve(props, &format!("crs:{crs}")), ch));
if channels.iter().all(|(c, _)| c.is_some()) {
for (c, ch) in channels {
if let Some(c) = c {
put(o, &format!("curve.{ch}"), c);
}
}
}
}
// ---- Color grading (split toning fields are shared with the older split-toning panel)
n(o, "SplitToningShadowHue", "grading.shadows.hue");
n(o, "SplitToningShadowSaturation", "grading.shadows.sat");
n(o, "ColorGradeShadowLum", "grading.shadows.lum");
n(o, "SplitToningHighlightHue", "grading.highlights.hue");
n(o, "SplitToningHighlightSaturation", "grading.highlights.sat");
n(o, "ColorGradeHighlightLum", "grading.highlights.lum");
n(o, "ColorGradeMidtoneHue", "grading.midtones.hue");
n(o, "ColorGradeMidtoneSat", "grading.midtones.sat");
n(o, "ColorGradeMidtoneLum", "grading.midtones.lum");
n(o, "ColorGradeGlobalHue", "grading.global.hue");
n(o, "ColorGradeGlobalSat", "grading.global.sat");
n(o, "ColorGradeGlobalLum", "grading.global.lum");
n(o, "ColorGradeBlending", "grading.blending");
n(o, "SplitToningBalance", "grading.balance");
// ---- Detail
n(o, "Sharpness", "detail.sharpen_amount");
n(o, "SharpenRadius", "detail.sharpen_radius");
n(o, "SharpenDetail", "detail.sharpen_detail");
n(o, "SharpenEdgeMasking", "detail.sharpen_masking");
n(o, "LuminanceSmoothing", "detail.nr_luminance");
n(o, "LuminanceNoiseReductionDetail", "detail.nr_detail");
n(o, "LuminanceNoiseReductionContrast", "detail.nr_contrast");
n(o, "ColorNoiseReduction", "detail.nr_color");
n(o, "ColorNoiseReductionDetail", "detail.nr_color_detail");
n(o, "ColorNoiseReductionSmoothness", "detail.nr_color_smoothness");
// ---- Effects: post-crop vignette + grain
n(o, "PostCropVignetteAmount", "vignette.amount");
n(o, "PostCropVignetteMidpoint", "vignette.midpoint");
n(o, "PostCropVignetteRoundness", "vignette.roundness");
n(o, "PostCropVignetteFeather", "vignette.feather");
n(o, "PostCropVignetteHighlightContrast", "vignette.highlights");
if let Some(st) = num(props, "crs:PostCropVignetteStyle") {
let style = match st as i64 {
2 => "colorPriority",
3 => "paintOverlay",
_ => "highlightPriority",
};
put(o, "vignette.style", json!(style));
}
n(o, "GrainAmount", "grain.amount");
n(o, "GrainSize", "grain.size");
n(o, "GrainFrequency", "grain.roughness");
// ---- Optics (manual corrections; lens profiles are ours, only the switch carries over).
// Our profile corrections are the file's own (DNG-embedded) ones, which Lightroom applies
// whatever its "Enable Profile Corrections" box says [inferred]: so only an enabling switch
// carries over, and `LensProfileEnable=0` (the default in most presets) leaves ours as it is.
if boolean(props, "crs:LensProfileEnable") == Some(true) {
put(o, "optics.lens_profile", json!(true));
}
if let Some(b) = boolean(props, "crs:AutoLateralCA") {
put(o, "optics.remove_ca", json!(b));
}
n(o, "LensManualDistortionAmount", "optics.distortion");
n(o, "VignetteAmount", "optics.vignetting");
n(o, "VignetteMidpoint", "optics.vignetting_midpoint");
n(o, "DefringePurpleAmount", "optics.defringe_purple_amount");
n(o, "DefringePurpleHueLo", "optics.defringe_purple_hue_lo");
n(o, "DefringePurpleHueHi", "optics.defringe_purple_hue_hi");
n(o, "DefringeGreenAmount", "optics.defringe_green_amount");
n(o, "DefringeGreenHueLo", "optics.defringe_green_hue_lo");
n(o, "DefringeGreenHueHi", "optics.defringe_green_hue_hi");
// ---- Calibration
n(o, "ShadowTint", "calibration.shadows_tint");
n(o, "RedHue", "calibration.red_hue");
n(o, "RedSaturation", "calibration.red_sat");
n(o, "GreenHue", "calibration.green_hue");
n(o, "GreenSaturation", "calibration.green_sat");
n(o, "BlueHue", "calibration.blue_hue");
n(o, "BlueSaturation", "calibration.blue_sat");
// ---- Geometry
n(o, "PerspectiveVertical", "geometry.vertical");
n(o, "PerspectiveHorizontal", "geometry.horizontal");
n(o, "PerspectiveRotate", "geometry.rotate");
n(o, "PerspectiveScale", "geometry.scale");
n(o, "PerspectiveAspect", "geometry.aspect");
n(o, "PerspectiveX", "geometry.offset_x");
n(o, "PerspectiveY", "geometry.offset_y");
if let Some(u) = num(props, "crs:PerspectiveUpright") {
let mode = match u as i64 {
1 => "auto",
2 => "level",
3 => "vertical",
4 => "full",
5 => "guided",
_ => "off",
};
put(o, "geometry.upright", json!(mode));
}
// ---- Crop (normalized edges of the unrotated image + straighten angle)
match boolean(props, "crs:HasCrop") {
Some(true) => {
let e = |k: &str, d: f64| num(props, &format!("crs:Crop{k}")).unwrap_or(d).clamp(0.0, 1.0);
let (l, t, r, b) = (e("Left", 0.0), e("Top", 0.0), e("Right", 1.0), e("Bottom", 1.0));
if r > l && b > t {
put(
o,
"crop.geometry",
json!({"rect": {"x0": l, "y0": t, "x1": r, "y1": b}, "angle": num(props, "crs:CropAngle").unwrap_or(0.0).clamp(-45.0, 45.0)}),
);
}
}
Some(false) => put(o, "crop.geometry", json!({"rect": {"x0": 0.0, "y0": 0.0, "x1": 1.0, "y1": 1.0}, "angle": 0.0})),
None => {}
}
out
}
/// [`to_partial`], plus the adjustments in the packet it could not carry over (field names
/// without the `crs:` prefix, grouped: `CameraProfile`, `Look`, `MaskGroupBasedCorrections`…).
///
/// With `values` (the packet's structured properties), local corrections become masks too
/// ([`crate::crs_masks`]; radial masks fitted to `aspect` = width / height); components that
/// can't be carried over are reported as `Mask: <kind>`.
pub fn to_partial_report(props: &Props, values: Option<&crate::crs_masks::Values>, target: Target, aspect: f64) -> (Value, Vec<String>) {
READ.with(|r| *r.borrow_mut() = Some(Default::default()));
SKIPPED.with(|r| *r.borrow_mut() = Some(Vec::new()));
let mut out = to_partial(props, target);
let mut read = READ.with(|r| r.borrow_mut().take()).unwrap_or_default();
let mut mask_skips = SKIPPED.with(|r| r.borrow_mut().take()).unwrap_or_default();
if let Some(values) = values {
let (masks, skipped) = crate::crs_masks::masks(values, aspect);
let has_masks = values.keys().any(|k| crate::crs_masks::CONTAINERS.contains(&k.as_str()));
// A photo's own packet holds the whole edit: masks it lists but has switched off mean "none", which has to
// be stated to replace the photo's. A preset's masks are added to the photo's, so it states nothing; and
// where a mask could not be carried over, the photo's are left alone.
if !masks.is_empty() || (has_masks && skipped.is_empty() && target != Target::Any) {
put(&mut out, "masks", Value::Array(masks));
}
if has_masks {
read.extend(crate::crs_masks::CONTAINERS.iter().map(|c| c.to_string()));
mask_skips.extend(skipped.into_iter().map(|k| format!("Mask: {k}")));
}
let (spots, skipped) = crate::crs_masks::spots(values, aspect);
let has_spots = values.keys().any(|k| crate::crs_masks::SPOT_CONTAINERS.contains(&k.as_str()));
if !spots.is_empty() || (has_spots && skipped.is_empty() && target != Target::Any) {
put(&mut out, "spots", Value::Array(spots));
}
if has_spots {
read.extend(crate::crs_masks::SPOT_CONTAINERS.iter().map(|c| c.to_string()));
mask_skips.extend(skipped.into_iter().map(|k| format!("Spot: {k}")));
}
}
// fields that only switch a panel on/off or name things: not adjustments by themselves; and
// Point Color slots that are all empty (-1)
let value_is = |k: &str, f: &dyn Fn(&[String]) -> bool| props.get(&format!("crs:{k}")).is_some_and(|v| f(v));
let empty_points = |v: &[String]| v.iter().all(|s| s.split(',').all(|n| n.trim().parse::<f64>().is_ok_and(|x| x == -1.0) || n.trim().is_empty()));
let quiet = |k: &str| {
k.starts_with("Enable")
|| k.starts_with("ToneCurveName")
|| k == "AutoTone"
|| k == "AutoGrayscaleMix"
|| (k == "PointColors" && value_is(k, &empty_points))
// the lens profile's strength, written at its default (100 %) next to every profile
|| (matches!(k, "LensProfileDistortionScale" | "LensProfileVignettingScale") && value_is(k, &|v| v.iter().all(|s| s.trim() == "100")))
};
let mut unmapped: Vec<String> = props
.keys()
.filter(|k| k.starts_with("crs:"))
.map(|k| k.split('/').next().unwrap_or(k))
.filter(|k| !NON_ADJUSTMENT.contains(k) && !read.contains(*k))
.map(|k| k.trim_start_matches("crs:").to_string())
.filter(|k| !quiet(k))
.collect();
unmapped.dedup();
unmapped.extend(mask_skips);
(out, unmapped)
}
/// The selected camera profile name from an XMP packet. The name is metadata only: it does not
/// identify or carry the profile's rendering data.
pub fn camera_profile_name(props: &Props) -> Option<&str> {
first(props, "crs:CameraProfile")
}
/// Whether an XMP packet contains a saved Lightroom Upright matrix. Lightroom's matrix uses a
/// coordinate convention that LightCraft does not currently import.
pub fn has_saved_upright_transform(props: &Props) -> bool {
props.keys().any(|key| {
key.strip_prefix("crs:").is_some_and(|name| {
name.starts_with("UprightTransform_") && props.get(key).is_some_and(|values| values.iter().any(|v| !v.trim().is_empty()))
})
})
}
/// Read an XMP preset (`crs:` fields + `crs:Name` / `crs:Group`) into one of our presets.
/// Returns `None` when the packet has no adjustments we understand.
pub fn preset_from_xmp(xmp: &str, fallback_name: &str) -> Option<Preset> {
let d = craft_metadata::parse_xmp(xmp).ok()?;
let props = &d.properties;
// with the packet's structured properties, so a preset of masks or spots alone is a preset, and one of both
// keeps them (presets have no photo to fit to: 3:2, as `crs_masks` assumes)
let (settings, _) = to_partial_report(props, Some(&d.values), Target::Any, 1.5);
if settings.as_object().is_none_or(Map::is_empty) {
return None;
}
let name = first(props, "crs:Name").unwrap_or(fallback_name).to_string();
let group = first(props, "crs:Group").unwrap_or("Imported Presets").to_string();
let uuid = first(props, "crs:UUID").map(|u| u.to_ascii_lowercase());
let id = format!("user.xmp.{}", uuid.unwrap_or_else(|| crate::presets::slug(&format!("{group}-{name}"))));
Some(Preset { id, name, group, settings, favorite: false, builtin: false })
}
#[cfg(test)]
mod tests;
+357
View File
@@ -0,0 +1,357 @@
use super::*;
use crate::{DevelopSettings, Upright, VignetteStyle, WbMode, apply_partial};
/// A hand-written sidecar in attribute form (as many tools write it).
const SIDECAR: &str = r#"<x:xmpmeta xmlns:x="adobe:ns:meta/">
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/"
crs:Version="99.0" crs:ProcessVersion="11.0" crs:WhiteBalance="Custom" crs:Temperature="5150" crs:Tint="+12"
crs:Exposure2012="+0.65" crs:Contrast2012="-14" crs:Highlights2012="-58" crs:Shadows2012="+41"
crs:Whites2012="+9" crs:Blacks2012="-17" crs:Texture="+6" crs:Clarity2012="+11" crs:Dehaze="+4"
crs:Vibrance="+19" crs:Saturation="-3" crs:HueAdjustmentOrange="-7" crs:SaturationAdjustmentBlue="-22"
crs:LuminanceAdjustmentAqua="+13" crs:ParametricShadows="+5" crs:ParametricHighlights="-8"
crs:ParametricMidtoneSplit="55" crs:CurveRefineSaturation="40" crs:SplitToningShadowHue="210" crs:SplitToningShadowSaturation="14"
crs:SplitToningHighlightHue="40" crs:SplitToningHighlightSaturation="9" crs:SplitToningBalance="+20"
crs:ColorGradeMidtoneHue="120" crs:ColorGradeMidtoneSat="6" crs:ColorGradeBlending="70"
crs:Sharpness="55" crs:SharpenRadius="+1.2" crs:SharpenDetail="30" crs:SharpenEdgeMasking="12"
crs:LuminanceSmoothing="18" crs:ColorNoiseReduction="25" crs:PostCropVignetteAmount="-21"
crs:PostCropVignetteStyle="2" crs:GrainAmount="15" crs:GrainSize="30" crs:GrainFrequency="60"
crs:PerspectiveUpright="2" crs:PerspectiveVertical="-10" crs:AutoLateralCA="1" crs:ConvertToGrayscale="False"
crs:ShadowTint="-7" crs:RedHue="+12" crs:RedSaturation="+20" crs:GreenHue="-5" crs:GreenSaturation="+3"
crs:BlueHue="-15" crs:BlueSaturation="+25"
crs:HasCrop="True" crs:CropTop="0.1" crs:CropLeft="0.05" crs:CropBottom="0.9" crs:CropRight="0.8" crs:CropAngle="1.5">
<crs:ToneCurvePV2012>
<rdf:Seq><rdf:li>0, 0</rdf:li><rdf:li>64, 52</rdf:li><rdf:li>192, 205</rdf:li><rdf:li>255, 255</rdf:li></rdf:Seq>
</crs:ToneCurvePV2012>
<crs:ToneCurvePV2012Red>
<rdf:Seq><rdf:li>0, 0</rdf:li><rdf:li>255, 255</rdf:li></rdf:Seq>
</crs:ToneCurvePV2012Red>
</rdf:Description>
</rdf:RDF>
</x:xmpmeta>"#;
fn props(x: &str) -> Props {
craft_metadata::parse_xmp(x).unwrap().properties
}
#[test]
fn maps_common_fields() {
let p = props(SIDECAR);
let partial = to_partial(&p, Target::RawAbsolute);
let s = apply_partial(&DevelopSettings::for_raw(5000.0, 0.0), &partial, 1.0);
assert!(has_adjustments(&p));
assert_common_tone_fields(&s);
assert_common_color_fields(&s);
assert_common_detail_fields(&s);
assert_common_geometry_fields(&s);
}
fn assert_common_tone_fields(s: &DevelopSettings) {
assert_eq!(s.wb.mode, WbMode::Custom);
assert_eq!((s.wb.temp, s.wb.tint), (5150.0, 12.0));
assert_eq!(s.light.exposure, 0.65);
assert_eq!((s.light.contrast, s.light.highlights, s.light.shadows, s.light.whites, s.light.blacks), (-14.0, -58.0, 41.0, 9.0, -17.0));
assert_eq!((s.effects.texture, s.effects.clarity, s.effects.dehaze), (6.0, 11.0, 4.0));
assert_eq!((s.color.vibrance, s.color.saturation), (19.0, -3.0));
assert_eq!(s.mixer.orange.hue, -7.0);
assert_eq!(s.mixer.blue.sat, -22.0);
assert_eq!(s.mixer.aqua.lum, 13.0);
assert_eq!((s.curve.shadows, s.curve.highlights, s.curve.split_mid), (5.0, -8.0, 55.0));
assert_eq!(s.curve.master.len(), 4);
assert_eq!(s.curve.refine_saturation, 40.0);
assert!((s.curve.master[1].x - 64.0 / 255.0).abs() < 1e-9 && (s.curve.master[1].y - 52.0 / 255.0).abs() < 1e-9);
assert!(s.curve.red.is_empty(), "identity channel curve maps to no curve");
}
fn assert_common_color_fields(s: &DevelopSettings) {
assert_eq!((s.grading.shadows.hue, s.grading.shadows.sat), (210.0, 14.0));
assert_eq!((s.grading.highlights.hue, s.grading.highlights.sat), (40.0, 9.0));
assert_eq!((s.grading.midtones.hue, s.grading.midtones.sat), (120.0, 6.0));
assert_eq!((s.grading.balance, s.grading.blending), (20.0, 70.0));
}
fn assert_common_detail_fields(s: &DevelopSettings) {
assert_eq!((s.detail.sharpen_amount, s.detail.sharpen_radius, s.detail.sharpen_detail, s.detail.sharpen_masking), (55.0, 1.2, 30.0, 12.0));
assert_eq!((s.detail.nr_luminance, s.detail.nr_color), (18.0, 25.0));
assert_eq!(s.vignette.amount, -21.0);
assert_eq!(s.vignette.style, VignetteStyle::ColorPriority);
assert_eq!((s.grain.amount, s.grain.size, s.grain.roughness), (15.0, 30.0, 60.0));
}
fn assert_common_geometry_fields(s: &DevelopSettings) {
assert_eq!(s.geometry.upright, Upright::Level);
assert_eq!(s.geometry.vertical, -10.0);
assert!(s.optics.remove_ca);
assert_eq!(s.treatment, crate::Treatment::Color);
let cal = s.calibration;
assert_eq!(
(cal.shadows_tint, cal.red_hue, cal.red_sat, cal.green_hue, cal.green_sat, cal.blue_hue, cal.blue_sat),
(-7.0, 12.0, 20.0, -5.0, 3.0, -15.0, 25.0)
);
let c = s.crop.geometry;
assert_eq!((c.rect.x0, c.rect.y0, c.rect.x1, c.rect.y1, c.angle), (0.05, 0.1, 0.8, 0.9, 1.5));
}
/// A sidecar curve with a `NaN` or `inf` point (Rust's `parse` reads both) is not a curve:
/// it is left out, rather than stored with a point the curve editor can't place.
#[test]
fn curves_with_non_finite_points_are_left_out() {
for bad in ["NaN, 0", "64, inf", "-inf, 3"] {
let x = SIDECAR.replace("<rdf:li>64, 52</rdf:li>", &format!("<rdf:li>{bad}</rdf:li>"));
let partial = to_partial(&props(&x), Target::RawAbsolute);
let s = apply_partial(&DevelopSettings::for_raw(5000.0, 0.0), &partial, 1.0);
assert!(s.curve.master.is_empty(), "{bad}: {:?}", s.curve.master);
assert!(s.curve.master.iter().all(|p| p.x.is_finite() && p.y.is_finite()));
}
}
#[test]
fn only_present_fields_are_in_the_partial() {
let x = r#"<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><rdf:Description
xmlns:c="http://ns.adobe.com/camera-raw-settings/1.0/" c:Vibrance="+30" c:GrainAmount="10"/></rdf:RDF>"#;
let partial = to_partial(&props(x), Target::Any);
assert_eq!(partial, json!({"color": {"vibrance": 30.0}, "grain": {"amount": 10.0}}));
}
#[test]
fn hdr_edit_mode_turns_hdr_editing_on_or_off() {
let x = |v: &str| {
format!(
r#"<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><rdf:Description
xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/" crs:HDREditMode="{v}" crs:Exposure2012="+1.5"/></rdf:RDF>"#
)
};
let on = apply_partial(&DevelopSettings::default(), &to_partial(&props(&x("1")), Target::RawAbsolute), 1.0);
assert!(on.hdr.enabled);
assert_eq!(on.light.exposure, 1.5);
assert_eq!(on.hdr.max_ev, crate::Hdr::DEFAULT_MAX_EV, "the rest of the HDR settings keep their defaults");
let true_form = apply_partial(&DevelopSettings::default(), &to_partial(&props(&x("True")), Target::RawAbsolute), 1.0);
assert!(true_form.hdr.enabled);
let mut hdr = DevelopSettings::default();
hdr.hdr.enabled = true;
assert!(!apply_partial(&hdr, &to_partial(&props(&x("0")), Target::RawAbsolute), 1.0).hdr.enabled, "0 turns it off");
// without the field nothing about HDR changes
let plain = r#"<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><rdf:Description
xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/" crs:Exposure2012="+1.5"/></rdf:RDF>"#;
assert!(to_partial(&props(plain), Target::RawAbsolute).get("hdr").is_none());
}
#[test]
fn element_form_bw_and_incremental_wb() {
let x = r#"<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/">
<crs:ConvertToGrayscale>True</crs:ConvertToGrayscale>
<crs:GrayMixerBlue>-35</crs:GrayMixerBlue>
<crs:IncrementalTemperature>25</crs:IncrementalTemperature>
<crs:IncrementalTint>-6</crs:IncrementalTint>
<crs:Temperature>4800</crs:Temperature>
</rdf:Description></rdf:RDF></x:xmpmeta>"#;
let p = props(x);
let rendered = apply_partial(&DevelopSettings::default(), &to_partial(&p, Target::Rendered), 1.0);
assert_eq!(rendered.treatment, crate::Treatment::Bw);
assert_eq!(rendered.bw_mix.blue, -35.0);
assert!((rendered.wb.temp - rel_to_kelvin(25.0)).abs() < 1e-6 && rendered.wb.temp > 6500.0);
assert_eq!(rendered.wb.tint, -6.0);
let raw = apply_partial(&DevelopSettings::default(), &to_partial(&p, Target::RawAbsolute), 1.0);
assert_eq!(raw.wb.temp, 4800.0);
}
#[test]
fn named_wb_and_already_applied() {
let x = r#"<rdf:Description xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/"
crs:WhiteBalance="Daylight" crs:Temperature="5500" crs:Tint="10" crs:AlreadyApplied="True"/>"#;
let p = props(x);
assert_eq!(to_partial(&p, Target::RawAbsolute), json!({"wb": {"mode": "daylight"}}));
assert!(!has_adjustments(&p));
let bookkeeping = r#"<rdf:Description xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/" crs:Version="1" crs:HasSettings="True"/>"#;
assert!(!has_adjustments(&props(bookkeeping)));
}
#[test]
fn custom_kelvin_on_relative_wb_raws_shifts_from_the_as_shot_white() {
// Issue storytold/lightcraft#510: a Sony ARW edited in Lightroom to Custom 3578 K / −5 next to an as-shot white
// of 3650 K / −2 (written for this test from the numbers in the issue).
let x = r#"<rdf:Description xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/"
crs:WhiteBalance="Custom" crs:Temperature="3578" crs:Tint="-5" crs:AsShotTemperature="3650" crs:AsShotTint="-2"/>"#;
let p = props(x);
let rel = to_partial(&p, Target::RawRelative);
// 3650 → 3578 K is +5.5 mired: the same shift from 6500 K lands near 6275 K on our scale
let t = rel["wb"]["temp"].as_f64().unwrap();
assert!((t - 6275.0).abs() < 5.0, "{t}");
assert_eq!(rel["wb"]["tint"], -3.0);
assert_eq!(rel["wb"]["mode"], "custom");
// a rendered file without `Incremental*` fields shifts the same way; a raw with a measured
// illuminant (and a preset) keeps the Kelvin value
assert_eq!(to_partial(&p, Target::Rendered)["wb"]["temp"], rel["wb"]["temp"]);
assert_eq!(to_partial(&p, Target::RawAbsolute)["wb"]["temp"], 3578.0);
assert_eq!(to_partial(&p, Target::Any)["wb"]["temp"], 3578.0);
// Kelvin read as Kelvin says so, so it stays Kelvin on a raw with that scale; a shift does not
assert_eq!(to_partial(&p, Target::RawAbsolute)["wb"]["scale"], "kelvin");
assert_eq!(to_partial(&p, Target::Any)["wb"]["scale"], "kelvin");
assert!(rel["wb"].get("scale").is_none() && to_partial(&p, Target::Rendered)["wb"].get("scale").is_none());
// the as-shot fields are a reference, not an adjustment: nothing to report
assert!(to_partial_report(&p, None, Target::RawRelative, 1.5).1.is_empty());
// no tint next to the as-shot tint: the custom tint is taken as the shift itself
let no_tint = props(&x.replace(r#" crs:AsShotTint="-2""#, ""));
assert_eq!(to_partial(&no_tint, Target::RawRelative)["wb"]["tint"], -5.0);
}
#[test]
fn custom_kelvin_without_an_as_shot_reference_stays_as_shot_and_is_reported() {
// The same edit from a Lightroom catalog, which keeps no as-shot white for Custom photos:
// 3578 K read on the relative scale would be a large blue shift (issue storytold/lightcraft#510)
let x = r#"<rdf:Description xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/"
crs:WhiteBalance="Custom" crs:Temperature="3578" crs:Tint="-5" crs:Exposure2012="+0.3"/>"#;
let p = props(x);
let (partial, unmapped) = to_partial_report(&p, None, Target::RawRelative, 1.5);
assert_eq!(partial["wb"], json!({"mode": "asShot"}));
assert_eq!(partial["light"]["exposure"], 0.3);
assert_eq!(unmapped.len(), 1, "{unmapped:?}");
assert!(unmapped[0].starts_with("Temperature, Tint"), "{unmapped:?}");
// a raw with a measured illuminant and a rendered file read it as before, and report nothing
assert_eq!(to_partial(&p, Target::RawAbsolute)["wb"]["temp"], 3578.0);
assert_eq!(to_partial(&p, Target::Rendered)["wb"]["temp"], 3578.0);
assert!(to_partial_report(&p, None, Target::RawAbsolute, 1.5).1.is_empty());
// an unusable reference (zero) counts as none
let zero = props(&x.replace(r#" crs:Tint="-5""#, r#" crs:Tint="-5" crs:AsShotTemperature="0""#));
assert_eq!(to_partial(&zero, Target::RawRelative)["wb"], json!({"mode": "asShot"}));
}
/// Lightroom writes `crs:Temperature` as Kelvin for a raw whose camera LightCraft has matrices for: the value
/// is read as written, marked Kelvin, and the as-shot reference is not needed (issue storytold/lightcraft#730); the same packet on
/// a raw without matrices still takes the storytold/lightcraft#510 shift.
#[test]
fn kelvin_is_direct_on_raws_whose_camera_has_matrices() {
let x = r#"<rdf:Description xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/"
crs:WhiteBalance="Custom" crs:Temperature="4650" crs:Tint="+3" crs:AsShotTemperature="5400" crs:AsShotTint="-1"/>"#;
let p = props(x);
let a7m3 = Target::RawAbsolute; // a camera with measured matrices
assert_eq!(to_partial(&p, a7m3)["wb"], json!({"mode": "custom", "temp": 4650.0, "tint": 3.0, "scale": "kelvin"}));
let a7m2 = Target::RawRelative; // one without
let shifted = to_partial(&p, a7m2);
assert!(shifted["wb"]["temp"].as_f64().is_some_and(|t| t > 5000.0 && t < 6500.0), "{shifted}");
assert_eq!(shifted["wb"]["tint"], 4.0);
assert!(shifted["wb"].get("scale").is_none());
// without the reference the Kelvin camera still reads it, the other stays As Shot
let bare = props(&x.replace(r#" crs:AsShotTemperature="5400" crs:AsShotTint="-1""#, ""));
assert_eq!(to_partial(&bare, a7m3)["wb"]["temp"], 4650.0);
assert_eq!(to_partial(&bare, a7m2)["wb"], json!({"mode": "asShot"}));
// a named preset carries no numbers either way
let daylight = props(&x.replace(r#"crs:WhiteBalance="Custom""#, r#"crs:WhiteBalance="Daylight""#));
assert_eq!(to_partial(&daylight, a7m3)["wb"], json!({"mode": "daylight"}));
}
#[test]
fn xmp_preset_with_name_and_group() {
// Written for this test: a minimal preset-shaped packet with localized name/group.
let x = r#"<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/"
crs:PresetType="Normal" crs:UUID="0123ABCD" crs:Contrast2012="+25" crs:SupportsAmount="True">
<crs:Name><rdf:Alt><rdf:li xml:lang="x-default">Punchy Test</rdf:li></rdf:Alt></crs:Name>
<crs:Group><rdf:Alt><rdf:li xml:lang="x-default">My Looks</rdf:li></rdf:Alt></crs:Group>
</rdf:Description></rdf:RDF></x:xmpmeta>"#;
let p = preset_from_xmp(x, "file").unwrap();
assert_eq!((p.name.as_str(), p.group.as_str(), p.id.as_str()), ("Punchy Test", "My Looks", "user.xmp.0123abcd"));
assert_eq!(p.settings, json!({"light": {"contrast": 25.0}}));
assert!(!p.builtin);
assert!(preset_from_xmp("<x/>", "f").is_none());
}
/// A preset packet (written for this test) with the bookkeeping fields Lightroom presets carry.
fn preset_packet(extra_attrs: &str, extra_elems: &str) -> String {
format!(
r#"<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/"
crs:PresetType="Normal" crs:Cluster="" crs:UUID="0123ABCD" crs:SupportsAmount2="True" crs:SupportsAmount="True"
crs:RequiresRGBTables="False" crs:Contrast2012="+25" crs:LensProfileEnable="0" crs:OverrideLookVignette="False"
crs:CropConstrainToWarp="0" crs:AsShotTemperature="5500" crs:AsShotTint="10" {extra_attrs}>
<crs:SortName><rdf:Alt><rdf:li xml:lang="x-default"/></rdf:Alt></crs:SortName>
<crs:Description><rdf:Alt><rdf:li xml:lang="x-default"/></rdf:Alt></crs:Description>
{extra_elems}
</rdf:Description></rdf:RDF></x:xmpmeta>"#
)
}
#[test]
fn channel_curves_need_the_master_and_all_channel_curves() {
// Lightroom applies red / green / blue curves only when the master and all three are present
let seq = |name: &str, pts: &str| format!("<crs:{name}><rdf:Seq>{pts}</rdf:Seq></crs:{name}>");
let identity = "<rdf:li>0, 0</rdf:li><rdf:li>255, 255</rdf:li>";
// the older single curve, straight: "no curve" is stated, so it replaces a curve the photo has
let legacy = format!(
r#"<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/">{}</rdf:Description></rdf:RDF></x:xmpmeta>"#,
seq("ToneCurve", identity)
);
let straight = to_partial(&props(&legacy), Target::RawAbsolute);
assert_eq!(straight.pointer("/curve/master"), Some(&serde_json::json!([])), "{straight}");
let mut curved = crate::DevelopSettings::default();
curved.curve.master = vec![craft_geom::Point::new(0.0, 0.0), craft_geom::Point::new(0.3, 0.5), craft_geom::Point::new(1.0, 1.0)];
assert!(curved.merged(&straight).unwrap().curve.master.is_empty());
let bent = "<rdf:li>0, 0</rdf:li><rdf:li>64, 40</rdf:li><rdf:li>255, 255</rdf:li>";
let packet = |curves: &[String]| {
format!(
r#"<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/" crs:ToneCurveName2012="Custom">{}
</rdf:Description></rdf:RDF></x:xmpmeta>"#,
curves.concat()
)
};
let partial = |curves: &[String]| to_partial(&props(&packet(curves)), Target::RawAbsolute);
let (master, red, green, blue) = (
seq("ToneCurvePV2012", identity),
seq("ToneCurvePV2012Red", identity),
seq("ToneCurvePV2012Green", bent),
seq("ToneCurvePV2012Blue", identity),
);
// a channel curve alone, or with the master but without its two siblings: ignored
let alone = partial(std::slice::from_ref(&green));
assert!(alone.pointer("/curve/green").is_none(), "{alone}");
let master_and_green = partial(&[master.clone(), green.clone()]);
assert!(master_and_green.pointer("/curve/green").is_none() && master_and_green.pointer("/curve/master").is_some(), "{master_and_green}");
// all four: read
let all = partial(&[master, red, green, blue]);
assert!(["/curve/master", "/curve/red", "/curve/green", "/curve/blue"].iter().all(|p| all.pointer(p).is_some()), "{all}");
}
fn unmapped(x: &str) -> Vec<String> {
to_partial_report(&props(x), None, Target::Any, 1.5).1
}
#[test]
fn preset_bookkeeping_is_not_reported_but_real_gaps_are() {
let empty_points = "<crs:PointColors><rdf:Seq><rdf:li>-1.000000, -1.000000, -1.000000, -1.000000</rdf:li></rdf:Seq></crs:PointColors>";
assert_eq!(unmapped(&preset_packet(r#"crs:HDREditMode="0""#, empty_points)), Vec::<String>::new());
// a used Point Color slot and an unknown adjustment still are (an HDR edit is carried over)
let used_points = "<crs:PointColors><rdf:Seq><rdf:li>0.5, 0.2, 0.1, 10, 0, 0, 0, 0</rdf:li></rdf:Seq></crs:PointColors>";
let got = unmapped(&preset_packet(r#"crs:HDREditMode="1" crs:FutureSlider="12""#, used_points));
assert_eq!(got, ["FutureSlider", "PointColors"]);
}
#[test]
fn lightroom_profile_bookkeeping_is_not_reported() {
// what Lightroom Classic writes next to every raw's edit: none of it changes the rendering
let bookkeeping = r#"crs:CompatibleVersion="268435456" crs:CameraProfileDigest="0A1B" crs:LensProfileDigest="2C3D"
crs:LensProfileName="Sony FE 24-70mm" crs:LensProfileFilename="x.lcp" crs:LensProfileIsEmbedded="False"
crs:LensProfileSetup="LensDefaults" crs:LensProfileDistortionScale="100" crs:LensProfileVignettingScale="100"
crs:CropConstrainToUnitSquare="1""#;
let look = r#"<crs:Look rdf:parseType="Resource"><crs:Name>Vivid</crs:Name></crs:Look>"#;
assert_eq!(unmapped(&preset_packet(bookkeeping, "")), Vec::<String>::new());
assert_eq!(unmapped(&preset_packet(bookkeeping, look)), ["Look"], "the Look is a real gap");
// a lens profile's strength away from 100 % is an adjustment we don't carry over
let scaled = preset_packet(r#"crs:LensProfileDistortionScale="60""#, "");
assert_eq!(unmapped(&scaled), ["LensProfileDistortionScale"]);
}
#[test]
fn disabled_lens_profile_switch_keeps_embedded_corrections() {
// Lightroom applies a file's built-in lens corrections regardless of its profile switch,
// and ours are only those: a preset's `LensProfileEnable=0` must not turn them off
let p = props(&preset_packet("", ""));
let mut d = DevelopSettings::default();
d.optics.lens_profile = true;
assert!(apply_partial(&d, &to_partial(&p, Target::Any), 1.0).optics.lens_profile);
let on = props(&preset_packet("", "").replace(r#"crs:LensProfileEnable="0""#, r#"crs:LensProfileEnable="1""#));
assert!(apply_partial(&DevelopSettings::default(), &to_partial(&on, Target::Any), 1.0).optics.lens_profile);
}
+442
View File
@@ -0,0 +1,442 @@
//! Interchange: local corrections (masks) stored as `crs:` structures in XMP sidecars, XMP
//! presets and `.lrtemplate` files → our [`Mask`](crate::Mask)s.
//!
//! Four containers hold them: `MaskGroupBasedCorrections` (current: each correction has a list
//! of mask components) and the older `GradientBasedCorrections`, `CircularGradientBasedCorrections`
//! and `PaintBasedCorrections`. Every correction carries its local sliders (`Local*`, stored as
//! −1..1 fractions; exposure ×4 EV) and its components (`crs:What` = `Mask/Gradient`,
//! `Mask/CircularGradient`, `Mask/Paint`, `Mask/Image`, `Mask/RangeMask`).
//!
//! Implemented from the public XMP data model and black-box observation; best effort — the
//! pipelines differ, and the component combine modes and AI mask kinds are mapped from what the
//! fields evidently mean. Unsupported components are reported, never guessed.
use std::collections::BTreeMap;
use craft_metadata::XmpValue;
use serde_json::{Value, json};
/// Top-level properties keyed `prefix:name`, with structure.
pub type Values = BTreeMap<String, XmpValue>;
/// The containers this module reads.
pub const CONTAINERS: [&str; 4] =
["crs:MaskGroupBasedCorrections", "crs:GradientBasedCorrections", "crs:CircularGradientBasedCorrections", "crs:PaintBasedCorrections"];
fn text<'a>(v: &'a XmpValue, k: &str) -> Option<&'a str> {
v.field(k).and_then(XmpValue::text).filter(|s| !s.is_empty())
}
fn num(v: &XmpValue, k: &str) -> Option<f64> {
let s = text(v, k)?;
let s = s.strip_prefix('+').unwrap_or(s);
s.parse::<f64>().ok().filter(|x| x.is_finite())
}
fn flag(v: &XmpValue, k: &str) -> Option<bool> {
text(v, k).map(|s| s.eq_ignore_ascii_case("true") || s == "1")
}
/// Local slider fields → (our `adjust` field, scale from the stored fraction).
const LOCAL: &[(&str, &str, f64)] = &[
("LocalExposure2012", "exposure", 4.0),
("LocalContrast2012", "contrast", 100.0),
("LocalHighlights2012", "highlights", 100.0),
("LocalShadows2012", "shadows", 100.0),
("LocalWhites2012", "whites", 100.0),
("LocalBlacks2012", "blacks", 100.0),
("LocalClarity2012", "clarity", 100.0),
("LocalTexture", "texture", 100.0),
("LocalDehaze", "dehaze", 100.0),
("LocalTemperature", "temp", 100.0),
("LocalTint", "tint", 100.0),
("LocalSaturation", "saturation", 100.0),
("LocalHue", "hue", 100.0),
("LocalSharpness", "sharpness", 100.0),
("LocalLuminanceNoise", "noise", 100.0),
("LocalMoire", "moire", 100.0),
("LocalDefringe", "defringe", 100.0),
("LocalToningSaturation", "color_sat", 100.0),
("LocalToningHue", "color_hue", 1.0),
// older process versions
("LocalExposure", "exposure", 4.0),
("LocalContrast", "contrast", 100.0),
("LocalClarity", "clarity", 100.0),
];
/// Is `crs` (without the `crs:` prefix) a local slider field we map?
pub fn is_local_field(crs: &str) -> bool {
LOCAL.iter().any(|(k, _, _)| *k == crs)
}
/// Our local adjustment values from the `Local*` slider fields that `get` finds (the name without
/// the `crs:` prefix → the stored fraction); process-version 2012 fields win over the older ones.
pub fn local_values(get: impl Fn(&str) -> Option<f64>) -> serde_json::Map<String, Value> {
let mut a = serde_json::Map::new();
for (crs, ours, k) in LOCAL {
if a.contains_key(*ours) {
continue;
}
if let Some(v) = get(crs).filter(|v| v.is_finite()) {
let lim = if *ours == "exposure" {
4.0
} else if *ours == "color_hue" {
360.0
} else {
100.0
};
let v = (v * k).clamp(if *ours == "color_hue" { 0.0 } else { -lim }, lim);
a.insert((*ours).into(), json!(v));
}
}
a
}
fn adjust(c: &XmpValue) -> Value {
let mut a = local_values(|crs| num(c, &format!("crs:{crs}")));
let amount = num(c, "crs:CorrectionAmount").unwrap_or(1.0);
a.insert("amount".into(), json!((amount * 100.0).clamp(0.0, 200.0)));
Value::Object(a)
}
/// The correction's local sliders we have no counterpart for (e.g. `LocalGrain`), when set:
/// reported, never dropped silently.
fn unmapped_local(c: &XmpValue) -> Vec<String> {
let XmpValue::Struct(m) = c else { return Vec::new() };
m.keys()
.filter_map(|k| {
let field = k.strip_prefix("crs:").filter(|f| f.starts_with("Local"))?;
// 100 = "curve saturation unchanged", written with every correction
let neutral = if field == "LocalCurveRefineSaturation" { 100.0 } else { 0.0 };
let set = num(c, k).is_some_and(|v| v != neutral);
(set && !LOCAL.iter().any(|(crs, ..)| *crs == field)).then(|| field.to_string())
})
.collect()
}
/// Perceptual lightness 0..1 (how range masks store luminance) → our range scale: log
/// luminance on −8..+4 EV mapped to 0..1.
fn lightness_to_range(l: f64) -> f64 {
let y = l.clamp(1e-4, 1.0).powf(2.2);
((y.log2() + 8.0) / 12.0).clamp(0.0, 1.0)
}
/// A range mask's four numbers (`"0 0.2 0.8 1"`; everything when the field is absent). `None` unless there are
/// exactly four and all are finite: a `NaN` would become `null` in the JSON and fail the whole merge.
fn range(s: Option<&str>) -> Option<[f64; 4]> {
let q: Vec<f64> = s.unwrap_or("0 0 1 1").split_whitespace().map(|v| v.parse().ok().filter(|v: &f64| v.is_finite())).collect::<Option<_>>()?;
q.try_into().ok()
}
/// The point of one `crs:Dabs` entry (`"d x y"`), or `None` when it has no two finite numbers: `"nan"` and
/// `"inf"` parse as numbers, and a point of them is JSON `null`, which no settings accept, so one damaged dab
/// would keep every adjustment in the packet from applying.
fn dab(d: &str) -> Option<Value> {
let mut it = d.split_whitespace().skip(1).filter_map(|v| v.parse::<f64>().ok());
let (x, y) = (it.next()?, it.next()?);
(x.is_finite() && y.is_finite()).then(|| pt(x, y))
}
fn pt(x: f64, y: f64) -> Value {
json!({"x": x, "y": y})
}
/// Whether a `Mask/CircularGradient` component puts its effect inside the ellipse, given the
/// container it came from (`crs:Flipped` means different things in different formats).
///
/// What Lightroom Classic does, from its exports of synthetic DNGs whose masks we wrote (issue storytold/lightcraft#1815):
/// - **`MaskGroupBasedCorrections`, `crs:Version` ≥ 2** (what Lightroom writes today): an ordinary
/// radial — effect inside — is written `Flipped="true"`, so `Flipped` is the "inside" flag.
/// Inverting the mask is a separate field, `crs:MaskInverted` (see [`component`]). `Flipped="false"`
/// is read as outside, the same sense as the legacy filter's; Lightroom never wrote one for us.
/// - **`MaskGroupBasedCorrections` without `crs:Version`**: Lightroom renders the effect inside
/// whatever `Flipped` says, and rewrites both `Flipped="false"` and `"true"` as `Flipped="true"`
/// with `Version="2"`. So `Flipped` is ignored here.
/// - **`CircularGradientBasedCorrections`** (the process-2012 Radial Filter): its default effect was
/// outside, and "Invert Mask" — effect inside — was recorded as `Flipped="true"`. The same "inside"
/// flag as version 2, with outside as the default when it is missing.
fn radial_inside(m: &XmpValue, container: &str) -> bool {
let flipped = flag(m, "crs:Flipped");
if container == "crs:MaskGroupBasedCorrections" {
if num(m, "crs:Version").is_some_and(|v| v >= 2.0) { flipped.unwrap_or(true) } else { true }
} else {
flipped.unwrap_or(false)
}
}
/// A `Mask/CircularGradient` component's feather on our 0..100 scale.
///
/// Lightroom halves `crs:Feather` when it upgrades a `MaskGroupBasedCorrections` radial without
/// `crs:Version` to version 2 (50 → 25, 100 → 50) and renders both the same, so the version-less
/// value is on twice the scale. Version 2's value is used as it is: its 25 and 50 put the middle of
/// Lightroom's fall-off at about 0.87 and 0.76 of the radius, ours at about 0.86 and 0.73. (The
/// shape differs: Lightroom's fall-off straddles the ellipse edge, ours ends at it.) The legacy
/// Radial Filter's value is used as it is: no observation says otherwise.
fn radial_feather(m: &XmpValue, container: &str) -> f64 {
let f = num(m, "crs:Feather").unwrap_or(50.0);
let versionless_group = container == "crs:MaskGroupBasedCorrections" && !num(m, "crs:Version").is_some_and(|v| v >= 2.0);
(if versionless_group { f / 2.0 } else { f }).clamp(0.0, 100.0)
}
/// One mask component of a correction in `container` → our component JSON; `Err(kind)` names an
/// unsupported one.
fn component(m: &XmpValue, container: &str, aspect: f64) -> Result<Value, String> {
let what = text(m, "crs:What").unwrap_or("");
let op = match num(m, "crs:MaskBlendMode").unwrap_or(0.0) as i64 {
1 => "subtract",
2 => "intersect",
_ => "add",
};
let invert = flag(m, "crs:MaskInverted").unwrap_or(false);
// positions are fractions of the image's width / height; our radii are in long-edge units
let (sx, sy) = if aspect >= 1.0 { (1.0, 1.0 / aspect) } else { (aspect, 1.0) };
let shape = match what {
"Mask/Gradient" => {
let g = |k: &str, d: f64| num(m, &format!("crs:{k}")).unwrap_or(d);
json!({"kind": "linear", "start": pt(g("FullX", 0.5), g("FullY", 0.0)), "end": pt(g("ZeroX", 0.5), g("ZeroY", 1.0))})
}
"Mask/CircularGradient" => {
let g = |k: &str, d: f64| num(m, &format!("crs:{k}")).unwrap_or(d);
let (l, r, t, b) = (g("Left", 0.25), g("Right", 0.75), g("Top", 0.25), g("Bottom", 0.75));
json!({
"kind": "radial",
"center": pt((l + r) / 2.0, (t + b) / 2.0),
"rx": ((r - l).abs() / 2.0 * sx).max(1e-3),
"ry": ((b - t).abs() / 2.0 * sy).max(1e-3),
"angle": g("Angle", 0.0),
"feather": radial_feather(m, container),
// our radial's `invert` = effect outside; `crs:MaskInverted` stays the component's
"invert": !radial_inside(m, container),
})
}
"Mask/Paint" => {
let pts: Vec<Value> =
m.field("crs:Dabs").map(XmpValue::items).unwrap_or_default().iter().filter_map(XmpValue::text).filter_map(dab).collect();
if pts.is_empty() {
return Err("empty brush".into());
}
let erase = num(m, "crs:MaskValue").is_some_and(|v| v <= 0.0);
json!({"kind": "brush", "strokes": [{
"points": pts,
"size": num(m, "crs:Radius").unwrap_or(0.03).clamp(0.001, 1.0),
"feather": (num(m, "crs:CenterWeight").unwrap_or(0.5) * 100.0).clamp(0.0, 100.0),
"flow": (num(m, "crs:Flow").unwrap_or(1.0) * 100.0).clamp(0.0, 100.0),
"density": (num(m, "crs:MaskValue").unwrap_or(1.0).abs() * 100.0).clamp(0.0, 100.0),
"erase": erase,
}]})
}
"Mask/Image" => match text(m, "crs:MaskSubType") {
Some("1") => json!({"kind": "subject"}),
Some("2") => json!({"kind": "sky"}),
other => return Err(format!("AI mask ({})", other.unwrap_or("?"))),
},
"Mask/RangeMask" => {
let r = m.field("crs:CorrectionRangeMask").unwrap_or(m);
match text(r, "crs:Type") {
Some("2") => {
let Some([a, b, c, d]) = range(text(r, "crs:LumRange")) else { return Err("luminance range".into()) };
// full strength at white (1, the top of their scale) takes in everything brighter: ours
// goes on above scene white, so that end stays open instead of cutting off at 0 EV
let open_top = c >= 1.0;
let (a, b, c, d) = (lightness_to_range(a), lightness_to_range(b), lightness_to_range(c), lightness_to_range(d));
let (hi, hi_feather) = if open_top { (1.0, 0.0) } else { (c, (d - c).max(0.0)) };
json!({"kind": "luminanceRange", "lo": b, "hi": hi, "lo_feather": (b - a).max(0.0), "hi_feather": hi_feather})
}
Some("3") => {
let Some([a, b, c, _]) = range(text(r, "crs:DepthRange")) else { return Err("depth range".into()) };
json!({"kind": "depthRange", "lo": b, "hi": c, "feather": (b - a).max(0.0)})
}
_ => return Err("colour range".into()),
}
}
other => return Err(if other.is_empty() { "unknown mask".into() } else { other.trim_start_matches("Mask/").to_string() }),
};
Ok(json!({"op": op, "invert": invert, "shape": shape}))
}
/// Masks in `values` (JSON for `DevelopSettings::masks`), plus the kinds of component that
/// couldn't be carried over. `aspect` = width / height of the target (presets: assume 3:2).
pub fn masks(values: &Values, aspect: f64) -> (Vec<Value>, Vec<String>) {
let mut out = Vec::new();
let mut skipped = Vec::new();
for container in CONTAINERS {
let Some(list) = values.get(container) else { continue };
for c in list.items() {
if flag(c, "crs:CorrectionActive") == Some(false) {
continue;
}
let comps = c.field("crs:CorrectionMasks").map(XmpValue::items).unwrap_or_default();
let mut parts = Vec::new();
for m in comps {
match component(m, container, aspect) {
Ok(v) => parts.push(v),
Err(kind) => skipped.push(kind),
}
}
if parts.is_empty() {
continue;
}
skipped.extend(unmapped_local(c));
// brush dabs of one correction are one brush component
let mut merged: Vec<Value> = Vec::new();
// where the brush of each op and sense sits in `merged` (no scan of it per dab): an inverted run
// and a plain one paint different areas, so they stay two components
let mut brush_at: std::collections::HashMap<String, usize> = std::collections::HashMap::new();
for p in parts {
let is_brush = p["shape"]["kind"] == "brush";
let key = format!("{} {}", p["op"], p["invert"]);
if is_brush
&& let Some(prev) = brush_at.get(&key).and_then(|&i| merged.get_mut(i))
&& let (Some(a), Some(b)) = (prev["shape"]["strokes"].as_array_mut(), p["shape"]["strokes"].as_array())
{
a.extend(b.iter().cloned());
continue;
}
if is_brush {
brush_at.insert(key, merged.len());
}
merged.push(p);
}
let n = out.len() + 1;
let name = text(c, "crs:CorrectionName").map(str::to_string).unwrap_or_else(|| format!("Mask {n}"));
out.push(json!({"id": n, "name": name, "visible": true, "invert": false, "components": merged, "adjust": adjust(c)}));
}
}
skipped.sort();
skipped.dedup();
(out, skipped)
}
/// The containers spot removal is stored in: `RetouchAreas` (current, one struct per spot with a
/// mask component) and `RetouchInfo` (older, one `key = value, …` line per spot; still written
/// beside `RetouchAreas` for older readers and read on its own when that is all there is).
pub const SPOT_CONTAINERS: [&str; 2] = ["crs:RetouchAreas", "crs:RetouchInfo"];
/// One `RetouchAreas` item → a [`Spot`](crate::Spot) as JSON. `aspect` = width /
/// height of the target: horizontal sizes are stored as fractions of the width, ours of the long
/// edge. Returns the component kind it can't carry over.
fn spot(item: &XmpValue, aspect: f64) -> Result<Value, String> {
let mode = match text(item, "crs:SpotType") {
Some("clone") => "clone",
_ => "heal",
};
let comps = item.field("crs:Masks").map(XmpValue::items).unwrap_or_default();
let Some(m) = comps.first() else { return Err("spot without a mask".into()) };
let width_to_long = aspect.min(1.0);
let (points, size) = match text(m, "crs:What").unwrap_or("") {
// a circle: centre + half-sizes in image fractions
"Mask/Ellipse" => {
let (Some(x), Some(y), Some(sx)) = (num(m, "crs:X"), num(m, "crs:Y"), num(m, "crs:SizeX")) else {
return Err("ellipse spot".into());
};
(vec![pt(x, y)], sx * width_to_long)
}
// the shape exiftool's schema also allows for a spot
"Mask/CircularGradient" => {
let (Some(t), Some(l), Some(b), Some(r)) = (num(m, "crs:Top"), num(m, "crs:Left"), num(m, "crs:Bottom"), num(m, "crs:Right")) else {
return Err("circular spot".into());
};
(vec![pt((l + r) / 2.0, (t + b) / 2.0)], (r - l).abs() / 2.0 * width_to_long)
}
// a brushed removal: the dabs are the path
"Mask/Paint" => {
let pts: Vec<Value> =
m.field("crs:Dabs").map(XmpValue::items).unwrap_or_default().iter().filter_map(XmpValue::text).filter_map(dab).collect();
if pts.is_empty() {
return Err("empty brushed spot".into());
}
(pts, num(m, "crs:Radius").unwrap_or(0.02))
}
other => return Err(if other.is_empty() { "unknown spot".into() } else { other.trim_start_matches("Mask/").to_string() }),
};
let size = size.clamp(0.001, 0.25);
// the source is stored as its absolute position (`SourceX`, and `OffsetY` despite the name);
// ours is the offset from the target; anything but an explicit source leaves it automatic
let explicit = text(item, "crs:SourceState").is_none_or(|s| s == "sourceSetExplicitly");
let source_offset = match (explicit, num(item, "crs:SourceX"), num(item, "crs:OffsetY"), points.first()) {
(true, Some(sx), Some(sy), Some(p)) => {
let (Some(x), Some(y)) = (p["x"].as_f64(), p["y"].as_f64()) else { return Err("spot centre".into()) };
let (dx, dy) = (sx - x, sy - y);
(dx.is_finite() && dy.is_finite() && (dx != 0.0 || dy != 0.0)).then(|| pt(dx, dy))
}
_ => None,
};
let feather = (num(item, "crs:Feather").unwrap_or(0.0) * 100.0).clamp(0.0, 100.0);
let opacity = (num(item, "crs:Opacity").unwrap_or(1.0) * 100.0).clamp(0.0, 100.0);
Ok(json!({"mode": mode, "points": points, "size": size, "feather": feather, "opacity": opacity, "source_offset": source_offset}))
}
/// One `RetouchInfo` line (`centerX = 0.5, centerY = 0.5, radius = 0.01, sourceState = …,
/// sourceX = …, sourceY = …, spotType = heal`) → a spot as JSON.
fn legacy_spot(line: &str, aspect: f64) -> Option<Value> {
let mut kv = BTreeMap::new();
for part in line.split(',') {
if let Some((k, v)) = part.split_once('=') {
kv.insert(k.trim().to_string(), v.trim().to_string());
}
}
let f = |k: &str| kv.get(k).and_then(|s| s.parse::<f64>().ok()).filter(|x| x.is_finite());
let (x, y, r) = (f("centerX")?, f("centerY")?, f("radius")?);
let mode = if kv.get("spotType").is_some_and(|s| s == "clone") { "clone" } else { "heal" };
let explicit = kv.get("sourceState").is_none_or(|s| s == "sourceSetExplicitly");
let source_offset = match (explicit, f("sourceX"), f("sourceY")) {
(true, Some(sx), Some(sy)) if sx != x || sy != y => Some(pt(sx - x, sy - y)),
_ => None,
};
let opacity = (f("opacity").unwrap_or(1.0) * 100.0).clamp(0.0, 100.0);
Some(
json!({"mode": mode, "points": [pt(x, y)], "size": (r * aspect.min(1.0)).clamp(0.001, 0.25), "feather": 0.0, "opacity": opacity, "source_offset": source_offset}),
)
}
/// Spot removal in `values` (JSON for `DevelopSettings::spots`), plus the kinds of spot that
/// couldn't be carried over. `aspect` = width / height of the target (presets: assume 3:2).
pub fn spots(values: &Values, aspect: f64) -> (Vec<Value>, Vec<String>) {
let mut out = Vec::new();
let mut skipped = Vec::new();
let current = values.get("crs:RetouchAreas");
if let Some(list) = current {
for item in list.items() {
match spot(item, aspect) {
Ok(v) => out.push(v),
Err(kind) => skipped.push(kind),
}
}
}
// the older list is read only from a packet without the current one: beside it, it is what the spots were
// before (an emptied `RetouchAreas` means they were removed)
if current.is_none()
&& let Some(list) = values.get("crs:RetouchInfo")
{
out.extend(list.items().iter().filter_map(XmpValue::text).filter_map(|l| legacy_spot(l, aspect)));
}
skipped.sort();
skipped.dedup();
(out, skipped)
}
/// The aspect radial masks are computed for when the target's shape isn't known yet.
pub const DEFAULT_ASPECT: f64 = 1.5;
/// Re-fit radial masks in `partial` (computed for aspect `from`) to a target of aspect `to`.
pub fn refit_radials(partial: &mut Value, from: f64, to: f64) {
let scale = |a: f64| if a >= 1.0 { (1.0, 1.0 / a) } else { (a, 1.0) };
let ((fx, fy), (tx, ty)) = (scale(from), scale(to));
let Some(masks) = partial.get_mut("masks").and_then(Value::as_array_mut) else { return };
for m in masks {
for c in m["components"].as_array_mut().into_iter().flatten() {
let s = &mut c["shape"];
if s["kind"] == "radial" {
if let Some(rx) = s["rx"].as_f64() {
s["rx"] = json!(rx / fx * tx);
}
if let Some(ry) = s["ry"].as_f64() {
s["ry"] = json!(ry / fy * ty);
}
}
}
}
}
#[cfg(test)]
mod tests;
+340
View File
@@ -0,0 +1,340 @@
use super::*;
use crate::{DevelopSettings, MaskOp, MaskShape};
/// A packet in the shape local corrections take (values written for this test).
const PACKET: &str = r#"<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/" crs:Exposure2012="0.2">
<crs:MaskGroupBasedCorrections><rdf:Seq>
<rdf:li><rdf:Description crs:What="Correction" crs:CorrectionAmount="1" crs:CorrectionActive="true" crs:CorrectionName="Darker sky"
crs:LocalExposure2012="-0.25" crs:LocalSaturation="0.3" crs:LocalTemperature="-0.1">
<crs:CorrectionMasks><rdf:Seq>
<rdf:li crs:What="Mask/Image" crs:MaskSubType="2" crs:MaskBlendMode="0" crs:MaskInverted="false"/>
<rdf:li crs:What="Mask/Gradient" crs:MaskBlendMode="2" crs:FullX="0.5" crs:FullY="0" crs:ZeroX="0.5" crs:ZeroY="0.6"/>
</rdf:Seq></crs:CorrectionMasks>
</rdf:Description></rdf:li>
<rdf:li><rdf:Description crs:What="Correction" crs:CorrectionAmount="0.5" crs:LocalContrast2012="0.2">
<crs:CorrectionMasks><rdf:Seq>
<rdf:li crs:What="Mask/CircularGradient" crs:Top="0.3" crs:Left="0.2" crs:Bottom="0.7" crs:Right="0.8" crs:Angle="10" crs:Feather="40" crs:Flipped="true" crs:Version="2"/>
<rdf:li crs:What="Mask/RangeMask" crs:MaskBlendMode="2"><crs:CorrectionRangeMask crs:Type="2" crs:LumRange="0.4 0.5 0.8 0.9"/></rdf:li>
<rdf:li crs:What="Mask/Image" crs:MaskSubType="9"/>
</rdf:Seq></crs:CorrectionMasks>
</rdf:Description></rdf:li>
<rdf:li><rdf:Description crs:What="Correction" crs:CorrectionActive="false" crs:LocalExposure2012="1">
<crs:CorrectionMasks><rdf:Seq><rdf:li crs:What="Mask/Image" crs:MaskSubType="1"/></rdf:Seq></crs:CorrectionMasks>
</rdf:Description></rdf:li>
</rdf:Seq></crs:MaskGroupBasedCorrections>
<crs:PaintBasedCorrections><rdf:Seq>
<rdf:li crs:What="Correction" crs:LocalClarity2012="0.4"><crs:CorrectionMasks><rdf:Seq>
<rdf:li crs:What="Mask/Paint" crs:Radius="0.05" crs:Flow="0.8" crs:CenterWeight="0.3" crs:MaskValue="1">
<crs:Dabs><rdf:Seq><rdf:li>d 0.1 0.2</rdf:li><rdf:li>d 0.15 0.22</rdf:li></rdf:Seq></crs:Dabs></rdf:li>
<rdf:li crs:What="Mask/Paint" crs:Radius="0.02" crs:MaskValue="1"><crs:Dabs><rdf:Seq><rdf:li>d 0.5 0.5</rdf:li></rdf:Seq></crs:Dabs></rdf:li>
</rdf:Seq></crs:CorrectionMasks></rdf:li>
</rdf:Seq></crs:PaintBasedCorrections>
</rdf:Description></rdf:RDF></x:xmpmeta>"#;
fn settings() -> (DevelopSettings, Vec<String>) {
let d = craft_metadata::parse_xmp(PACKET).unwrap();
let (partial, unmapped) = crate::crs::to_partial_report(&d.properties, Some(&d.values), crate::crs::Target::Any, 1.5);
(DevelopSettings::default().merged(&partial).expect("valid settings"), unmapped)
}
#[test]
fn corrections_become_masks() {
let (s, unmapped) = settings();
assert_eq!(s.light.exposure, 0.2, "global settings still map");
assert_eq!(s.masks.len(), 3, "inactive corrections are skipped: {:?}", s.masks);
let sky = &s.masks[0];
assert_eq!(sky.name, "Darker sky");
assert_eq!((sky.adjust.exposure, sky.adjust.saturation, sky.adjust.temp, sky.adjust.amount), (-1.0, 30.0, -10.0, 100.0));
assert_eq!(sky.components[0].shape, MaskShape::Sky);
assert_eq!(sky.components[1].op, MaskOp::Intersect);
let MaskShape::Linear { start, end } = &sky.components[1].shape else { panic!() };
assert_eq!((start.y, end.y), (0.0, 0.6), "full effect at the Full point");
let rad = &s.masks[1];
assert_eq!((rad.name.as_str(), rad.adjust.contrast, rad.adjust.amount), ("Mask 2", 20.0, 50.0));
let MaskShape::Radial { center, rx, ry, angle, feather, invert } = &rad.components[0].shape else { panic!() };
assert!((center.x - 0.5).abs() < 1e-9 && (center.y - 0.5).abs() < 1e-9);
assert!((rx - 0.3).abs() < 1e-9 && (ry - 0.2 / 1.5).abs() < 1e-9, "radii in long-edge units: {rx} {ry}");
assert_eq!((*angle, *feather, *invert), (10.0, 40.0, false), "Flipped=\"true\" is Lightroom's ordinary radial: effect inside");
assert!(!rad.components[0].invert);
let MaskShape::LuminanceRange { lo, hi, lo_feather, .. } = &rad.components[1].shape else { panic!() };
assert!(lo < hi && *lo_feather > 0.0);
let brush = &s.masks[2];
assert_eq!(brush.adjust.clarity, 40.0);
assert_eq!(brush.components.len(), 1, "the brush's dab runs are one component");
let MaskShape::Brush { strokes } = &brush.components[0].shape else { panic!() };
assert_eq!((strokes.len(), strokes[0].points.len(), strokes[0].flow, strokes[0].feather), (2, 2, 80.0, 30.0));
assert_eq!(unmapped, vec!["Mask: AI mask (9)".to_string()]);
}
#[test]
fn range_to_white_stays_open_and_unmapped_local_sliders_are_reported() {
// written for this test: a highlights range (full from 0.85 up to white) carrying a local slider we lack
let x = r#"<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/">
<crs:MaskGroupBasedCorrections><rdf:Seq>
<rdf:li><rdf:Description crs:What="Correction" crs:LocalClarity2012="-0.3" crs:LocalGrain="0.4" crs:LocalCurveRefineSaturation="100">
<crs:CorrectionMasks><rdf:Seq>
<rdf:li crs:What="Mask/RangeMask"><crs:CorrectionRangeMask crs:Type="2" crs:LumRange="0.6 0.85 1 1"/></rdf:li>
</rdf:Seq></crs:CorrectionMasks>
</rdf:Description></rdf:li>
</rdf:Seq></crs:MaskGroupBasedCorrections>
</rdf:Description></rdf:RDF></x:xmpmeta>"#;
let d = craft_metadata::parse_xmp(x).unwrap();
let (partial, unmapped) = crate::crs::to_partial_report(&d.properties, Some(&d.values), crate::crs::Target::Any, 1.5);
let s = DevelopSettings::default().merged(&partial).expect("valid settings");
let MaskShape::LuminanceRange { hi, hi_feather, .. } = &s.masks[0].components[0].shape else { panic!() };
assert_eq!((*hi, *hi_feather), (1.0, 0.0), "brighter than scene white is still in the range");
assert_eq!(s.masks[0].adjust.clarity, -30.0);
assert_eq!(unmapped, ["Mask: LocalGrain"], "a refine saturation of 100 is neutral, not reported");
}
#[test]
fn presets_add_masks_once() {
let (s, _) = settings();
let partial = json!({"masks": serde_json::to_value(&s.masks).unwrap(), "light": {"exposure": 0.5}});
let p = crate::Preset { id: "t".into(), name: "t".into(), group: "g".into(), settings: partial, favorite: false, builtin: false };
let mut mine = DevelopSettings::default();
mine.masks.push(crate::Mask { id: 7, name: "Mine".into(), ..Default::default() });
let once = p.apply(&mine, 1.0);
assert_eq!(once.masks.len(), 4, "added to the photo's own mask");
assert_eq!(once.masks[1].id, 8, "fresh ids");
assert_eq!(p.apply(&once, 1.0).masks.len(), 4, "applying again adds nothing");
let half = p.apply(&mine, 0.5);
assert_eq!(half.masks[1].adjust.amount, 50.0, "amount scales the masks");
}
/// One radial correction in `container`, with `attrs` on its mask component (values written
/// for this test; the component attributes follow what Lightroom Classic writes).
fn radial_packet(container: &str, attrs: &str) -> String {
format!(
r#"<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/" crs:Exposure2012="0">
<crs:{container}><rdf:Seq>
<rdf:li><rdf:Description crs:What="Correction" crs:CorrectionAmount="1" crs:LocalExposure2012="0.25">
<crs:CorrectionMasks><rdf:Seq>
<rdf:li crs:What="Mask/CircularGradient" crs:MaskValue="1" crs:Top="0.25" crs:Left="0.25" crs:Bottom="0.75" crs:Right="0.75" crs:Angle="0" crs:Midpoint="50" crs:Roundness="0" {attrs}/>
</rdf:Seq></crs:CorrectionMasks>
</rdf:Description></rdf:li>
</rdf:Seq></crs:{container}>
</rdf:Description></rdf:RDF></x:xmpmeta>"#
)
}
fn radial_settings(container: &str, attrs: &str) -> DevelopSettings {
let d = craft_metadata::parse_xmp(&radial_packet(container, attrs)).unwrap();
let (partial, unmapped) = crate::crs::to_partial_report(&d.properties, Some(&d.values), crate::crs::Target::Any, 1.5);
assert!(unmapped.is_empty(), "{unmapped:?}");
let s = DevelopSettings::default().merged(&partial).unwrap();
assert_eq!(s.masks.len(), 1, "{:?}", s.masks);
s
}
/// (the radial's `invert`, its feather, the component's `invert`).
fn radial_of(s: &DevelopSettings) -> (bool, f64, bool) {
let c = &s.masks[0].components[0];
let MaskShape::Radial { invert, feather, .. } = &c.shape else { panic!("{:?}", c.shape) };
(*invert, *feather, c.invert)
}
#[test]
fn lightroom_radial_flipped_is_inside() {
// as Lightroom Classic writes an ordinary radial mask today (storytold/lightcraft#1815)
let s = radial_settings("MaskGroupBasedCorrections", r#"crs:MaskInverted="false" crs:Feather="25" crs:Flipped="true" crs:Version="2""#);
assert_eq!(radial_of(&s), (false, 25.0, false));
// no MaskInverted at all reads the same
let s = radial_settings("MaskGroupBasedCorrections", r#"crs:Feather="25" crs:Flipped="true" crs:Version="2""#);
assert_eq!(radial_of(&s), (false, 25.0, false));
}
#[test]
fn lightroom_radial_mask_inverted_is_outside() {
let s = radial_settings("MaskGroupBasedCorrections", r#"crs:MaskInverted="true" crs:Feather="25" crs:Flipped="true" crs:Version="2""#);
assert_eq!(radial_of(&s), (false, 25.0, true), "the inversion is the component's");
// version 2 with Flipped="false": outside, the legacy sense of the flag
let s = radial_settings("MaskGroupBasedCorrections", r#"crs:MaskInverted="false" crs:Feather="25" crs:Flipped="false" crs:Version="2""#);
assert_eq!(radial_of(&s), (true, 25.0, false));
}
#[test]
fn versionless_group_radial_is_inside_with_half_the_feather() {
// Lightroom renders both inside and rewrites them Flipped="true", Feather halved, Version="2"
for flipped in ["true", "false"] {
let s = radial_settings("MaskGroupBasedCorrections", &format!(r#"crs:MaskInverted="false" crs:Feather="50" crs:Flipped="{flipped}""#));
assert_eq!(radial_of(&s), (false, 25.0, false), "Flipped={flipped}");
}
}
#[test]
fn legacy_radial_filter_is_outside_unless_flipped() {
// the process-2012 Radial Filter: effect outside by default, "Invert Mask" = Flipped="true"
let s = radial_settings("CircularGradientBasedCorrections", r#"crs:Feather="50" crs:Flipped="false""#);
assert_eq!(radial_of(&s), (true, 50.0, false));
assert_eq!(radial_of(&radial_settings("CircularGradientBasedCorrections", r#"crs:Feather="50""#)), (true, 50.0, false));
let s = radial_settings("CircularGradientBasedCorrections", r#"crs:Feather="50" crs:Flipped="true""#);
assert_eq!(radial_of(&s), (false, 50.0, false));
}
/// Spot removal in the shape Lightroom Classic writes it (values written for this test):
/// a healed circle with an explicit source, a cloned circle with an automatic source, a
/// brushed removal, a circular-gradient spot, one without a mask, and the legacy list.
const SPOTS: &str = r#"<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="" xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/" crs:Exposure2012="0.1">
<crs:RetouchInfo><rdf:Seq>
<rdf:li>centerX = 0.4, centerY = 0.3, radius = 0.01, sourceState = sourceSetExplicitly, sourceX = 0.45, sourceY = 0.3, spotType = heal</rdf:li>
</rdf:Seq></crs:RetouchInfo>
<crs:RetouchAreas><rdf:Seq>
<rdf:li><rdf:Description crs:SpotType="heal" crs:SourceState="sourceSetExplicitly" crs:Method="poisson" crs:SourceX="0.45" crs:OffsetY="0.3" crs:Opacity="1" crs:Feather="0" crs:Seed="1">
<crs:Masks><rdf:Seq><rdf:li crs:What="Mask/Ellipse" crs:MaskActive="true" crs:MaskValue="1" crs:X="0.4" crs:Y="0.3" crs:SizeX="0.01" crs:SizeY="0.015"/></rdf:Seq></crs:Masks>
</rdf:Description></rdf:li>
<rdf:li><rdf:Description crs:SpotType="clone" crs:SourceState="sourceAutoComputed" crs:Opacity="0.5" crs:Feather="0.25">
<crs:Masks><rdf:Seq><rdf:li crs:What="Mask/Ellipse" crs:X="0.7" crs:Y="0.6" crs:SizeX="0.02" crs:SizeY="0.02"/></rdf:Seq></crs:Masks>
</rdf:Description></rdf:li>
<rdf:li><rdf:Description crs:SpotType="heal" crs:SourceState="sourceSetExplicitly" crs:SourceX="0.2" crs:OffsetY="0.9">
<crs:Masks><rdf:Seq><rdf:li crs:What="Mask/Paint" crs:Radius="0.03" crs:MaskValue="1">
<crs:Dabs><rdf:Seq><rdf:li>d 0.1 0.8</rdf:li><rdf:li>d 0.12 0.82</rdf:li><rdf:li>d 0.14 0.84</rdf:li></rdf:Seq></crs:Dabs></rdf:li></rdf:Seq></crs:Masks>
</rdf:Description></rdf:li>
<rdf:li><rdf:Description crs:SpotType="heal" crs:SourceX="0.6" crs:OffsetY="0.5">
<crs:Masks><rdf:Seq><rdf:li crs:What="Mask/CircularGradient" crs:Top="0.48" crs:Left="0.49" crs:Bottom="0.52" crs:Right="0.51"/></rdf:Seq></crs:Masks>
</rdf:Description></rdf:li>
<rdf:li><rdf:Description crs:SpotType="heal">
<crs:Masks><rdf:Seq><rdf:li crs:What="Mask/Gradient" crs:FullX="0" crs:FullY="0" crs:ZeroX="1" crs:ZeroY="1"/></rdf:Seq></crs:Masks>
</rdf:Description></rdf:li>
</rdf:Seq></crs:RetouchAreas>
</rdf:Description></rdf:RDF></x:xmpmeta>"#;
#[test]
fn retouch_areas_become_spots() {
use crate::SpotMode;
let d = craft_metadata::parse_xmp(SPOTS).unwrap();
let (partial, unmapped) = crate::crs::to_partial_report(&d.properties, Some(&d.values), crate::crs::Target::Any, 1.5);
let s = DevelopSettings::default().merged(&partial).expect("valid settings");
assert_eq!(s.light.exposure, 0.1, "global settings still map");
assert_eq!(s.spots.len(), 4, "the gradient 'spot' is skipped: {:?}", s.spots);
let heal = &s.spots[0];
assert_eq!((heal.mode, heal.points.len(), heal.opacity, heal.feather), (SpotMode::Heal, 1, 100.0, 0.0));
assert!((heal.points[0].x - 0.4).abs() < 1e-9 && (heal.points[0].y - 0.3).abs() < 1e-9);
assert!((heal.size - 0.01).abs() < 1e-9, "a landscape target: width fractions are long-edge fractions");
let src = heal.source_offset.expect("explicit source");
assert!((src.x - 0.05).abs() < 1e-9 && src.y.abs() < 1e-9, "source stored absolute, ours an offset: {src:?}");
let clone = &s.spots[1];
assert_eq!((clone.mode, clone.opacity, clone.feather, clone.source_offset), (SpotMode::Clone, 50.0, 25.0, None));
let brushed = &s.spots[2];
assert_eq!((brushed.points.len(), brushed.size), (3, 0.03));
let src = brushed.source_offset.expect("explicit source");
assert!((src.x - 0.1).abs() < 1e-9 && (src.y - 0.1).abs() < 1e-9);
let circ = &s.spots[3];
assert!((circ.points[0].x - 0.5).abs() < 1e-9 && (circ.points[0].y - 0.5).abs() < 1e-9 && (circ.size - 0.01).abs() < 1e-9);
assert_eq!(unmapped, vec!["Spot: Gradient".to_string()], "{unmapped:?}");
}
#[test]
fn portrait_target_scales_spot_sizes() {
let d = craft_metadata::parse_xmp(SPOTS).unwrap();
let (partial, _) = crate::crs::to_partial_report(&d.properties, Some(&d.values), crate::crs::Target::Any, 2.0 / 3.0);
let s = DevelopSettings::default().merged(&partial).unwrap();
assert!((s.spots[0].size - 0.01 * 2.0 / 3.0).abs() < 1e-9, "a width fraction on a portrait target: {}", s.spots[0].size);
}
#[test]
fn legacy_retouch_info_is_read_on_its_own() {
let packet = SPOTS.replace("crs:RetouchAreas", "crs:Ignored");
let d = craft_metadata::parse_xmp(&packet).unwrap();
let (partial, unmapped) = crate::crs::to_partial_report(&d.properties, Some(&d.values), crate::crs::Target::Any, 1.5);
let s = DevelopSettings::default().merged(&partial).unwrap();
assert_eq!(s.spots.len(), 1, "{:?}", s.spots);
assert_eq!(s.spots[0].mode, crate::SpotMode::Heal);
assert!((s.spots[0].points[0].x - 0.4).abs() < 1e-9 && (s.spots[0].size - 0.01).abs() < 1e-9);
assert!(s.spots[0].source_offset.is_some_and(|o| (o.x - 0.05).abs() < 1e-9));
assert!(unmapped.iter().any(|u| u == "Ignored"), "{unmapped:?}");
assert!(!unmapped.iter().any(|u| u == "RetouchInfo"), "{unmapped:?}");
}
/// `"nan"` parses as a number. A dab of it is dropped, and the rest of the packet still applies.
#[test]
fn a_dab_that_is_not_a_number_is_dropped() {
let packet = PACKET.replace("d 0.15 0.22", "d nan 0.22").replace("d 0.5 0.5", "d 0.5 inf");
let d = craft_metadata::parse_xmp(&packet).unwrap();
let (partial, _) = crate::crs::to_partial_report(&d.properties, Some(&d.values), crate::crs::Target::Any, 1.5);
let s = DevelopSettings::default().merged(&partial).expect("the packet's other adjustments apply");
assert_eq!(s.light.exposure, 0.2);
let brush = s.masks.iter().flat_map(|m| &m.components).find_map(|c| match &c.shape {
MaskShape::Brush { strokes } => Some(strokes),
_ => None,
});
let points: usize = brush.expect("the brush is kept").iter().map(|k| k.points.len()).sum();
assert_eq!(points, 1, "one dab of three was a point");
}
/// Two brush runs of one correction that differ in `crs:MaskInverted` paint different areas: two components.
#[test]
fn brush_runs_of_different_sense_stay_apart() {
let packet = PACKET.replace(r#"crs:What="Mask/Paint" crs:Radius="0.02""#, r#"crs:What="Mask/Paint" crs:MaskInverted="true" crs:Radius="0.02""#);
assert_ne!(packet, PACKET);
let d = craft_metadata::parse_xmp(&packet).unwrap();
let (partial, _) = crate::crs::to_partial_report(&d.properties, Some(&d.values), crate::crs::Target::Any, 1.5);
let s = DevelopSettings::default().merged(&partial).unwrap();
let brushes: Vec<bool> =
s.masks.iter().flat_map(|m| &m.components).filter(|c| matches!(c.shape, MaskShape::Brush { .. })).map(|c| c.invert).collect();
assert_eq!(brushes, [false, true]);
}
/// The older `crs:RetouchInfo` is not read beside a current `crs:RetouchAreas`, even one with no spot we carry over.
#[test]
fn legacy_retouch_info_is_not_read_beside_an_emptied_current_list() {
let (head, rest) = SPOTS.split_once("<crs:RetouchAreas>").unwrap();
let (_, tail) = rest.split_once("</crs:RetouchAreas>").unwrap();
let gradient_only = r#"<crs:RetouchAreas><rdf:Seq><rdf:li><rdf:Description crs:SpotType="heal">
<crs:Masks><rdf:Seq><rdf:li crs:What="Mask/Gradient" crs:FullX="0" crs:FullY="0" crs:ZeroX="1" crs:ZeroY="1"/></rdf:Seq></crs:Masks>
</rdf:Description></rdf:li></rdf:Seq></crs:RetouchAreas>"#;
let d = craft_metadata::parse_xmp(&format!("{head}{gradient_only}{tail}")).unwrap();
let (spots, _) = super::spots(&d.values, 1.5);
assert!(spots.is_empty(), "{spots:?}");
}
/// An XMP preset keeps its masks, and one of masks alone is a preset.
#[test]
fn an_xmp_preset_keeps_its_masks() {
let with_both = crate::crs::preset_from_xmp(PACKET, "f").expect("a preset");
assert_eq!(with_both.settings["masks"].as_array().map(Vec::len), Some(3));
assert_eq!(with_both.settings["light"]["exposure"], 0.2);
let masks_only = PACKET.replace(r#" crs:Exposure2012="0.2""#, "");
assert_ne!(masks_only, PACKET);
assert!(crate::crs::preset_from_xmp(&masks_only, "f").is_some_and(|p| p.settings.get("masks").is_some()));
}
/// A range with a number that is not one cannot be read: that mask is reported, the rest of the packet applies.
#[test]
fn a_range_that_is_not_four_numbers_is_skipped_not_fatal() {
for bad in ["0.4 NaN 0.8 0.9", "0.4 inf 0.8 0.9", "0.4 0.5 0.8", "0.4 0.5 x 0.9", "0.4 0.5 0.8 0.9 1"] {
let packet = PACKET.replace("0.4 0.5 0.8 0.9", bad);
assert_ne!(packet, PACKET);
let d = craft_metadata::parse_xmp(&packet).unwrap();
let (partial, unmapped) = crate::crs::to_partial_report(&d.properties, Some(&d.values), crate::crs::Target::Any, 1.5);
let s = DevelopSettings::default().merged(&partial).unwrap_or_else(|e| panic!("{bad}: {e}"));
assert_eq!(s.light.exposure, 0.2, "{bad}");
assert!(unmapped.iter().any(|u| u == "Mask: luminance range"), "{bad}: {unmapped:?}");
}
}
/// A photo's own packet whose masks are all switched off says the photo has none; a preset says nothing about them.
#[test]
fn a_sidecar_with_only_inactive_masks_clears_the_photo_s() {
let (head, rest) = PACKET.split_once("<crs:MaskGroupBasedCorrections>").unwrap();
let (_, tail) = rest.rsplit_once("</crs:PaintBasedCorrections>").unwrap();
let off = r#"<crs:MaskGroupBasedCorrections><rdf:Seq><rdf:li><rdf:Description crs:What="Correction" crs:CorrectionActive="false" crs:LocalExposure2012="1">
<crs:CorrectionMasks><rdf:Seq><rdf:li crs:What="Mask/Image" crs:MaskSubType="2"/></rdf:Seq></crs:CorrectionMasks>
</rdf:Description></rdf:li></rdf:Seq></crs:MaskGroupBasedCorrections>"#;
let d = craft_metadata::parse_xmp(&format!("{head}{off}{tail}")).unwrap();
let report = |target| crate::crs::to_partial_report(&d.properties, Some(&d.values), target, 1.5).0;
let (mut photo, _) = settings();
assert!(!photo.masks.is_empty());
assert!(report(crate::crs::Target::Any).get("masks").is_none(), "a preset adds masks, it does not clear them");
let partial = report(crate::crs::Target::RawAbsolute);
assert_eq!(partial["masks"], serde_json::json!([]));
photo = photo.merged(&partial).unwrap();
assert!(photo.masks.is_empty());
// no container at all: the photo's masks are not the packet's to say
let none = craft_metadata::parse_xmp(&format!("{head}{tail}")).unwrap();
assert!(crate::crs::to_partial_report(&none.properties, Some(&none.values), crate::crs::Target::RawAbsolute, 1.5).0.get("masks").is_none());
}
+588
View File
@@ -0,0 +1,588 @@
//! The non-destructive edit model of LightCraft.
//!
//! [`DevelopSettings`] is the complete description of a photo's look: pure, serializable data.
//! The pipeline evaluates it; the catalog stores it; presets, copy/paste, sync, versions and history
//! are operations on it. Numeric sliders are addressed by id through [`controls`].
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
pub mod controls;
pub mod crs;
pub mod crs_masks;
pub mod presets;
pub mod segmask;
pub mod settings;
pub use controls::{CONTROLS, ControlSpec, Section, Track};
pub use presets::{Preset, SettingsGroup, apply_partial, extract_groups};
pub use segmask::{SegMask, with_grid_interner};
pub use settings::*;
use serde_json::Value;
impl DevelopSettings {
/// Settings for a freshly imported raw file (Lightroom applies capture sharpening and colour
/// noise reduction by default to raw files).
pub fn for_raw(as_shot_temp: f64, as_shot_tint: f64) -> DevelopSettings {
let mut s = DevelopSettings::default();
s.wb.temp = as_shot_temp;
s.wb.tint = as_shot_tint;
s.detail.sharpen_amount = 40.0;
s.detail.nr_color = 25.0;
s.detail.nr_outliers = true;
s
}
pub fn to_json(&self) -> Value {
serde_json::to_value(self).unwrap_or(Value::Null)
}
pub fn from_json(v: &Value) -> Result<DevelopSettings, serde_json::Error> {
serde_json::from_value(v.clone())
}
/// [`Self::to_json`] with the settings it leaves out at their defaults stated, for JSON that is copied, merged,
/// scaled or compared key by key (copy / paste, presets, Auto Sync). The stored JSON leaves them out (Remove Hot
/// Pixels when off, an untouched HDR edit, the default profile, …), so settings saved before they existed keep
/// their hash; a merge needs them, or copying a group would not turn them off on the target and a preset applied
/// at an amount would not find its base value. Settings inside lists (masks, strokes) are not stated: a list is
/// replaced whole. Neither are the process and the white-balance scale, which are not copied by value
/// ([`Self::merged`]).
pub fn to_json_for_merge(&self) -> Value {
fn state<T: serde::Serialize>(obj: &mut serde_json::Map<String, Value>, key: &str, field: &T) {
if !obj.contains_key(key) {
obj.insert(key.into(), serde_json::to_value(field).unwrap_or(Value::Null));
}
}
let mut v = self.to_json();
let Some(top) = v.as_object_mut() else { return v };
state(top, "profile", &self.profile);
state(top, "hdr", &self.hdr);
state(top, "curve", &self.curve);
if let Some(profile) = top.get_mut("profile").and_then(Value::as_object_mut) {
state(profile, "camera_local_tone", &self.profile.camera_local_tone);
}
if let Some(detail) = top.get_mut("detail").and_then(Value::as_object_mut) {
state(detail, "nr_outliers", &self.detail.nr_outliers);
}
if let Some(enhance) = top.get_mut("enhance").and_then(Value::as_object_mut) {
state(enhance, "denoise_on", &self.enhance.denoise_on);
}
if let Some(blur) = top.get_mut("lens_blur").and_then(Value::as_object_mut) {
let b = &self.lens_blur;
state(blur, "boost", &b.boost);
state(blur, "focus_mask", &b.focus_mask);
state(blur, "focus_strokes", &b.focus_strokes);
state(blur, "blur_strokes", &b.blur_strokes);
state(blur, "transition", &b.transition);
state(blur, "shape", &b.shape);
state(blur, "area", &b.area);
}
v
}
/// [`Self::from_json`] for settings from outside the app, such as a sidecar's `lc:settings`
/// (issue storytold/lightcraft#2555): kept in range as [`Self::merged`] keeps them.
pub fn from_untrusted_json(v: &Value) -> Result<DevelopSettings, serde_json::Error> {
let mut s = DevelopSettings::from_json(v)?;
s.keep_in_range(&DevelopSettings::default());
Ok(s)
}
/// Merge a partial JSON object into these settings (fields not mentioned are kept). A white balance that
/// names no [`WbScale`] keeps the meaning it always had (`Legacy`), whatever scale these settings were on: a
/// partial from before the scale existed, or one that never said, must not become Kelvin by landing on
/// Kelvin settings. Out-of-range values are brought back into range (`DevelopSettings::keep_in_range`).
pub fn merged(&self, partial: &Value) -> Result<DevelopSettings, serde_json::Error> {
let mut v = self.to_json();
presets::deep_merge(&mut v, partial);
let mut out = DevelopSettings::from_json(&v)?;
if let Some(wb) = partial.get("wb").and_then(Value::as_object)
&& (wb.contains_key("temp") || wb.contains_key("tint"))
&& !wb.contains_key("scale")
{
out.wb.scale = WbScale::Legacy;
}
out.keep_in_range(self);
Ok(out)
}
/// What crs XMP import does to the values it reads, for settings that arrive as JSON (presets, `develop.merge`,
/// `render --settings`; issue storytold/lightcraft#1946): every slider clamped through its control spec, point curves in 0..1, and a
/// crop with no area left as it was in `before`. The angle is kept within ±45° (not finite: 0). Unrotated, the crop
/// is clipped to the photo first; a turned crop may reach past 0..1 and is bounded where the photo's size is known
/// (`CropGeometry::bounded`, applied by the pipeline).
fn keep_in_range(&mut self, before: &DevelopSettings) {
for c in controls::CONTROLS {
if let Some(v) = controls::get(self, c.id) {
controls::set(self, c.id, v);
}
}
// the sliders of list entries (point colours, red eyes) have ranges too
for (id, _) in controls::indexed_instances(self) {
if let Some(v) = controls::get(self, &id) {
controls::set(self, &id, v);
}
}
let c = &mut self.curve;
for p in [&mut c.master, &mut c.red, &mut c.green, &mut c.blue].into_iter().flatten() {
*p = craft_geom::Point::new(p.x.clamp(0.0, 1.0), p.y.clamp(0.0, 1.0));
}
let g = &mut self.crop.geometry;
g.angle = if g.angle.is_finite() { g.angle.clamp(-45.0, 45.0) } else { 0.0 };
if g.angle == 0.0 {
g.rect = g.rect.intersect(&craft_geom::Rect::UNIT);
}
if g.rect.is_empty() {
// the rectangle it had, which under another angle may have reached outside the photo
let old = before.crop.geometry.rect;
let old = if g.angle == 0.0 { old.intersect(&craft_geom::Rect::UNIT) } else { old };
g.rect = if old.is_empty() { craft_geom::Rect::UNIT } else { old };
}
}
/// Stable 64-bit hash of the settings (FNV-1a over canonical JSON), for preview cache keys.
pub fn hash64(&self) -> u64 {
let s = serde_json::to_string(self).unwrap_or_default();
let mut h: u64 = 0xcbf2_9ce4_8422_2325;
for b in s.as_bytes() {
h ^= *b as u64;
h = h.wrapping_mul(0x0100_0000_01b3);
}
h
}
/// True if nothing differs from a fresh default (ignoring white balance "as shot" values, and
/// the rendering process: that is not an edit).
pub fn is_unedited(&self) -> bool {
let mut a = self.clone();
let d = DevelopSettings::default();
// as shot, the numbers (and the scale they are on) are the photo's own, not an edit; any other mode is one
if a.wb.mode == WbMode::AsShot {
a.wb = d.wb;
}
a.process = d.process;
a == d
}
pub fn section_enabled(&self, section: &str) -> bool {
!self.disabled_sections.iter().any(|s| s == section)
}
/// The settings as rendered: an Edit-panel section whose eye is off contributes nothing (issue
/// storytold/lightcraft#316). Light (with its tone curve), Color (white balance, presence, the mixers, colour grading
/// and point colour) and Detail are reset to their defaults here; Effects, Optics, Geometry and
/// Calibration the pipeline switches off where it applies them. Borrowed when every section is on.
pub fn effective(&self) -> std::borrow::Cow<'_, DevelopSettings> {
let off = |section: &str| !self.section_enabled(section);
if !(off("light") || off("color") || off("detail")) {
return std::borrow::Cow::Borrowed(self);
}
let mut d = self.clone();
if off("light") {
d.reset_section(Section::Light);
d.reset_section(Section::Curve);
}
if off("color") {
for section in [Section::Color, Section::Mixer, Section::BwMix, Section::Grading, Section::PointColor] {
d.reset_section(section);
}
d.point_colors.clear();
}
if off("detail") {
d.reset_section(Section::Detail);
}
std::borrow::Cow::Owned(d)
}
/// Whether a raw is decoded with its single outlier photosites replaced: Remove Hot Pixels is on and the Detail
/// section's eye is too (an Edit-panel section that is off contributes nothing, as in [`Self::effective`]).
pub fn removes_hot_pixels(&self) -> bool {
self.detail.nr_outliers && self.section_enabled("detail")
}
/// How much of the AI-denoised picture to mix in, 0 (none) to 1 (all of it): the Denoise amount, unless the Detail
/// section is switched off or the value is not a number.
pub fn denoise_amount(&self) -> f32 {
let a = self.enhance.denoise;
if a.is_finite() && self.enhance.denoise_enabled() && self.section_enabled("detail") { (a / 100.0).clamp(0.0, 1.0) as f32 } else { 0.0 }
}
pub fn set_section_enabled(&mut self, section: &str, on: bool) {
self.disabled_sections.retain(|s| s != section);
if !on {
self.disabled_sections.push(section.to_string());
}
}
/// Reset every control in `section` to its default, the sliders of its list entries (each point colour, each
/// red eye) too, and the settings of the section that are not controls (the creative profile, the curve, the
/// white balance mode, Upright and its guides, the lens profile and Remove Chromatic Aberration switches).
pub fn reset_section(&mut self, section: Section) {
for c in controls::in_section(section) {
controls::set(self, c.id, c.default);
}
for (id, spec) in controls::indexed_instances(self) {
if spec.section == section {
controls::set(self, &id, spec.default);
}
}
match section {
Section::Curve => {
let d = ToneCurve::default();
self.curve = d;
}
Section::Color => self.wb.mode = WbMode::AsShot,
Section::Detail => {
self.enhance.denoise_on = None;
// not a slider: reset like them, to the general default (off)
self.detail.nr_outliers = false;
}
// the creative profile is not a control: the chosen look goes back to the default one,
// and so does the camera's own local tone mapping
Section::Profile => {
self.profile = Profile::default();
}
// Upright, its guides and its solved transform are not sliders
Section::Geometry => self.geometry = Geometry::default(),
// the two switches are not sliders
Section::Optics => {
self.optics.remove_ca = false;
self.optics.lens_profile = false;
}
_ => {}
}
}
/// The middle of the crop, in normalized photo coordinates (the photo's middle when the crop
/// isn't a usable rectangle).
pub fn crop_center(&self) -> craft_geom::Point {
let r = self.crop.geometry.rect;
let (x, y) = ((r.x0 + r.x1) / 2.0, (r.y0 + r.y1) / 2.0);
if x.is_finite() && y.is_finite() { craft_geom::Point::new(x, y) } else { craft_geom::Point::new(0.5, 0.5) }
}
/// Next free mask id: one past the highest, or, when that is `u32::MAX` (ids come from files,
/// pastes and agents), the lowest one no mask uses.
pub fn next_mask_id(&self) -> u32 {
match self.masks.iter().map(|m| m.id).max() {
None => 1,
// fewer masks than ids: one of the first `masks.len() + 1` is free
Some(max) => max
.checked_add(1)
.or_else(|| {
let used: std::collections::HashSet<u32> = self.masks.iter().map(|m| m.id).collect();
(1..=u32::MAX).find(|id| !used.contains(id))
})
.unwrap_or(0),
}
}
}
#[cfg(test)]
mod tests_process;
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
/// Remove Hot Pixels (storytold/lightcraft#1345) is on for a newly imported raw and off for everything else, and an edit saved
/// before the box existed reads as off, so it renders as it did.
#[test]
fn hot_pixel_box_is_on_for_new_raws_only() {
assert!(DevelopSettings::for_raw(5500.0, 10.0).detail.nr_outliers);
assert!(!DevelopSettings::default().detail.nr_outliers);
let mut saved = DevelopSettings::for_raw(5500.0, 10.0).to_json();
let detail = saved.get_mut("detail").and_then(|d| d.as_object_mut()).unwrap();
assert!(detail.remove("nr_outliers").is_some());
let read = DevelopSettings::from_json(&saved).unwrap();
assert!(!read.detail.nr_outliers);
assert_eq!(read.detail.nr_color, 25.0, "the rest of the saved edit is kept");
assert_ne!(read.hash64(), DevelopSettings::for_raw(5500.0, 10.0).hash64(), "cached renders are told apart");
// off is omitted: an edit saved before the box keeps its JSON, and so its hash and cached thumbnails
assert_eq!(read.to_json(), saved);
// copying Detail still carries the box when it is off
let copied = crate::extract_groups(&read, &[crate::SettingsGroup::Detail]);
assert_eq!(copied["detail"]["nr_outliers"], false);
let mut target = DevelopSettings::for_raw(5500.0, 10.0).to_json();
crate::presets::deep_merge(&mut target, &copied);
assert!(!DevelopSettings::from_json(&target).unwrap().detail.nr_outliers);
// the Detail eye switches it off for the decode too, and Reset Detail resets it like the sliders
let mut raw = DevelopSettings::for_raw(5500.0, 10.0);
assert!(raw.removes_hot_pixels());
raw.set_section_enabled("detail", false);
assert!(!raw.removes_hot_pixels());
raw.set_section_enabled("detail", true);
raw.reset_section(Section::Detail);
assert!(!raw.detail.nr_outliers && !raw.removes_hot_pixels());
}
#[test]
fn serde_roundtrip_default_and_edited() {
let mut s = DevelopSettings::default();
controls::set(&mut s, "light.exposure", 1.25);
s.masks.push(Mask {
id: 1,
components: vec![MaskComponent {
name: None,
op: MaskOp::Add,
invert: false,
shape: MaskShape::Radial { center: craft_geom::Point::new(0.5, 0.5), rx: 0.2, ry: 0.1, angle: 10.0, feather: 50.0, invert: false },
}],
..Default::default()
});
let v = s.to_json();
let back = DevelopSettings::from_json(&v).unwrap();
assert_eq!(back, s);
assert_ne!(back.hash64(), DevelopSettings::default().hash64());
}
#[test]
fn white_balance_scale_reads_absent_as_legacy_and_writes_only_kelvin() {
// settings from before the scale existed: no field, `Legacy`, and written back without it
let old = json!({"wb": {"mode": "custom", "temp": 5800.0, "tint": 3.0}});
let s = DevelopSettings::from_json(&old).unwrap();
assert_eq!(s.wb.scale, WbScale::Legacy);
assert_eq!(s.to_json()["wb"], old["wb"]);
assert_eq!(DevelopSettings::default().wb.scale, WbScale::Legacy);
assert!(DevelopSettings::default().to_json()["wb"].get("scale").is_none());
// written on the Kelvin scale: said so, and read back
let mut k = s.clone();
k.wb.scale = WbScale::Kelvin;
assert_eq!(k.to_json()["wb"]["scale"], json!("kelvin"));
assert_eq!(DevelopSettings::from_json(&k.to_json()).unwrap(), k);
assert_ne!(k.hash64(), s.hash64());
// an unknown scale from a newer build is an error, not a panic
assert!(DevelopSettings::from_json(&json!({"wb": {"scale": "mired"}})).is_err());
}
#[test]
fn a_partial_white_balance_without_a_scale_is_legacy() {
let mut base = DevelopSettings::default();
base.wb.scale = WbScale::Kelvin;
// an old preset's white balance lands on Kelvin settings: it keeps its relative meaning
let out = apply_partial(&base, &json!({"wb": {"mode": "custom", "temp": 5800.0}}), 1.0);
assert_eq!((out.wb.scale, out.wb.temp), (WbScale::Legacy, 5800.0));
let out = apply_partial(&base, &json!({"wb": {"tint": 12.0}}), 1.0);
assert_eq!(out.wb.scale, WbScale::Legacy);
// one that says Kelvin stays Kelvin; a mode alone leaves the scale as it was
let out = apply_partial(&base, &json!({"wb": {"mode": "custom", "temp": 5800.0, "scale": "kelvin"}}), 1.0);
assert_eq!(out.wb.scale, WbScale::Kelvin);
let out = apply_partial(&base, &json!({"wb": {"mode": "cloudy"}}), 1.0);
assert_eq!(out.wb.scale, WbScale::Kelvin);
let out = apply_partial(&base, &json!({"light": {"exposure": 1.0}}), 1.0);
assert_eq!(out.wb.scale, WbScale::Kelvin);
// the plain merge (`develop.merge`) follows the same rule
assert_eq!(base.merged(&json!({"wb": {"temp": 5800.0}})).unwrap().wb.scale, WbScale::Legacy);
assert_eq!(base.merged(&json!({"wb": {"temp": 5800.0, "scale": "kelvin"}})).unwrap().wb.scale, WbScale::Kelvin);
assert_eq!(base.merged(&json!({"wb": {"mode": "auto"}})).unwrap().wb.scale, WbScale::Kelvin);
}
#[test]
fn default_hdr_is_not_serialized_so_existing_hashes_stay() {
let s = DevelopSettings::default();
assert!(s.to_json().get("hdr").is_none(), "HDR off must not change the settings JSON or hash64");
let mut on = s.clone();
on.hdr.enabled = true;
assert!(on.to_json().get("hdr").is_some());
assert_ne!(on.hash64(), s.hash64());
assert_eq!(DevelopSettings::from_json(&on.to_json()).unwrap(), on);
}
#[test]
fn hdr_peak_is_finite_for_a_non_finite_headroom() {
let mut h = Hdr { enabled: true, max_ev: f64::NAN, ..Hdr::default() };
assert_eq!(h.peak(), (Hdr::DEFAULT_MAX_EV as f32).exp2());
h.max_ev = f64::INFINITY;
assert_eq!(h.peak(), (Hdr::DEFAULT_MAX_EV as f32).exp2());
h.max_ev = -3.0;
assert_eq!(h.peak(), 1.0);
}
#[test]
fn missing_fields_take_defaults_and_unknown_ignored() {
let s = DevelopSettings::from_json(&json!({"light": {"exposure": 0.5}, "futureThing": 3})).unwrap();
assert_eq!(s.light.exposure, 0.5);
assert_eq!(s.grading.blending, 50.0);
}
/// Settings with one colour-range mask of `n` distinct samples (built in code, so not capped).
fn color_range_settings(n: usize) -> DevelopSettings {
let samples = (0..n).map(|i| [i as f64 / 1000.0, 0.1, -0.1]).collect();
let mut s = DevelopSettings::default();
s.masks.push(Mask {
id: 1,
components: vec![MaskComponent { name: None, op: MaskOp::Add, invert: false, shape: MaskShape::ColorRange { samples, refine: 50.0 } }],
..Default::default()
});
s
}
fn color_range_samples(s: &DevelopSettings) -> &[[f64; 3]] {
match s.masks.first().and_then(|m| m.components.first()).map(|c| &c.shape) {
Some(MaskShape::ColorRange { samples, .. }) => samples,
other => panic!("expected a colour range, got {other:?}"),
}
}
/// Issue storytold/lightcraft#2556: `mask.add`/`mask.update` capped a colour range's samples, but a sidecar `lc:settings`, a
/// preset, `develop.merge`, `render --settings` or a catalog / history load took any number (render cost is
/// pixels x samples). Every load now keeps the first [`MAX_COLOR_RANGE_SAMPLES`], in order.
#[test]
fn color_range_samples_are_capped_however_settings_load() {
let big = color_range_settings(1000);
let want = &color_range_samples(&big)[..MAX_COLOR_RANGE_SAMPLES];
let v = big.to_json();
let loaded = DevelopSettings::from_json(&v).unwrap();
assert_eq!(color_range_samples(&loaded).len(), MAX_COLOR_RANGE_SAMPLES);
assert_eq!(color_range_samples(&loaded), want);
let from_str: DevelopSettings = serde_json::from_str(&v.to_string()).unwrap();
assert_eq!(color_range_samples(&from_str), want);
// `develop.merge`, `render --settings` and presets merge a partial
let merged = DevelopSettings::default().merged(&json!({"masks": v["masks"]})).unwrap();
assert_eq!(color_range_samples(&merged), want);
let preset =
Preset { id: "p".into(), name: "P".into(), group: "G".into(), settings: json!({"masks": v["masks"]}), favorite: false, builtin: false };
assert_eq!(color_range_samples(&preset.apply(&DevelopSettings::default(), 1.0)), want);
// a capped list round-trips, and a short one is unchanged
assert_eq!(DevelopSettings::from_json(&loaded.to_json()).unwrap(), loaded);
let few = color_range_settings(2);
assert_eq!(DevelopSettings::from_json(&few.to_json()).unwrap(), few);
// a list that isn't samples is still refused
let mut bad = v.clone();
bad["masks"][0]["components"][0]["shape"]["samples"] = json!([[0.1, 0.2]]);
assert!(DevelopSettings::from_json(&bad).is_err());
}
#[test]
fn merge_partial() {
let s = DevelopSettings::default();
let m = s.merged(&json!({"light": {"contrast": 20}, "effects": {"clarity": 10}})).unwrap();
assert_eq!(m.light.contrast, 20.0);
assert_eq!(m.effects.clarity, 10.0);
assert_eq!(m.light.exposure, 0.0);
}
#[test]
fn merged_settings_are_kept_in_range() {
// issue storytold/lightcraft#1946: `develop.merge`, `render --settings` and presets stored whatever the JSON said
let mut base = DevelopSettings::default();
base.crop.geometry.rect = craft_geom::Rect::new(0.1, 0.2, 0.8, 0.9);
let m = base
.merged(&json!({"light": {"exposure": 1e308}, "vignette": {"amount": -1e308}, "geometry": {"scale": 0}, "optics": {"distortion": 1e308}}))
.unwrap();
assert_eq!((m.light.exposure, m.vignette.amount, m.geometry.scale, m.optics.distortion), (5.0, -100.0, 50.0, 100.0));
// point curves stay in 0..1, as an imported XMP curve does
let m = base.merged(&json!({"curve": {"master": [{"x": -3, "y": 0}, {"x": 1, "y": 1e308}]}})).unwrap();
assert_eq!(m.curve.master, vec![craft_geom::Point::new(0.0, 0.0), craft_geom::Point::new(1.0, 1.0)]);
// a crop with no area is left out, as XMP import leaves out one whose edges are inverted
for rect in
[json!({"x0": 0.9, "x1": 0.1, "y0": 0, "y1": 1}), json!({"x0": 1e308, "x1": -1e308, "y0": 0, "y1": 1}), json!({"x0": 0.5, "x1": 0.5})]
{
let m = base.merged(&json!({"crop": {"geometry": {"rect": rect}}})).unwrap();
assert_eq!(m.crop.geometry.rect, base.crop.geometry.rect, "{rect}");
}
// a turned crop may reach outside; put back under no angle, it is clipped like any unrotated crop
let mut turned = base.clone();
turned.crop.geometry.angle = 10.0;
turned.crop.geometry.rect = craft_geom::Rect::new(-0.1, 0.2, 0.8, 0.9);
let m = turned.merged(&json!({"crop": {"geometry": {"angle": 0, "rect": {"x0": 0.5, "x1": 0.5}}}})).unwrap();
assert_eq!((m.crop.geometry.angle, m.crop.geometry.rect), (0.0, craft_geom::Rect::new(0.0, 0.2, 0.8, 0.9)));
// unrotated, the crop stays inside the photo
let m = base.merged(&json!({"crop": {"geometry": {"rect": {"x0": -1e308, "y0": 0.25, "x1": 1e308, "y1": 0.75}}}})).unwrap();
assert_eq!(m.crop.geometry.rect, craft_geom::Rect::new(0.0, 0.25, 1.0, 0.75));
}
#[test]
fn unedited_and_reset() {
let mut s = DevelopSettings::default();
s.wb.temp = 5000.0;
assert!(s.is_unedited());
s.light.exposure = 1.0;
s.light.shadows = 30.0;
assert!(!s.is_unedited());
s.reset_section(Section::Light);
assert!(s.is_unedited());
}
#[test]
fn resetting_the_profile_section_restores_the_default_profile() {
// the chosen creative profile is not a control, so resetting the section must restore it too
let mut s = DevelopSettings::default();
s.profile.id = "lc.muted.matte-soft".into();
s.profile.amount = 40.0;
s.reset_section(Section::Profile);
assert_eq!(s.profile.id, "lc.color", "the creative profile is reset to the default one");
assert_eq!(s.profile.amount, 100.0);
}
#[test]
fn resetting_the_profile_section_clears_the_camera_local_tone() {
// the camera's local tone mapping is not a control either: a Profile reset switches it off
let mut s = DevelopSettings::default();
s.profile.camera_local_tone = true;
s.reset_section(Section::Profile);
assert!(!s.profile.camera_local_tone);
}
#[test]
fn section_toggles() {
let mut s = DevelopSettings::default();
assert!(s.section_enabled("effects"));
s.set_section_enabled("effects", false);
s.set_section_enabled("effects", false);
assert!(!s.section_enabled("effects"));
assert_eq!(s.disabled_sections.len(), 1);
s.set_section_enabled("effects", true);
assert!(s.section_enabled("effects"));
}
#[test]
fn the_denoise_amount_is_a_slider_and_follows_the_detail_section() {
let mut s = DevelopSettings::default();
assert_eq!(s.denoise_amount(), 0.0);
assert!(controls::set(&mut s, "enhance.denoise", 60.0));
assert_eq!(controls::get(&s, "enhance.denoise"), Some(60.0));
assert!((s.denoise_amount() - 0.6).abs() < 1e-6);
// the slider's range is 0 to 100; values outside it are brought in
controls::set(&mut s, "enhance.denoise", 500.0);
assert_eq!(s.denoise_amount(), 1.0);
controls::set(&mut s, "enhance.denoise", -5.0);
assert_eq!(s.denoise_amount(), 0.0);
// switching the Detail section off switches the denoise off with it; a settings file with a bad number does nothing
controls::set(&mut s, "enhance.denoise", 80.0);
s.set_section_enabled("detail", false);
assert_eq!(s.denoise_amount(), 0.0);
s.set_section_enabled("detail", true);
s.enhance.denoise = f64::NAN;
assert_eq!(s.denoise_amount(), 0.0);
// it is part of Detail: a reset of the section clears it
controls::set(&mut s, "enhance.denoise", 40.0);
s.reset_section(Section::Detail);
assert_eq!(s.enhance.denoise, 0.0);
// The later independent switch preserves Amount when off, and can be on at zero.
controls::set(&mut s, "enhance.denoise", 75.0);
s.enhance.denoise_on = Some(false);
assert_eq!(s.denoise_amount(), 0.0);
assert_eq!(s.enhance.denoise, 75.0);
s.enhance.denoise_on = Some(true);
assert_eq!(s.denoise_amount(), 0.75);
controls::set(&mut s, "enhance.denoise", 0.0);
assert!(s.enhance.denoise_enabled());
s.reset_section(Section::Detail);
assert_eq!(s.enhance.denoise_on, None);
}
#[test]
fn next_mask_id_after_the_highest_id_is_unused() {
// ids come from files, pastes and agents: one at the limit must not overflow (a panic in
// debug builds) or wrap to an id another mask has
let mut s = DevelopSettings::default();
assert_eq!(s.next_mask_id(), 1);
s.masks = vec![Mask { id: u32::MAX, ..Default::default() }, Mask { id: 1, ..Default::default() }];
let next = s.next_mask_id();
assert!(!s.masks.iter().any(|m| m.id == next), "{next}");
assert_eq!(next, 2);
}
}
+675
View File
@@ -0,0 +1,675 @@
//! Presets and copy/paste subsets.
//!
//! A preset is a *partial* settings object (JSON) — only the settings it names. Applying it changes
//! exactly the settings it names (a leaf: a number, a flag, a name; an array is one leaf): each is
//! computed from the photo's *original* state (its import settings, when known) and the preset's
//! value, and replaces the photo's value; every other setting keeps the photo's value (issue
//! storytold/lightcraft#2159). `amount` (0..200 %) moves each named number between the original and the preset's
//! value. Copy/paste/sync use the same group selection ([`SettingsGroup`]) and merge into the
//! current settings as before.
//!
//! The rendering process ([`crate::ProcessVersion`]) is in no group: copy, paste, sync and presets
//! made from a photo never carry it, so the photos they change keep their own. A partial that names
//! `process` itself (Apply Settings JSON) sets it like any other field.
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use std::borrow::Cow;
use crate::DevelopSettings;
/// Groups shown in "Choose settings to copy" / "Create preset" (Lightroom's checklist).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum SettingsGroup {
Profile,
Treatment,
WhiteBalance,
Light,
ToneCurve,
Color,
ColorMixer,
ColorGrading,
Effects,
Vignette,
Grain,
Detail,
Optics,
Geometry,
Crop,
Masks,
Spots,
RedEye,
LensBlur,
Calibration,
}
impl SettingsGroup {
pub const ALL: [SettingsGroup; 20] = [
SettingsGroup::Profile,
SettingsGroup::Treatment,
SettingsGroup::WhiteBalance,
SettingsGroup::Light,
SettingsGroup::ToneCurve,
SettingsGroup::Color,
SettingsGroup::ColorMixer,
SettingsGroup::ColorGrading,
SettingsGroup::Effects,
SettingsGroup::Vignette,
SettingsGroup::Grain,
SettingsGroup::Detail,
SettingsGroup::Optics,
SettingsGroup::Geometry,
SettingsGroup::Crop,
SettingsGroup::Masks,
SettingsGroup::Spots,
SettingsGroup::RedEye,
SettingsGroup::LensBlur,
SettingsGroup::Calibration,
];
/// Groups included by default when copying (Lightroom excludes crop, masks and spots by default).
pub fn default_copy() -> Vec<SettingsGroup> {
SettingsGroup::ALL
.into_iter()
.filter(|g| !matches!(g, SettingsGroup::Crop | SettingsGroup::Masks | SettingsGroup::Spots | SettingsGroup::RedEye))
.collect()
}
pub fn label(self) -> &'static str {
match self {
SettingsGroup::Profile => "Profile",
SettingsGroup::Treatment => "Treatment",
SettingsGroup::WhiteBalance => "White Balance",
SettingsGroup::Light => "Light",
SettingsGroup::ToneCurve => "Tone Curve",
SettingsGroup::Color => "Color",
SettingsGroup::ColorMixer => "Color Mixer",
SettingsGroup::ColorGrading => "Color Grading",
SettingsGroup::Effects => "Effects",
SettingsGroup::Vignette => "Vignette",
SettingsGroup::Grain => "Grain",
SettingsGroup::Detail => "Detail",
SettingsGroup::Optics => "Optics",
SettingsGroup::Geometry => "Geometry",
SettingsGroup::Crop => "Crop",
SettingsGroup::Masks => "Masking",
SettingsGroup::Spots => "Remove",
SettingsGroup::RedEye => "Red Eye",
SettingsGroup::LensBlur => "Lens Blur",
SettingsGroup::Calibration => "Calibration",
}
}
/// Top-level JSON keys of `DevelopSettings` that belong to the group.
pub fn keys(self) -> &'static [&'static str] {
match self {
SettingsGroup::Profile => &["profile"],
SettingsGroup::Treatment => &["treatment"],
SettingsGroup::WhiteBalance => &["wb"],
SettingsGroup::Light => &["light", "hdr"],
SettingsGroup::ToneCurve => &["curve"],
SettingsGroup::Color => &["color"],
SettingsGroup::ColorMixer => &["mixer", "bw_mix", "point_colors"],
SettingsGroup::ColorGrading => &["grading"],
SettingsGroup::Effects => &["effects"],
SettingsGroup::Vignette => &["vignette"],
SettingsGroup::Grain => &["grain"],
SettingsGroup::Detail => &["detail", "enhance"],
SettingsGroup::Optics => &["optics"],
SettingsGroup::Geometry => &["geometry"],
SettingsGroup::Crop => &["crop", "orientation"],
SettingsGroup::Masks => &["masks"],
SettingsGroup::Spots => &["spots"],
SettingsGroup::RedEye => &["red_eye"],
SettingsGroup::LensBlur => &["lens_blur"],
SettingsGroup::Calibration => &["calibration"],
}
}
}
/// The subset of `s` covering `groups`, as a partial JSON object.
pub fn extract_groups(s: &DevelopSettings, groups: &[SettingsGroup]) -> Value {
let full = s.to_json_for_merge();
let mut out = Map::new();
for g in groups {
for k in g.keys() {
if let Some(v) = full.get(*k) {
out.insert((*k).to_string(), v.clone());
}
}
}
Value::Object(out)
}
/// Recursively merge `patch` into `base` (objects merge; everything else replaces).
pub fn deep_merge(base: &mut Value, patch: &Value) {
match (base, patch) {
(Value::Object(b), Value::Object(p)) => {
for (k, v) in p {
match b.get_mut(k) {
Some(bv) if bv.is_object() && v.is_object() => deep_merge(bv, v),
_ => {
b.insert(k.clone(), v.clone());
}
}
}
}
(b, p) => *b = p.clone(),
}
}
/// Interpolate numbers in `patch` towards/away from `base` by `t` (1 = patch as-is); non-numeric
/// values are taken from the patch when `t >= 0.5`.
fn scale_patch(base: &Value, patch: &Value, t: f64) -> Value {
match (base, patch) {
(Value::Object(b), Value::Object(p)) => {
let mut out = Map::new();
for (k, pv) in p {
let bv = b.get(k).unwrap_or(&Value::Null);
out.insert(k.clone(), scale_patch(bv, pv, t));
}
Value::Object(out)
}
// Integer fields (the grain seed, ids) are discrete like strings: an interpolated seed would
// not deserialize as an integer, and the whole preset would silently not apply.
(Value::Number(b), Value::Number(p)) if b.is_f64() || p.is_f64() => {
let (b, p) = (b.as_f64().unwrap_or(0.0), p.as_f64().unwrap_or(0.0));
serde_json::Number::from_f64(b + (p - b) * t).map(Value::Number).unwrap_or(Value::Null)
}
(b, p) => {
if t >= 0.5 {
p.clone()
} else {
b.clone()
}
}
}
}
/// Apply a partial settings object with an amount (1.0 = 100 %). Out-of-range values are clamped
/// through the control specs, as every merge does ([`DevelopSettings::merged`]).
pub fn apply_partial(s: &DevelopSettings, partial: &Value, amount: f64) -> DevelopSettings {
let patch = if (amount - 1.0).abs() < 1e-9 { Cow::Borrowed(partial) } else { Cow::Owned(scale_patch(&s.to_json_for_merge(), partial, amount)) };
// (a white balance without a scale keeps its old meaning: `DevelopSettings::merged`)
s.merged(&patch).unwrap_or_else(|_| s.clone())
}
/// Top-level settings keys that hold per-photo pixel repairs: a preset's named repairs compose on
/// the photo's own values instead of the original's (masks are added by [`Preset::apply_on`]), and
/// a preset without them leaves the photo's alone.
const REPAIR_KEYS: [&str; 3] = ["masks", "spots", "red_eye"];
/// The settings `settings` (a partial JSON object) names, applied to `current` at `amount`: each
/// named setting is computed from `original` (the photo's import state) and the preset's value,
/// and replaces the photo's value (issue storytold/lightcraft#2159). Every setting the preset does not name keeps the
/// photo's current value, edits included. Pixel repairs compose on the photo's own values, as they
/// always have.
fn compose_named(current: &DevelopSettings, original: &DevelopSettings, settings: &Value, amount: f64) -> DevelopSettings {
// At 100 % the preset's own values apply as they are, and `original` is not read. The presets
// panel calls this for every visible row on every frame, so the scaling base is built below only.
if (amount - 1.0).abs() < 1e-9 {
return current.merged(settings).unwrap_or_else(|_| current.clone());
}
let cur = current.to_json();
// with the settings the stored JSON leaves out at their defaults: a preset's HDR edit at half amount is halfway
// from the original's, which is there even when the original never touched it
let mut base = original.to_json_for_merge();
if let (Some(b), Some(c)) = (base.as_object_mut(), cur.as_object()) {
for k in REPAIR_KEYS {
if let Some(v) = c.get(k) {
b.insert(k.to_string(), v.clone());
}
}
}
let composed = match settings.as_object() {
Some(patch) => Value::Object(interpolate_object(base.as_object(), patch, amount)),
None => Value::Object(Map::new()),
};
// `merged` deep-merges: the named settings replace, everything else stays as `current` has it
current.merged(&composed).unwrap_or_else(|_| current.clone())
}
/// The leaves of `patch` that apply at `t` (below 100 %), each computed from the same place in
/// `base`. A leaf the amount does not reach is left out, so the photo keeps its own value there.
fn interpolate_object(base: Option<&Map<String, Value>>, patch: &Map<String, Value>, t: f64) -> Map<String, Value> {
let mut out = Map::new();
for (k, pv) in patch {
let bv = base.and_then(|b| b.get(k));
let v = match pv {
Value::Object(p) => Some(Value::Object(interpolate_object(bv.and_then(Value::as_object), p, t))),
_ => interpolate_leaf(bv, pv, t),
};
if let Some(v) = v {
out.insert(k.clone(), v);
}
}
out
}
/// One leaf at `t`. Numbers move from `base` towards `patch`. Other values switch to the preset's
/// at half amount and up, and below it take the base's value. A null in the base is the baseline
/// value the import state recorded (a cleared option, such as a free crop aspect): below half
/// amount it applies and clears the photo's value, as the amount contract promises. A null the
/// preset writes is a value like any other, so it applies at half amount and up (a preset can
/// clear an option field such as a crop aspect).
fn interpolate_leaf(base: Option<&Value>, patch: &Value, t: f64) -> Option<Value> {
match (base, patch) {
// integer fields (the grain seed, ids) are discrete like strings: see `scale_patch`
(Some(Value::Number(b)), Value::Number(p)) if b.is_f64() || p.is_f64() => {
let (b, p) = (b.as_f64().unwrap_or(0.0), p.as_f64().unwrap_or(0.0));
serde_json::Number::from_f64(b + (p - b) * t).map(Value::Number)
}
_ if t >= 0.5 => Some(patch.clone()),
_ => base.cloned(),
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Preset {
pub id: String,
pub name: String,
pub group: String,
/// Partial settings.
pub settings: Value,
#[serde(default)]
pub favorite: bool,
/// Built-in presets ship with the app and can't be deleted.
#[serde(default)]
pub builtin: bool,
}
impl Preset {
pub fn from_settings(id: &str, name: &str, group: &str, s: &DevelopSettings, groups: &[SettingsGroup]) -> Preset {
Preset { id: id.into(), name: name.into(), group: group.into(), settings: extract_groups(s, groups), favorite: false, builtin: false }
}
/// Apply at `amount` (1.0 = 100 %), with `s` as both the photo's current and its original
/// settings (see [`Preset::apply_on`]): right for the import default preset and for scratch
/// bases. Masks in the preset are added to the photo's own (ones it already has are skipped),
/// their effect scaled by the amount.
pub fn apply(&self, s: &DevelopSettings, amount: f64) -> DevelopSettings {
self.apply_on(s, s, amount)
}
/// Apply at `amount` (1.0 = 100 %), composing on `original` (the photo's import state, or the
/// photo's current settings when that is not known): each setting the preset names is computed
/// from `original` and the preset's value, `amount` moving it between the two, and replaces the
/// photo's value. Every setting the preset does not name keeps `current`'s value, and so do
/// the photo's pixel repairs (masks, spots, red eye), which the preset patches; masks in the
/// preset are added to the photo's own (ones it already has are skipped), their effect scaled
/// by the amount. A second preset therefore restores what the first one changed in the
/// settings it names (issue storytold/lightcraft#2159), and nothing it leaves out.
pub fn apply_on(&self, current: &DevelopSettings, original: &DevelopSettings, amount: f64) -> DevelopSettings {
let Some(masks) = self.settings.get("masks").and_then(Value::as_array).filter(|m| !m.is_empty()) else {
return compose_named(current, original, &self.settings, amount);
};
let mut rest = self.settings.clone();
if let Some(o) = rest.as_object_mut() {
o.remove("masks");
}
let mut out = compose_named(current, original, &rest, amount);
let ids = add_masks(&mut out, masks, amount);
// Lens Blur's focus mask names a mask by id, and the preset's masks were given the photo's free ids. It is a
// discrete setting, taken from the preset at half amount and up (`interpolate_leaf`).
let named = rest.get("lens_blur").and_then(|b| b.get("focus_mask")).and_then(Value::as_u64).and_then(|id| u32::try_from(id).ok());
if let Some(named) = named
&& amount >= 0.5
&& let Some(&id) = ids.get(&named)
{
out.lens_blur.focus_mask = Some(id);
}
out
}
}
/// The preset's masks, added to the photo's own (ones it already has are skipped), their effect
/// scaled by the amount. At no amount none is added: a mask of no effect would still be in the
/// photo's list, and would be the one "it already has" when the preset is applied again.
/// Returns the id each of the preset's masks has in the photo (its own, or the one it was given).
fn add_masks(out: &mut DevelopSettings, masks: &[Value], amount: f64) -> std::collections::HashMap<u32, u32> {
let mut ids = std::collections::HashMap::new();
if amount.is_nan() || amount <= 0.0 {
return ids;
}
// the masks by name, kept up to date: a preset of many masks compares each with its
// namesakes only, not with every mask added before it
let mut by_name: std::collections::HashMap<String, Vec<usize>> = std::collections::HashMap::new();
for (i, q) in out.masks.iter().enumerate() {
by_name.entry(q.name.clone()).or_default().push(i);
}
let mut next_id = out.next_mask_id();
let mut used: std::collections::HashSet<u32> = out.masks.iter().map(|q| q.id).collect();
for m in masks {
let Ok(mut m) = serde_json::from_value::<crate::Mask>(m.clone()) else { continue };
let had = by_name.get(&m.name).and_then(|ix| ix.iter().filter_map(|&i| out.masks.get(i)).find(|q| q.components == m.components));
if let Some(q) = had {
ids.entry(m.id).or_insert(q.id);
continue;
}
// ids run on from the first free one, past any a mask already has (a scan for the
// next free id per mask would be another pass over them)
while used.contains(&next_id) {
next_id = next_id.checked_add(1).unwrap_or(1);
}
ids.entry(m.id).or_insert(next_id);
m.id = next_id;
used.insert(next_id);
m.adjust.amount = (m.adjust.amount * amount).clamp(0.0, 200.0);
by_name.entry(m.name.clone()).or_default().push(out.masks.len());
out.masks.push(m);
}
ids
}
/// Lower-case ASCII slug for ids (`"Warm & Soft"` → `warm-soft`).
pub fn slug(s: &str) -> String {
let mut out = String::new();
for c in s.chars() {
if c.is_ascii_alphanumeric() {
out.push(c.to_ascii_lowercase());
} else if !out.ends_with('-') && !out.is_empty() {
out.push('-');
}
}
let out = out.trim_end_matches('-').to_string();
if out.is_empty() { "preset".into() } else { out }
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
#[test]
fn extract_and_apply_roundtrip() {
let mut a = DevelopSettings::default();
a.light.exposure = 1.0;
a.effects.clarity = 30.0;
a.crop.geometry.angle = 5.0;
let p = Preset::from_settings("p", "P", "User", &a, &SettingsGroup::default_copy());
assert!(p.settings.get("crop").is_none());
let b = p.apply(&DevelopSettings::default(), 1.0);
assert_eq!(b.light.exposure, 1.0);
assert_eq!(b.effects.clarity, 30.0);
assert_eq!(b.crop.geometry.angle, 0.0);
}
#[test]
fn amount_scales_numbers() {
let base = DevelopSettings::default();
let partial = json!({"light": {"exposure": 1.0, "contrast": 40}});
let half = apply_partial(&base, &partial, 0.5);
assert!((half.light.exposure - 0.5).abs() < 1e-9);
assert!((half.light.contrast - 20.0).abs() < 1e-9);
let more = apply_partial(&base, &partial, 2.0);
assert!((more.light.contrast - 80.0).abs() < 1e-9);
// clamped through specs
let lots = apply_partial(&base, &json!({"light": {"exposure": 4.0}}), 2.0);
assert_eq!(lots.light.exposure, 5.0);
}
/// A preset with the Grain group (its seed is an integer) used to do nothing at any amount
/// other than 100 %: the interpolated seed failed to deserialize and the preset was dropped.
#[test]
fn amount_keeps_integer_fields_whole() {
let mut a = DevelopSettings::default();
a.light.exposure = 1.0;
a.grain.amount = 40.0;
a.grain.seed = 12345;
let p = Preset::from_settings("p", "P", "User", &a, &SettingsGroup::default_copy());
assert!(p.settings.pointer("/grain/seed").is_some_and(Value::is_u64), "the default copy groups include the grain seed");
let base = DevelopSettings::default();
for (amount, seed) in [(0.3, 0), (0.5, 12345), (1.5, 12345), (2.0, 12345)] {
let out = p.apply(&base, amount);
assert!((out.light.exposure - amount.min(5.0)).abs() < 1e-9, "{amount}: exposure {}", out.light.exposure);
assert!((out.grain.amount - (40.0 * amount).min(100.0)).abs() < 1e-9, "{amount}: grain {}", out.grain.amount);
assert_eq!(out.grain.seed, seed, "{amount}: seed");
}
}
/// A preset changes only the settings it names: a setting in a group it styles but does not
/// name keeps the photo's value, and so does a whole group it leaves out.
#[test]
fn apply_on_changes_only_the_settings_it_names() {
let mut current = DevelopSettings::default();
current.light.exposure = 2.0;
current.light.blacks = -30.0;
current.effects.clarity = 30.0;
let original = DevelopSettings::default();
let p = Preset {
id: "p".into(),
name: "P".into(),
group: "G".into(),
settings: json!({"light": {"contrast": 12.0}}),
favorite: false,
builtin: false,
};
let out = p.apply_on(&current, &original, 1.0);
assert_eq!(out.light.contrast, 12.0);
assert_eq!(out.light.exposure, 2.0, "a setting the preset doesn't name keeps the photo's value");
assert_eq!(out.light.blacks, -30.0, "a setting in the same group, not named, keeps the photo's value");
assert_eq!(out.effects.clarity, 30.0, "a group the preset doesn't name is untouched");
}
/// A partial preset that names one colour of the mixer leaves the other colours, and the
/// unnamed settings of the colour it names, as the photo has them.
#[test]
fn apply_on_keeps_the_mixer_colours_it_does_not_name() {
let mut current = DevelopSettings::default();
current.mixer.red.sat = 20.0;
current.mixer.blue.hue = 15.0;
current.mixer.blue.sat = 5.0;
let original = DevelopSettings::default();
let p = Preset {
id: "p".into(),
name: "P".into(),
group: "G".into(),
settings: json!({"mixer": {"blue": {"sat": 15.0, "lum": -25.0}}}),
favorite: false,
builtin: false,
};
let out = p.apply_on(&current, &original, 1.0);
assert_eq!(out.mixer.red.sat, 20.0, "a colour the preset doesn't name");
assert_eq!(out.mixer.blue.hue, 15.0, "a setting of a named colour that the preset doesn't name");
assert_eq!((out.mixer.blue.sat, out.mixer.blue.lum), (15.0, -25.0));
}
/// The white balance is not one setting: a preset that names only the temperature keeps the
/// photo's tint.
#[test]
fn apply_on_keeps_the_white_balance_fields_it_does_not_name() {
let mut current = DevelopSettings::default();
current.wb.temp = 6000.0;
current.wb.tint = 12.0;
let original = DevelopSettings::default();
let p = Preset {
id: "p".into(),
name: "P".into(),
group: "G".into(),
settings: json!({"wb": {"temp": 5000.0}}),
favorite: false,
builtin: false,
};
let out = p.apply_on(&current, &original, 1.0);
assert_eq!((out.wb.temp, out.wb.tint), (5000.0, 12.0));
}
/// A preset's amount 0 changes nothing when the original is the photo's current settings (no
/// import state is recorded for the photo), and any other amount moves the named settings
/// from where the photo has them.
#[test]
fn apply_on_without_an_import_state_scales_from_the_current_settings() {
let mut current = DevelopSettings::default();
current.light.exposure = 2.0;
current.light.blacks = -30.0;
let p = Preset {
id: "p".into(),
name: "P".into(),
group: "G".into(),
settings: json!({"light": {"exposure": 0.45, "contrast": 12.0}}),
favorite: false,
builtin: false,
};
assert_eq!(p.apply_on(&current, &current, 0.0), current, "amount 0 applies nothing");
let half = p.apply_on(&current, &current, 0.5);
assert!((half.light.exposure - 1.225).abs() < 1e-9, "{}", half.light.exposure);
assert_eq!(half.light.blacks, -30.0);
}
/// An unresolved `crs:Look` reference (its profile object has no id; the importer leaves
/// `look` in it) changes nothing: the photo keeps its own profile.
#[test]
fn an_unresolved_profile_reference_keeps_the_photos_profile() {
let mut current = DevelopSettings::default();
current.profile.id = "lc.vivid".into();
current.profile.amount = 60.0;
let p = Preset {
id: "p".into(),
name: "P".into(),
group: "G".into(),
settings: json!({"profile": {"look": {"name": "Not imported", "amount": 100.0}}, "light": {"contrast": 12.0}}),
favorite: false,
builtin: false,
};
for amount in [1.0, 0.5] {
let out = p.apply_on(&current, &current, amount);
assert_eq!((out.profile.id.as_str(), out.profile.amount), ("lc.vivid", 60.0), "amount {amount}");
}
}
/// The amount interpolates between the original and the preset, not between the visible
/// values and the preset: a preset at 50 % looks the same however the photo was edited before.
#[test]
fn apply_on_scales_against_the_original() {
let mut current = DevelopSettings::default();
current.light.exposure = 2.0;
let original = DevelopSettings::default();
let p = Preset {
id: "p".into(),
name: "P".into(),
group: "G".into(),
settings: json!({"light": {"exposure": 0.45}}),
favorite: false,
builtin: false,
};
let out = p.apply_on(&current, &original, 0.5);
assert!((out.light.exposure - 0.225).abs() < 1e-9, "{}", out.light.exposure);
}
/// Pixel repairs are the photo's own: a preset's are patched in, and one without them never
/// restores the original's.
#[test]
fn apply_on_patches_pixel_repairs_into_the_current_ones() {
let current = DevelopSettings {
spots: serde_json::from_value(json!([{"mode": "heal", "points": [[0.5, 0.5]], "size": 0.05, "feather": 50.0, "opacity": 100.0}]))
.unwrap(),
..Default::default()
};
let original = DevelopSettings::default();
let none = Preset {
id: "p".into(),
name: "P".into(),
group: "G".into(),
settings: json!({"light": {"contrast": 10.0}}),
favorite: false,
builtin: false,
};
let out = none.apply_on(&current, &original, 1.0);
assert_eq!(out.spots.len(), 1, "the photo's spot survives a preset without spots");
let clearing = Preset {
id: "q".into(),
name: "Q".into(),
group: "G".into(),
settings: json!({"light": {"contrast": 10.0}, "spots": []}),
favorite: false,
builtin: false,
};
let out = clearing.apply_on(&current, &original, 1.0);
assert_eq!(out.spots.len(), 0, "a preset that names spots replaces them, as before");
}
/// A null a preset writes into an option field (here a crop aspect: null is "free") is the
/// preset's value, so it clears the photo's aspect from half amount up, as any value of the
/// preset does; below half amount the import baseline applies, which here is null as well.
#[test]
fn a_preset_null_clears_an_option_field_from_half_amount() {
let mut current = DevelopSettings::default();
current.crop.aspect = Some((3, 2));
let original = DevelopSettings::default(); // the import state has no aspect
let p = Preset {
id: "p".into(),
name: "P".into(),
group: "G".into(),
settings: json!({"crop": {"aspect": null}}),
favorite: false,
builtin: false,
};
for amount in [1.0, 0.7, 0.5] {
assert_eq!(p.apply_on(&current, &original, amount).crop.aspect, None, "amount {amount}: the preset's null clears the aspect");
}
assert_eq!(p.apply_on(&current, &original, 0.3).crop.aspect, None, "below half amount the import baseline (no aspect) applies");
}
/// The import state has no aspect, and that null is the baseline below half amount (the amount
/// contract: a named setting moves between the import state and the preset's value); from half
/// amount the preset's aspect applies.
#[test]
fn a_null_in_the_original_is_the_baseline_below_half_amount() {
let mut current = DevelopSettings::default();
current.crop.aspect = Some((3, 2));
let original = DevelopSettings::default();
let p = Preset {
id: "p".into(),
name: "P".into(),
group: "G".into(),
settings: json!({"crop": {"aspect": [16, 9]}}),
favorite: false,
builtin: false,
};
assert_eq!(p.apply_on(&current, &original, 0.4).crop.aspect, None, "40 %: the import baseline (no aspect) applies");
assert_eq!(p.apply_on(&current, &original, 0.6).crop.aspect, Some((16, 9)), "60 %: the preset's aspect applies");
}
#[test]
fn deep_merge_objects() {
let mut a = json!({"x": {"a": 1, "b": 2}, "y": [1]});
deep_merge(&mut a, &json!({"x": {"b": 3}, "y": [2, 3]}));
assert_eq!(a, json!({"x": {"a": 1, "b": 3}, "y": [2, 3]}));
}
#[test]
fn preset_masks_get_unused_ids_after_a_mask_id_at_the_limit() {
let s = DevelopSettings { masks: vec![crate::Mask { id: u32::MAX, name: "Theirs".into(), ..Default::default() }], ..Default::default() };
let p = Preset {
id: "p".into(),
name: "P".into(),
group: "User".into(),
settings: json!({"masks": [{"id": 7, "name": "A"}, {"id": 7, "name": "B"}]}),
favorite: false,
builtin: false,
};
let out = p.apply(&s, 1.0);
let mut ids: Vec<u32> = out.masks.iter().map(|m| m.id).collect();
assert_eq!(ids.len(), 3);
ids.sort_unstable();
ids.dedup();
assert_eq!(ids.len(), 3, "{:?}", out.masks);
}
#[test]
fn preset_masks_skip_ids_an_existing_mask_has_after_the_first_free_one() {
// the first free id is 1, and 2 is taken: the second added mask must not get 2
let theirs = |id| crate::Mask { id, name: format!("T{id}"), ..Default::default() };
let s = DevelopSettings { masks: vec![theirs(u32::MAX), theirs(2)], ..Default::default() };
let p = Preset {
id: "p".into(),
name: "P".into(),
group: "User".into(),
settings: json!({"masks": [{"name": "A"}, {"name": "B"}]}),
favorite: false,
builtin: false,
};
let mut ids: Vec<u32> = p.apply(&s, 1.0).masks.iter().map(|m| m.id).collect();
ids.sort_unstable();
assert_eq!(ids, [1, 2, 3, u32::MAX]);
}
}
+337
View File
@@ -0,0 +1,337 @@
//! Model segmentations stored with a mask ([`SegMask`]), so rendering never needs the model.
use std::cell::RefCell;
use std::collections::HashMap;
use serde::{Deserialize, Serialize, Serializer};
/// Logits are stored in steps of 1/`SCALE`, clamped to ±127/`SCALE` (≈ ±15.9: a sigmoid of
/// 1 − 1.2e-7, i.e. fully in or out).
const SCALE: f32 = 8.0;
/// Largest grid a stored segmentation may claim (hostile input caps the allocation).
pub const MAX_SIDE: usize = 1024;
/// A segmentation computed by a model (SAM 3 in `lightcraft-segment`): `side × side` logits
/// over the uncropped, oriented image stretched to a square (row `y`, column `x` covers
/// normalized `((x + 0.5) / side, (y + 0.5) / side)`), quantized to `i8`, deflated and base64
/// encoded. Coverage at a point is the sigmoid of the bilinearly sampled logit, so edges stay
/// smooth at any output size.
#[derive(Clone, Debug, PartialEq, Deserialize)]
pub struct SegMask {
pub side: u32,
/// The grid's bytes (quantized, deflated, base64), unless this is a reference into the
/// snapshot's shared grid table (`grid` is set and `data` is empty).
#[serde(default)]
pub data: String,
/// The part of the image the grid covers, normalized `[x0, y0, x1, y1]` (`None` = all of
/// it). A zoomed-in pass over one object covers just its surroundings, at a higher
/// resolution than a pass over the whole photo.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rect: Option<[f64; 4]>,
/// Index into the catalog snapshot's shared grid table (`Catalog::grids`) this mask refers
/// to instead of carrying its own `data`. A serialization detail of snapshots only: the
/// snapshot writer sets it (through the interner, into its own table), `Catalog::repair`
/// resolves it when a snapshot is read, and no other serialization writes it. A `grid` that
/// arrives from any other document (a command, a preset, XMP, a log record) is read but
/// never written back, so it cannot point a snapshot at another mask's grid.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub grid: Option<u32>,
}
impl SegMask {
/// From `side × side` logits over the whole image.
pub fn from_logits(side: usize, logits: &[f32]) -> SegMask {
// `side` is the caller's. One no mask may have (see [`MAX_SIDE`]) gives a mask without data, which reads as
// damaged, instead of a `side` cut down to 32 bits that some other grid would fit.
if side > MAX_SIDE {
return SegMask { side: 0, data: String::new(), rect: None, grid: None };
}
let q: Vec<u8> = logits.iter().take(side.saturating_mul(side)).map(|l| ((l * SCALE).round().clamp(-127.0, 127.0) as i8) as u8).collect();
let z = miniz_oxide::deflate::compress_to_vec(&q, 8);
SegMask { side: side as u32, data: base64_encode(&z), rect: None, grid: None }
}
/// From `side × side` logits over the part `rect` of the image.
pub fn from_logits_in(side: usize, logits: &[f32], rect: [f64; 4]) -> SegMask {
SegMask { rect: Some(rect), ..SegMask::from_logits(side, logits) }
}
/// The covered part, normalized (the whole image without a `rect`); `None` when damaged.
pub fn bounds(&self) -> Option<[f64; 4]> {
let r = self.rect.unwrap_or([0.0, 0.0, 1.0, 1.0]);
(r.iter().all(|v| v.is_finite()) && r[2] > r[0] && r[3] > r[1]).then_some(r)
}
/// The logits, or `None` when the data is damaged or claims an absurd size.
pub fn logits(&self) -> Option<Vec<f32>> {
let side = self.side as usize;
if side == 0 || side > MAX_SIDE {
return None;
}
// Deflate's worst case is the bytes stored plus a few per block, and base64 adds a third. Text longer than
// that (with room for line breaks) is not this grid, so it is turned away before it is decoded.
let cells = side * side;
if self.data.len() > (cells + cells / 8 + 64) * 2 {
return None;
}
let z = base64_decode(&self.data)?;
let q = miniz_oxide::inflate::decompress_to_vec_with_limit(&z, side * side).ok()?;
(q.len() == side * side).then(|| q.iter().map(|b| f32::from(*b as i8) / SCALE).collect())
}
}
// The grid table a snapshot serialization refers to: each distinct grid's data → its index.
thread_local! {
static INTERNER: RefCell<Option<HashMap<String, u32>>> = const { RefCell::new(None) };
}
/// Serializes masks as references into a shared grid table (`grid` = index, `data` omitted)
/// while `f` runs, one thread at a time (snapshot writes). Nested calls are ignored (`None`):
/// the outermost writer owns the table.
pub fn with_grid_interner<T>(map: HashMap<String, u32>, f: impl FnOnce() -> T) -> Option<T> {
INTERNER.with(|i| {
if i.borrow().is_some() {
return None;
}
struct Guard;
impl Drop for Guard {
fn drop(&mut self) {
INTERNER.with(|j| *j.borrow_mut() = None);
}
}
*i.borrow_mut() = Some(map);
let _guard = Guard;
Some(f())
})
}
impl Serialize for SegMask {
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
use serde::ser::SerializeMap;
// While a snapshot is being written with a shared grid table, a mask whose exact bytes
// are in the table refers to it by index instead of repeating the blob (issue storytold/lightcraft#2154).
if !self.data.is_empty()
&& let Some(id) = INTERNER.with(|i| i.borrow().as_ref().and_then(|m| m.get(&self.data).copied()))
{
let len = if self.rect.is_some() { 3 } else { 2 };
let mut map = serializer.serialize_map(Some(len))?;
map.serialize_entry("side", &self.side)?;
map.serialize_entry("grid", &id)?;
if let Some(rect) = self.rect {
map.serialize_entry("rect", &rect)?;
}
return map.end();
}
// Without a table hit: exactly the pre-v10 derived form (field order and skips included),
// so every serialization that doesn't dedup keeps its bytes (`hash64`, cache keys). `grid`
// is never written here: a value read from some document is dropped on save, and only the
// interner above can write a reference (into the table of the snapshot being written).
let len = 2 + usize::from(self.rect.is_some());
let mut map = serializer.serialize_map(Some(len))?;
map.serialize_entry("side", &self.side)?;
map.serialize_entry("data", &self.data)?;
if let Some(rect) = self.rect {
map.serialize_entry("rect", &rect)?;
}
map.end()
}
}
/// Most zoomed-in detail patches one AI mask component keeps (the app makes one; each costs a
/// decode per render, so a hostile document can't make rendering explode).
pub const MAX_DETAIL: usize = 4;
/// Deserialize a component's detail patches, keeping at most [`MAX_DETAIL`] (the rest are
/// skipped without being decoded).
pub(crate) fn de_detail<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Vec<SegMask>, D::Error> {
struct Capped;
impl<'de> serde::de::Visitor<'de> for Capped {
type Value = Vec<SegMask>;
fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
f.write_str("a list of segmentations")
}
fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut seq: A) -> Result<Vec<SegMask>, A::Error> {
let mut out = Vec::new();
while out.len() < MAX_DETAIL {
match seq.next_element::<SegMask>()? {
Some(m) => out.push(m),
None => return Ok(out),
}
}
while seq.next_element::<serde::de::IgnoredAny>()?.is_some() {}
Ok(out)
}
}
d.deserialize_seq(Capped)
}
const B64: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
fn base64_encode(bytes: &[u8]) -> String {
let mut out = String::with_capacity(bytes.len().div_ceil(3) * 4);
for chunk in bytes.chunks(3) {
let b = [chunk.first().copied().unwrap_or(0), chunk.get(1).copied().unwrap_or(0), chunk.get(2).copied().unwrap_or(0)];
let n = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]);
for i in 0..4 {
if i <= chunk.len() {
out.push(char::from(B64[((n >> (18 - 6 * i)) & 63) as usize]));
} else {
out.push('=');
}
}
}
out
}
fn base64_decode(s: &str) -> Option<Vec<u8>> {
let mut out = Vec::with_capacity(s.len() / 4 * 3);
let (mut acc, mut bits) = (0u32, 0u32);
let mut padded = false;
for c in s.bytes().filter(|c| !c.is_ascii_whitespace()) {
if c == b'=' {
padded = true;
continue;
}
if padded {
return None;
}
let v = B64.iter().position(|b| *b == c)? as u32;
acc = (acc << 6) | v;
bits += 6;
if bits >= 8 {
bits -= 8;
out.push((acc >> bits) as u8);
acc &= (1 << bits) - 1;
}
}
if bits == 6 {
return None;
}
Some(out)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn base64_round_trips() {
for n in 0..10 {
let v: Vec<u8> = (0..n).map(|i| (i * 37 + 11) as u8).collect();
assert_eq!(base64_decode(&base64_encode(&v)).unwrap(), v);
}
assert_eq!(base64_encode(b"Man"), "TWFu");
assert_eq!(base64_encode(b"Ma"), "TWE=");
assert!(base64_decode("TW!u").is_none());
assert!(base64_decode("Z").is_none());
assert!(base64_decode("Zm9vY").is_none());
assert!(base64_decode("Zg==!!!not-base64").is_none());
assert_eq!(base64_decode("Zg==\n").unwrap(), b"f");
}
#[test]
fn logits_round_trip_quantized() {
let side = 16;
let l: Vec<f32> = (0..side * side).map(|i| (i as f32 - 128.0) / 4.0).collect();
let m = SegMask::from_logits(side, &l);
let back = m.logits().unwrap();
for (a, b) in l.iter().zip(&back) {
assert!((a.clamp(-127.0 / SCALE, 127.0 / SCALE) - b).abs() <= 0.5 / SCALE + 1e-6);
}
}
#[test]
fn a_hostile_document_keeps_at_most_max_detail_patches() {
let patch = serde_json::to_value(SegMask::from_logits(4, &[1.0; 16])).unwrap();
let shape = serde_json::json!({"kind": "object", "hint": [{"x": 0.5, "y": 0.5}], "detail": vec![patch; 10_000]});
let s: crate::MaskShape = serde_json::from_value(shape).unwrap();
let crate::MaskShape::Object { detail, .. } = s else { panic!("an Object") };
assert_eq!(detail.len(), MAX_DETAIL);
// and a whole develop document with them still loads
let mut d = crate::DevelopSettings::default();
d.masks.push(crate::Mask {
id: 1,
components: vec![crate::MaskComponent {
name: None,
op: crate::MaskOp::Add,
invert: false,
shape: crate::MaskShape::Prompt { text: "x".into(), seg: None, detail: vec![SegMask::from_logits(4, &[1.0; 16]); 50], edge: 0.0 },
}],
..Default::default()
});
let back: crate::DevelopSettings = serde_json::from_str(&serde_json::to_string(&d).unwrap()).unwrap();
let crate::MaskShape::Prompt { detail, .. } = &back.masks[0].components[0].shape else { panic!("a Prompt") };
assert_eq!(detail.len(), MAX_DETAIL);
}
#[test]
fn a_side_no_mask_may_have_makes_no_mask() {
// 2³² + 1 cut down to 32 bits is 1, which one logit would fit
for side in [MAX_SIDE + 1, u32::MAX as usize + 2, usize::MAX] {
let m = SegMask::from_logits(side, &[1.0]);
assert_eq!((m.side, m.logits()), (0, None), "side {side}");
}
// the largest grid, with data deflate cannot shrink, still reads back
let noise: Vec<f32> = (0..MAX_SIDE * MAX_SIDE).map(|i| ((i as u64).wrapping_mul(0x9E37_79B9_7F4A_7C15) >> 56) as i8 as f32 / SCALE).collect();
let m = SegMask::from_logits(MAX_SIDE, &noise);
assert_eq!(m.logits().map(|l| l.len()), Some(MAX_SIDE * MAX_SIDE));
// text far longer than any grid of this side deflates to is turned away
let long = SegMask { side: 2, data: "A".repeat(1 << 20), rect: None, grid: None };
assert!(long.logits().is_none());
}
#[test]
fn damaged_data_is_none() {
let mut m = SegMask::from_logits(8, &[1.0; 64]);
m.side = 9;
assert!(m.logits().is_none(), "size mismatch");
m.side = 100_000;
assert!(m.logits().is_none(), "absurd size");
assert!(SegMask { side: 8, data: "not base64 !".into(), rect: None, grid: None }.logits().is_none());
assert!(SegMask { rect: Some([0.5, 0.0, 0.2, 1.0]), ..SegMask::from_logits(2, &[0.0; 4]) }.bounds().is_none());
}
/// A `grid` read from a document is never written outside the snapshot interner, with or
/// without data: the bytes stay the pre-v10 form, so `hash64` and cache keys don't depend on
/// a stray value (issue storytold/lightcraft#2154).
#[test]
fn stray_grid_is_never_written_outside_the_interner() {
let empty = SegMask { side: 4, data: String::new(), rect: None, grid: None };
let stray = SegMask { grid: Some(3), ..empty.clone() };
assert_eq!(serde_json::to_string(&stray).unwrap(), "{\"side\":4,\"data\":\"\"}");
assert_eq!(serde_json::to_string(&stray).unwrap(), serde_json::to_string(&empty).unwrap());
let with_data = SegMask { grid: Some(3), ..SegMask::from_logits(4, &[1.0; 16]) };
assert!(!serde_json::to_string(&with_data).unwrap().contains("grid"), "no grid key outside the interner");
}
/// Without the snapshot interner the JSON is exactly the derived form it always was; with
/// it, a pooled grid serializes as an index and the data is left to the table (issue storytold/lightcraft#2154).
#[test]
fn serialization_refs_only_under_the_interner() {
let m = SegMask::from_logits(4, &[1.0; 16]);
let plain = serde_json::to_string(&m).unwrap();
assert_eq!(plain, format!("{{\"side\":4,\"data\":\"{}\"}}", m.data), "no interner: unchanged bytes");
let with_rect = SegMask { rect: Some([0.0, 0.0, 0.5, 0.5]), ..m.clone() };
assert_eq!(serde_json::to_string(&with_rect).unwrap(), format!("{{\"side\":4,\"data\":\"{}\",\"rect\":[0.0,0.0,0.5,0.5]}}", m.data));
let mut table = std::collections::HashMap::new();
table.insert(m.data.clone(), 3u32);
let referenced = with_grid_interner(table, || serde_json::to_string(&m).unwrap()).unwrap();
assert_eq!(referenced, "{\"side\":4,\"grid\":3}", "pooled grid: an index, no data");
// a grid the table doesn't hold, and an empty-data mask, stay inline
let other = SegMask::from_logits(2, &[0.0; 4]);
let mixed = with_grid_interner(std::collections::HashMap::new(), || serde_json::to_string(&other).unwrap()).unwrap();
assert_eq!(mixed, format!("{{\"side\":2,\"data\":\"{}\"}}", other.data));
// the interner is gone afterwards: serialization is inline again
assert_eq!(serde_json::to_string(&m).unwrap(), plain);
// nested calls are ignored: the outer writer keeps its table
let outer_table = std::collections::HashMap::from([(m.data.clone(), 0u32)]);
let nested = with_grid_interner(outer_table, || {
let inner_table = std::collections::HashMap::from([(other.data.clone(), 1u32)]);
(with_grid_interner(inner_table, || serde_json::to_string(&other).unwrap()), serde_json::to_string(&m).unwrap())
})
.unwrap();
assert_eq!(nested.0, None, "the nested writer is refused");
assert_eq!(nested.1, "{\"side\":4,\"grid\":0}");
}
}
File diff suppressed because it is too large. Load diff
+162
View File
@@ -0,0 +1,162 @@
//! Process versions: settings saved before they existed stay on V1, new settings get the latest,
//! and numbers this build doesn't know load without harm.
use serde_json::{Value, json};
use crate::*;
/// Complete settings as LightCraft wrote them before process versions existed (main at 8f924a9:
/// `serde_json::to_string` of a raw photo with tone, colour, curve, grading, effects and a radial
/// mask), one top-level key per line. There is no `process` field.
const LEGACY: &str = r#"
{
"version": 1,
"profile": {"id": "lc.color", "amount": 100.0},
"treatment": "color",
"wb": {"mode": "asShot", "temp": 5200.0, "tint": 4.0},
"light": {"exposure": 0.4, "contrast": 30.0, "highlights": -60.0, "shadows": 40.0, "whites": 15.0, "blacks": -20.0},
"curve": {"highlights": -10.0, "lights": 0.0, "darks": 10.0, "shadows": 0.0, "split_shadows": 25.0, "split_mid": 50.0, "split_highlights": 75.0, "master": [{"x": 0.0, "y": 0.05}, {"x": 0.5, "y": 0.55}, {"x": 1.0, "y": 0.95}], "red": [], "green": [], "blue": [], "refine_saturation": 100.0},
"color": {"vibrance": 20.0, "saturation": -5.0},
"mixer": {"red": {"hue": 0.0, "sat": 0.0, "lum": 0.0}, "orange": {"hue": 0.0, "sat": 0.0, "lum": 15.0}, "yellow": {"hue": 0.0, "sat": 0.0, "lum": 0.0}, "green": {"hue": 0.0, "sat": 0.0, "lum": 0.0}, "aqua": {"hue": 0.0, "sat": 0.0, "lum": 0.0}, "blue": {"hue": 0.0, "sat": -30.0, "lum": 0.0}, "purple": {"hue": 0.0, "sat": 0.0, "lum": 0.0}, "magenta": {"hue": 0.0, "sat": 0.0, "lum": 0.0}},
"point_colors": [],
"bw_mix": {"red": 0.0, "orange": 0.0, "yellow": 0.0, "green": 0.0, "aqua": 0.0, "blue": 0.0, "purple": 0.0, "magenta": 0.0},
"grading": {"shadows": {"hue": 220.0, "sat": 20.0, "lum": -5.0}, "midtones": {"hue": 0.0, "sat": 0.0, "lum": 0.0}, "highlights": {"hue": 40.0, "sat": 15.0, "lum": 5.0}, "global": {"hue": 0.0, "sat": 0.0, "lum": 0.0}, "blending": 50.0, "balance": 0.0},
"effects": {"texture": 20.0, "clarity": 25.0, "dehaze": 15.0},
"vignette": {"amount": -25.0, "midpoint": 50.0, "roundness": 0.0, "feather": 50.0, "highlights": 0.0, "style": "highlightPriority"},
"grain": {"amount": 20.0, "size": 25.0, "roughness": 50.0, "seed": 0},
"detail": {"sharpen_amount": 40.0, "sharpen_radius": 1.0, "sharpen_detail": 25.0, "sharpen_masking": 0.0, "nr_luminance": 20.0, "nr_detail": 50.0, "nr_contrast": 0.0, "nr_color": 25.0, "nr_color_detail": 50.0, "nr_color_smoothness": 50.0},
"optics": {"remove_ca": false, "lens_profile": false, "profile_distortion": 100.0, "profile_vignetting": 100.0, "defringe_purple_amount": 0.0, "defringe_purple_hue_lo": 30.0, "defringe_purple_hue_hi": 70.0, "defringe_green_amount": 0.0, "defringe_green_hue_lo": 40.0, "defringe_green_hue_hi": 60.0, "distortion": 0.0, "vignetting": 0.0, "vignetting_midpoint": 50.0, "ca_red": 0.0, "ca_blue": 0.0},
"geometry": {"upright": "off", "guides": [], "upright_transform": null, "vertical": 0.0, "horizontal": 0.0, "rotate": 0.0, "aspect": 0.0, "scale": 100.0, "offset_x": 0.0, "offset_y": 0.0, "constrain_crop": false},
"crop": {"geometry": {"rect": {"x0": 0.0, "y0": 0.0, "x1": 1.0, "y1": 1.0}, "angle": 0.0}, "aspect": null, "flip_h": false, "flip_v": false},
"orientation": "Normal",
"masks": [{"id": 1, "name": "Mask 1", "visible": true, "invert": false, "components": [{"op": "add", "invert": false, "shape": {"kind": "radial", "center": {"x": 0.4, "y": 0.5}, "rx": 0.3, "ry": 0.2, "angle": 15.0, "feather": 60.0, "invert": false}}], "adjust": {"temp": 10.0, "tint": 0.0, "exposure": 0.5, "contrast": 0.0, "highlights": 0.0, "shadows": 0.0, "whites": 0.0, "blacks": 0.0, "texture": 0.0, "clarity": 30.0, "dehaze": 0.0, "hue": 0.0, "saturation": 0.0, "sharpness": 0.0, "noise": 0.0, "moire": 0.0, "defringe": 0.0, "color_hue": 0.0, "color_sat": 0.0, "amount": 100.0}}],
"spots": [],
"red_eye": [],
"lens_blur": {"enabled": false, "amount": 0.0, "focal_distance": 0.0, "focal_range": 0.0},
"enhance": {"denoise": 0.0, "raw_details": false, "super_resolution": false},
"calibration": {"shadows_tint": 0.0, "red_hue": 0.0, "red_sat": 0.0, "green_hue": 0.0, "green_sat": 0.0, "blue_hue": 0.0, "blue_sat": 0.0},
"disabled_sections": []
}
"#;
fn legacy() -> Value {
serde_json::from_str(LEGACY).unwrap()
}
#[test]
fn settings_saved_before_process_versions_load_as_v1() {
let v = legacy();
assert!(v.get("process").is_none(), "the fixture predates the field");
let s = DevelopSettings::from_json(&v).unwrap();
// V1 as a number, not `LATEST`: once a newer process is the latest, this is what keeps every
// existing catalog, sidecar and preset on the rendering it was made with
assert_eq!(s.process, ProcessVersion(1));
assert_eq!(s.process, ProcessVersion::legacy());
assert_eq!((s.light.exposure, s.light.highlights, s.masks.len(), s.detail.sharpen_amount), (0.4, -60.0, 1, 40.0));
// the smallest legacy file too, and settings nested in other records (history, versions)
assert_eq!(DevelopSettings::from_json(&json!({})).unwrap().process, ProcessVersion(1));
let nested: Vec<DevelopSettings> = serde_json::from_value(json!([{}, {"light": {"exposure": 1.0}}])).unwrap();
assert!(nested.iter().all(|s| s.process == ProcessVersion(1)));
// saved again, they gain no field: files and preview-cache keys (`hash64`) stay as they were
assert!(s.to_json().get("process").is_none());
}
#[test]
fn new_settings_get_the_latest_process() {
assert_eq!(DevelopSettings::default().process, ProcessVersion::LATEST);
assert_eq!(DevelopSettings::for_raw(5200.0, 4.0).process, ProcessVersion::LATEST);
assert_eq!(ProcessVersion::LATEST, Process::LATEST.version());
assert_eq!(ProcessVersion::V1, ProcessVersion(1));
// the processes are listed oldest first, the latest last, each with its own number
let versions: Vec<u32> = Process::ALL.iter().map(|p| p.version().0).collect();
assert!(versions.windows(2).all(|w| w[0] < w[1]), "{versions:?}");
assert_eq!(Process::ALL.last(), Some(&Process::LATEST));
assert!(Process::ALL.iter().all(|p| p.version().process() == *p && p.version().is_known()));
}
#[test]
fn v1_is_left_out_when_saving_and_other_processes_are_kept() {
let mut s = DevelopSettings::from_json(&legacy()).unwrap();
assert!(s.to_json().get("process").is_none());
let before = s.hash64();
s.process = ProcessVersion(2);
let v = s.to_json();
assert_eq!(v["process"], json!(2));
assert_eq!(DevelopSettings::from_json(&v).unwrap().process, ProcessVersion(2));
assert_ne!(s.hash64(), before, "another process is another preview");
}
#[test]
fn unknown_process_numbers_load_and_render_with_the_newest_known() {
// written by a newer LightCraft: kept as it is, rendered with the latest process this build has
let s = DevelopSettings::from_json(&json!({"process": LATEST_PLUS_ONE, "light": {"exposure": 0.5}})).unwrap();
assert_eq!(s.process, ProcessVersion(LATEST_PLUS_ONE));
assert_eq!(s.process.process(), Process::LATEST);
assert!(!s.process.is_known());
assert!(!s.process.is_outdated(), "never downgraded by Update to Current Process");
assert_eq!(s.to_json()["process"], json!(LATEST_PLUS_ONE));
assert_eq!(s.merged(&json!({"light": {"exposure": 1.0}})).unwrap().process, ProcessVersion(LATEST_PLUS_ONE));
// below V1 (no LightCraft writes it): rendered as V1, and updatable
let zero = DevelopSettings::from_json(&json!({"process": 0})).unwrap().process;
assert_eq!((zero.process(), zero.is_known(), zero.is_outdated()), (Process::V1, false, true));
let max = DevelopSettings::from_json(&json!({"process": u32::MAX})).unwrap().process;
assert_eq!(max.process(), Process::LATEST);
// a whole number written as a float is that number
assert_eq!(DevelopSettings::from_json(&json!({"process": 2.0})).unwrap().process, ProcessVersion(2));
}
#[test]
fn a_damaged_process_value_reads_as_v1_and_keeps_the_edits() {
let too_big = u64::from(u32::MAX) + 1;
for bad in [
json!(-1),
json!(1.5),
json!(-0.5),
json!(1e300),
json!(too_big),
json!(u64::MAX),
json!("2"),
json!(null),
json!(true),
json!([2]),
json!({"v": 2}),
] {
let mut v = legacy();
v["process"] = bad.clone();
let s = DevelopSettings::from_json(&v).unwrap_or_else(|e| panic!("{bad}: {e}"));
assert_eq!(s.process, ProcessVersion::V1, "{bad}");
assert_eq!((s.light.exposure, s.masks.len(), s.curve.master.len()), (0.4, 1, 3), "{bad}: the rest of the settings load");
// nested in other records too (history, versions, the catalog)
let nested: Vec<DevelopSettings> = serde_json::from_value(json!([v])).unwrap();
assert_eq!(nested[0].process, ProcessVersion::V1);
}
}
#[test]
fn the_process_is_not_an_edit_nor_part_of_copied_settings() {
let mut s = DevelopSettings { process: ProcessVersion(LATEST_PLUS_ONE), ..Default::default() };
assert!(s.is_unedited(), "a photo on another process is not edited for that");
s.light.exposure = 1.0;
assert!(!s.is_unedited());
// resetting a section or a slider leaves the process alone
s.reset_section(Section::Light);
assert_eq!(s.process, ProcessVersion(LATEST_PLUS_ONE));
// copy / paste / sync / presets: no group carries the process, so the target keeps its own
assert!(SettingsGroup::ALL.iter().all(|g| !g.keys().contains(&"process")));
s.light.exposure = 1.0;
let copied = extract_groups(&s, &SettingsGroup::ALL);
assert!(copied.get("process").is_none());
let target = DevelopSettings::from_json(&legacy()).unwrap();
let pasted = apply_partial(&target, &copied, 1.0);
assert_eq!((pasted.process, pasted.light.exposure), (ProcessVersion(1), 1.0));
// (at another amount, without Grain: its integer seed doesn't survive scaling, a separate issue)
let groups: Vec<SettingsGroup> = SettingsGroup::ALL.into_iter().filter(|g| *g != SettingsGroup::Grain).collect();
let preset = Preset::from_settings("p", "P", "User", &s, &groups);
let half = preset.apply(&target, 0.5);
assert_eq!((half.process, half.light.exposure), (ProcessVersion(1), 0.7));
// a partial that names a process explicitly (Apply Settings JSON) sets it
assert_eq!(target.merged(&json!({"process": LATEST_PLUS_ONE})).unwrap().process, ProcessVersion(LATEST_PLUS_ONE));
}
/// A process other than the latest: a newer LightCraft's number (no older one than V1 exists).
const LATEST_PLUS_ONE: u32 = ProcessVersion::LATEST.0 + 1;
@@ -0,0 +1,120 @@
//! Copy / paste, presets at an amount, section reset and settings from outside the app: the settings the stored
//! JSON leaves out at their defaults, and the sliders of list entries, behave like every other setting.
#![allow(clippy::unwrap_used)]
use craft_develop_model::{DevelopSettings, Mask, PointColor, Preset, Section, SegMask, SettingsGroup, Upright, WbMode, extract_groups};
use craft_geom::Point;
use serde_json::json;
fn preset(settings: serde_json::Value) -> Preset {
Preset { id: "t".into(), name: "t".into(), group: "g".into(), settings, favorite: false, builtin: false }
}
/// The camera's local tone and an HDR edit are left out of the stored JSON when off. Copying Profile and Light from
/// a photo without them turns them off on the photo pasted onto.
#[test]
fn copying_a_group_carries_what_the_stored_json_leaves_out() {
let copied = extract_groups(&DevelopSettings::default(), &[SettingsGroup::Profile, SettingsGroup::Light]);
let mut target = DevelopSettings::default();
target.profile.camera_local_tone = true;
target.hdr.enabled = true;
target.hdr.sdr_brightness = 40.0;
let pasted = target.merged(&copied).unwrap();
assert!(!pasted.profile.camera_local_tone);
assert_eq!(pasted.hdr, DevelopSettings::default().hdr);
// the stored JSON itself is unchanged: settings saved before these existed keep their hash
assert!(DevelopSettings::default().to_json().get("hdr").is_none());
}
/// Lens Blur's own left-out settings are stated in a copy too.
#[test]
fn copying_lens_blur_clears_the_target_s_boost_and_focus_mask() {
let copied = extract_groups(&DevelopSettings::default(), &[SettingsGroup::LensBlur]);
let mut target = DevelopSettings::default();
target.lens_blur.boost = 30.0;
target.lens_blur.focus_mask = Some(2);
let pasted = target.merged(&copied).unwrap();
assert_eq!((pasted.lens_blur.boost, pasted.lens_blur.focus_mask), (0.0, None));
}
/// A preset's HDR value at half amount is halfway from the original's, though the original's JSON has no `hdr`.
#[test]
fn a_preset_at_half_amount_starts_from_a_default_the_json_leaves_out() {
let d = DevelopSettings::default();
let half = preset(json!({"hdr": {"sdr_brightness": 40.0}})).apply_on(&d, &d, 0.5);
assert_eq!(half.hdr.sdr_brightness, 20.0);
}
/// Settings from a sidecar are kept in range, the sliders of point colours and red eyes too.
#[test]
fn untrusted_settings_keep_list_sliders_in_range() {
let s = DevelopSettings::from_untrusted_json(&json!({"point_colors": [{"hue_shift": 250.0}]})).unwrap();
assert_eq!(s.point_colors[0].hue_shift, 100.0);
}
/// As shot, the white balance numbers are the photo's own. A chosen white balance is an edit.
#[test]
fn a_chosen_white_balance_is_an_edit() {
let mut s = DevelopSettings::default();
s.wb.temp = 5200.0;
assert!(s.is_unedited(), "as shot: the numbers are the photo's");
s.wb.mode = WbMode::Daylight;
assert!(!s.is_unedited());
}
#[test]
fn resetting_point_color_resets_each_sample_s_sliders() {
let mut s = DevelopSettings::default();
s.point_colors.push(PointColor { hue_shift: 40.0, ..Default::default() });
s.reset_section(Section::PointColor);
assert_eq!(s.point_colors[0].hue_shift, 0.0);
}
#[test]
fn resetting_geometry_and_optics_resets_what_is_not_a_slider() {
let mut s = DevelopSettings::default();
s.geometry.upright = Upright::Guided;
s.geometry.guides.push((Point::new(0.1, 0.1), Point::new(0.1, 0.9)));
s.optics.remove_ca = true;
s.optics.lens_profile = true;
s.reset_section(Section::Geometry);
s.reset_section(Section::Optics);
assert!(s.geometry.is_identity() && s.geometry.guides.is_empty());
assert!(!s.optics.remove_ca && !s.optics.lens_profile);
}
/// At no amount a preset adds no mask, so applying it again at an amount still adds its masks.
#[test]
fn a_preset_at_no_amount_adds_no_mask() {
let masks = serde_json::to_value([Mask { id: 1, name: "Sky".into(), ..Default::default() }]).unwrap();
let p = preset(json!({"masks": masks}));
let none = p.apply(&DevelopSettings::default(), 0.0);
assert!(none.masks.is_empty());
let full = p.apply(&none, 1.0);
assert_eq!(full.masks.len(), 1);
assert_eq!(full.masks[0].adjust.amount, Mask::default().adjust.amount);
}
/// A preset's Lens Blur focus mask follows its mask to the id the photo gives it.
#[test]
fn a_preset_s_focus_mask_follows_its_mask_s_new_id() {
let masks = serde_json::to_value([Mask { id: 2, name: "Subject".into(), ..Default::default() }]).unwrap();
let p = preset(json!({"masks": masks, "lens_blur": {"amount": 50.0, "focus_mask": 2}}));
let mut mine = DevelopSettings::default();
for id in 1..=3 {
mine.masks.push(Mask { id, name: format!("Mine {id}"), ..Default::default() });
}
let out = p.apply(&mine, 1.0);
let subject = out.masks.iter().find(|m| m.name == "Subject").unwrap();
assert_eq!(subject.id, 4);
assert_eq!(out.lens_blur.focus_mask, Some(4), "not the photo's own mask 2");
// applied again, the mask is already there and the focus mask still names it
assert_eq!(p.apply(&out, 1.0).lens_blur.focus_mask, Some(4));
}
/// A side whose square is past `usize` takes the logits there are.
#[test]
fn a_mask_grid_of_an_absurd_side_does_not_overflow() {
let m = SegMask::from_logits(usize::MAX, &[0.0, 1.0]);
assert!(m.logits().is_none(), "and reads as damaged");
}
+18
View File
@@ -0,0 +1,18 @@
[package]
name = "craft-develop"
description = "The raw develop pipeline, CPU path: sensor data from craft-raw (or a decoded linear image) and craft-develop-model settings in, the rendered picture out."
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-develop-model = { workspace = true }
serde = { workspace = true }
[dev-dependencies]
proptest = { workspace = true }
+3
View File
@@ -0,0 +1,3 @@
//! Colour helpers for the develop pipeline.
pub mod spline;
+206
View File
@@ -0,0 +1,206 @@
//! Curves for tone mapping: monotone cubic Hermite splines (Fritsch–Carlson) and lookup tables.
//!
//! Monotone interpolation never overshoots between control points, so a point curve can't invert
//! tones by accident (a common complaint with natural cubic splines).
use serde::{Deserialize, Serialize};
/// A curve through control points in `0..1 × 0..1` (x strictly increasing after normalization).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct MonotoneCurve {
xs: Vec<f64>,
ys: Vec<f64>,
ms: Vec<f64>,
}
impl MonotoneCurve {
/// Build from points; sorts by x, merges duplicates. Fewer than two points → identity.
pub fn new(points: &[(f64, f64)]) -> MonotoneCurve {
let mut p: Vec<(f64, f64)> = points.iter().copied().filter(|(x, y)| x.is_finite() && y.is_finite()).collect();
p.sort_by(|a, b| a.0.total_cmp(&b.0));
p.dedup_by(|a, b| (a.0 - b.0).abs() < 1e-9);
if p.len() < 2 {
p = vec![(0.0, 0.0), (1.0, 1.0)];
}
let n = p.len();
let xs: Vec<f64> = p.iter().map(|q| q.0).collect();
let ys: Vec<f64> = p.iter().map(|q| q.1).collect();
let d: Vec<f64> = (0..n - 1).map(|i| (ys[i + 1] - ys[i]) / (xs[i + 1] - xs[i])).collect();
let mut ms = vec![0.0; n];
ms[0] = d[0];
ms[n - 1] = d[n - 2];
for i in 1..n - 1 {
ms[i] = if d[i - 1] * d[i] <= 0.0 { 0.0 } else { (d[i - 1] + d[i]) / 2.0 };
}
// Fritsch–Carlson limiter where the data is monotone within a segment.
for i in 0..n - 1 {
if d[i] == 0.0 {
ms[i] = 0.0;
ms[i + 1] = 0.0;
continue;
}
let a = ms[i] / d[i];
let b = ms[i + 1] / d[i];
let s = a * a + b * b;
if s > 9.0 {
let t = 3.0 / s.sqrt();
ms[i] = t * a * d[i];
ms[i + 1] = t * b * d[i];
}
}
MonotoneCurve { xs, ys, ms }
}
pub fn identity() -> MonotoneCurve {
MonotoneCurve::new(&[(0.0, 0.0), (1.0, 1.0)])
}
pub fn eval(&self, x: f64) -> f64 {
// NaN passes both bound checks below and would send the search past either end
if x.is_nan() {
return x;
}
let n = self.xs.len();
if x <= self.xs[0] {
return self.ys[0] + self.ms[0] * (x - self.xs[0]).min(0.0) * 0.0;
}
if x >= self.xs[n - 1] {
return self.ys[n - 1];
}
let i = match self.xs.binary_search_by(|v| v.total_cmp(&x)) {
Ok(i) => return self.ys[i],
Err(i) => i - 1,
};
let h = self.xs[i + 1] - self.xs[i];
let t = (x - self.xs[i]) / h;
let (t2, t3) = (t * t, t * t * t);
(2.0 * t3 - 3.0 * t2 + 1.0) * self.ys[i]
+ (t3 - 2.0 * t2 + t) * h * self.ms[i]
+ (-2.0 * t3 + 3.0 * t2) * self.ys[i + 1]
+ (t3 - t2) * h * self.ms[i + 1]
}
/// Sample into a LUT of `n` entries (at least 2) over `0..1`.
pub fn to_lut(&self, n: usize) -> Lut1 {
let n = n.max(2);
Lut1 { v: (0..n).map(|i| self.eval(i as f64 / (n - 1) as f64) as f32).collect() }
}
pub fn points(&self) -> Vec<(f64, f64)> {
self.xs.iter().copied().zip(self.ys.iter().copied()).collect()
}
}
/// A 1-D lookup table over `0..1` with linear interpolation; inputs outside clamp.
#[derive(Clone, Debug, PartialEq)]
pub struct Lut1 {
pub v: Vec<f32>,
}
impl Lut1 {
/// At least 2 entries, like [`Lut1::from_fn`].
pub fn identity(n: usize) -> Lut1 {
Lut1::from_fn(n, |x| x)
}
/// `f` sampled at `n` evenly spaced points over `0..1` (at least 2).
pub fn from_fn(n: usize, f: impl Fn(f32) -> f32) -> Lut1 {
let n = n.max(2);
Lut1 { v: (0..n).map(|i| f(i as f32 / (n - 1) as f32)).collect() }
}
/// `v` is public, so a table shorter than 2 entries is read as constant (1) or the identity (0).
#[inline]
pub fn eval(&self, x: f32) -> f32 {
let x = x.clamp(0.0, 1.0);
let n = self.v.len();
if n < 2 {
return self.v.first().copied().unwrap_or(x);
}
let f = x * (n - 1) as f32;
let i = (f as usize).min(n - 2);
let t = f - i as f32;
self.v[i] + (self.v[i + 1] - self.v[i]) * t
}
/// `self ∘ inner` (apply `inner` first).
pub fn compose(&self, inner: &Lut1) -> Lut1 {
Lut1 { v: inner.v.iter().map(|&x| self.eval(x)).collect() }
}
pub fn is_identity(&self) -> bool {
let n = self.v.len();
self.v.iter().enumerate().all(|(i, &y)| (y - i as f32 / (n - 1) as f32).abs() < 1e-6)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn identity_curve() {
let c = MonotoneCurve::identity();
for i in 0..=10 {
let x = i as f64 / 10.0;
assert!((c.eval(x) - x).abs() < 1e-12);
}
assert!(c.to_lut(256).is_identity());
}
#[test]
fn passes_through_points_and_is_monotone() {
let pts = [(0.0, 0.0), (0.25, 0.15), (0.5, 0.5), (0.75, 0.88), (1.0, 1.0)];
let c = MonotoneCurve::new(&pts);
for (x, y) in pts {
assert!((c.eval(x) - y).abs() < 1e-12);
}
let mut prev = -1.0;
for i in 0..=1000 {
let y = c.eval(i as f64 / 1000.0);
assert!(y >= prev - 1e-12);
prev = y;
}
}
#[test]
fn no_overshoot_on_flat_segment() {
let c = MonotoneCurve::new(&[(0.0, 0.0), (0.4, 0.5), (0.6, 0.5), (1.0, 1.0)]);
for i in 400..=600 {
let y = c.eval(i as f64 / 1000.0);
assert!((y - 0.5).abs() < 1e-9, "{y}");
}
}
#[test]
fn lut_compose() {
let a = Lut1::from_fn(1024, |x| x * x);
let b = Lut1::from_fn(1024, |x| x.sqrt());
let c = a.compose(&b);
assert!((c.eval(0.3) - 0.3).abs() < 2e-3);
}
#[test]
fn nan_input_and_short_luts_do_not_panic() {
let c = MonotoneCurve::new(&[(0.0, 0.0), (0.5, 0.6), (1.0, 1.0)]);
assert!(c.eval(f64::NAN).is_nan());
assert!(c.eval(-f64::NAN).is_nan());
for n in [0, 1] {
assert_eq!(c.to_lut(n).v.len(), 2, "{n}");
assert!(Lut1::identity(n).is_identity(), "{n}");
assert_eq!(Lut1::from_fn(n, |x| x).v.len(), 2, "{n}");
}
assert_eq!(Lut1 { v: vec![] }.eval(0.3), 0.3);
assert_eq!(Lut1 { v: vec![] }.eval(-1.0), 0.0, "inputs outside 0..1 clamp, as for any table");
assert_eq!(Lut1 { v: vec![] }.eval(2.0), 1.0);
assert_eq!(Lut1 { v: vec![0.7] }.eval(0.3), 0.7);
}
proptest::proptest! {
#[test]
fn monotone_for_increasing_data(ys in proptest::collection::vec(0.0f64..1.0, 3..8)) {
let mut ys = ys; ys.sort_by(|a, b| a.total_cmp(b));
let n = ys.len();
let pts: Vec<(f64, f64)> = ys.iter().enumerate().map(|(i, y)| (i as f64 / (n - 1) as f64, *y)).collect();
let c = MonotoneCurve::new(&pts);
let mut prev = f64::MIN;
for i in 0..=200 { let y = c.eval(i as f64 / 200.0); proptest::prop_assert!(y >= prev - 1e-9); prev = y; }
}
}
}
+238
View File
@@ -0,0 +1,238 @@
//! The parametric tone curve model shared by the pipeline renderer and the UI curve editor.
//!
//! Lightroom-style tone curve parametric model: four regions (shadows, darks, lights, highlights)
//! separated by three split points. Each region contributes a cosine-windowed bump, summed and
//! forced monotone.
use crate::color::spline::Lut1;
use craft_develop_model::ToneCurve;
/// The four shape controls of the parametric curve, in graph order: region 0 is the darkest.
pub const PARAM_AMOUNTS: [&str; 4] = ["curve.shadows", "curve.darks", "curve.lights", "curve.highlights"];
/// Resolution the parametric curve is sampled at, matching the renderer's LUT.
pub const PARAM_LUT: usize = 1024;
/// The parametric (region) curve of a [`ToneCurve`]: the four region amounts, each a cosine bump
/// over its window between two splits, summed and then forced monotone.
///
/// This is the renderer's curve, not an approximation of it — both `curve_luts` in the pipeline
/// and the curve editor in the UI use this struct so they can never disagree.
#[derive(Clone, Debug)]
pub struct ParametricCurve {
/// The curve, sampled and already forced monotone.
lut: [f32; PARAM_LUT],
/// The three region boundaries as fractions of the graph (0..1).
pub splits: [f64; 3],
/// The four region amounts, in graph order (0 = shadows, 3 = highlights).
pub amounts: [f64; 4],
}
impl ParametricCurve {
pub fn new(c: &ToneCurve) -> ParametricCurve {
let s0 = if c.split_shadows.is_nan() { 0.25 } else { (c.split_shadows / 100.0).clamp(0.0, 1.0) as f32 };
let s1 = if c.split_mid.is_nan() { 0.50_f32.max(s0) } else { (c.split_mid / 100.0).clamp(s0 as f64, 1.0) as f32 };
let s2 = if c.split_highlights.is_nan() { 0.75_f32.max(s1) } else { (c.split_highlights / 100.0).clamp(s1 as f64, 1.0) as f32 };
let clean_amt = |a: f64| if a.is_nan() { 0.0 } else { a.clamp(-100.0, 100.0) };
let (a0, a1, a2, a3) = (clean_amt(c.shadows), clean_amt(c.darks), clean_amt(c.lights), clean_amt(c.highlights));
let splits = [s0 as f64, s1 as f64, s2 as f64];
let amounts = [a0, a1, a2, a3];
let regions = [(0.0, s0, a0), (s0, s1, a1), (s1, s2, a2), (s2, 1.0, a3)];
let mut lut = [0.0_f32; PARAM_LUT];
let mut prev = 0.0_f32;
for (i, entry) in lut.iter_mut().enumerate() {
let x = i as f32 / (PARAM_LUT - 1) as f32;
let mut d = 0.0_f32;
for (a, b, amt) in regions {
if amt == 0.0 {
continue;
}
let (ctr, half) = ((a + b) / 2.0, (b - a) * 0.75 + 0.05);
if half <= f32::EPSILON {
continue;
}
let t = ((x - ctr) / half).clamp(-1.0, 1.0);
d += (amt / 100.0) as f32 * 0.22 * (0.5 + 0.5 * (t * std::f32::consts::PI).cos());
}
let y = (x + d * 4.0 * x * (1.0 - x)).clamp(0.0, 1.0);
prev = prev.max(y);
*entry = prev;
}
ParametricCurve { lut, splits, amounts }
}
/// Convert the evaluated parametric curve into a 1024-entry [`Lut1`].
pub fn to_lut(&self) -> Lut1 {
Lut1 { v: self.lut.to_vec() }
}
/// The curve at `x` (0 = black, 1 = white), read off the table (so it never overshoots the ends).
pub fn at(&self, x: f64) -> f64 {
let x = if x.is_nan() { 0.0 } else { x.clamp(0.0, 1.0) as f32 };
let at = x * (PARAM_LUT - 1) as f32;
let i = at.floor().clamp(0.0, (PARAM_LUT - 1) as f32) as usize;
let cur = self.lut.get(i).copied().unwrap_or(0.0);
let next = self.lut.get(i + 1).copied().unwrap_or(cur);
let f = at - i as f32;
(cur + (next - cur) * f) as f64
}
/// Where region `region`'s handle sits on the input axis: the middle of its own window, so a
/// handle never has to cross a split to be grabbed.
pub fn region_x(&self, region: usize) -> f64 {
let (a, b) = self.region_window(region);
(a + b) / 2.0
}
/// The window (two splits, as fractions of the graph) region `region` owns.
pub fn region_window(&self, region: usize) -> (f64, f64) {
let s0 = self.split_x(0);
let s1 = self.split_x(1);
let s2 = self.split_x(2);
match region {
0 => (0.0, s0),
1 => (s0, s1),
2 => (s1, s2),
_ => (s2, 1.0),
}
}
/// The half-width of region `region`'s own bump, as fraction of the graph.
pub fn region_half(&self, region: usize) -> f64 {
let (a, b) = self.region_window(region);
(b - a) * 0.75 + 0.05
}
/// The cosine window region `region` applies at `x` (1 at its centre, 0 at the window edges).
pub fn region_window_at(&self, region: usize, x: f64) -> f64 {
let ctr = self.region_x(region);
let half = self.region_half(region);
if half <= f64::EPSILON {
return 0.0;
}
let t = ((x - ctr) / half).clamp(-1.0, 1.0);
0.5 + 0.5 * (t * std::f64::consts::PI).cos()
}
/// The region that owns graph position `x`: the one whose own window contains it. The four
/// windows tile 0..1, so this is always defined and a drag anywhere on the curve moves exactly
/// one slider — the region under the pointer.
pub fn region_at(&self, x: f64) -> usize {
let x = if x.is_nan() { 0.0 } else { x.clamp(0.0, 1.0) };
let s0 = self.split_x(0);
let s1 = self.split_x(1);
let s2 = self.split_x(2);
if x <= s0 {
0
} else if x <= s1 {
1
} else if x <= s2 {
2
} else {
3
}
}
/// How much output level region `region`'s bump gains at `x` per unit of its slider: the bump is
/// linear in the amount, so this is a constant for a given `x`. A drag converts the pointer's
/// vertical motion into a slider change through it.
pub fn level_per_unit(&self, region: usize, x: f64) -> f64 {
let x = x.clamp(0.0, 1.0);
0.22 / 100.0 * self.region_window_at(region, x) * 4.0 * x * (1.0 - x)
}
/// The baseline level at `x` from the identity diagonal plus the contributions of all regions
/// *except* `region`. Used when inverting the model for `region` while holding the other three
/// regions fixed.
pub fn base_level_without(&self, region: usize, x: f64) -> f64 {
let x = x.clamp(0.0, 1.0);
let mut d = 0.0;
for i in 0..4 {
if i == region {
continue;
}
let amt = self.amounts.get(i).copied().unwrap_or(0.0);
if amt == 0.0 {
continue;
}
d += (amt / 100.0) * 0.22 * self.region_window_at(i, x);
}
x + d * 4.0 * x * (1.0 - x)
}
/// The curve level region `region` sits at when its slider holds `amount`, at graph position `x`,
/// holding the other regions fixed at their current settings.
pub fn handle_level_at(&self, region: usize, amount: f64, x: f64) -> f64 {
(self.base_level_without(region, x) + amount * self.level_per_unit(region, x)).clamp(0.0, 1.0)
}
/// The amount that puts region `region`'s curve at `level` at `x`, with the other three
/// regions held fixed — the inverse of [`Self::handle_level_at`]. A level the region cannot
/// reach saturates rather than jumping.
pub fn amount_at_level(&self, region: usize, level: f64, x: f64) -> f64 {
let per_unit = self.level_per_unit(region, x);
if per_unit.abs() <= f64::EPSILON {
return self.amounts.get(region).copied().unwrap_or(0.0);
}
let base = self.base_level_without(region, x);
((level.clamp(0.0, 1.0) - base) / per_unit).clamp(-100.0, 100.0).round()
}
/// The graph position split `split` (0..=2) sits at, 0..1.
pub fn split_x(&self, split: usize) -> f64 {
self.splits.get(split).copied().unwrap_or(0.5)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn non_finite_or_inverted_splits_do_not_panic_or_poison_curve() {
let c = ToneCurve {
split_shadows: 80.0,
split_mid: 20.0,
split_highlights: f64::NAN,
shadows: f64::NAN,
lights: f64::INFINITY,
..Default::default()
};
let model = ParametricCurve::new(&c);
assert!(model.at(0.5).is_finite());
assert!(model.at(f64::NAN).is_finite());
assert!(model.region_at(f64::NAN) < 4);
assert!((model.splits[0] - 0.8).abs() < 1e-6);
assert!((model.splits[1] - 0.8).abs() < 1e-6);
assert!((model.splits[2] - 0.8).abs() < 1e-6);
}
#[test]
fn horizontal_inversion_at_x_0_51_with_darks_60_preserves_zero_lights() {
let c = ToneCurve { darks: 60.0, lights: 0.0, ..Default::default() };
let model = ParametricCurve::new(&c);
assert_eq!(model.region_at(0.51), 2, "x=0.51 is inside the Lights region");
let level = model.at(0.51);
assert!((level - 0.5619).abs() < 0.001, "extracted model at 0.51 is ~0.5619: {level}");
// With other regions held fixed, inverting at level ~0.5619 must return Lights = 0, NOT 45!
let lights = model.amount_at_level(2, level, 0.51);
assert_eq!(lights, 0.0, "zero vertical delta preserves Lights=0: {lights}");
}
#[test]
fn a_curve_level_and_its_amount_are_inverses_with_other_regions_present() {
let c = ToneCurve { shadows: 20.0, darks: -30.0, lights: 40.0, highlights: -10.0, ..Default::default() };
let model = ParametricCurve::new(&c);
for region in 0..4 {
let centre = model.region_x(region);
let (_, upper) = model.region_window(region);
for x in [centre, centre + (upper - centre) * 0.5] {
for amount in [-100.0, -40.0, 0.0, 30.0, 100.0] {
let level = model.handle_level_at(region, amount, x);
let back = model.amount_at_level(region, level, x);
assert!((back - amount).abs() <= 1.0, "region {region} at {x}: {amount} -> {level} -> {back}");
}
}
}
}
}
+5
View File
@@ -0,0 +1,5 @@
//! Raw develop pipeline (CPU path), extracted from LightCraft.
pub mod color;
pub mod curve;
pub mod lut;
+164
View File
@@ -0,0 +1,164 @@
//! 3D LUT profiles: `.cube` files (the plain-text Cube LUT format: `LUT_3D_SIZE`, optional
//! `DOMAIN_MIN` / `DOMAIN_MAX`, then size³ "r g b" lines with red changing fastest), applied to
//! the display-encoded output colour and blended by the profile amount. Profiles are registered
//! here by id (`lut:…`) and found by the finishing stage (CPU loop and GPU kernel alike).
use std::collections::HashMap;
use std::sync::{Arc, OnceLock, RwLock};
/// A 3D colour lookup table.
#[derive(Clone, Debug, PartialEq)]
pub struct Lut3d {
pub size: usize,
pub data: Vec<[f32; 3]>,
pub domain_min: [f32; 3],
pub domain_max: [f32; 3],
pub title: Option<String>,
}
impl Lut3d {
/// Parse a `.cube` file.
pub fn parse_cube(text: &str) -> Result<Lut3d, String> {
let (mut size, mut title) = (0usize, None);
let (mut min, mut max) = ([0.0f32; 3], [1.0f32; 3]);
let mut data = Vec::new();
let three = |rest: &str| -> Option<[f32; 3]> {
let v: Vec<f32> = rest.split_whitespace().filter_map(|x| x.parse().ok()).collect();
(v.len() == 3 && v.iter().all(|x| x.is_finite())).then(|| [v[0], v[1], v[2]])
};
for line in text.lines() {
let l = line.trim();
if l.is_empty() || l.starts_with('#') {
continue;
}
if let Some(r) = l.strip_prefix("TITLE") {
title = Some(r.trim().trim_matches('"').to_string());
} else if let Some(r) = l.strip_prefix("LUT_3D_SIZE") {
size = r.trim().parse().map_err(|_| format!("bad LUT_3D_SIZE `{}`", r.trim()))?;
if !(2..=256).contains(&size) {
return Err(format!("LUT_3D_SIZE {size} out of range"));
}
} else if l.starts_with("LUT_1D_SIZE") {
return Err("1D LUTs are not supported (only 3D .cube files)".into());
} else if let Some(r) = l.strip_prefix("DOMAIN_MIN") {
min = three(r).ok_or("bad DOMAIN_MIN")?;
} else if let Some(r) = l.strip_prefix("DOMAIN_MAX") {
max = three(r).ok_or("bad DOMAIN_MAX")?;
} else if l.starts_with(|c: char| c.is_ascii_alphabetic()) {
// a data line of `nan` / `inf` starts with a letter too: it is bad data, not a keyword
if l.split_whitespace().next().is_some_and(|w| w.parse::<f32>().is_ok()) {
return Err(format!("bad line `{l}`"));
}
// other keywords (LUT_IN_VIDEO_RANGE…) are ignored
} else {
data.push(three(l).ok_or_else(|| format!("bad line `{l}`"))?);
}
}
if size == 0 {
return Err("not a 3D .cube LUT (no LUT_3D_SIZE)".into());
}
if data.len() != size * size * size {
return Err(format!("expected {} entries, found {}", size * size * size, data.len()));
}
Ok(Lut3d { size, data, domain_min: min, domain_max: max, title })
}
/// Look up `c` (trilinear).
pub fn apply(&self, c: [f32; 3]) -> [f32; 3] {
let n = self.size;
let s = (n - 1) as f32;
let mut idx = [0usize; 3];
let mut frac = [0.0f32; 3];
for k in 0..3 {
let span = (self.domain_max[k] - self.domain_min[k]).max(1e-6);
let x = (((c[k] - self.domain_min[k]) / span).clamp(0.0, 1.0)) * s;
let i = (x.floor() as usize).min(n - 2);
idx[k] = i;
frac[k] = x - i as f32;
}
let at = |r: usize, g: usize, b: usize| self.data[r + n * (g + n * b)];
let lerp = |a: [f32; 3], b: [f32; 3], t: f32| [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
let (r, g, b) = (idx[0], idx[1], idx[2]);
let c00 = lerp(at(r, g, b), at(r + 1, g, b), frac[0]);
let c10 = lerp(at(r, g + 1, b), at(r + 1, g + 1, b), frac[0]);
let c01 = lerp(at(r, g, b + 1), at(r + 1, g, b + 1), frac[0]);
let c11 = lerp(at(r, g + 1, b + 1), at(r + 1, g + 1, b + 1), frac[0]);
lerp(lerp(c00, c10, frac[1]), lerp(c01, c11, frac[1]), frac[2])
}
}
fn registry() -> &'static RwLock<HashMap<String, Arc<Lut3d>>> {
static R: OnceLock<RwLock<HashMap<String, Arc<Lut3d>>>> = OnceLock::new();
R.get_or_init(Default::default)
}
/// Make a LUT available to renders under profile id `id` (`lut:…`).
pub fn register(id: &str, lut: Lut3d) {
registry().write().unwrap_or_else(|e| e.into_inner()).insert(id.to_string(), Arc::new(lut));
}
/// The LUT registered for profile `id`.
pub fn get(id: &str) -> Option<Arc<Lut3d>> {
if !id.starts_with("lut:") {
return None;
}
registry().read().unwrap_or_else(|e| e.into_inner()).get(id).cloned()
}
/// Forget a LUT profile.
pub fn unregister(id: &str) {
registry().write().unwrap_or_else(|e| e.into_inner()).remove(id);
}
/// Profile ids that render with a LUT.
pub fn is_lut_profile(id: &str) -> bool {
id.starts_with("lut:")
}
#[cfg(test)]
mod tests {
use super::*;
fn cube(f: impl Fn([f32; 3]) -> [f32; 3], n: usize) -> String {
let mut s = format!("TITLE \"test\"\nLUT_3D_SIZE {n}\n");
for b in 0..n {
for g in 0..n {
for r in 0..n {
let c = f([r as f32 / (n - 1) as f32, g as f32 / (n - 1) as f32, b as f32 / (n - 1) as f32]);
s.push_str(&format!("{} {} {}\n", c[0], c[1], c[2]));
}
}
}
s
}
#[test]
fn identity_and_swap() {
let id = Lut3d::parse_cube(&cube(|c| c, 17)).unwrap();
assert_eq!(id.title.as_deref(), Some("test"));
let v = id.apply([0.2, 0.55, 0.9]);
assert!(v.iter().zip([0.2, 0.55, 0.9]).all(|(a, b)| (a - b).abs() < 1e-5), "{v:?}");
let swap = Lut3d::parse_cube(&cube(|c| [c[2], c[1], c[0]], 9)).unwrap();
let v = swap.apply([0.1, 0.5, 0.8]);
assert!((v[0] - 0.8).abs() < 1e-5 && (v[2] - 0.1).abs() < 1e-5, "{v:?}");
assert!(Lut3d::parse_cube("LUT_1D_SIZE 4\n0 0 0").is_err());
assert!(Lut3d::parse_cube("LUT_3D_SIZE 2\n0 0 0\n").is_err(), "too few entries");
}
#[test]
fn non_finite_entries_rejected() {
let bad_line = |body: &str| {
let e = Lut3d::parse_cube(body).expect_err(body);
assert!(e.starts_with("bad line"), "{e}");
};
bad_line(&format!("LUT_3D_SIZE 2\n{}", "-inf inf nan\n".repeat(8)));
bad_line(&format!("LUT_3D_SIZE 2\n{}", "1e39 0 0\n".repeat(8)));
bad_line(&format!("LUT_3D_SIZE 2\n-inf 0 0\n{}", "0 0 0\n".repeat(7)));
bad_line(&format!("LUT_3D_SIZE 2\nnan 0 0\n{}", "0 0 0\n".repeat(8)));
bad_line(&format!("LUT_3D_SIZE 2\ninf 0 0\n{}", "0 0 0\n".repeat(8)));
let ok = cube(|c| c, 2);
assert!(Lut3d::parse_cube(&ok).is_ok());
assert!(Lut3d::parse_cube(&format!("DOMAIN_MIN nan 0 0\n{ok}")).is_err());
assert!(Lut3d::parse_cube(&format!("DOMAIN_MAX inf 1 1\n{ok}")).is_err());
}
}
+16
View File
@@ -0,0 +1,16 @@
[package]
name="craft-dex"
description="Dalvik DEX reader and bytecode decoder with retained input bounds and partial-report semantics"
version.workspace=true
edition.workspace=true
license.workspace=true
rust-version.workspace=true
repository.workspace=true
[lints]
workspace=true
[dependencies]
serde={workspace=true}
thiserror={workspace=true}
[dev-dependencies]
craft-testkit = { workspace = true }
+85
View File
@@ -0,0 +1,85 @@
//! Checked little/big-endian reads over untrusted bytes. Every read returns `None` when out of range.
#[derive(Debug, Clone, Copy)]
pub struct Reader<'a> {
data: &'a [u8],
}
impl<'a> Reader<'a> {
pub fn new(data: &'a [u8]) -> Self {
Reader { data }
}
pub fn len(&self) -> usize {
self.data.len()
}
pub fn is_empty(&self) -> bool {
self.data.is_empty()
}
pub fn data(&self) -> &'a [u8] {
self.data
}
pub fn slice(&self, off: usize, len: usize) -> Option<&'a [u8]> {
let end = off.checked_add(len)?;
self.data.get(off..end)
}
pub fn u8(&self, off: usize) -> Option<u8> {
self.data.get(off).copied()
}
fn arr<const N: usize>(&self, off: usize) -> Option<[u8; N]> {
self.slice(off, N)?.try_into().ok()
}
pub fn u16_le(&self, off: usize) -> Option<u16> {
self.arr(off).map(u16::from_le_bytes)
}
pub fn u32_le(&self, off: usize) -> Option<u32> {
self.arr(off).map(u32::from_le_bytes)
}
/// A NUL-terminated string starting at `off`, at most `max` bytes, lossily decoded.
pub fn cstr(&self, off: usize, max: usize) -> Option<String> {
let rest = self.data.get(off..)?;
let rest = rest.get(..max.min(rest.len()))?;
let end = rest.iter().position(|&b| b == 0).unwrap_or(rest.len());
Some(String::from_utf8_lossy(rest.get(..end)?).into_owned())
}
/// Unsigned LEB128 at `off`: (value, bytes consumed). At most 10 bytes.
pub fn uleb128(&self, off: usize) -> Option<(u64, usize)> {
let mut result = 0u64;
for i in 0..10usize {
let b = self.u8(off.checked_add(i)?)?;
let payload = u64::from(b & 0x7f);
let shift = 7 * i as u32;
if shift > 0 && payload.checked_shl(shift)? >> shift != payload {
return None;
}
result |= payload << shift;
if b & 0x80 == 0 {
return Some((result, i + 1));
}
}
None
}
}
/// Decode one modified UTF-8 code unit. Invalid bytes consume only themselves,
/// so a damaged sequence cannot hide valid text or borrow missing bytes.
pub(crate) fn mutf8_unit(bytes: &[u8]) -> (u16, usize) {
match bytes {
[a @ 0x00..=0x7f, ..] => (u16::from(*a), 1),
[0xc0, 0x80, ..] => (0, 2),
[a @ 0xc2..=0xdf, b @ 0x80..=0xbf, ..] => ((u16::from(*a & 0x1f) << 6) | u16::from(*b & 0x3f), 2),
[a @ 0xe0..=0xef, b @ 0x80..=0xbf, c @ 0x80..=0xbf, ..] if *a != 0xe0 || *b >= 0xa0 => {
((u16::from(*a & 0x0f) << 12) | (u16::from(*b & 0x3f) << 6) | u16::from(*c & 0x3f), 3)
}
_ => (0xfffd, 1),
}
}
File diff suppressed because it is too large. Load diff
+696
View File
@@ -0,0 +1,696 @@
//! Dalvik bytecode: the opcode table (all 256 slots and three payload pseudo-instructions) and a
//! decoder for every instruction format. Pure decoding; index operands are resolved by the caller.
use serde::Serialize;
/// What an index operand refers to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum IndexKind {
None,
String,
Type,
Field,
Method,
CallSite,
MethodHandle,
Proto,
}
/// Instruction formats from the Dalvik specification (`10x`, `35c`, …).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub enum Fmt {
F10x,
F12x,
F11n,
F11x,
F10t,
F20t,
F22x,
F21t,
F21s,
F21h,
F21c,
F23x,
F22b,
F22t,
F22s,
F22c,
F30t,
F32x,
F31i,
F31t,
F31c,
F35c,
F3rc,
F45cc,
F4rcc,
F51l,
}
impl Fmt {
/// Length in 16-bit code units.
pub fn units(self) -> usize {
use Fmt::*;
match self {
F10x | F12x | F11n | F11x | F10t => 1,
F20t | F22x | F21t | F21s | F21h | F21c | F23x | F22b | F22t | F22s | F22c => 2,
F30t | F32x | F31i | F31t | F31c | F35c | F3rc => 3,
F45cc | F4rcc => 4,
F51l => 5,
}
}
}
/// One opcode slot.
#[derive(Debug, Clone, Copy)]
pub struct Op {
pub name: &'static str,
pub fmt: Fmt,
pub index: IndexKind,
}
const fn op(name: &'static str, fmt: Fmt, index: IndexKind) -> Op {
Op { name, fmt, index }
}
const UNUSED: Op = op("unused", Fmt::F10x, IndexKind::None);
const UNOPS: [&str; 21] = [
"neg-int",
"not-int",
"neg-long",
"not-long",
"neg-float",
"neg-double",
"int-to-long",
"int-to-float",
"int-to-double",
"long-to-int",
"long-to-float",
"long-to-double",
"float-to-int",
"float-to-long",
"float-to-double",
"double-to-int",
"double-to-long",
"double-to-float",
"int-to-byte",
"int-to-char",
"int-to-short",
];
const BINOPS: [&str; 32] = [
"add-int",
"sub-int",
"mul-int",
"div-int",
"rem-int",
"and-int",
"or-int",
"xor-int",
"shl-int",
"shr-int",
"ushr-int",
"add-long",
"sub-long",
"mul-long",
"div-long",
"rem-long",
"and-long",
"or-long",
"xor-long",
"shl-long",
"shr-long",
"ushr-long",
"add-float",
"sub-float",
"mul-float",
"div-float",
"rem-float",
"add-double",
"sub-double",
"mul-double",
"div-double",
"rem-double",
];
const BINOPS_2ADDR: [&str; 32] = [
"add-int/2addr",
"sub-int/2addr",
"mul-int/2addr",
"div-int/2addr",
"rem-int/2addr",
"and-int/2addr",
"or-int/2addr",
"xor-int/2addr",
"shl-int/2addr",
"shr-int/2addr",
"ushr-int/2addr",
"add-long/2addr",
"sub-long/2addr",
"mul-long/2addr",
"div-long/2addr",
"rem-long/2addr",
"and-long/2addr",
"or-long/2addr",
"xor-long/2addr",
"shl-long/2addr",
"shr-long/2addr",
"ushr-long/2addr",
"add-float/2addr",
"sub-float/2addr",
"mul-float/2addr",
"div-float/2addr",
"rem-float/2addr",
"add-double/2addr",
"sub-double/2addr",
"mul-double/2addr",
"div-double/2addr",
"rem-double/2addr",
];
const LIT16: [&str; 8] =
["add-int/lit16", "rsub-int", "mul-int/lit16", "div-int/lit16", "rem-int/lit16", "and-int/lit16", "or-int/lit16", "xor-int/lit16"];
const LIT8: [&str; 11] = [
"add-int/lit8",
"rsub-int/lit8",
"mul-int/lit8",
"div-int/lit8",
"rem-int/lit8",
"and-int/lit8",
"or-int/lit8",
"xor-int/lit8",
"shl-int/lit8",
"shr-int/lit8",
"ushr-int/lit8",
];
const CMP: [&str; 5] = ["cmpl-float", "cmpg-float", "cmpl-double", "cmpg-double", "cmp-long"];
const IF2: [&str; 6] = ["if-eq", "if-ne", "if-lt", "if-ge", "if-gt", "if-le"];
const IFZ: [&str; 6] = ["if-eqz", "if-nez", "if-ltz", "if-gez", "if-gtz", "if-lez"];
const ARR: [&str; 14] = [
"aget",
"aget-wide",
"aget-object",
"aget-boolean",
"aget-byte",
"aget-char",
"aget-short",
"aput",
"aput-wide",
"aput-object",
"aput-boolean",
"aput-byte",
"aput-char",
"aput-short",
];
const IFIELD: [&str; 14] = [
"iget",
"iget-wide",
"iget-object",
"iget-boolean",
"iget-byte",
"iget-char",
"iget-short",
"iput",
"iput-wide",
"iput-object",
"iput-boolean",
"iput-byte",
"iput-char",
"iput-short",
];
const SFIELD: [&str; 14] = [
"sget",
"sget-wide",
"sget-object",
"sget-boolean",
"sget-byte",
"sget-char",
"sget-short",
"sput",
"sput-wide",
"sput-object",
"sput-boolean",
"sput-byte",
"sput-char",
"sput-short",
];
const INVOKE: [&str; 5] = ["invoke-virtual", "invoke-super", "invoke-direct", "invoke-static", "invoke-interface"];
const INVOKE_RANGE: [&str; 5] =
["invoke-virtual/range", "invoke-super/range", "invoke-direct/range", "invoke-static/range", "invoke-interface/range"];
fn pick(list: &[&'static str], i: u8, base: u8) -> &'static str {
list.get(usize::from(i.wrapping_sub(base))).copied().unwrap_or("unused")
}
/// The opcode table entry for `b`.
pub fn opcode(b: u8) -> Op {
use Fmt::*;
use IndexKind as K;
match b {
0x00 => op("nop", F10x, K::None),
0x01 => op("move", F12x, K::None),
0x02 => op("move/from16", F22x, K::None),
0x03 => op("move/16", F32x, K::None),
0x04 => op("move-wide", F12x, K::None),
0x05 => op("move-wide/from16", F22x, K::None),
0x06 => op("move-wide/16", F32x, K::None),
0x07 => op("move-object", F12x, K::None),
0x08 => op("move-object/from16", F22x, K::None),
0x09 => op("move-object/16", F32x, K::None),
0x0a => op("move-result", F11x, K::None),
0x0b => op("move-result-wide", F11x, K::None),
0x0c => op("move-result-object", F11x, K::None),
0x0d => op("move-exception", F11x, K::None),
0x0e => op("return-void", F10x, K::None),
0x0f => op("return", F11x, K::None),
0x10 => op("return-wide", F11x, K::None),
0x11 => op("return-object", F11x, K::None),
0x12 => op("const/4", F11n, K::None),
0x13 => op("const/16", F21s, K::None),
0x14 => op("const", F31i, K::None),
0x15 => op("const/high16", F21h, K::None),
0x16 => op("const-wide/16", F21s, K::None),
0x17 => op("const-wide/32", F31i, K::None),
0x18 => op("const-wide", F51l, K::None),
0x19 => op("const-wide/high16", F21h, K::None),
0x1a => op("const-string", F21c, K::String),
0x1b => op("const-string/jumbo", F31c, K::String),
0x1c => op("const-class", F21c, K::Type),
0x1d => op("monitor-enter", F11x, K::None),
0x1e => op("monitor-exit", F11x, K::None),
0x1f => op("check-cast", F21c, K::Type),
0x20 => op("instance-of", F22c, K::Type),
0x21 => op("array-length", F12x, K::None),
0x22 => op("new-instance", F21c, K::Type),
0x23 => op("new-array", F22c, K::Type),
0x24 => op("filled-new-array", F35c, K::Type),
0x25 => op("filled-new-array/range", F3rc, K::Type),
0x26 => op("fill-array-data", F31t, K::None),
0x27 => op("throw", F11x, K::None),
0x28 => op("goto", F10t, K::None),
0x29 => op("goto/16", F20t, K::None),
0x2a => op("goto/32", F30t, K::None),
0x2b => op("packed-switch", F31t, K::None),
0x2c => op("sparse-switch", F31t, K::None),
0x2d..=0x31 => op(pick(&CMP, b, 0x2d), F23x, K::None),
0x32..=0x37 => op(pick(&IF2, b, 0x32), F22t, K::None),
0x38..=0x3d => op(pick(&IFZ, b, 0x38), F21t, K::None),
0x44..=0x51 => op(pick(&ARR, b, 0x44), F23x, K::None),
0x52..=0x5f => op(pick(&IFIELD, b, 0x52), F22c, K::Field),
0x60..=0x6d => op(pick(&SFIELD, b, 0x60), F21c, K::Field),
0x6e..=0x72 => op(pick(&INVOKE, b, 0x6e), F35c, K::Method),
0x74..=0x78 => op(pick(&INVOKE_RANGE, b, 0x74), F3rc, K::Method),
0x7b..=0x8f => op(pick(&UNOPS, b, 0x7b), F12x, K::None),
0x90..=0xaf => op(pick(&BINOPS, b, 0x90), F23x, K::None),
0xb0..=0xcf => op(pick(&BINOPS_2ADDR, b, 0xb0), F12x, K::None),
0xd0..=0xd7 => op(pick(&LIT16, b, 0xd0), F22s, K::None),
0xd8..=0xe2 => op(pick(&LIT8, b, 0xd8), F22b, K::None),
0xfa => op("invoke-polymorphic", F45cc, K::Method),
0xfb => op("invoke-polymorphic/range", F4rcc, K::Method),
0xfc => op("invoke-custom", F35c, K::CallSite),
0xfd => op("invoke-custom/range", F3rc, K::CallSite),
0xfe => op("const-method-handle", F21c, K::MethodHandle),
0xff => op("const-method-type", F21c, K::Proto),
_ => UNUSED,
}
}
/// Switch and array payloads.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
pub enum Payload {
PackedSwitch { first_key: i32, targets: Vec<i32> },
SparseSwitch { keys: Vec<i32>, targets: Vec<i32> },
FillArrayData { element_width: u16, count: u32, data: Vec<u8> },
}
/// One decoded instruction.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct Insn {
/// Offset in 16-bit code units from the start of the method's code.
pub offset: u32,
pub opcode: u8,
pub name: &'static str,
/// Length in code units.
pub units: u32,
/// Registers in operand order (for ranges: every register in the range).
pub regs: Vec<u32>,
/// True for `/range` forms.
pub range: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub literal: Option<i64>,
/// Absolute branch or payload target, in code units.
#[serde(skip_serializing_if = "Option::is_none")]
pub target: Option<i64>,
pub index_kind: IndexKind,
#[serde(skip_serializing_if = "Option::is_none")]
pub index: Option<u32>,
/// Second index (the proto of `invoke-polymorphic`).
#[serde(skip_serializing_if = "Option::is_none")]
pub index2: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub payload: Option<Payload>,
}
/// Most entries decoded from one payload.
const MAX_PAYLOAD: usize = 65_536;
/// Maximum payload bytes retained by one decoded method, including copies attached to users.
pub const DEFAULT_MAX_PAYLOAD_BYTES: usize = 64 << 20;
impl Payload {
fn retained_bytes(&self) -> usize {
match self {
Self::PackedSwitch { targets, .. } => targets.len().saturating_mul(4),
Self::SparseSwitch { keys, targets } => keys.len().saturating_add(targets.len()).saturating_mul(4),
Self::FillArrayData { data, .. } => data.len(),
}
}
fn complete(&self) -> bool {
match self {
Self::FillArrayData { element_width, count, data } => u64::from(*element_width) * u64::from(*count) == data.len() as u64,
_ => true,
}
}
}
fn u32_at(code: &[u16], i: usize) -> Option<u32> {
Some(u32::from(*code.get(i)?) | (u32::from(*code.get(i + 1)?) << 16))
}
/// Decode a payload pseudo-instruction at `pc`; returns it and its length in units.
fn payload(code: &[u16], pc: usize) -> Option<(Payload, usize)> {
let ident = *code.get(pc)?;
match ident {
0x0100 => {
let size = usize::from(*code.get(pc + 1)?);
let first_key = u32_at(code, pc + 2)? as i32;
let mut targets = Vec::with_capacity(size.min(MAX_PAYLOAD));
for i in 0..size.min(MAX_PAYLOAD) {
targets.push(u32_at(code, pc + 4 + i * 2)? as i32);
}
Some((Payload::PackedSwitch { first_key, targets }, size * 2 + 4))
}
0x0200 => {
let size = usize::from(*code.get(pc + 1)?);
let mut keys = Vec::with_capacity(size.min(MAX_PAYLOAD));
let mut targets = Vec::with_capacity(size.min(MAX_PAYLOAD));
for i in 0..size.min(MAX_PAYLOAD) {
keys.push(u32_at(code, pc + 2 + i * 2)? as i32);
targets.push(u32_at(code, pc + 2 + size * 2 + i * 2)? as i32);
}
Some((Payload::SparseSwitch { keys, targets }, size * 4 + 2))
}
0x0300 => {
let width = *code.get(pc + 1)?;
if !matches!(width, 1 | 2 | 4 | 8) {
return None;
}
let count = u32_at(code, pc + 2)?;
let bytes = usize::from(width).checked_mul(count as usize)?;
let units = bytes.checked_add(1)? / 2 + 4;
if pc.checked_add(units)? > code.len() {
return None;
}
let mut data = Vec::with_capacity(bytes.min(MAX_PAYLOAD));
for i in 0..bytes.min(MAX_PAYLOAD) {
let u = *code.get(pc + 4 + i / 2)?;
data.push(if i % 2 == 0 { u as u8 } else { (u >> 8) as u8 });
}
Some((Payload::FillArrayData { element_width: width, count, data }, units))
}
_ => None,
}
}
/// Decode one instruction at `pc`, or `None` when it runs past the end.
pub fn decode_one(code: &[u16], pc: usize) -> Option<Insn> {
use Fmt::*;
let u0 = *code.get(pc)?;
let b = (u0 & 0xff) as u8;
let hi = (u0 >> 8) as u8;
if b == 0 && hi != 0 {
let (p, units) = payload(code, pc)?;
let name = match p {
Payload::PackedSwitch { .. } => "packed-switch-payload",
Payload::SparseSwitch { .. } => "sparse-switch-payload",
Payload::FillArrayData { .. } => "array-data-payload",
};
return Some(Insn {
offset: pc as u32,
opcode: 0,
name,
units: units as u32,
regs: vec![],
range: false,
literal: None,
target: None,
index_kind: IndexKind::None,
index: None,
index2: None,
payload: Some(p),
});
}
let o = opcode(b);
let n = o.fmt.units();
if pc.checked_add(n)? > code.len() {
return None;
}
let u = |i: usize| code.get(pc + i).copied().unwrap_or(0);
let a4 = u32::from(hi & 0x0f);
let b4 = u32::from(hi >> 4);
let aa = u32::from(hi);
let rel = |d: i64| pc as i64 + d;
let mut insn = Insn {
offset: pc as u32,
opcode: b,
name: o.name,
units: n as u32,
regs: vec![],
range: false,
literal: None,
target: None,
index_kind: o.index,
index: None,
index2: None,
payload: None,
};
match o.fmt {
F10x => {}
F12x => insn.regs = vec![a4, b4],
F11n => {
insn.regs = vec![a4];
insn.literal = Some(i64::from((hi as i8) >> 4));
}
F11x => insn.regs = vec![aa],
F10t => insn.target = Some(rel(i64::from(hi as i8))),
F20t => insn.target = Some(rel(i64::from(u(1) as i16))),
F22x => insn.regs = vec![aa, u32::from(u(1))],
F21t => {
insn.regs = vec![aa];
insn.target = Some(rel(i64::from(u(1) as i16)));
}
F21s => {
insn.regs = vec![aa];
insn.literal = Some(i64::from(u(1) as i16));
}
F21h => {
insn.regs = vec![aa];
let v = i64::from(u(1) as i16);
insn.literal = Some(if b == 0x19 { v << 48 } else { v << 16 });
}
F21c => {
insn.regs = vec![aa];
insn.index = Some(u32::from(u(1)));
}
F23x => insn.regs = vec![aa, u32::from(u(1) & 0xff), u32::from(u(1) >> 8)],
F22b => {
insn.regs = vec![aa, u32::from(u(1) & 0xff)];
insn.literal = Some(i64::from((u(1) >> 8) as u8 as i8));
}
F22t => {
insn.regs = vec![a4, b4];
insn.target = Some(rel(i64::from(u(1) as i16)));
}
F22s => {
insn.regs = vec![a4, b4];
insn.literal = Some(i64::from(u(1) as i16));
}
F22c => {
insn.regs = vec![a4, b4];
insn.index = Some(u32::from(u(1)));
}
F30t => insn.target = Some(rel(i64::from((u32::from(u(1)) | (u32::from(u(2)) << 16)) as i32))),
F32x => insn.regs = vec![u32::from(u(1)), u32::from(u(2))],
F31i => {
insn.regs = vec![aa];
insn.literal = Some(i64::from((u32::from(u(1)) | (u32::from(u(2)) << 16)) as i32));
}
F31t => {
insn.regs = vec![aa];
insn.target = Some(rel(i64::from((u32::from(u(1)) | (u32::from(u(2)) << 16)) as i32)));
}
F31c => {
insn.regs = vec![aa];
insn.index = Some(u32::from(u(1)) | (u32::from(u(2)) << 16));
}
F35c | F45cc => {
if b4 > 5 {
return None;
}
let count = b4 as usize;
let g = a4;
let w = u(2);
let all = [u32::from(w & 0xf), u32::from((w >> 4) & 0xf), u32::from((w >> 8) & 0xf), u32::from(w >> 12), g];
insn.regs = all.iter().take(count).copied().collect();
insn.index = Some(u32::from(u(1)));
if o.fmt == F45cc {
insn.index2 = Some(u32::from(u(3)));
}
}
F3rc | F4rcc => {
let first = u32::from(u(2));
let end = first.checked_add(aa)?;
if end > u32::from(u16::MAX) + 1 {
return None;
}
insn.regs = (first..end).collect();
insn.range = true;
insn.index = Some(u32::from(u(1)));
if o.fmt == F4rcc {
insn.index2 = Some(u32::from(u(3)));
}
}
F51l => {
insn.regs = vec![aa];
let v = u64::from(u(1)) | (u64::from(u(2)) << 16) | (u64::from(u(3)) << 32) | (u64::from(u(4)) << 48);
insn.literal = Some(v as i64);
}
}
Some(insn)
}
/// Decode a whole method body, attaching each switch/array payload to the instruction that
/// references it. Stops at `max` instructions and caps all retained payload copies together.
pub fn decode(code: &[u16], max: usize) -> (Vec<Insn>, bool) {
decode_with_payload_limit(code, max, DEFAULT_MAX_PAYLOAD_BYTES)
}
/// Decode with an explicit aggregate payload byte budget. Payloads that do not fit are omitted;
/// their instruction metadata remains and the returned completeness flag is false. A source
/// payload and every attached copy consume the same budget, before the copy is allocated.
pub fn decode_with_payload_limit(code: &[u16], max: usize, max_payload_bytes: usize) -> (Vec<Insn>, bool) {
let mut out = Vec::new();
let mut pc = 0usize;
let mut complete = true;
let mut bytes_left = max_payload_bytes;
while pc < code.len() {
if out.len() >= max {
complete = false;
break;
}
match decode_one(code, pc) {
Some(mut i) => {
pc += (i.units as usize).max(1);
if let Some(p) = &i.payload {
complete &= p.complete();
if let Some(left) = bytes_left.checked_sub(p.retained_bytes()) {
bytes_left = left;
} else {
i.payload = None;
complete = false;
}
}
out.push(i);
}
None => {
complete = false;
break;
}
}
}
// Attach payloads to their users (31t formats).
// The decoder visits offsets in order. Index their positions without copying any payload.
let payloads: Vec<(i64, usize)> = out.iter().enumerate().filter(|(_, i)| i.payload.is_some()).map(|(n, i)| (i64::from(i.offset), n)).collect();
for n in 0..out.len() {
let Some(target) = out.get(n).filter(|i| matches!(i.opcode, 0x26 | 0x2b | 0x2c)).and_then(|i| i.target) else { continue };
let Ok(position) = payloads.binary_search_by_key(&target, |(offset, _)| *offset) else { continue };
let Some(payload) = payloads.get(position).and_then(|(_, index)| out.get(*index)).and_then(|i| i.payload.as_ref()) else { continue };
let Some(left) = bytes_left.checked_sub(payload.retained_bytes()) else {
complete = false;
continue;
};
bytes_left = left;
let copy = payload.clone();
if let Some(instruction) = out.get_mut(n) {
instruction.payload = Some(copy);
}
}
(out, complete)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn table_is_complete() {
let mut named = 0;
for b in 0..=255u8 {
let o = opcode(b);
if o.name != "unused" {
named += 1;
}
}
// 256 slots minus the 0x3e-0x43, 0x73, 0x79-0x7a and 0xe3-0xf9 holes.
assert_eq!(named, 256 - 6 - 1 - 2 - 23);
assert_eq!(opcode(0x6e).name, "invoke-virtual");
assert_eq!(opcode(0x8f).name, "int-to-short");
assert_eq!(opcode(0xaf).name, "rem-double");
assert_eq!(opcode(0xcf).name, "rem-double/2addr");
assert_eq!(opcode(0xe2).name, "ushr-int/lit8");
}
#[test]
fn decodes_formats() {
// const/4 v1, #-1 ; invoke-static {v0, v1}, meth@5 ; packed-switch v0, +4 ; return-void
// payload: packed, size 2, first 10, targets 1, 2
let code: Vec<u16> = vec![0xf112, 0x2071, 5, 0x0010, 0x002b, 4, 0, 0x000e, 0x0100, 2, 10, 0, 1, 0, 2, 0];
let (ins, complete) = decode(&code, 100);
assert!(complete);
assert_eq!(ins[0].name, "const/4");
assert_eq!(ins[0].literal, Some(-1));
assert_eq!(ins[0].regs, vec![1]);
assert_eq!(ins[1].name, "invoke-static");
assert_eq!(ins[1].regs, vec![0, 1]);
assert_eq!(ins[1].index, Some(5));
assert_eq!(ins[2].name, "packed-switch");
assert_eq!(ins[2].target, Some(8));
assert_eq!(ins[2].payload, Some(Payload::PackedSwitch { first_key: 10, targets: vec![1, 2] }));
assert_eq!(ins[4].name, "packed-switch-payload");
// const-wide v0, 0x1122334455667788
let (w, _) = decode(&[0x0018, 0x7788, 0x5566, 0x3344, 0x1122], 10);
assert_eq!(w[0].literal, Some(0x1122_3344_5566_7788));
// fill-array-data payload width 1 count 3
let (f, _) = decode(&[0x0300, 1, 3, 0, 0x0201, 0x0003], 10);
assert_eq!(f[0].payload, Some(Payload::FillArrayData { element_width: 1, count: 3, data: vec![1, 2, 3] }));
// invoke-virtual/range {v4..v6}
let (r, _) = decode(&[0x0374, 9, 4], 10);
assert_eq!(r[0].regs, vec![4, 5, 6]);
assert!(r[0].range);
}
#[test]
fn hostile() {
for seed in 0..200 {
let n = crate::test_support::noise(seed, 256);
let code: Vec<u16> = n.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes(*c)).collect();
let _ = decode(&code, 1000);
}
let _ = decode(&[0x0300, 0xffff, 0xffff, 0xffff], 10);
let _ = decode(&[0x0200, 0xffff], 10);
let _ = decode(&[0x0018], 10);
}
}
+42
View File
@@ -0,0 +1,42 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
//! Dalvik DEX inspection and bytecode decoding. Never executes bytecode.
mod bytes;
/// Checked byte reader accepted by the signed-LEB compatibility helper.
pub use bytes::Reader;
pub mod dex;
pub mod dex_ops;
pub use dex::*;
#[cfg(test)]
mod test_support;
/// Parser admission failures; damaged substructures retain the original partial-report behavior.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum DexError {
#[error("the file ends early ({0})")]
Truncated(String),
#[error("the file is malformed ({0})")]
Malformed(String),
#[error("not supported: {0}")]
Unsupported(String),
}
use DexError as FormatError;
#[cfg(test)]
#[path = "regressions/array_widths.rs"]
mod array_widths;
#[cfg(test)]
#[path = "regressions/capped_table_boundaries.rs"]
mod capped_table_boundaries;
#[cfg(test)]
#[path = "regressions/invoke_registers.rs"]
mod invoke_registers;
#[cfg(test)]
#[path = "regressions/payload_budgets.rs"]
mod payload_budgets;
#[cfg(test)]
#[path = "regressions/signed_leb128.rs"]
mod signed_leb128;
@@ -0,0 +1,39 @@
use crate::dex_ops::{Payload, decode, decode_one};
#[test]
fn zero_width_does_not_describe_a_huge_complete_array() {
let code = [0x0300, 0, 0xffff, 0xffff];
assert!(decode_one(&code, 0).is_none());
assert!(!decode(&code, 16).1);
}
#[test]
fn unsupported_element_widths_are_refused_even_for_empty_arrays() {
for width in [0, 3, 5, 6, 7, 9, 16, u16::MAX] {
assert!(decode_one(&[0x0300, width, 0, 0], 0).is_none(), "width {width}");
}
}
#[test]
fn all_primitive_widths_and_odd_byte_padding_still_decode() {
for width in [1u16, 2, 4, 8] {
let count = 3u32;
let bytes = usize::from(width) * count as usize;
let mut code = vec![0x0300, width, count as u16, 0];
code.resize(4 + bytes.div_ceil(2), 0x2211);
let instruction = decode_one(&code, 0).unwrap();
assert_eq!(instruction.units as usize, code.len());
match instruction.payload.unwrap() {
Payload::FillArrayData { element_width, count: decoded, data } => {
assert_eq!(element_width, width);
assert_eq!(decoded, count);
assert_eq!(data.len(), bytes);
assert_eq!(data[0], 0x11);
}
other => panic!("unexpected payload {other:?}"),
}
assert!(decode_one(&[0x0300, width, 0, 0], 0).is_some());
code.pop();
assert!(decode_one(&code, 0).is_none());
}
}
@@ -0,0 +1,114 @@
use crate::dex::{self, ClassDef, Code};
const MEMBER_CAP: usize = 65_536;
const HANDLER_CAP: usize = 256;
fn uleb(mut value: u32, bytes: &mut Vec<u8>) {
loop {
let byte = (value & 0x7f) as u8;
value >>= 7;
bytes.push(byte | if value == 0 { 0 } else { 0x80 });
if value == 0 {
break;
}
}
}
fn sleb(mut value: i32, bytes: &mut Vec<u8>) {
loop {
let byte = value as u8 & 0x7f;
value >>= 7;
let done = (value == 0 && byte & 0x40 == 0) || (value == -1 && byte & 0x40 != 0);
bytes.push(byte | if done { 0 } else { 0x80 });
if done {
break;
}
}
}
fn header() -> Vec<u8> {
let mut bytes = vec![0; 0x70];
bytes[..8].copy_from_slice(b"dex\n035\0");
bytes[36..40].copy_from_slice(&0x70u32.to_le_bytes());
bytes[40..44].copy_from_slice(&0x1234_5678u32.to_le_bytes());
bytes
}
fn class_data(count: usize) -> dex::ClassData {
let mut bytes = header();
for n in [count as u32, 0, 1, 0] {
uleb(n, &mut bytes);
}
bytes.extend_from_slice(&[0, 1].repeat(count));
bytes.extend_from_slice(&[3, 9, 7]);
let len = bytes.len() as u32;
bytes[32..36].copy_from_slice(&len.to_le_bytes());
let class = ClassDef {
class_idx: 0,
access: 0,
superclass_idx: 0,
interfaces_off: 0,
source_file_idx: 0,
annotations_off: 0,
class_data_off: 0x70,
static_values_off: 0,
};
dex::parse(&bytes).unwrap().class_data(&class)
}
fn code(size: i32, payload: &[u8]) -> Code {
let mut bytes = header();
bytes.extend_from_slice(&[1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 8, 0, 0, 0]);
bytes.extend_from_slice(&[0; 16]);
bytes.extend_from_slice(&[0, 0, 0, 0, 1, 0, 1, 0]);
bytes.push(1);
sleb(size, &mut bytes);
bytes.extend_from_slice(payload);
let len = bytes.len() as u32;
bytes[32..36].copy_from_slice(&len.to_le_bytes());
dex::parse(&bytes).unwrap().code(0x70).unwrap()
}
#[test]
fn capped_class_members_do_not_become_the_next_group() {
let data = class_data(MEMBER_CAP + 1);
assert_eq!(data.static_fields.len(), MEMBER_CAP);
assert!(data.direct_methods.is_empty());
assert!(!data.complete);
}
#[test]
fn an_exact_member_limit_keeps_the_following_group() {
let data = class_data(MEMBER_CAP);
assert_eq!(data.static_fields.len(), MEMBER_CAP);
assert!(data.complete);
assert_eq!(data.direct_methods, [dex::EncodedMethod { method_idx: 3, access: 9, code_off: 7 }]);
}
#[test]
fn an_unread_typed_handler_is_not_a_catch_all() {
let mut payload = [0, 1].repeat(HANDLER_CAP + 1);
payload.push(7);
let parsed = code(-((HANDLER_CAP + 1) as i32), &payload);
assert_eq!(parsed.tries[0].handlers.len(), HANDLER_CAP);
assert!(parsed.tries[0].handlers.iter().all(|handler| handler.exception.is_some() && handler.address == 1));
}
#[test]
fn an_incomplete_typed_handler_cannot_supply_a_catch_all_address() {
let parsed = code(-2, &[0, 1, 0]);
assert_eq!(parsed.tries[0].handlers.len(), 1);
assert!(parsed.tries[0].handlers[0].exception.is_some());
assert_eq!(parsed.tries[0].handlers[0].address, 1);
}
#[test]
fn complete_typed_lists_keep_their_real_catch_all() {
for count in [0, 1, HANDLER_CAP] {
let mut payload = [0, 1].repeat(count);
payload.push(7);
let parsed = code(-(count as i32), &payload);
assert_eq!(parsed.tries[0].handlers.len(), count + 1);
assert_eq!(parsed.tries[0].handlers.last(), Some(&dex::Handler { exception: None, address: 7 }));
}
}
@@ -0,0 +1,33 @@
use crate::dex_ops::{decode, decode_one};
#[test]
fn fixed_register_lists_cannot_claim_more_than_five_arguments() {
for op in [0x24u16, 0x6e, 0x6f, 0x70, 0x71, 0x72, 0xfa, 0xfc] {
for count in 6..=15 {
let code = [(count << 12) | op, 1, 0x4321, 2];
assert!(decode_one(&code, 0).is_none(), "opcode {op:#x}, count {count}");
assert!(!decode(&code, 16).1);
}
}
}
#[test]
fn range_arguments_cannot_leave_the_encoded_register_space() {
for op in [0x25u16, 0x74, 0x75, 0x76, 0x77, 0x78, 0xfb, 0xfd] {
assert!(decode_one(&[0x0200 | op, 1, u16::MAX, 2], 0).is_none(), "{op:#x}");
assert!(decode_one(&[0xff00 | op, 1, u16::MAX - 1, 2], 0).is_none(), "{op:#x}");
}
}
#[test]
fn zero_and_boundary_register_lists_remain_valid() {
let fixed = decode_one(&[0x5571, 1, 0x4321], 0).unwrap();
assert_eq!(fixed.regs, vec![1, 2, 3, 4, 5]);
assert!(decode_one(&[0x0071, 1, 0], 0).unwrap().regs.is_empty());
let range = decode_one(&[0x0277, 1, u16::MAX - 1], 0).unwrap();
assert_eq!(range.regs, vec![65534, 65535]);
assert!(decode_one(&[0x0077, 1, u16::MAX], 0).unwrap().regs.is_empty());
let polymorphic = decode_one(&[0x01fb, 1, u16::MAX, 2], 0).unwrap();
assert_eq!(polymorphic.regs, vec![65535]);
assert_eq!(polymorphic.index2, Some(2));
}
@@ -0,0 +1,88 @@
use crate::dex_ops::{self, Payload};
fn arrays(references: usize, bytes: usize) -> Vec<u16> {
let mut code = Vec::new();
let offset = (references * 3).next_multiple_of(2);
for n in 0..references {
let relative = u32::try_from(offset - n * 3).unwrap();
code.extend([0x0026, relative as u16, (relative >> 16) as u16]);
}
code.resize(offset, 0);
let count = u32::try_from(bytes).unwrap();
code.extend([0x0300, 1, count as u16, (count >> 16) as u16]);
code.resize(code.len() + bytes.div_ceil(2), 0x5a5a);
code
}
fn bytes(rows: &[dex_ops::Insn]) -> usize {
rows.iter()
.map(|i| match i.payload.as_ref() {
Some(Payload::FillArrayData { data, .. }) => data.len(),
Some(Payload::PackedSwitch { targets, .. }) => targets.len() * 4,
Some(Payload::SparseSwitch { keys, targets }) => (keys.len() + targets.len()) * 4,
None => 0,
})
.sum()
}
#[test]
fn shared_arrays_charge_the_source_and_each_attached_copy() {
let code = arrays(4, 8);
let (rows, complete) = dex_ops::decode_with_payload_limit(&code, 100, 24);
assert!(!complete);
assert_eq!(bytes(&rows), 24);
assert!(rows[0].payload.is_some() && rows[1].payload.is_some());
assert!(rows[2].payload.is_none() && rows[3].payload.is_none());
assert!(rows.last().unwrap().payload.is_some());
let (full, complete) = dex_ops::decode_with_payload_limit(&code, 100, 40);
assert!(complete);
assert_eq!(bytes(&full), 40);
}
#[test]
fn zero_budget_keeps_offsets_and_payload_instruction_metadata() {
let code = arrays(2, 8);
let (rows, complete) = dex_ops::decode_with_payload_limit(&code, 100, 0);
assert!(!complete);
assert_eq!(rows.iter().map(|i| i.offset).collect::<Vec<_>>(), [0, 3, 6]);
assert_eq!(rows[2].name, "array-data-payload");
assert_eq!(rows[2].units, 8);
assert!(rows.iter().all(|i| i.payload.is_none()));
assert!(dex_ops::decode_with_payload_limit(&[0x000e], 100, 0).1);
}
#[test]
fn both_switch_tables_are_accounted_and_backward_references_work() {
// packed table: one target; sparse table: one key and one target; users follow the tables.
let code = [0x0100, 1, 7, 0, 1, 0, 0x0200, 1, 9, 0, 2, 0, 0x002b, 0xfff4, 0xffff, 0x002c, 0xfff7, 0xffff];
let (rows, complete) = dex_ops::decode_with_payload_limit(&code, 100, 24);
assert!(complete);
assert_eq!(rows[2].payload, Some(Payload::PackedSwitch { first_key: 7, targets: vec![1] }));
assert_eq!(rows[3].payload, Some(Payload::SparseSwitch { keys: vec![9], targets: vec![2] }));
let (rows, complete) = dex_ops::decode_with_payload_limit(&code, 100, 16);
assert!(!complete);
assert!(rows[2].payload.is_some());
assert!(rows[3].payload.is_none());
assert_eq!(bytes(&rows), 16);
}
#[test]
fn the_existing_per_array_cap_is_reported_as_partial() {
let (rows, complete) = dex_ops::decode(&arrays(1, 65_537), 100);
assert!(!complete);
assert_eq!(bytes(&rows), 2 * 65_536);
let (rows, complete) = dex_ops::decode(&arrays(1, 8), 1);
assert!(!complete);
assert_eq!(rows.len(), 1);
assert!(rows[0].payload.is_none());
}
#[test]
#[ignore = "memory regression: run separately with a 128 MiB address-space limit"]
fn repeated_array_references_stay_under_the_default_byte_budget() {
let code = arrays(2048, 65_536);
let (rows, complete) = dex_ops::decode(&code, 200_000);
assert!(!complete);
assert_eq!(rows.len(), 2049);
assert_eq!(bytes(&rows), dex_ops::DEFAULT_MAX_PAYLOAD_BYTES);
}
@@ -0,0 +1,94 @@
use crate::bytes::Reader;
use crate::dex::{self, Code, Handler, sleb128};
#[test]
fn rejects_invalid_fifth_byte_sign_extensions() {
for prefix in [0x80, 0xff] {
for last in 0x08..=0x77 {
let mut encoded = vec![prefix; 4];
encoded.push(last);
assert_eq!(sleb128(&Reader::new(&encoded), 0), None, "last byte {last:#x}");
}
}
}
#[test]
fn retains_signed_32_bit_limits_and_ordinary_values() {
assert_eq!(sleb128(&Reader::new(&[0xff, 0xff, 0xff, 0xff, 0x07]), 0), Some((i64::from(i32::MAX), 5)));
assert_eq!(sleb128(&Reader::new(&[0x80, 0x80, 0x80, 0x80, 0x78]), 0), Some((i64::from(i32::MIN), 5)));
assert_eq!(sleb128(&Reader::new(&[0x9b, 0xf1, 0x59]), 0), Some((-624485, 3)));
assert_eq!(sleb128(&Reader::new(&[0xe5, 0x8e, 0x26]), 0), Some((624485, 3)));
assert_eq!(sleb128(&Reader::new(&[0xff, 0x7f]), 0), Some((-1, 2)));
assert_eq!(sleb128(&Reader::new(&[0x80, 0]), 0), Some((0, 2)));
assert_eq!(sleb128(&Reader::new(&[0x55, 0x7f, 0x55]), 1), Some((-1, 1)));
}
#[test]
fn retains_valid_five_byte_sign_extensions() {
assert_eq!(sleb128(&Reader::new(&[0x80, 0x80, 0x80, 0x80, 0]), 0), Some((0, 5)));
assert_eq!(sleb128(&Reader::new(&[0x81, 0x80, 0x80, 0x80, 0]), 0), Some((1, 5)));
assert_eq!(sleb128(&Reader::new(&[0xff, 0xff, 0xff, 0xff, 0x7f]), 0), Some((-1, 5)));
}
#[test]
fn rejects_values_longer_than_five_bytes() {
for (prefix, last) in [(0x80, 0), (0xff, 0x7f)] {
for length in [6, 10] {
let mut encoded = vec![prefix; length - 1];
encoded.push(last);
assert_eq!(sleb128(&Reader::new(&encoded), 0), None, "{encoded:x?}");
}
}
}
#[test]
fn rejects_truncated_values_and_out_of_range_offsets() {
assert_eq!(sleb128(&Reader::new(&[0x80; 5]), 0), None);
assert_eq!(sleb128(&Reader::new(&[0x80]), 0), None);
assert_eq!(sleb128(&Reader::new(&[]), 0), None);
assert_eq!(sleb128(&Reader::new(&[0]), usize::MAX), None);
}
fn code_with_handler(size: &[u8], payload: &[u8]) -> Code {
let mut bytes = vec![0; 0x70];
bytes[..8].copy_from_slice(b"dex\n035\0");
bytes[36..40].copy_from_slice(&0x70u32.to_le_bytes());
bytes[40..44].copy_from_slice(&0x1234_5678u32.to_le_bytes());
// Eight nop instructions and one try entry pointing to the first encoded handler.
bytes.extend_from_slice(&[1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 8, 0, 0, 0]);
bytes.extend_from_slice(&[0; 16]);
bytes.extend_from_slice(&[0, 0, 0, 0, 1, 0, 1, 0]);
bytes.push(1);
bytes.extend_from_slice(size);
bytes.extend_from_slice(payload);
let len = bytes.len() as u32;
bytes[32..36].copy_from_slice(&len.to_le_bytes());
dex::parse(&bytes).unwrap().code(0x70).unwrap()
}
#[test]
fn invalid_sizes_do_not_create_handlers() {
let sizes: &[&[u8]] = &[
&[0x80, 0x80, 0x80, 0x80, 0x08],
&[0x80, 0x80, 0x80, 0x80, 0x77],
&[0x80, 0x80, 0x80, 0x80, 0x80, 0],
&[0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0],
];
for size in sizes {
// These bytes could be a type/address pair or a catch-all address if size is accepted.
let code = code_with_handler(size, &[0, 7]);
assert_eq!(code.tries.len(), 1);
assert!(code.tries[0].handlers.is_empty(), "invalid size {size:x?}");
}
}
#[test]
fn valid_catch_all_handlers_are_retained() {
for size in [&[0][..], &[0x80, 0x80, 0x80, 0x80, 0][..]] {
let code = code_with_handler(size, &[7]);
assert_eq!(code.tries.len(), 1);
assert_eq!(code.tries[0].start, 0);
assert_eq!(code.tries[0].end, 1);
assert_eq!(code.tries[0].handlers, vec![Handler { exception: None, address: 7 }]);
}
}
+430
View File
@@ -0,0 +1,430 @@
// Synthetic DEX fixture and deterministic mutations retained from Craft Anything.
pub use craft_testkit::sample_damage::{mutations, noise};
pub mod android {
pub const HELLO: &str = "Hello, Craft!";
fn u16le(v: &mut Vec<u8>, x: u16) {
v.extend_from_slice(&x.to_le_bytes());
}
fn u32le(v: &mut Vec<u8>, x: u32) {
v.extend_from_slice(&x.to_le_bytes());
}
fn uleb(v: &mut Vec<u8>, mut x: u32) {
loop {
let b = (x & 0x7f) as u8;
x >>= 7;
if x == 0 {
v.push(b);
break;
}
v.push(b | 0x80);
}
}
fn sleb(v: &mut Vec<u8>, mut x: i32) {
loop {
let b = (x & 0x7f) as u8;
x >>= 7;
let done = (x == 0 && b & 0x40 == 0) || (x == -1 && b & 0x40 != 0);
v.push(if done { b } else { b | 0x80 });
if done {
break;
}
}
}
fn align4(v: &mut Vec<u8>) {
while !v.len().is_multiple_of(4) {
v.push(0);
}
}
#[derive(Debug, Clone, Default)]
pub struct TrySpec {
pub start: u32,
pub count: u16,
/// (type idx, handler address)
pub handlers: Vec<(u32, u32)>,
pub catch_all: Option<u32>,
}
#[derive(Debug, Clone, Default)]
pub struct CodeSpec {
pub registers: u16,
pub ins: u16,
pub outs: u16,
pub insns: Vec<u16>,
pub tries: Vec<TrySpec>,
}
#[derive(Debug, Clone)]
pub struct MethodSpec {
pub method: u32,
pub access: u32,
pub code: Option<CodeSpec>,
}
#[derive(Debug, Clone, Default)]
pub struct ClassSpec {
pub class: u32,
pub access: u32,
pub superclass: u32,
pub interfaces: Vec<u32>,
pub source_file: u32,
pub annotations: Vec<u32>,
pub static_fields: Vec<(u32, u32)>,
pub instance_fields: Vec<(u32, u32)>,
pub direct: Vec<MethodSpec>,
pub virtuals: Vec<MethodSpec>,
}
#[derive(Debug, Clone, Default)]
pub struct DexBuilder {
strings: Vec<String>,
types: Vec<u32>,
protos: Vec<(u32, u32, Vec<u32>)>,
fields: Vec<(u32, u32, u32)>,
methods: Vec<(u32, u32, u32)>,
pub classes: Vec<ClassSpec>,
}
impl DexBuilder {
pub fn string(&mut self, s: &str) -> u32 {
if let Some(i) = self.strings.iter().position(|x| x == s) {
return i as u32;
}
self.strings.push(s.to_string());
(self.strings.len() - 1) as u32
}
pub fn ty(&mut self, desc: &str) -> u32 {
let s = self.string(desc);
if let Some(i) = self.types.iter().position(|&x| x == s) {
return i as u32;
}
self.types.push(s);
(self.types.len() - 1) as u32
}
pub fn proto(&mut self, ret: &str, params: &[&str]) -> u32 {
let short = |d: &str| if d.starts_with('L') || d.starts_with('[') { 'L' } else { d.chars().next().unwrap() };
let shorty: String = std::iter::once(short(ret)).chain(params.iter().map(|p| short(p))).collect();
let s = self.string(&shorty);
let r = self.ty(ret);
let ps: Vec<u32> = params.iter().map(|p| self.ty(p)).collect();
if let Some(i) = self.protos.iter().position(|p| p.1 == r && p.2 == ps) {
return i as u32;
}
self.protos.push((s, r, ps));
(self.protos.len() - 1) as u32
}
pub fn field(&mut self, cls: &str, ty: &str, name: &str) -> u32 {
let c = self.ty(cls);
let t = self.ty(ty);
let n = self.string(name);
if let Some(i) = self.fields.iter().position(|&f| f == (c, t, n)) {
return i as u32;
}
self.fields.push((c, t, n));
(self.fields.len() - 1) as u32
}
pub fn method(&mut self, cls: &str, name: &str, ret: &str, params: &[&str]) -> u32 {
let c = self.ty(cls);
let p = self.proto(ret, params);
let n = self.string(name);
if let Some(i) = self.methods.iter().position(|&m| m == (c, p, n)) {
return i as u32;
}
self.methods.push((c, p, n));
(self.methods.len() - 1) as u32
}
pub fn build(self) -> Vec<u8> {
let ns = self.strings.len();
let nt = self.types.len();
let np = self.protos.len();
let nf = self.fields.len();
let nm = self.methods.len();
let nc = self.classes.len();
let string_ids = 0x70;
let type_ids = string_ids + ns * 4;
let proto_ids = type_ids + nt * 4;
let field_ids = proto_ids + np * 12;
let method_ids = field_ids + nf * 8;
let class_defs = method_ids + nm * 8;
let mut data_start = class_defs + nc * 32;
data_start = (data_start + 3) & !3;
let mut d: Vec<u8> = Vec::new();
let at = |d: &Vec<u8>| (data_start + d.len()) as u32;
// type lists
let tl = |d: &mut Vec<u8>, list: &[u32]| -> u32 {
if list.is_empty() {
return 0;
}
align4(d);
let o = at(d);
u32le(d, list.len() as u32);
for &t in list {
u16le(d, t as u16);
}
o
};
let proto_params: Vec<u32> = self.protos.iter().map(|p| tl(&mut d, &p.2)).collect();
let class_ifaces: Vec<u32> = self.classes.iter().map(|c| tl(&mut d, &c.interfaces)).collect();
// string data
let mut string_offs = Vec::new();
for s in &self.strings {
string_offs.push(at(&d));
uleb(&mut d, s.encode_utf16().count() as u32);
for c in s.encode_utf16() {
if c == 0 {
d.extend_from_slice(&[0xc0, 0x80]);
} else if c < 0x80 {
d.push(c as u8);
} else if c < 0x800 {
d.extend_from_slice(&[0xc0 | (c >> 6) as u8, 0x80 | (c & 0x3f) as u8]);
} else {
d.extend_from_slice(&[0xe0 | (c >> 12) as u8, 0x80 | ((c >> 6) & 0x3f) as u8, 0x80 | (c & 0x3f) as u8]);
}
}
d.push(0);
}
// code items, class data, annotations
let mut class_data_offs = Vec::new();
let mut annot_offs = Vec::new();
for c in &self.classes {
let code_off = |d: &mut Vec<u8>, m: &MethodSpec| -> u32 {
let Some(code) = &m.code else { return 0 };
align4(d);
let o = at(d);
u16le(d, code.registers);
u16le(d, code.ins);
u16le(d, code.outs);
u16le(d, code.tries.len() as u16);
u32le(d, 0);
u32le(d, code.insns.len() as u32);
for &i in &code.insns {
u16le(d, i);
}
if !code.tries.is_empty() {
if code.insns.len() % 2 == 1 {
u16le(d, 0);
}
let mut list = Vec::new();
uleb(&mut list, code.tries.len() as u32);
let mut offs = Vec::new();
for t in &code.tries {
offs.push(list.len() as u16);
let n = t.handlers.len() as i32;
sleb(&mut list, if t.catch_all.is_some() { -n } else { n });
for &(ty, addr) in &t.handlers {
uleb(&mut list, ty);
uleb(&mut list, addr);
}
if let Some(a) = t.catch_all {
uleb(&mut list, a);
}
}
for (t, off) in code.tries.iter().zip(offs) {
u32le(d, t.start);
u16le(d, t.count);
u16le(d, off);
}
d.extend_from_slice(&list);
}
o
};
let mut direct = c.direct.clone();
direct.sort_by_key(|m| m.method);
let mut virtuals = c.virtuals.clone();
virtuals.sort_by_key(|m| m.method);
let direct_offs: Vec<u32> = direct.iter().map(|m| code_off(&mut d, m)).collect();
let virtual_offs: Vec<u32> = virtuals.iter().map(|m| code_off(&mut d, m)).collect();
let cd = at(&d);
let mut sf = c.static_fields.clone();
sf.sort();
let mut inf = c.instance_fields.clone();
inf.sort();
uleb(&mut d, sf.len() as u32);
uleb(&mut d, inf.len() as u32);
uleb(&mut d, direct.len() as u32);
uleb(&mut d, virtuals.len() as u32);
for list in [&sf, &inf] {
let mut prev = 0;
for &(f, a) in list.iter() {
uleb(&mut d, f - prev);
uleb(&mut d, a);
prev = f;
}
}
for (list, offs) in [(&direct, &direct_offs), (&virtuals, &virtual_offs)] {
let mut prev = 0;
for (m, &o) in list.iter().zip(offs.iter()) {
uleb(&mut d, m.method - prev);
uleb(&mut d, m.access);
uleb(&mut d, o);
prev = m.method;
}
}
class_data_offs.push(cd);
if c.annotations.is_empty() {
annot_offs.push(0);
} else {
let mut items = Vec::new();
for &t in &c.annotations {
items.push(at(&d));
d.push(1); // runtime visibility
uleb(&mut d, t);
uleb(&mut d, 0);
}
align4(&mut d);
let set_off = at(&d);
u32le(&mut d, items.len() as u32);
for i in items {
u32le(&mut d, i);
}
let dir = at(&d);
u32le(&mut d, set_off);
u32le(&mut d, 0);
u32le(&mut d, 0);
u32le(&mut d, 0);
annot_offs.push(dir);
}
}
align4(&mut d);
let file_size = data_start + d.len();
let mut out = vec![0u8; data_start];
out[..8].copy_from_slice(b"dex\n035\0");
let put = |out: &mut Vec<u8>, off: usize, v: u32| out[off..off + 4].copy_from_slice(&v.to_le_bytes());
put(&mut out, 32, file_size as u32);
put(&mut out, 36, 0x70);
put(&mut out, 40, 0x1234_5678);
for (i, (n, o)) in
[(ns, string_ids), (nt, type_ids), (np, proto_ids), (nf, field_ids), (nm, method_ids), (nc, class_defs)].iter().enumerate()
{
put(&mut out, 56 + i * 8, *n as u32);
put(&mut out, 60 + i * 8, if *n == 0 { 0 } else { *o as u32 });
}
put(&mut out, 104, d.len() as u32);
put(&mut out, 108, data_start as u32);
for (i, o) in string_offs.iter().enumerate() {
put(&mut out, string_ids + i * 4, *o);
}
for (i, t) in self.types.iter().enumerate() {
put(&mut out, type_ids + i * 4, *t);
}
for (i, p) in self.protos.iter().enumerate() {
put(&mut out, proto_ids + i * 12, p.0);
put(&mut out, proto_ids + i * 12 + 4, p.1);
put(&mut out, proto_ids + i * 12 + 8, proto_params[i]);
}
for (i, (c, t, n)) in self.fields.iter().enumerate() {
out[field_ids + i * 8..field_ids + i * 8 + 2].copy_from_slice(&(*c as u16).to_le_bytes());
out[field_ids + i * 8 + 2..field_ids + i * 8 + 4].copy_from_slice(&(*t as u16).to_le_bytes());
put(&mut out, field_ids + i * 8 + 4, *n);
}
for (i, (c, p, n)) in self.methods.iter().enumerate() {
out[method_ids + i * 8..method_ids + i * 8 + 2].copy_from_slice(&(*c as u16).to_le_bytes());
out[method_ids + i * 8 + 2..method_ids + i * 8 + 4].copy_from_slice(&(*p as u16).to_le_bytes());
put(&mut out, method_ids + i * 8 + 4, *n);
}
for (i, c) in self.classes.iter().enumerate() {
let o = class_defs + i * 32;
for (k, v) in
[c.class, c.access, c.superclass, class_ifaces[i], c.source_file, annot_offs[i], class_data_offs[i], 0].iter().enumerate()
{
put(&mut out, o + k * 4, *v);
}
}
out.extend_from_slice(&d);
let sum = adler32(&out[12..]);
put(&mut out, 8, sum);
out
}
}
fn adler32(data: &[u8]) -> u32 {
let (mut a, mut b) = (1u32, 0u32);
for &x in data {
a = (a + u32::from(x)) % 65521;
b = (b + a) % 65521;
}
(b << 16) | a
}
const MAIN: &str = "Lcom/example/notes/MainActivity;";
const UTIL: &str = "Lcom/example/notes/Util;";
const STRING: &str = "Ljava/lang/String;";
/// `classes.dex` of the Notes app: `MainActivity` (constructor, `onCreate`, `run`, `pick` with a
/// packed switch inside a try/catch) and `Util` (two `log` overloads printing through
/// `System.out`).
pub fn notes_dex() -> Vec<u8> {
let mut b = DexBuilder::default();
let activity = b.ty("Landroid/app/Activity;");
let main = b.ty(MAIN);
let runnable = b.ty("Ljava/lang/Runnable;");
let deprecated = b.ty("Ljava/lang/Deprecated;");
let rte = b.ty("Ljava/lang/RuntimeException;");
let object = b.ty("Ljava/lang/Object;");
let util = b.ty(UTIL);
let tag = b.field(MAIN, STRING, "TAG");
let count = b.field(MAIN, "I", "count");
let out = b.field("Ljava/lang/System;", "Ljava/io/PrintStream;", "out");
let super_init = b.method("Landroid/app/Activity;", "<init>", "V", &[]);
let super_create = b.method("Landroid/app/Activity;", "onCreate", "V", &["Landroid/os/Bundle;"]);
let init = b.method(MAIN, "<init>", "V", &[]);
let on_create = b.method(MAIN, "onCreate", "V", &["Landroid/os/Bundle;"]);
let run = b.method(MAIN, "run", "V", &[]);
let pick = b.method(MAIN, "pick", "I", &["I"]);
let log_s = b.method(UTIL, "log", "V", &[STRING]);
let log_i = b.method(UTIL, "log", "V", &["I"]);
let println = b.method("Ljava/io/PrintStream;", "println", "V", &[STRING]);
let hello = b.string(HELLO);
let main_src = b.string("MainActivity.java");
let util_src = b.string("Util.java");
let code = |registers, ins, outs, insns: Vec<u16>| Some(CodeSpec { registers, ins, outs, insns, tries: vec![] });
b.classes.push(ClassSpec {
class: main,
access: 0x1,
superclass: activity,
interfaces: vec![runnable],
source_file: main_src,
annotations: vec![deprecated],
static_fields: vec![(tag, 0x1a)],
instance_fields: vec![(count, 0x2)],
direct: vec![MethodSpec { method: init, access: 0x10001, code: code(1, 1, 1, vec![0x1070, super_init as u16, 0x0000, 0x000e]) }],
virtuals: vec![
MethodSpec {
method: on_create,
access: 0x1,
code: code(3, 2, 2, vec![0x001a, hello as u16, 0x1071, log_s as u16, 0x0000, 0x206f, super_create as u16, 0x0021, 0x000e]),
},
MethodSpec { method: run, access: 0x1, code: code(1, 1, 1, vec![0x7012, 0x1071, log_i as u16, 0x0000, 0x000e]) },
MethodSpec {
method: pick,
access: 0x1,
code: Some(CodeSpec {
registers: 3,
ins: 2,
outs: 0,
insns: vec![0x022b, 10, 0, 0x0012, 0x000f, 0x1012, 0x000f, 0x2012, 0x000f, 0x0000, 0x0100, 2, 1, 0, 5, 0, 7, 0],
tries: vec![TrySpec { start: 0, count: 3, handlers: vec![(rte, 3)], catch_all: Some(3) }],
}),
},
],
});
b.classes.push(ClassSpec {
class: util,
access: 0x11,
superclass: object,
source_file: util_src,
direct: vec![
MethodSpec { method: log_s, access: 0x9, code: code(2, 1, 2, vec![0x0062, out as u16, 0x206e, println as u16, 0x0010, 0x000e]) },
MethodSpec { method: log_i, access: 0x9, code: code(1, 1, 0, vec![0x000e]) },
],
..ClassSpec::default()
});
b.build()
}
}
+1
View File
@@ -17,6 +17,7 @@ craft-wordmodel = { workspace = true }
chrono = { version = "0.4.45", default-features = false, features = ["std"] }
image = { version = "0.25", default-features = false, features = ["png", "bmp"] }
log = "0.4"
md4 = "0.11"
miniz_oxide = "0.9"
sha1 = "0.11"
thiserror = { workspace = true }
+79 -12
View File
@@ -3,7 +3,7 @@
//! picture's place in the BLIP store, crop, alt text) and the `OfficeArtFBSE` with the BLIP
//! embedded in it. The character 0x01 in the text points here through `sprmCPicLocation`.
use sha1::Digest;
use md4::Digest;
/// `PICF.cbHeader`.
const CB_HEADER: u16 = 0x44;
@@ -77,14 +77,15 @@ impl Blip {
}
}
/// The `OfficeArtBlip*` record.
fn record(&self, w_emu: i32, h_emu: i32) -> Vec<u8> {
/// The `OfficeArtBlip*` record and its format-defined identifier.
fn record(&self, w_emu: i32, h_emu: i32) -> (Vec<u8>, [u8; 16]) {
let (raw, (typ, inst)) = match self {
Blip::Png(b) => (b, BLIP_PNG),
Blip::Jpeg(b) => (b, BLIP_JPEG),
Blip::Metafile(b, emf) => (b, if *emf { BLIP_EMF } else { BLIP_WMF }),
};
let mut body = uid(raw).to_vec();
let id = uid(raw);
let mut body = id.to_vec();
match self {
Blip::Png(b) | Blip::Jpeg(b) => {
body.push(0xFF); // tag
@@ -106,16 +107,14 @@ impl Blip {
body.extend_from_slice(&packed);
}
}
rec(0, inst, typ, &body)
(rec(0, inst, typ, &body), id)
}
}
/// A 16-byte id for a BLIP (the format wants an MD4; any digest identifies it).
/// MS-ODRAW requires MD4 of the uncompressed BLIP payload, not the original import file.
/// This legacy-format identifier is not authentication or a security integrity check.
fn uid(bytes: &[u8]) -> [u8; 16] {
let d = sha1::Sha1::digest(bytes);
let mut u = [0u8; 16];
u.copy_from_slice(d.get(..16).unwrap_or(&[0; 16]));
u
md4::Md4::digest(bytes).into()
}
/// An OfficeArt record: header (version, instance, type, length) then the body.
@@ -147,9 +146,10 @@ impl Pictures {
let gh = (h.max(1.0) / (1.0 - ct - cb).max(0.01)).min(1584.0);
let emu = |pt: f32| (pt * 12_700.0).round() as i32;
let blip_rec = blip.record(emu(gw), emu(gh));
let (blip_rec, id) = blip.record(emu(gw), emu(gh));
let mut fbse = vec![blip.bt(), blip.bt()];
fbse.extend_from_slice(&uid(bytes));
// Reuse the embedded BLIP's identifier after PNG conversion/placeable-header removal.
fbse.extend_from_slice(&id);
fbse.extend_from_slice(&0x00FFu16.to_le_bytes()); // tag
fbse.extend_from_slice(&(blip_rec.len() as u32).to_le_bytes());
fbse.extend_from_slice(&1u32.to_le_bytes()); // cRef
@@ -209,3 +209,70 @@ impl Pictures {
u32::try_from(at).ok()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn blip_uid_matches_rfc1320_vectors() {
assert_eq!(uid(b""), [0x31, 0xd6, 0xcf, 0xe0, 0xd1, 0x6a, 0xe9, 0x31, 0xb7, 0x3c, 0x59, 0xd7, 0xe0, 0xc0, 0x89, 0xc0]);
assert_eq!(uid(b"abc"), [0xa4, 0x48, 0x01, 0x7a, 0xaf, 0x21, 0xd8, 0x52, 0x5f, 0xc1, 0x0a, 0xe8, 0x7a, 0xa6, 0x72, 0x9d]);
}
fn check_record_ids(input: &[u8], payload: &[u8]) {
let mut pictures = Pictures::default();
assert_eq!(pictures.add(input, 1.0, 1.0, [0.0; 4], ""), Some(0));
let bytes = &pictures.data;
let shape = usize::from(CB_HEADER);
let shape_len = u32::from_le_bytes(bytes[shape + 4..shape + 8].try_into().unwrap()) as usize;
let fbse = shape + 8 + shape_len;
assert_eq!(&bytes[fbse + 2..fbse + 4], &FBSE.to_le_bytes());
let embedded = fbse + 8 + 36;
let typ = u16::from_le_bytes(bytes[embedded + 2..embedded + 4].try_into().unwrap());
let emitted = if typ == BLIP_WMF.0 || typ == BLIP_EMF.0 {
// Controlled tiny fixtures: skip the UID and 34-byte metafile header.
miniz_oxide::inflate::decompress_to_vec_zlib(&bytes[embedded + 58..]).unwrap()
} else {
assert!(typ == BLIP_PNG.0 || typ == BLIP_JPEG.0);
bytes[embedded + 25..].to_vec()
};
assert_eq!(emitted, payload, "stored image bytes must retain the expected conversion");
let expected = uid(&emitted);
assert_eq!(&bytes[fbse + 10..fbse + 26], &expected, "FBSE must identify stored data");
assert_eq!(&bytes[embedded + 8..embedded + 24], &expected, "BLIP must share the same identifier");
}
#[test]
fn blip_ids_identify_unmodified_payloads() {
// Tiny format-dispatch fixtures exercise identifier bytes, not image validation.
let png = b"\x89PNGsmall";
check_record_ids(png, png);
let jpeg = b"\xff\xd8\xffsmall";
check_record_ids(jpeg, jpeg);
let wmf = [1, 0, 9, 0, 0, 3, 9, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0];
check_record_ids(&wmf, &wmf);
let mut emf = vec![0; 44];
emf[..4].copy_from_slice(&1u32.to_le_bytes());
emf[40..44].copy_from_slice(b" EMF");
check_record_ids(&emf, &emf);
}
#[test]
fn blip_ids_exclude_placeable_wmf_header() {
let wmf = [1, 0, 9, 0, 0, 3, 9, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0];
let mut placeable = vec![0; 22];
placeable[..4].copy_from_slice(&[0xd7, 0xcd, 0xc6, 0x9a]);
placeable.extend_from_slice(&wmf);
check_record_ids(&placeable, &wmf);
}
#[test]
fn blip_ids_identify_converted_bmp_payload() {
let mut bmp = std::io::Cursor::new(Vec::new());
image::DynamicImage::new_rgb8(1, 1).write_to(&mut bmp, image::ImageFormat::Bmp).unwrap();
let Blip::Png(encoded) = Blip::of(bmp.get_ref()).unwrap() else { panic!("BMP must become PNG") };
assert_ne!(bmp.get_ref(), &encoded);
check_record_ids(bmp.get_ref(), &encoded);
}
}
+79 -1
View File
@@ -315,7 +315,8 @@ pub fn read_preview(bytes: &[u8], preview_entry: &str) -> Option<Vec<u8>> {
archive.read(preview_entry, PREVIEW_LIMIT).ok().flatten()
}
/// Read a bounded preview from a seekable file without loading the full bundle into memory.
/// Read a preview from a seekable ZIP, including archives with a leading prefix.
/// The decompressed preview is limited to 4 MiB; archive discovery may perform substantial I/O.
pub fn read_preview_from<R: Read + Seek>(reader: R, preview_entry: &str) -> Option<Vec<u8>> {
const PREVIEW_LIMIT: u64 = 4 << 20;
let mut zip = zip::ZipArchive::new(reader).ok()?;
@@ -328,6 +329,22 @@ pub fn read_preview_from<R: Read + Seek>(reader: R, preview_entry: &str) -> Opti
(u64::try_from(preview.len()).ok()? <= PREVIEW_LIMIT).then_some(preview)
}
/// Read a preview only from a ZIP with a local-file header at byte zero.
///
/// Use for native formats whose contract excludes prefixed/self-extracting archives.
/// Nonmatching inputs require at most four bytes read, regardless of the initial cursor position.
/// Matching ZIPs still require directory I/O; this is not an overall read/time budget.
pub fn read_unprefixed_preview_from<R: Read + Seek>(mut reader: R, preview_entry: &str) -> Option<Vec<u8>> {
reader.seek(std::io::SeekFrom::Start(0)).ok()?;
let mut magic = [0u8; 4];
reader.read_exact(&mut magic).ok()?;
if &magic != b"PK\x03\x04" {
return None;
}
reader.seek(std::io::SeekFrom::Start(0)).ok()?;
read_preview_from(reader, preview_entry)
}
fn read_legacy(bytes: &[u8], spec: Spec<'_>) -> Result<Package, Error> {
let mut document: Value = serde_json::from_slice(bytes).map_err(|e| Error::NotBundle(e.to_string()))?;
let mut assets = Vec::new();
@@ -409,6 +426,67 @@ mod tests {
assert_eq!(read_preview(&bytes, SPEC.preview_entry).as_deref(), Some(&b"png"[..]));
}
/// Counts the bytes read through it.
struct Counting<R> {
inner: R,
read: usize,
}
impl<R: Read> Read for Counting<R> {
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
let n = self.inner.read(buf)?;
self.read += n;
Ok(n)
}
}
impl<R: Seek> Seek for Counting<R> {
fn seek(&mut self, pos: std::io::SeekFrom) -> std::io::Result<u64> {
self.inner.seek(pos)
}
}
#[test]
fn preview_from_a_reader_reads_a_bundle() {
let bytes = write(br#"{}"#, 4, "Test 0.1", Some(b"png"), &[], &[], SPEC).unwrap();
assert_eq!(read_preview_from(Cursor::new(&bytes), SPEC.preview_entry).as_deref(), Some(&b"png"[..]));
}
#[test]
fn prefixed_bundle_admission_is_explicit() {
let bundle = write(br#"{}"#, 4, "Test 0.1", Some(b"png"), &[], &[], SPEC).unwrap();
let mut bytes = b"MZsynthetic-prefix".to_vec();
bytes.extend(bundle);
let mut original = zip::ZipArchive::new(Cursor::new(&bytes)).unwrap();
let mut preview = Vec::new();
original.by_name(SPEC.preview_entry).unwrap().read_to_end(&mut preview).unwrap();
assert_eq!(preview, b"png");
assert!(has_document(&bytes, SPEC));
assert!(!starts_with_mimetype(&bytes, SPEC));
assert_eq!(read_preview_from(Cursor::new(&bytes), SPEC.preview_entry), Some(preview));
assert_eq!(read_unprefixed_preview_from(Cursor::new(&bytes), SPEC.preview_entry), None);
}
#[test]
fn preview_from_an_advanced_reader_still_reads_the_bundle() {
let bytes = write(br#"{}"#, 4, "Test 0.1", Some(b"png"), &[], &[], SPEC).unwrap();
for offset in [1, 4, bytes.len() / 2, bytes.len()] {
let mut reader = Cursor::new(&bytes);
reader.set_position(offset as u64);
assert_eq!(read_preview_from(reader.clone(), SPEC.preview_entry).as_deref(), Some(&b"png"[..]), "offset {offset}");
assert_eq!(read_unprefixed_preview_from(reader, SPEC.preview_entry).as_deref(), Some(&b"png"[..]), "offset {offset}");
}
}
#[test]
fn preview_from_a_non_zip_reads_only_its_signature() {
let mut file = Counting { inner: Cursor::new(vec![0x42u8; 1 << 20]), read: 0 };
assert_eq!(read_unprefixed_preview_from(&mut file, SPEC.preview_entry), None);
assert!(file.read <= 4, "read {} bytes of a file that is not a zip", file.read);
let mut empty = Counting { inner: Cursor::new(Vec::new()), read: 0 };
assert_eq!(read_unprefixed_preview_from(&mut empty, SPEC.preview_entry), None);
}
#[test]
fn extracts_legacy_inline_assets() {
let loaded = read(br#"{"assetData":{"7":"AQID"},"name":"x"}"#, 4, SPEC).unwrap();
+2 -2
View File
@@ -3,8 +3,8 @@
//! [`read`] turns a `.docx` package into a [`craft_wordmodel::Document`]; [`fn@write`] does the
//! reverse. Both are written from the public specification. The reader is lenient (unknown
//! markup is skipped, bad numbers fall back to defaults) and bounded (zip entry sizes, total
//! decompressed size, XML depth and element counts are capped), so hostile input yields an
//! error or a best-effort document, never a panic.
//! decompressed size, XML depth, element counts per part and a package-wide element budget are
//! capped), so hostile input yields an error or a best-effort document, never a panic.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
// The code came from an app whose lints allow this.
#![allow(clippy::type_complexity)]
+138 -4
View File
@@ -1,5 +1,6 @@
//! OPC package access: bounded zip reading, relationships, part names.
use std::cell::Cell;
use std::collections::{BTreeMap, HashMap};
use std::sync::Arc;
@@ -113,6 +114,13 @@ pub const CUSTOM_XML_ROOTS: &str = "wordcraft:customXml.roots";
/// The original `word/settings.xml` when it holds settings the model doesn't (merged into on
/// save by `write::settings_merge`). Not a package part: WordCraft's own bookkeeping.
pub const SETTINGS_ORIG: &str = "wordcraft:settings.orig";
/// The theme's East Asian, complex-script and per-script fonts (`a:ea`, `a:cs`, `a:font
/// script="Hans"` in `a:majorFont` / `a:minorFont`), which the model doesn't hold: `major|minor
/// \tface\tea|cs\ttypeface` and `major|minor\tscript\t<script>\ttypeface` lines (per font, at
/// most 256 script ids of 8 characters or fewer and 256 longer ones, such as `zh-Hant-TW`). Written back into the theme on save, so the
/// `w:eastAsiaTheme` and `w:cstheme` slots a save keeps still name a font in Word. Not a package
/// part: WordCraft's own bookkeeping.
pub const THEME_FONTS: &str = "wordcraft:theme.fonts";
/// Extended properties (`docProps/app.xml`) the model doesn't hold but a save keeps
/// ([`APP_KEPT_PROPS`]): `name\tvalue` lines. Not a package part: WordCraft's own bookkeeping.
pub const APP_KEPT: &str = "wordcraft:app.kept";
@@ -216,6 +224,14 @@ fn opc_error(e: craft_opc::Error) -> DocxError {
/// document keeps as it is (a picture, an embedded object) is handed over rather than copied.
pub struct Package {
opc: craft_opc::Package,
/// Elements this package's XML parts may still be parsed into. Every XML part read through
/// [`Package::xml`] charges it, so a file of many parts each inside the per-part cap builds
/// bounded tree memory in total — a chart part with no series builds a maximal tree for
/// almost no graphic work, and the trees the reader keeps accumulate.
budget: Cell<usize>,
/// What [`Package::reset_budget`] restores: the cap the package was opened with (the default,
/// or a smaller one from [`Package::open_limited_within`]).
budget_cap: usize,
}
impl Package {
@@ -227,8 +243,16 @@ impl Package {
/// `max_total` (counting entries that fail their checksum), is an error. A damaged entry is
/// left out with a logged warning.
pub fn open_limited(bytes: &[u8], max_part: u64, max_total: u64) -> Result<Package, DocxError> {
Package::open_limited_within(bytes, max_part, max_total, xml::MAX_ELEMENTS_TOTAL)
}
/// [`open_limited`] with an XML element budget of its own (nested documents share their
/// container's, tests use a small one).
pub fn open_limited_within(bytes: &[u8], max_part: u64, max_total: u64, max_elements: usize) -> Result<Package, DocxError> {
let limits = craft_opc::Limits::new(MAX_ENTRIES, max_part, max_total);
craft_opc::Package::open(bytes, &limits).map(|opc| Package { opc }).map_err(opc_error)
craft_opc::Package::open(bytes, &limits)
.map(|opc| Package { opc, budget: Cell::new(max_elements), budget_cap: max_elements })
.map_err(opc_error)
}
/// The bytes of all its parts.
@@ -244,7 +268,27 @@ impl Package {
/// A package from parts already in memory (a Flat OPC file, a converted document), by part
/// name without the leading `/`.
pub fn from_parts(files: BTreeMap<String, Vec<u8>>) -> Package {
Package { opc: craft_opc::Package::from_parts(files) }
Package { opc: craft_opc::Package::from_parts(files), budget: Cell::new(xml::MAX_ELEMENTS_TOTAL), budget_cap: xml::MAX_ELEMENTS_TOTAL }
}
/// Start a read's element budget over: the budget is per read, not per package's lifetime.
pub(crate) fn reset_budget(&self) {
self.budget.set(self.budget_cap);
}
/// The XML elements left of the package's budget: nested documents open within it.
pub(crate) fn elements_left(&self) -> usize {
self.budget.get()
}
/// Charge `count` elements a parsed part built against the budget.
pub(crate) fn charge(&self, count: usize) -> Result<(), DocxError> {
let left = self.budget.get();
if count > left {
return Err(DocxError::Limit(format!("{count} XML elements, {left} left of the package's {} budget", self.budget_cap)));
}
self.budget.set(left - count);
Ok(())
}
/// Part bytes by name (leading `/` ignored; case-insensitive).
@@ -261,14 +305,28 @@ impl Package {
/// [`Package::xml`] for the main document part: malformed XML is an error, not a truncated read.
pub fn xml_strict(&self, name: &str) -> Result<Option<El>, DocxError> {
match self.get(name) {
Some(b) => xml::parse_strict(b).map(Some),
Some(b) => {
// The parser stops at the remaining budget or the per-part cap, whichever is less:
// a part over what is left of the package's budget is refused before the whole
// per-part tree is built.
let (el, count) = xml::parse_strict_counted(b, self.budget.get().min(xml::MAX_ELEMENTS))?;
self.charge(count)?;
Ok(Some(el))
}
None => Ok(None),
}
}
/// A package part as a parsed XML tree, charged against the element budget: the parser
/// stops at what is left of the budget or the per-part cap, whichever is less, and the
/// count it built is charged after. A lenient read: malformed XML is a truncated one.
pub fn xml(&self, name: &str) -> Result<Option<El>, DocxError> {
match self.get(name) {
Some(b) => xml::parse(b).map(Some),
Some(b) => {
let (el, count) = xml::parse_counted(b, self.budget.get().min(xml::MAX_ELEMENTS))?;
self.charge(count)?;
Ok(Some(el))
}
None => Ok(None),
}
}
@@ -448,6 +506,82 @@ mod tests {
let junk = EmbeddedManifest::parse(b"R\tnope\trId1\tk\tt\tI\nP\tonly-two\n\t\t\n\xff\xfe");
assert!(junk.parts.is_empty());
}
/// A file of many parts each inside the per-part cap is bounded in total: every XML part
/// read through the package charges a package-wide budget, and a part over it is skipped
/// (warned), never built. A chart part with no series builds a maximal tree for almost no
/// graphic work, so the trees a reader keeps would otherwise accumulate one per part.
#[test]
fn the_xml_element_budget_is_package_wide() {
let ns = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main""#;
let rels = r#"<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/><Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering" Target="numbering.xml"/></Relationships>"#;
let document = format!(r#"<w:document {ns}><w:body/></w:document>"#);
let dense = |root: &str| format!(r#"<{root} {ns}>{}</{root}>"#, "<a/>".repeat(900));
let z = zip_of(&[
("word/document.xml", document.into_bytes()),
("word/_rels/document.xml.rels", rels.as_bytes().to_vec()),
("word/styles.xml", dense("w:styles").into_bytes()),
("word/numbering.xml", dense("w:numbering").into_bytes()),
]);
let pkg = Package::open_limited_within(&z, MAX_PART, MAX_TOTAL, 1_000).unwrap();
// styles (900 elements) reads; numbering (900 more) is over what is left and is skipped
// with a warning, not built.
let read = || crate::read::read_opened(&pkg, None);
let (first, warned) = crate::test_log::warnings(read);
assert!(first.is_ok(), "{:?}", first.err());
let refused: Vec<_> = warned.iter().filter(|w| w.contains("numbering") && w.contains("XML element")).collect();
assert_eq!(refused.len(), 1, "{warned:?}");
// The budget is per read: a second read starts it over and behaves the same.
let (second, warned) = crate::test_log::warnings(read);
assert!(second.is_ok(), "{:?}", second.err());
assert_eq!(warned.iter().filter(|w| w.contains("numbering") && w.contains("XML element")).count(), 1, "{warned:?}");
}
/// The main document part itself is strict: over the budget it is an error, not a
/// best-effort read of a tree the file then paid for.
#[test]
fn a_main_part_over_the_element_budget_is_refused() {
let ns = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main""#;
let document = format!(r#"<w:document {ns}>{}</w:document>"#, "<a/>".repeat(20));
let z = zip_of(&[("word/document.xml", document.into_bytes())]);
let pkg = Package::open_limited_within(&z, MAX_PART, MAX_TOTAL, 10).unwrap();
assert!(matches!(crate::read::read_opened(&pkg, None), Err(DocxError::Limit(_))));
}
/// A part over what is left of the package's budget is refused while parsing, not after the
/// whole per-part tree is built: the parser stops at the remaining budget or the per-part
/// cap, whichever is less, so the file pays for at most what is left of the budget.
#[test]
fn a_part_over_the_remaining_budget_is_refused_while_parsing() {
let ns = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main""#;
let document = format!(r#"<w:document {ns}>{}</w:document>"#, "<a/>".repeat(200));
let z = zip_of(&[("word/document.xml", document.into_bytes())]);
// 200 elements: inside the per-part cap, over the package's 100 budget. The parse
// refuses at the budget, so the error is the parse's, not the charge's, and names
// the effective limit for this parse (the remaining budget), not the whole budget.
let pkg = Package::open_limited_within(&z, MAX_PART, MAX_TOTAL, 100).unwrap();
let e = crate::read::read_opened(&pkg, None).expect_err("refused");
assert_eq!(e, DocxError::Limit("over the XML element budget for this parse: at most 100 elements".into()));
}
/// A part parsed earlier shrinks what is left of the budget: the next part is refused while
/// parsing at the remaining, not at the whole budget, and the error names the effective limit
/// for this parse (the remaining), not the package's budget.
#[test]
fn an_earlier_part_reduces_the_remaining_budget_the_next_part_names_it() {
let ns = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main""#;
let styles = format!(r#"<w:styles {ns}>{}</w:styles>"#, "<a/>".repeat(60));
let settings = format!(r#"<w:settings {ns}>{}</w:settings>"#, "<a/>".repeat(60));
let z = zip_of(&[("word/styles.xml", styles.into_bytes()), ("word/settings.xml", settings.into_bytes())]);
// 100 elements of budget. The styles part parses (the main-part path: `xml_strict`) and
// charges its 61 elements, leaving 39.
let pkg = Package::open_limited_within(&z, MAX_PART, MAX_TOTAL, 100).unwrap();
pkg.xml_strict("word/styles.xml").unwrap();
// The settings part needs 61 elements, over the 39 left and under the per-part cap: the
// parse refuses at the remaining, so the error names 39, not the package's 100 budget.
let e = pkg.xml("word/settings.xml").expect_err("refused");
assert_eq!(e, DocxError::Limit("over the XML element budget for this parse: at most 39 elements".into()));
}
}
#[cfg(test)]
+7 -5
View File
@@ -154,9 +154,11 @@ pub(crate) fn read_opened(pkg: &Package, chunks: Option<ChunkImporter>) -> Resul
read_opened_in(pkg, ChunkState::new(chunks)).map(|(doc, ..)| doc)
}
/// [`read_opened`] with what chunks may still bring in; also gives the chunks, chunk bytes and
/// graphic work left of that.
fn read_opened_in(pkg: &Package, chunks: ChunkState) -> Result<(Document, usize, u64, usize), DocxError> {
/// [`read_opened`] with what chunks may still bring in; also gives the chunks, chunk bytes,
/// graphic work and XML elements left of that.
fn read_opened_in(pkg: &Package, chunks: ChunkState) -> Result<(Document, usize, u64, usize, usize), DocxError> {
// The budget is per read, so a package read twice (tests, a Flat OPC conversion) starts over.
pkg.reset_budget();
let root_rels = pkg.rels("");
let main = root_rels.by_type(rt::OFFICE_DOC).filter(|r| !r.external).map(|r| r.target.clone()).unwrap_or_else(|| "word/document.xml".to_string());
let Some(root) = pkg.xml_strict(&main)? else {
@@ -371,11 +373,11 @@ fn read_opened_in(pkg: &Package, chunks: ChunkState) -> Result<(Document, usize,
if r.shape_ids {
keep_glued_ids(&mut r.doc, &r.glued);
}
let (left, bytes, graphic) = (r.chunks.left, r.chunks.bytes, r.chunks.graphic);
let (left, bytes, graphic, elements) = (r.chunks.left, r.chunks.bytes, r.chunks.graphic, pkg.elements_left());
let mut doc = r.doc;
doc.skipped_parts.extend(pkg.skipped().iter().cloned());
doc.ensure_nonempty();
Ok((doc, left, bytes, graphic))
Ok((doc, left, bytes, graphic, elements))
}
/// Most move ranges open at once, and most move names tracked, per file.
+182 -7
View File
@@ -110,11 +110,27 @@ impl Reader<'_> {
log::warn!("docx: alternative format chunks nest deeper than {MAX_CHUNK_NESTING}; the inner ones are left out");
return None;
}
let pkg =
Package::open_limited(bytes, MAX_PART, self.chunks.bytes).map_err(|e| log::warn!("docx: unreadable nested document chunk: {e}")).ok()?;
// The nested document shares the file's element budget: open_limited_within, not a
// fresh cap — nesting goes deep, so 5 packages each getting 16M is the OOM class the
// budget exists for. The container's own parse spent part of the chain, so the cap is
// the lesser of the chain and what the container has left.
let cap = self.chunks.elements.min(self.pkg.elements_left());
let pkg = Package::open_limited_within(bytes, MAX_PART, self.chunks.bytes, cap)
.map_err(|e| log::warn!("docx: unreadable nested document chunk: {e}"))
.ok()?;
self.chunks.bytes = self.chunks.bytes.saturating_sub(pkg.size());
let state = ChunkState { nesting: self.chunks.nesting + 1, depth: depth + 1, ..self.chunks };
let (doc, left, bytes, graphic) = match super::read_opened_in(&pkg, state) {
let read = super::read_opened_in(&pkg, state);
// A parsed main part can still fail semantic validation (for example, a non-Word
// root). Charge its elements before returning that error, so later siblings cannot
// reuse the reservation. On success this is the same single charge as before.
let elements = pkg.elements_left();
self.chunks.elements = elements;
let spent = cap.saturating_sub(elements);
if let Err(e) = self.pkg.charge(spent) {
log::warn!("docx: nested document chunk outspent the container's element budget: {e}");
}
let (doc, left, bytes, graphic, _) = match read {
Ok(read) => read,
Err(e) => {
log::warn!("docx: unreadable nested document chunk: {e}");
@@ -139,6 +155,9 @@ pub(crate) struct ChunkState<'a> {
/// Graphic work left in the file's budget ([`super::MAX_GRAPHIC_WORK`]): nested documents'
/// charts and diagrams count against it too.
pub graphic: usize,
/// XML elements left in the file's budget: nested packages share their container's
/// ([`crate::xml::MAX_ELEMENTS_TOTAL`]), not one of their own.
pub elements: usize,
/// How deep in nested WordprocessingML chunks this reader is.
pub nesting: u8,
/// The XML depth its stories start at (a nested document's: that of the chunk naming it).
@@ -148,7 +167,15 @@ pub(crate) struct ChunkState<'a> {
impl<'a> ChunkState<'a> {
pub fn new(import: Option<ChunkImporter<'a>>) -> Self {
ChunkState { left: MAX_CHUNKS, bytes: MAX_TOTAL, graphic: super::MAX_GRAPHIC_WORK, nesting: 0, depth: 0, import }
ChunkState {
left: MAX_CHUNKS,
bytes: MAX_TOTAL,
graphic: super::MAX_GRAPHIC_WORK,
elements: crate::xml::MAX_ELEMENTS_TOTAL,
nesting: 0,
depth: 0,
import,
}
}
}
@@ -159,7 +186,7 @@ mod tests {
use craft_wordmodel::{Block, Document, InlineObject};
use super::ChunkState;
use crate::package::Package;
use crate::package::{MAX_PART, MAX_TOTAL, Package};
/// A package whose body is `body`, with the document relationship `rel` (id, type, target) to
/// the part `(name, bytes)`.
@@ -198,8 +225,8 @@ mod tests {
let outer = package(r#"<w:altChunk r:id="rIdC"/>"#, ("rIdC", "aFChunk", "afchunk.docx"), ("word/afchunk.docx", &inner));
let pkg = Package::open(&outer).unwrap();
let read = |graphic| {
let (d, .., left) = super::super::read_opened_in(&pkg, ChunkState { graphic, ..ChunkState::new(None) }).unwrap();
(drawn(&d), left)
let (d, .., work, _) = super::super::read_opened_in(&pkg, ChunkState { graphic, ..ChunkState::new(None) }).unwrap();
(drawn(&d), work)
};
let (shown, left) = read(super::super::MAX_GRAPHIC_WORK);
assert!(shown);
@@ -207,4 +234,152 @@ mod tests {
// With the file's budget spent, the nested document doesn't get one of its own.
assert_eq!(read(0), (false, 0));
}
/// A package whose body is `body`, with the document relationships `rels` (id, type, target)
/// and the parts `(name, bytes)` they name.
fn package_parts(body: &str, rels: &[(&str, &str, &str)], parts: &[(&str, &[u8])]) -> Vec<u8> {
let ns = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main""#;
let rels_xml =
|inner: &str| format!(r#"<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">{inner}</Relationships>"#);
let rel = |(id, ty, target): &(&str, &str, &str)| {
format!(r#"<Relationship Id="{id}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/{ty}" Target="{target}"/>"#)
};
let names: String = rels.iter().map(rel).collect::<Vec<_>>().join("");
let mut files: Vec<(&str, Vec<u8>)> = vec![
("_rels/.rels", rels_xml(&rel(&("rId1", "officeDocument", "word/document.xml"))).into_bytes()),
("word/document.xml", format!(r#"<w:document {ns}><w:body>{body}</w:body></w:document>"#).into_bytes()),
("word/_rels/document.xml.rels", rels_xml(&names).into_bytes()),
];
files.extend(parts.iter().map(|(name, bytes)| (*name, bytes.to_vec())));
let mut zw = zip::ZipWriter::new(std::io::Cursor::new(Vec::new()));
for (name, bytes) in files {
zw.start_file(name, zip::write::SimpleFileOptions::default()).unwrap();
zw.write_all(&bytes).unwrap();
}
zw.finish().unwrap().into_inner()
}
/// Whether the body holds a paragraph with `s`.
fn has(d: &Document, s: &str) -> bool {
d.body.iter().any(|b| b.as_para().map(|p| p.text.contains(s)).unwrap_or(false))
}
#[test]
fn a_nested_documents_elements_come_out_of_the_files_budget() {
// Three levels: the outer's altChunk names the inner, whose altChunk names the
// innermost. The chain spends down: the inner's own parse charges the file's budget,
// so the innermost opens with what the inner has left, not a fresh cap.
let innermost = package(r#"<w:p><w:r><w:t>innermost</w:t></w:r></w:p>"#, ("rIdZ", "chart", "charts/z.xml"), ("word/charts/z.xml", b"<a/>"));
let inner = package(
r#"<w:p><w:r><w:t>inner</w:t></w:r></w:p><w:altChunk r:id="rIdD"/>"#,
("rIdD", "aFChunk", "afchunk.docx"),
("word/afchunk.docx", &innermost),
);
let outer = package(r#"<w:altChunk r:id="rIdC"/>"#, ("rIdC", "aFChunk", "afchunk.docx"), ("word/afchunk.docx", &inner));
let pkg = Package::open(&outer).unwrap();
let read = |elements| {
let (d, ..) = super::super::read_opened_in(&pkg, ChunkState { elements, ..ChunkState::new(None) }).unwrap();
(has(&d, "inner"), has(&d, "innermost"))
};
// With room, both levels flow in.
assert_eq!(read(crate::xml::MAX_ELEMENTS_TOTAL), (true, true));
// The inner's own parse (its rels, then its main part) charged the file's budget: the
// innermost is left out instead of getting one of its own (before this, each nested
// package started with the full 16M).
assert_eq!(read(10), (true, false));
}
#[test]
fn a_nested_documents_elements_charge_the_container() {
// The nested document's XML usage comes out of the container's budget too: the cap
// the nested package was given, minus its returned remainder, is charged, so the
// container's remaining parts parse against what is left of the shared cap — not a
// budget that ignores the chunk.
let nested = package(r#"<w:p><w:r><w:t>inner</w:t></w:r></w:p>"#, ("rIdZ", "chart", "charts/z.xml"), ("word/charts/z.xml", b"<a/>"));
let body = r#"<w:p><w:r><w:t>after</w:t></w:r></w:p>"#;
let with = package(&format!(r#"<w:altChunk r:id="rIdC"/>{body}"#), ("rIdC", "aFChunk", "afchunk.docx"), ("word/afchunk.docx", &nested));
let without = package(body, ("rIdZ", "chart", "charts/z.xml"), ("word/charts/z.xml", b"<a/>"));
let read = |outer: &[u8]| {
let pkg = Package::open(outer).unwrap();
let (d, ..) = super::super::read_opened_in(&pkg, ChunkState { elements: 10, ..ChunkState::new(None) }).unwrap();
(has(&d, "inner"), pkg.elements_left())
};
let (inner_in, charged) = read(&with);
assert!(inner_in);
let (_, base) = read(&without);
assert!(charged < base, "the nested document's usage is the container's: {charged} of {base}");
}
#[test]
fn a_grandchilds_reservation_charges_every_level() {
// Three levels: the innermost's reservation comes out of the inner's budget, and the
// inner's out of the outer's — the chain charges every container, so the outer's
// remainder is smaller with the deeper chain than with a shallow one.
let innermost = package(r#"<w:p><w:r><w:t>leaf</w:t></w:r></w:p>"#, ("rIdZ", "chart", "charts/z.xml"), ("word/charts/z.xml", b"<a/>"));
let inner = package(
r#"<w:p><w:r><w:t>mid</w:t></w:r></w:p><w:altChunk r:id="rIdD"/>"#,
("rIdD", "aFChunk", "afchunk.docx"),
("word/afchunk.docx", &innermost),
);
let outer = package(r#"<w:altChunk r:id="rIdC"/>"#, ("rIdC", "aFChunk", "afchunk.docx"), ("word/afchunk.docx", &inner));
let pkg = Package::open(&outer).unwrap();
let (d, .., elements) = super::super::read_opened_in(&pkg, ChunkState::new(None)).unwrap();
assert!(has(&d, "mid"), "the inner document didn't flow in");
assert!(has(&d, "leaf"), "the innermost document didn't flow in");
// The same container with a shallow chain: one reservation instead of two.
let shallow = package(r#"<w:altChunk r:id="rIdC"/>"#, ("rIdC", "aFChunk", "afchunk.docx"), ("word/afchunk.docx", &innermost));
let pkg = Package::open(&shallow).unwrap();
let (.., shallow_elements) = super::super::read_opened_in(&pkg, ChunkState::new(None)).unwrap();
assert!(elements < shallow_elements, "every level's reservation is charged: {elements} of {shallow_elements}");
}
#[test]
fn a_charged_budget_bounds_the_containers_part_and_the_sibling_after_it() {
// The container's budget pays for the parts it parses (the section's header, read
// during the chunk's own walk) and for the chunks after the first one: with a budget
// that fits the grandchild chunk and the header but not the sibling document's XML,
// the sibling is left out; skip the header's charge and it would flow in.
let hdr = r#"<w:hdr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:p><w:r><w:t>head</w:t></w:r></w:p><w:p><w:r><w:t>head</w:t></w:r></w:p><w:p><w:r><w:t>head</w:t></w:r></w:p></w:hdr>"#;
let gc = package(r#"<w:p><w:r><w:t>gc</w:t></w:r></w:p>"#, ("rIdZ", "chart", "charts/z.xml"), ("word/charts/z.xml", b"<a/>"));
let sibling =
package(&r#"<w:p><w:r><w:t>sibling</w:t></w:r></w:p>"#.repeat(8), ("rIdZ", "chart", "charts/z.xml"), ("word/charts/z.xml", b"<a/>"));
let inner = package_parts(
r#"<w:p><w:r><w:t>mid</w:t></w:r></w:p><w:altChunk r:id="rIdD"/><w:p><w:pPr><w:sectPr><w:headerReference r:id="rIdH"/></w:sectPr></w:pPr></w:p><w:altChunk r:id="rIdS"/>"#,
&[("rIdD", "aFChunk", "afchunk.docx"), ("rIdH", "header", "header1.xml"), ("rIdS", "aFChunk", "afchunk2.docx")],
&[("word/afchunk.docx", &gc), ("word/header1.xml", hdr.as_bytes()), ("word/afchunk2.docx", &sibling)],
);
let outer = package(r#"<w:altChunk r:id="rIdC"/>"#, ("rIdC", "aFChunk", "afchunk.docx"), ("word/afchunk.docx", &inner));
let pkg = Package::open(&outer).unwrap();
let read = |elements| {
let (d, ..) = super::super::read_opened_in(&pkg, ChunkState { elements, ..ChunkState::new(None) }).unwrap();
(has(&d, "mid"), has(&d, "gc"), has(&d, "sibling"))
};
// With room, everything flows in.
assert_eq!(read(crate::xml::MAX_ELEMENTS_TOTAL), (true, true, true));
// The grandchild chunk and the header fit the file's budget; the sibling document's
// XML (8 paragraphs) doesn't, so it's left out instead of getting a fresh cap.
assert_eq!(read(40), (true, true, false));
}
#[test]
fn a_rejected_nested_root_still_charges_the_siblings_budget() {
// Four outer elements, sixty rejected elements, five sibling elements: 69 in total.
let bad_xml = format!("<notword>{}</notword>", "<a/>".repeat(59));
let mut zip = zip::ZipWriter::new(std::io::Cursor::new(Vec::new()));
zip.start_file("word/document.xml", zip::write::SimpleFileOptions::default()).unwrap();
zip.write_all(bad_xml.as_bytes()).unwrap();
let bad = zip.finish().unwrap().into_inner();
let sibling = package_parts(r#"<w:p><w:r><w:t>sibling</w:t></w:r></w:p>"#, &[], &[]);
let outer = package_parts(
r#"<w:altChunk r:id="bad"/><w:altChunk r:id="good"/>"#,
&[("bad", "aFChunk", "bad.docx"), ("good", "aFChunk", "good.docx")],
&[("word/bad.docx", &bad), ("word/good.docx", &sibling)],
);
for (cap, included, remaining) in [(69, true, 0), (68, false, 4)] {
let pkg = Package::open_limited_within(&outer, MAX_PART, MAX_TOTAL, cap).unwrap();
let doc = super::super::read_opened(&pkg, None).unwrap();
assert_eq!(has(&doc, "sibling"), included, "budget {cap}");
assert_eq!(pkg.elements_left(), remaining, "budget {cap}");
}
}
}
+27
View File
@@ -227,6 +227,33 @@ impl Reader<'_> {
};
self.pc.major_scripts = scripts("a:majorFont");
self.pc.minor_scripts = scripts("a:minorFont");
// Kept for the save, which writes the theme from the model (`package::THEME_FONTS`).
let mut kept = String::new();
for (key, tag) in [("major", "a:majorFont"), ("minor", "a:minorFont")] {
let Some(f) = fs.child(tag) else { continue };
let clean = |v: &str| !v.is_empty() && v.len() < 256 && !v.contains(['\t', '\n', '\r']);
// The default faces and the per-script ones are told apart by their kind, so an
// `a:font script="cs"` is not taken for the `a:cs` face.
let faces = ["a:ea", "a:cs"].into_iter().filter_map(|n| Some(("face", &n[2..], f.child(n)?.attr("typeface")?)));
for (kind, which, face) in faces.filter(|(_, _, face)| clean(face)) {
kept.push_str(&format!("{key}\t{kind}\t{which}\t{face}\n"));
}
// At most 256 of the script ids font resolution takes (8 characters or fewer, as
// above) and 256 longer ones (a language tag such as `zh-Hant-TW`), counted apart
// so the longer ones never push out a mapping resolution uses.
let mut counts = (0usize, 0usize);
let per_script = f.els().filter(|e| e.name == "a:font").filter_map(|e| Some((e.attr("script")?, e.attr("typeface")?)));
for (script, face) in per_script.filter(|(script, face)| clean(script) && clean(face)) {
let n = if script.len() <= 8 { &mut counts.0 } else { &mut counts.1 };
if *n < 256 {
*n += 1;
kept.push_str(&format!("{key}\tscript\t{script}\t{face}\n"));
}
}
}
if !kept.is_empty() {
self.doc.passthrough.insert(crate::package::THEME_FONTS.into(), Arc::new(kept.into_bytes()));
}
}
self.pc.major_font = self.doc.settings.major_font.clone();
self.pc.minor_font = self.doc.settings.minor_font.clone();
+43 -12
View File
@@ -6,7 +6,7 @@ use craft_wordmodel::para::cap_alt;
use craft_wordmodel::props::{
Align, Border, BorderStyle, Borders, CellProps, CharProps, CombineBrackets, EastAsianLayout, HeightRule, Highlight, Kashida, LineSpacing, NumRef,
ParaProps, ParagraphTextDirection, Rgb, RowProps, TabAlign, TabLeader, TabStop, TableFloat, TableLook, TableProps, TextAlignment, TextColor,
TextDirection, Underline, VAlign, VMerge, VertAlign,
TextDirection, ThemeFont, Underline, VAlign, VMerge, VertAlign,
};
use craft_wordmodel::section::{
Columns, DocGrid, DocGridType, LineNumberRestart, LineNumbering, MAX_CHAR_SPACE, MAX_GRID_PITCH, NotePos, NoteProps, NoteRestart, NumFormat,
@@ -277,6 +277,18 @@ impl PropCtx {
// The East Asian font (Chinese, Japanese, Korean text). A `w:eastAsiaTheme` font
// is left to inherit, like `w:cstheme`.
c.font_ea = k.attr("w:eastAsia").filter(|f| !f.is_empty() && f.len() < 256).map(str::to_string);
// The theme slots themselves are kept for saving: Word resolves them (over the
// named fonts) when it lays the text out, and dropping them changes its line
// breaks in a document with an East Asian language.
c.font_ea_theme = k.attr("w:eastAsiaTheme").and_then(ThemeFont::parse);
c.font_cs_theme = k.attr("w:cstheme").and_then(ThemeFont::parse);
// The Latin slots too, when `font` came from them: saving writes them back while
// they still name `font`, so the text keeps following the theme in Word.
if c.font.is_some() {
let latin = |a: &str| k.attr(a).and_then(ThemeFont::parse).filter(|t| t.is_latin());
c.font_ascii_theme = latin("w:asciiTheme");
c.font_hansi_theme = latin("w:hAnsiTheme");
}
}
"w:b" => c.bold = Some(on_off(k)),
"w:bCs" => c.bold_cs = Some(on_off(k)),
@@ -530,26 +542,45 @@ fn shd_fill(e: &El) -> Option<Rgb> {
}
impl PropCtx {
/// One border (`CT_Border`); its theme colour supersedes `w:color`, as for text.
/// One border (`CT_Border`); its theme colour supersedes `w:color`, as for text. One without
/// `w:sz` is width 0, as `w:sz="0"`: Word draws both at its thinnest line and gives them no
/// room, for paragraph, character and page borders (storytold/wordcraft#5065).
pub fn border(&self, e: &El) -> Border {
self.border_or(e, 0.0)
}
/// One border, `missing` points wide when it gives no `w:sz`.
fn border_or(&self, e: &El, missing: f32) -> Border {
let style = BorderStyle::from_ooxml(e.attr("w:val").unwrap_or("single"));
let width = e.attr("w:sz").and_then(|v| measure(v, 8.0)).unwrap_or(0.5).clamp(0.0, 12.0);
let width = e.attr("w:sz").and_then(|v| measure(v, 8.0)).unwrap_or(missing).clamp(0.0, 12.0);
let color = self.theme_color(e, "w:themeColor", "w:themeTint", "w:themeShade").or_else(|| e.attr("w:color").and_then(Rgb::parse));
let space = e.attr("w:space").and_then(|v| measure(v, 1.0)).unwrap_or(0.0).clamp(0.0, 31.0);
Border { style, width, color, space }
}
/// `w:pBdr`, `w:tblBorders`, `w:tcBorders`, `w:pgBorders`.
/// `w:pBdr`, `w:pgBorders`.
pub fn borders(&self, e: &El) -> Borders {
self.borders_or(e, 0.0)
}
/// `w:tblBorders`, `w:tcBorders`, and a table style's. A border without `w:sz` is width 0 here
/// too, as `w:sz="0"`: Word gives neither any room, where `w:sz="1"` takes an eighth of a
/// point (storytold/wordcraft#5764). Read as half a point, every row below a pandoc table's
/// header rule moved down half a point.
pub fn table_borders(&self, e: &El) -> Borders {
self.borders_or(e, 0.0)
}
fn borders_or(&self, e: &El, missing: f32) -> Borders {
let mut b = Borders::default();
for k in e.els() {
match k.local() {
"top" => b.top = Some(self.border(k)),
"left" | "start" => b.left = Some(self.border(k)),
"bottom" => b.bottom = Some(self.border(k)),
"right" | "end" => b.right = Some(self.border(k)),
"between" | "insideH" => b.between = Some(self.border(k)),
"insideV" => b.inside_v = Some(self.border(k)),
"top" => b.top = Some(self.border_or(k, missing)),
"left" | "start" => b.left = Some(self.border_or(k, missing)),
"bottom" => b.bottom = Some(self.border_or(k, missing)),
"right" | "end" => b.right = Some(self.border_or(k, missing)),
"between" | "insideH" => b.between = Some(self.border_or(k, missing)),
"insideV" => b.inside_v = Some(self.border_or(k, missing)),
_ => {}
}
}
@@ -599,7 +630,7 @@ impl PropCtx {
}
"w:jc" => t.align = k.attr("w:val").map(align),
"w:tblInd" => t.indent = tw(k, "w:w"),
"w:tblBorders" => t.borders = Some(self.borders(k)),
"w:tblBorders" => t.borders = Some(self.table_borders(k)),
"w:shd" => t.shading = self.shd_fill(k),
"w:tblLayout" => t.fixed = k.attr("w:type") == Some("fixed"),
"w:bidiVisual" => t.bidi_visual = on_off(k),
@@ -705,7 +736,7 @@ pub fn tcpr(pc: &PropCtx, e: &El) -> (CellProps, bool) {
"w:gridSpan" => c.span = k.attr("w:val").and_then(u32_of).unwrap_or(1).clamp(1, 63),
"w:hMerge" => hcont = k.attr("w:val") != Some("restart"),
"w:vMerge" => c.vmerge = if k.attr("w:val") == Some("restart") { VMerge::Restart } else { VMerge::Continue },
"w:tcBorders" => c.borders = Some(pc.borders(k)),
"w:tcBorders" => c.borders = Some(pc.table_borders(k)),
"w:shd" => c.shading = pc.shd_fill(k),
"w:noWrap" => c.no_wrap = on_off(k),
"w:hideMark" => c.hide_mark = on_off(k),
+2 -2
View File
@@ -26,7 +26,7 @@ impl Reader<'_> {
let source = self.keep_embedded(c.child("a:graphic")?, rels, &[])?;
float.set_spin(xfrm_spin(content.child("w14:xfrm")));
float.bare_turn = !anchored && float.rot != 0.0 && float.effect == [0.0; 4];
let (px, py) = float.spin_pad(w, h);
let (px, py) = float.effect_spin_pad(w, h);
for (e, p) in float.effect.iter_mut().zip([px, py, px, py]) {
if *e != 0.0 {
*e = (*e - p).clamp(0.0, 1584.0);
@@ -100,7 +100,7 @@ impl Reader<'_> {
if let Some(f) = obj.float_mut() {
// None recorded: Word keeps an inline one's line to the frame (see `Float::bare_turn`).
f.bare_turn = !anchored && !fx_room && f.rot != 0.0 && f.effect == [0.0; 4];
let (px, py) = f.spin_pad(w, h);
let (px, py) = f.effect_spin_pad(w, h);
for (e, p) in f.effect.iter_mut().zip([px, py, px, py]) {
// Zero adds no effects room when rotation contracts this axis.
if *e != 0.0 {
+26 -15
View File
@@ -151,20 +151,24 @@ impl Reader<'_> {
let type_id = shape.attr("type").map(|t| t.trim().trim_start_matches('#'));
let shapetype = type_id.and_then(|id| pict.els().find(|e| e.name == "v:shapetype" && e.attr("id") == Some(id)));
let attr = |name: &str| shape.attr(name).or_else(|| shapetype.and_then(|t| t.attr(name)));
let on = |name: &str| {
attr(name).is_none_or(|v| {
let t = v.trim();
!t.eq_ignore_ascii_case("f") && !t.eq_ignore_ascii_case("false") && t != "0"
})
};
let stroke = on("stroked").then(|| attr("strokecolor").map_or(Some(Rgb::BLACK), vml_color)).flatten();
// A `v:stroke` switches the outline on or off (`on`), colours it (`color`) and can make it
// fully transparent (`opacity`), as Google Docs writes its invisible horizontal rules
// (ECMA-376 Part 4 §19.1.2.21). Word resolves each of these per property: the shape's own
// `v:stroke`, then the shape's attribute (`stroked`, `strokecolor`), then the same two on
// its shapetype. Freeforms keep the stroke's opacity themselves (below).
let stroke_prop = |name: &str, shape_attr: Option<&str>| vml_stroke_prop(shape, shapetype, name, shape_attr);
let enabled = stroke_prop("on", Some("stroked")).is_none_or(|v| {
let t = v.trim();
!(t.eq_ignore_ascii_case("f") || t.eq_ignore_ascii_case("false") || t == "0")
});
let freeform_stroke = enabled.then(|| stroke_prop("color", Some("strokecolor")).map_or(Some(Rgb::BLACK), vml_color)).flatten();
let stroke_opacity = stroke_prop("opacity", None).and_then(vml_opacity).unwrap_or(1.0);
// A fully transparent outline is kept as a shape without one, as Word keeps it.
let transparent = stroke_opacity == 0.0;
let stroke = freeform_stroke.filter(|_| !transparent);
let stroke_width = attr("strokeweight").and_then(|v| measure(v, 1.0)).unwrap_or(0.75).clamp(0.0, 100.0);
let fill = vml_fill(shape, shapetype);
let endcap = shape
.child("v:stroke")
.and_then(|s| s.attr("endcap"))
.or_else(|| shapetype.and_then(|t| t.child("v:stroke")).and_then(|s| s.attr("endcap")));
let cap = match endcap {
let cap = match stroke_prop("endcap", None) {
Some("square") => craft_wordmodel::connector::LineCap::Square,
Some("round") => craft_wordmodel::connector::LineCap::Round,
_ => craft_wordmodel::connector::LineCap::Flat,
@@ -292,12 +296,12 @@ impl Reader<'_> {
{
let opacity = |el: &str| shape.child(el).and_then(|e| e.attr("opacity")).and_then(vml_opacity).unwrap_or(1.0);
let fill = fill.filter(|_| !vp.no_fill && opacity("v:fill") > 0.0);
let stroke = stroke.filter(|_| !vp.no_stroke);
let stroke = freeform_stroke.filter(|_| !vp.no_stroke);
if stroke.is_none() && fill.is_none() {
return None;
}
let mut f = vp.freeform;
f.alpha = opacity("v:stroke");
f.alpha = stroke_opacity;
return Some(InlineObject::Shape {
kind: ShapeKind::Freeform,
w,
@@ -369,7 +373,7 @@ impl Reader<'_> {
float.flip_h ^= x1 < x0;
float.flip_v ^= y1 < y0;
}
if stroke.is_none() && (fill.is_none() || kind == ShapeKind::Line) {
if stroke.is_none() && !transparent && (fill.is_none() || kind == ShapeKind::Line) {
return None;
}
Some(InlineObject::Shape {
@@ -663,6 +667,13 @@ fn vml_opacity(v: &str) -> Option<f32> {
vml_fraction(v).map(|f| f.clamp(0.0, 1.0))
}
/// One stroke property as Word resolves it: the shape's own `v:stroke` attribute `name`, then the
/// shape's attribute `shape_attr` (`stroked`, `strokecolor`), then the same two on its shapetype.
fn vml_stroke_prop<'a>(shape: &'a El, shapetype: Option<&'a El>, name: &str, shape_attr: Option<&str>) -> Option<&'a str> {
let level = move |e: &'a El| e.child("v:stroke").and_then(|s| s.attr(name)).or_else(move || shape_attr.and_then(|a| e.attr(a)));
level(shape).or_else(|| shapetype.and_then(level))
}
/// A VML shape's turn: `rotation` in degrees, or 65536ths of one with an `fd` suffix; `flip`: `x`
/// and/or `y`.
fn vml_spin(style: &str) -> craft_wordmodel::geom::Spin {
+12 -3
View File
@@ -279,10 +279,19 @@ impl Reader<'_> {
let mut t = TableStyleParts::default();
if let Some(tp) = s.child("w:tblPr") {
if let Some(b) = tp.child("w:tblBorders") {
t.borders = Some(self.pc.borders(b));
t.borders = Some(self.pc.table_borders(b));
}
t.fill = tp.child("w:shd").and_then(|e| self.pc.shd_fill(e));
t.cell_margins = tp.child("w:tblCellMar").map(props::margins);
// Only a twips indent (`dxa`, the default) is a length: `nil` is no indent, and `pct`
// or `auto` have no meaning for an indent (ECMA-376 §17.4.50), so the style sets none.
// A `w:w` left out is 0 (`CT_TblWidth`), which still overrides a based-on style's.
t.indent = tp.child("w:tblInd").and_then(|e| match e.attr("w:type").unwrap_or("dxa") {
"dxa" if e.attr("w:w").is_none() => Some(0.0),
"dxa" => tw(e, "w:w").map(|i| i.clamp(-1584.0, 1584.0)),
"nil" => Some(0.0),
_ => None,
});
t.band_size = tp.child_val("w:tblStyleRowBandSize").and_then(u32_of).map(|n| n.min(1000));
t.col_band_size = tp.child_val("w:tblStyleColBandSize").and_then(u32_of).map(|n| n.min(1000));
}
@@ -293,7 +302,7 @@ impl Reader<'_> {
let f = PartFormat {
chr: c.child("w:rPr").map(|r| self.pc.rpr(r)).unwrap_or_default(),
fill: tc.and_then(|p| p.child("w:shd")).and_then(|e| self.pc.shd_fill(e)),
borders: tc.and_then(|p| p.child("w:tcBorders")).map(|b| self.pc.borders(b)),
borders: tc.and_then(|p| p.child("w:tcBorders")).map(|b| self.pc.table_borders(b)),
align: ppr.as_ref().and_then(|p| p.align),
v_align: tc.and_then(|p| p.child_val("w:vAlign")).map(|v| match v {
"center" => VAlign::Center,
@@ -312,7 +321,7 @@ impl Reader<'_> {
t.fill = f.fill;
}
if let Some(b) = c.child("w:tblPr").and_then(|p| p.child("w:tblBorders")) {
t.borders = Some(self.pc.borders(b));
t.borders = Some(self.pc.table_borders(b));
}
if f.v_align.is_some() {
t.regions.insert(part, PartFormat { v_align: f.v_align, ..PartFormat::default() });
+2 -2
View File
@@ -530,9 +530,9 @@ impl super::Writer<'_> {
}
}
"wp:effectExtent" => {
// Word's effect extent also covers a rotated object's overhang (its rotated bounds),
// Word's effect extent also covers a rotated object's overhang (`Float::effect_spin_pad`),
// unless the file it came from kept none.
let (px, py) = if float.is_bare_turn() { (0.0, 0.0) } else { float.spin_pad(w, h) };
let (px, py) = if float.is_bare_turn() { (0.0, 0.0) } else { float.effect_spin_pad(w, h) };
let [el, et, er, eb] = float.effect_extent();
let ext = [el + px, et + py, er + px, eb + py].map(emu);
e.attrs.retain(|(k, _)| !matches!(k.as_str(), "l" | "t" | "r" | "b"));
+2
View File
@@ -12,6 +12,8 @@ use crate::package::FONT_TABLE_PART;
/// The parts of the package [`write_as`] zips, in order, `[Content_Types].xml` first: (part name
/// without the leading `/`, bytes).
pub(crate) fn write_parts(doc: &Document, flavor: Flavor) -> Result<Vec<(String, Vec<u8>)>, DocxError> {
// Theme font slots are written while they name the run's font in this theme.
let _theme_fonts = super::props::ThemeFontsGuard::set(&doc.settings.major_font, &doc.settings.minor_font);
// A range field must be whole in the file: drop markers that lost their partner in editing.
let balanced;
let doc = if doc.has_unbalanced_field_ranges() {
+58 -7
View File
@@ -2,12 +2,46 @@
use craft_wordmodel::props::{
Align, Border, BorderStyle, Borders, CellProps, CharProps, EastAsianLayout, HeightRule, Highlight, Kashida, LineSpacing, ParaProps, RowProps,
TabAlign, TabLeader, TableFloat, TableLook, TableProps, TextColor, VAlign, VMerge, VertAlign,
TabAlign, TabLeader, TableFloat, TableLook, TableProps, TextColor, ThemeFont, VAlign, VMerge, VertAlign,
};
use crate::units::{n, twips};
use crate::xml::W;
thread_local! {
/// The theme's (major, minor) Latin fonts of the document being saved, for [`latin_slot`].
static THEME_FONTS: std::cell::RefCell<Option<(String, String)>> = const { std::cell::RefCell::new(None) };
}
/// Holds the document's theme fonts while a package is written; restores the previous ones on
/// drop (a nested write, as for an embedded document, gets its own).
pub(crate) struct ThemeFontsGuard(Option<(String, String)>);
impl ThemeFontsGuard {
pub(crate) fn set(major: &str, minor: &str) -> ThemeFontsGuard {
ThemeFontsGuard(THEME_FONTS.with(|t| t.replace(Some((major.to_string(), minor.to_string())))))
}
}
impl Drop for ThemeFontsGuard {
fn drop(&mut self) {
let prev = self.0.take();
THEME_FONTS.with(|t| *t.borrow_mut() = prev);
}
}
/// A Latin theme slot worth writing: it names `font` in the theme being saved. Otherwise (the
/// font was changed, or the theme was, or no theme is known) it is left out, so Word shows
/// `font` as WordCraft does.
fn latin_slot(slot: Option<ThemeFont>, font: Option<&String>) -> Option<&'static str> {
let (slot, font) = (slot?, font?);
let names = |(major, minor): &(String, String)| {
let named = if slot.is_major() { major } else { minor };
!named.is_empty() && named.eq_ignore_ascii_case(font)
};
THEME_FONTS.with(|t| t.borrow().as_ref().is_some_and(names)).then_some(slot.as_str())
}
fn toggle(w: &mut W, name: &str, v: Option<bool>) {
match v {
Some(true) => w.empty(name, &[]),
@@ -21,12 +55,8 @@ fn round(v: f32) -> i64 {
v.round().clamp(-1e9, 1e9) as i64
}
/// `w:rPr` content (without the wrapper). Link and revision marks are not run properties.
pub fn rpr_inner(w: &mut W, c: &CharProps) {
if let Some(s) = &c.style {
w.val("w:rStyle", s);
}
// Emit only explicit properties so absent values keep inheriting from the style chain.
/// `w:rFonts`: the named fonts, then the theme slots still worth writing.
fn rfonts(w: &mut W, c: &CharProps) {
let mut fonts: Vec<(&str, &str)> = Vec::new();
if let Some(f) = &c.font {
fonts.extend([("w:ascii", f.as_str()), ("w:hAnsi", f.as_str())]);
@@ -37,9 +67,30 @@ pub fn rpr_inner(w: &mut W, c: &CharProps) {
if let Some(cs) = &c.font_cs {
fonts.push(("w:cs", cs));
}
if let Some(t) = latin_slot(c.font_ascii_theme, c.font.as_ref()) {
fonts.push(("w:asciiTheme", t));
}
if let Some(t) = latin_slot(c.font_hansi_theme, c.font.as_ref()) {
fonts.push(("w:hAnsiTheme", t));
}
if let Some(t) = c.font_ea_theme {
fonts.push(("w:eastAsiaTheme", t.as_str()));
}
if let Some(t) = c.font_cs_theme {
fonts.push(("w:cstheme", t.as_str()));
}
if !fonts.is_empty() {
w.empty("w:rFonts", &fonts);
}
}
/// `w:rPr` content (without the wrapper). Link and revision marks are not run properties.
pub fn rpr_inner(w: &mut W, c: &CharProps) {
if let Some(s) = &c.style {
w.val("w:rStyle", s);
}
// Emit only explicit properties so absent values keep inheriting from the style chain.
rfonts(w, c);
toggle(w, "w:b", c.bold);
toggle(w, "w:bCs", c.bold_cs);
toggle(w, "w:i", c.italic);
+17 -3
View File
@@ -245,11 +245,25 @@ pub(super) fn theme_xml(doc: &Document) -> Vec<u8> {
}
w.close("a:clrScheme");
w.open("a:fontScheme", &[("name", name)]);
for (tag, face) in [("a:majorFont", &s.major_font), ("a:minorFont", &s.minor_font)] {
// The file's own East Asian, complex-script and per-script fonts, as read
// (`package::THEME_FONTS`): the theme slots a save keeps resolve through them in Word.
let kept = doc.passthrough.get(crate::package::THEME_FONTS).map(|b| String::from_utf8_lossy(b).into_owned()).unwrap_or_default();
let kept: Vec<[&str; 4]> = kept
.lines()
.filter_map(|l| {
let mut it = l.splitn(4, '\t');
Some([it.next()?, it.next()?, it.next()?, it.next()?])
})
.collect();
for (key, tag, face) in [("major", "a:majorFont", &s.major_font), ("minor", "a:minorFont", &s.minor_font)] {
let of = |which: &str| kept.iter().find(|[k, kind, w, _]| *k == key && *kind == "face" && *w == which).map_or("", |[.., f]| *f);
w.open(tag, &[]);
w.empty("a:latin", &[("typeface", face)]);
w.empty("a:ea", &[("typeface", "")]);
w.empty("a:cs", &[("typeface", "")]);
w.empty("a:ea", &[("typeface", of("ea"))]);
w.empty("a:cs", &[("typeface", of("cs"))]);
for [_, _, script, f] in kept.iter().filter(|[k, kind, ..]| *k == key && *kind == "script") {
w.empty("a:font", &[("script", script), ("typeface", f)]);
}
w.close(tag);
}
w.close("a:fontScheme");
+2 -2
View File
@@ -328,9 +328,9 @@ impl Writer<'_> {
}
}
w.empty("wp:extent", &[("cx", &cx), ("cy", &cy)]);
// Word's effect extent also covers a rotated object's overhang (its rotated bounds), unless
// Word's effect extent also covers a rotated object's overhang (`Float::effect_spin_pad`), unless
// the file it came from kept none.
let (px, py) = if float.is_bare_turn() { (0.0, 0.0) } else { float.spin_pad(iw, ih) };
let (px, py) = if float.is_bare_turn() { (0.0, 0.0) } else { float.effect_spin_pad(iw, ih) };
let [el, et, er, eb] = float.effect_extent();
let [el, et, er, eb] = [el + px, et + py, er + px, eb + py].map(emu);
w.empty("wp:effectExtent", &[("l", &el), ("t", &et), ("r", &er), ("b", &eb)]);
+27 -16
View File
@@ -1,6 +1,7 @@
use super::{Level, LevelSuffix, ParaProps, Style, StyleKind, TablePart, VAlign, W, Writer, props, xml};
use crate::write::props::open_change;
use craft_wordmodel::Document;
use craft_wordmodel::styles::TableStyleParts;
/// Built-in names Word keeps in lower case in styles.xml.
fn file_style_name(name: &str) -> String {
@@ -61,6 +62,31 @@ pub(super) fn styles_xml(wr: &mut Writer<'_>) -> Vec<u8> {
/// One `w:style` element. A tracked change of its paragraph/run properties is nested in the
/// corresponding property element as `w:pPrChange` / `w:rPrChange`.
/// A table style's own table properties (`w:tblPr`), in ECMA-376 order.
fn table_style_tblpr(w: &mut W, t: &TableStyleParts) {
if t.borders.is_none() && t.cell_margins.is_none() && t.indent.is_none() && t.band_size.is_none() && t.col_band_size.is_none() {
return;
}
w.open("w:tblPr", &[]);
if let Some(n) = t.band_size {
w.val("w:tblStyleRowBandSize", &n.min(1000).to_string());
}
if let Some(n) = t.col_band_size {
w.val("w:tblStyleColBandSize", &n.min(1000).to_string());
}
// Kept even at 0: Word places a table whose style chain sets no indent differently.
if let Some(i) = t.indent {
w.empty("w:tblInd", &[("w:w", &crate::units::twips(i)), ("w:type", "dxa")]);
}
if let Some(b) = &t.borders {
props::borders(w, "w:tblBorders", b, Some("w:insideH"), &[]);
}
if let Some(m) = &t.cell_margins {
props::margins(w, "w:tblCellMar", m);
}
w.close("w:tblPr");
}
fn style_xml(wr: &mut Writer<'_>, w: &mut W, st: &Style, flagged: &[StyleKind]) {
let ty = match st.kind {
StyleKind::Paragraph => "paragraph",
@@ -114,22 +140,7 @@ fn style_xml(wr: &mut Writer<'_>, w: &mut W, st: &Style, flagged: &[StyleKind])
}
style_property_xml(wr, w, st);
if let Some(t) = &st.table {
if t.borders.is_some() || t.cell_margins.is_some() || t.band_size.is_some() || t.col_band_size.is_some() {
w.open("w:tblPr", &[]);
if let Some(n) = t.band_size {
w.val("w:tblStyleRowBandSize", &n.min(1000).to_string());
}
if let Some(n) = t.col_band_size {
w.val("w:tblStyleColBandSize", &n.min(1000).to_string());
}
if let Some(b) = &t.borders {
props::borders(w, "w:tblBorders", b, Some("w:insideH"), &[]);
}
if let Some(m) = &t.cell_margins {
props::margins(w, "w:tblCellMar", m);
}
w.close("w:tblPr");
}
table_style_tblpr(w, t);
// The conditional formatting parts (ECMA-376 §17.7.6): paragraph and run properties,
// then cell borders, shading and vertical alignment. The whole table's text formatting
// is the style's own (above).
+47 -18
View File
@@ -10,6 +10,10 @@ use crate::DocxError;
pub const MAX_DEPTH: usize = 256;
/// Maximum number of elements in one part.
pub const MAX_ELEMENTS: usize = 8_000_000;
/// Maximum number of elements summed over every part a read parses: a file of many parts each
/// inside [`MAX_ELEMENTS`] would otherwise cost a tree per part, and the trees a reader keeps
/// (the main part's, charts' and diagrams') accumulate.
pub const MAX_ELEMENTS_TOTAL: usize = MAX_ELEMENTS * 2;
/// Maximum number of attributes on one element (#3702).
pub const MAX_ATTRS: usize = 1024;
@@ -329,19 +333,31 @@ pub fn parse(bytes: &[u8]) -> Result<El, DocxError> {
parse_ns(bytes, &[])
}
/// [`parse`], with the number of elements it built, stopping early at `max` elements: the caller
/// charges the count against a package-wide budget (see [`MAX_ELEMENTS_TOTAL`]), and a part over
/// what is left of it is refused before the whole per-part tree is built.
pub fn parse_counted(bytes: &[u8], max: usize) -> Result<(El, usize), DocxError> {
parse_with(bytes, &[], false, max)
}
/// [`parse_counted`], strict, for a part whose loss would be silent data loss (the main
/// document): a mismatched end tag or an element left open at the end of the data is an error,
/// not a cue to stop reading.
pub fn parse_strict_counted(bytes: &[u8], max: usize) -> Result<(El, usize), DocxError> {
parse_with(bytes, &[], true, max)
}
/// [`parse`] with `extra` namespaces (prefix, URI) mapped to canonical prefixes first, so a
/// related vocabulary (WordprocessingML 2003) reads with the prefixes the reader knows.
pub fn parse_ns(bytes: &[u8], extra: &[(&'static str, &str)]) -> Result<El, DocxError> {
parse_with(bytes, extra, false)
parse_with(bytes, extra, false, MAX_ELEMENTS).map(|(e, _)| e)
}
/// [`parse`] for a part whose loss would be silent data loss (the main document): a mismatched end
/// tag or an element left open at the end of the data is an error, not a cue to stop reading.
pub fn parse_strict(bytes: &[u8]) -> Result<El, DocxError> {
parse_with(bytes, &[], true)
}
fn parse_with(bytes: &[u8], extra: &[(&'static str, &str)], strict: bool) -> Result<El, DocxError> {
/// The XML parser everything else goes through: transcodes UTF-16, walks the events and builds
/// the tree depth-first, stopping at `max` elements and counting the ones it built. A mismatched
/// end tag or an element left open at the end of the data is an error when `strict`, a cue to
/// stop reading when not.
fn parse_with(bytes: &[u8], extra: &[(&'static str, &str)], strict: bool, max: usize) -> Result<(El, usize), DocxError> {
let namespaces: Vec<(&str, &str)> =
extra.iter().copied().chain(NAMESPACES.iter().copied()).chain(OTHER_NAMESPACES.iter().copied()).chain(STRICT.iter().copied()).collect();
// The prefix of an element: its namespace's, with two exceptions for Strict documents
@@ -375,7 +391,9 @@ fn parse_with(bytes: &[u8], extra: &[(&'static str, &str)], strict: bool) -> Res
max_depth: MAX_DEPTH + 1,
// Text stretches count as nodes too: two for each element.
max_nodes: 2 * MAX_ELEMENTS,
max_elements: MAX_ELEMENTS,
// The parse stops here before the whole tree is built: a part over what is left of the
// package's element budget pays for at most that, not for the per-part cap.
max_elements: max,
max_attrs: MAX_ATTRS,
max_attrs_total: 2 * MAX_ELEMENTS,
};
@@ -383,17 +401,27 @@ fn parse_with(bytes: &[u8], extra: &[(&'static str, &str)], strict: bool) -> Res
if strict {
options = options.strict();
}
let root = options.parse(bytes).map_err(|e| if e.is_limit() { DocxError::Limit(e.to_string()) } else { DocxError::Xml(e.to_string()) })?;
Ok(from_tree(root))
let root = options.parse(bytes).map_err(|e| match &e {
craft_xml::Error::TooManyElements(_) => DocxError::Limit(format!("over the XML element budget for this parse: at most {max} elements")),
e if e.is_limit() => DocxError::Limit(e.to_string()),
e => DocxError::Xml(e.to_string()),
})?;
Ok(from_tree_counted(root))
}
/// The `craft-xml` tree as this module's (whose shape the reader was written against).
/// The `craft-xml` tree as this module's (whose shape the reader was written against), with the
/// number of elements the subtree holds (the caller charges it against a package-wide budget).
// shortcut: one copy of each parsed part; read craft_xml::El directly when the reader is ported to it.
fn from_tree(e: craft_xml::El) -> El {
fn from_tree_counted(e: craft_xml::El) -> (El, usize) {
let mut kids = Vec::with_capacity(e.children.len());
let mut count = 1usize;
for n in e.children {
match n {
craft_xml::Node::El(c) => kids.push(Node::El(from_tree(c))),
craft_xml::Node::El(c) => {
let (kid, built) = from_tree_counted(c);
count += built;
kids.push(Node::El(kid));
}
craft_xml::Node::Text(t) | craft_xml::Node::CData(t) => match kids.last_mut() {
Some(Node::Text(prev)) => prev.push_str(&t),
_ => kids.push(Node::Text(t)),
@@ -401,7 +429,7 @@ fn from_tree(e: craft_xml::El) -> El {
craft_xml::Node::Pi { .. } | craft_xml::Node::Comment(_) => {}
}
}
El { name: e.name, attrs: e.attrs, kids }
(El { name: e.name, attrs: e.attrs, kids }, count)
}
/// This module's tree as `craft-xml`'s, for the shared readers (`craft-drawingml`, `craft-math`)
@@ -515,12 +543,13 @@ mod tests {
fn strict_parsing_rejects_a_dropped_entity_and_trailing_markup() {
let bad = [&b"<w:t>before &unknown; after</w:t>"[..], b"<a></a><b></b>", b"<a></a><b>"];
for xml in bad {
assert!(parse_strict(xml).is_err(), "{}", String::from_utf8_lossy(xml));
assert!(parse_strict_counted(xml, MAX_ELEMENTS).is_err(), "{}", String::from_utf8_lossy(xml));
}
assert!(
parse_strict(
parse_strict_counted(
b"<a>x &amp; y</a>
"
",
MAX_ELEMENTS
)
.is_ok()
);
+44
View File
@@ -0,0 +1,44 @@
//! The package-wide XML element budget: a file of many parts each inside the per-part
//! cap reads bounded, where every part used to build its own tree and the trees the
//! reader keeps accumulated.
use crate::fixtures;
use craft_docx::read;
const W_NS: &str = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships""#;
#[test]
fn a_file_of_element_budget_parts_still_reads() {
// Nine chart parts of 2M elements each: 18M over the package's 16M budget. The later
// parts are skipped with a warning instead of built, and the file still reads. Before
// the budget, every part's whole tree was parsed and the chart trees stayed cached for
// the whole read (~230 MB per 2M-element part, measured), so a file like this cost one
// tree per part and scales linearly with the part count.
let parts = 9usize;
let chunk = "<a/>".repeat(2_000_000);
let chart_xml = format!(r#"<c:chart {W_NS}>{chunk}</c:chart>"#);
let mut document = format!(
r#"<w:document {W_NS} xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:c="http://schemas.openxmlformats.org/drawingml/2006/chart"><w:body>"#
);
for i in 0..parts {
document.push_str(&format!(
r#"<w:p><w:r><w:drawing><wp:inline><wp:extent cx="635000" cy="635000"/><a:graphic><a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/chart"><c:chart r:id="rId{i}"/></a:graphicData></a:graphic></wp:inline></w:drawing></w:r></w:p>"#
));
}
document.push_str("</w:body></w:document>");
let mut rels = String::from(r#"<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">"#);
for i in 0..parts {
rels.push_str(&format!(
r#"<Relationship Id="rId{i}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart" Target="charts/chart{i}.xml"/>"#
));
}
rels.push_str("</Relationships>");
let mut entries: Vec<(&str, Vec<u8>)> = vec![("word/document.xml", document.into_bytes()), ("word/_rels/document.xml.rels", rels.into_bytes())];
for i in 0..parts {
entries.push((Box::leak(format!("word/charts/chart{i}.xml").into_boxed_str()), chart_xml.clone().into_bytes()));
}
let refs: Vec<(&str, &[u8])> = entries.iter().map(|(n, b)| (*n, b.as_slice())).collect();
let z = fixtures::zip(&refs);
let doc = read(&z).expect("a file over the element budget still reads, the extra parts skipped");
assert_eq!(doc.body.len(), parts, "the document's own paragraphs read");
}
+207 -5
View File
@@ -4,7 +4,7 @@ use std::io::Write;
use std::sync::Arc;
use craft_wordmodel::fill::Fill;
use craft_wordmodel::para::{Anchor, FloatAlign, NoteKind, ShapeKind, Wrap};
use craft_wordmodel::para::{Anchor, Float, FloatAlign, NoteKind, ShapeKind, Wrap};
use craft_wordmodel::props::{Align, Border, BorderStyle, Rgb, TextColor, Underline, VMerge};
use craft_wordmodel::{Block, Document, InlineObject, Paragraph, RevisionKind};
@@ -1241,6 +1241,75 @@ fn char_border_reads_and_nil_resolves_off() {
assert_eq!(d.styles.resolve_char(None, nil).border, None);
}
/// storytold/wordcraft#5065: a paragraph, character or page border without `w:sz` is width 0, as
/// `w:sz="0"` (Word draws both at its thinnest line and gives them no room), and saving writes
/// `w:sz="0"`. Table and cell borders are read on their own (`PropCtx::table_borders`).
#[test]
fn a_border_without_a_size_is_width_0() {
let body = |sz: &str| {
let b = |side: &str| format!(r#"<w:{side} w:val="single"{sz}/>"#);
format!(
r#"<w:p><w:pPr><w:pBdr>{}</w:pBdr></w:pPr><w:r><w:rPr><w:bdr w:val="single"{sz}/></w:rPr><w:t>a</w:t></w:r></w:p><w:sectPr><w:pgBorders>{}</w:pgBorders></w:sectPr>"#,
b("bottom"),
b("left")
)
};
// Paragraph, character and page border widths.
let widths = |d: &Document| {
let p = paras(d)[0];
[
p.props.borders.and_then(|b| b.bottom).map(|b| b.width),
p.props_of_char(0).border.map(|b| b.width),
d.last_section.page_borders.and_then(|b| b.left).map(|b| b.width),
]
};
for (sz, width) in [("", 0.0), (r#" w:sz="0""#, 0.0), (r#" w:sz="1""#, 0.125), (r#" w:sz="2""#, 0.25), (r#" w:sz="4""#, 0.5)] {
assert_eq!(widths(&read_body(&body(sz))), [Some(width); 3], "{sz:?}");
}
// A width-0 border is still a border: it resolves, to be drawn.
let d = read_body(&body(""));
let p = paras(&d)[0];
assert!(d.styles.resolve_para(&p.props).borders.and_then(|b| b.bottom).is_some());
assert!(d.styles.resolve_char(None, p.props_of_char(0)).border.is_some());
let saved = craft_docx::write(&d).unwrap();
let xml = text(&unzip(&saved), "word/document.xml");
assert!(xml.contains(r#"w:val="single" w:sz="0""#) && !xml.contains(r#"w:sz="1""#), "{xml}");
assert_eq!(widths(&craft_docx::read(&saved).unwrap()), [Some(0.0); 3]);
}
/// storytold/wordcraft#5764: a table, cell or table-style border without `w:sz` is width 0 too, as
/// `w:sz="0"`. Word gives neither any room (`w:sz="1"` takes an eighth of a point), so read as half
/// a point it moved every row below a pandoc table's header rule. Saving writes `w:sz="0"`.
#[test]
fn a_table_border_without_a_size_is_width_0() {
let styles = format!(
r#"<w:styles {W_NS}><w:style w:type="table" w:styleId="Ruled"><w:name w:val="Ruled"/><w:tblPr><w:tblBorders><w:top w:val="single"/></w:tblBorders></w:tblPr><w:tblStylePr w:type="firstRow"><w:tcPr><w:tcBorders><w:bottom w:val="single"/></w:tcBorders></w:tcPr></w:tblStylePr></w:style></w:styles>"#
);
let body = r#"<w:tbl><w:tblPr><w:tblStyle w:val="Ruled"/><w:tblBorders><w:bottom w:val="single"/></w:tblBorders><w:tblLook w:firstRow="1" w:val="0020"/></w:tblPr><w:tblGrid><w:gridCol w:w="2400"/></w:tblGrid><w:tr><w:tc><w:tcPr><w:tcBorders><w:left w:val="single"/></w:tcBorders></w:tcPr><w:p/></w:tc></w:tr></w:tbl><w:p/>"#;
let widths = |d: &Document| {
let t = d.body.iter().find_map(|b| b.as_table()).expect("a table");
let parts = d.styles.get("Ruled").and_then(|s| s.table.clone()).expect("the style's parts");
[
t.props.borders.and_then(|b| b.bottom).map(|b| b.width),
t.rows[0].cells[0].props.borders.and_then(|b| b.left).map(|b| b.width),
parts.borders.and_then(|b| b.top).map(|b| b.width),
parts.header_borders.and_then(|b| b.bottom).map(|b| b.width),
]
};
let d = craft_docx::read(&docx(body, &[("rId1", "styles", "styles.xml")], &[("word/styles.xml", &styles)])).unwrap();
assert_eq!(widths(&d), [Some(0.0); 4]);
let rule = d.styles.get("Ruled").and_then(|s| s.table.clone()).and_then(|p| p.header_borders).and_then(|b| b.bottom).expect("the header rule");
assert!(rule.is_drawn() && !rule.is_visible(), "drawn, taking no room: {rule:?}");
let saved = craft_docx::write(&d).unwrap();
let parts = unzip(&saved);
let styles = text(&parts, "word/styles.xml");
let ruled = styles.split("<w:style ").find(|s| s.contains(r#"w:styleId="Ruled""#)).expect("the style is saved");
for xml in [text(&parts, "word/document.xml").as_str(), ruled] {
assert!(xml.contains(r#"w:val="single" w:sz="0""#) && !xml.contains(r#"w:sz="4""#), "{xml}");
}
assert_eq!(widths(&craft_docx::read(&saved).unwrap()), [Some(0.0); 4]);
}
#[test]
fn anchor_alignment_reference_areas_and_distances() {
let shape = |pos: &str, dist: &str| {
@@ -2189,9 +2258,10 @@ fn rotated_ole_objects_round_trip() {
let body = text(&unzip(&out), "word/document.xml");
assert_eq!(attr_values(&body, "a:xfrm", "rot"), ["5400000"]);
assert_eq!(attr_values(&body, "a:xfrm", "flipH"), ["1"]);
// 72 × 36 pt turned 90°: 18 pt narrower each side, 18 pt taller each side.
assert_eq!(attr_values(&body, "wp:effectExtent", "l"), ["-228600"]);
assert_eq!(attr_values(&body, "wp:effectExtent", "t"), ["228600"]);
// 72 × 36 pt turned 90°: Word measures that against the frame turned with it, so a quarter
// turn adds no effect extent.
assert_eq!(attr_values(&body, "wp:effectExtent", "l"), ["0"]);
assert_eq!(attr_values(&body, "wp:effectExtent", "t"), ["0"]);
let back = craft_docx::read(&out).unwrap();
let o = &paras(&back)[0].objects[0];
assert!(matches!(o, InlineObject::Image { ole: Some(_), .. }), "{o:?}");
@@ -2986,6 +3056,83 @@ fn arrowheads_keep_their_kind_and_size() {
assert_eq!(ends(&craft_docx::read(&bytes).unwrap()), expected);
}
/// A `v:stroke` that is switched off or fully transparent leaves the shape without an outline:
/// Google Docs writes its horizontal rules as such rectangles, which Word doesn't show. Its `on`
/// wins over the shape's `stroked`, in both directions, as in Word.
#[test]
fn vml_invisible_strokes_draw_no_outline() {
let red = Some(Rgb(0xC0, 0, 0));
for (attrs, stroke, want) in [
("", r##"<v:stroke color="#000000" filltype="solid" opacity="0" weight="1.0pt"/>"##, None),
("", r#"<v:stroke on="f"/>"#, None),
// A VML opacity can also be a percentage or 65536ths with an `f` suffix.
("", r#"<v:stroke opacity="0%"/>"#, None),
("", r#"<v:stroke opacity="0f"/>"#, None),
("", r#"<v:stroke opacity="50%"/>"#, Some(Rgb::BLACK)),
("", "", Some(Rgb::BLACK)),
(r##" stroked="t" strokecolor="#c00000""##, r#"<v:stroke on="f"/>"#, None),
(r##" stroked="f" strokecolor="#c00000""##, r#"<v:stroke on="t"/>"#, red),
// The stroke's own colour wins over the shape's `strokecolor`, as in Word.
(r##" strokecolor="#0000ff""##, r##"<v:stroke color="#c00000"/>"##, red),
(r##" stroked="f" strokecolor="#0000ff""##, r##"<v:stroke on="t" color="#c00000"/>"##, red),
] {
let body = format!(
r#"<w:p><w:r><w:pict><v:rect style="width:475.5pt;height:.05pt" alt="" o:hr="f" o:hrstd="t" o:hralign="center"{attrs}>{stroke}</v:rect></w:pict></w:r></w:p>"#
);
let d = read_body(&body);
let InlineObject::Shape { kind: ShapeKind::Rectangle, stroke: got, .. } = &paras(&d)[0].objects[0] else { panic!("{body}") };
assert_eq!(*got, want, "{body}");
let again = craft_docx::read(&craft_docx::write(&d).unwrap()).unwrap();
let InlineObject::Shape { stroke: saved, .. } = &paras(&again)[0].objects[0] else { panic!("{body}") };
assert_eq!(saved, got, "{body}");
}
// A freeform's outline is switched off the same way.
let freeform = r##"<w:p><w:r><w:pict><v:shape style="width:200pt;height:40pt" coordsize="200,40" path="m0,0l200,0,200,40,0,40xe" fillcolor="#ffffcc" strokecolor="#c00000"><v:stroke on="f"/></v:shape></w:pict></w:r></w:p>"##;
let d = read_body(freeform);
let InlineObject::Shape { kind: ShapeKind::Freeform, stroke, .. } = &paras(&d)[0].objects[0] else { panic!("{freeform}") };
assert_eq!(*stroke, None);
}
/// Word resolves each stroke property separately: the shape's own `v:stroke`, then the shape's
/// attribute, then the same two on its shapetype, so a shapetype's stroke switched off or made
/// transparent still applies to a shape whose own `v:stroke` only sets a dash (checked in Word).
#[test]
fn vml_stroke_properties_inherit_one_by_one() {
let green = Some(Rgb(0, 0x80, 0));
let blue = Some(Rgb(0, 0, 0xFF));
for (shapetype, shape, want) in [
(r#"<v:stroke on="f"/>"#, r##"strokecolor="#008000"><v:stroke dashstyle="dash"/>"##, None),
(r#"<v:stroke opacity="0"/>"#, r##"strokecolor="#008000"><v:stroke dashstyle="dash"/>"##, None),
(r#"<v:stroke on="f"/>"#, r##"stroked="t" strokecolor="#008000">"##, green),
(r##"<v:stroke color="#c00000"/>"##, r##"strokecolor="#0000ff">"##, blue),
] {
let body = format!(
r##"<w:p><w:r><w:pict><v:shapetype id="st" coordsize="21600,21600" o:spt="1" path="m,l,21600r21600,l21600,xe">{shapetype}</v:shapetype><v:shape type="#st" style="width:100pt;height:30pt" {shape}</v:shape></w:pict></w:r></w:p>"##
);
let d = read_body(&body);
let InlineObject::Shape { stroke, .. } = &paras(&d)[0].objects[0] else { panic!("{body}") };
assert_eq!(*stroke, want, "{body}");
}
// An inherited transparent stroke also clears a freeform's outline alpha.
let freeform = r##"<w:p><w:r><w:pict><v:shapetype id="st"><v:stroke opacity="0"/></v:shapetype><v:shape type="#st" style="width:200pt;height:40pt" coordsize="200,40" path="m0,0l200,0,200,40,0,40xe" fillcolor="#ffffcc"/></w:pict></w:r></w:p>"##;
let d = read_body(freeform);
let InlineObject::Shape { kind: ShapeKind::Freeform, freeform: Some(f), .. } = &paras(&d)[0].objects[0] else { panic!("{freeform}") };
assert_eq!(f.alpha, 0.0);
}
/// A line whose stroke is fully transparent stays in the document without an outline, as Word
/// keeps it, and is saved that way instead of being dropped.
#[test]
fn vml_transparent_line_is_kept() {
let body = r##"<w:p><w:r><w:pict><v:line from="0,0" to="200pt,0" strokecolor="#000000"><v:stroke opacity="0"/></v:line></w:pict></w:r></w:p>"##;
let d = read_body(body);
let InlineObject::Shape { kind: ShapeKind::Line, stroke: None, .. } = &paras(&d)[0].objects[0] else { panic!("{:?}", paras(&d)[0].objects) };
let again = craft_docx::read(&craft_docx::write(&d).unwrap()).unwrap();
let InlineObject::Shape { kind: ShapeKind::Line, stroke: None, .. } = &paras(&again)[0].objects[0] else {
panic!("{:?}", paras(&again)[0].objects)
};
}
/// The right arrow's shapetype as Word writes it (ECMA-376 Part 4 `v:shapetype`, `o:spt` 13).
const VML_RIGHT_ARROW_TYPE: &str = r#"<v:shapetype id="_x0000_t13" coordsize="21600,21600" o:spt="13" adj="16200,5400" path="m@0,l@0@1,0@1,0@2@0@2@0,21600,21600,10800xe"><v:stroke joinstyle="miter"/><v:formulas><v:f eqn="val #0"/><v:f eqn="val #1"/></v:formulas><v:path o:connecttype="custom"/></v:shapetype>"#;
@@ -3563,7 +3710,7 @@ fn native_ink_markup_limit_does_not_write_a_dangling_reference() {
fn native_ink_preserves_inner_transform_and_rotation_padding_on_unrelated_saves() {
let mut files = unzip(&ink_docx(false, false));
let body = text(&files, "word/document.xml")
.replace("<wp:docPr", r#"<wp:effectExtent l="55468" t="512668" r="55468" b="512668"/><wp:docPr"#)
.replace("<wp:docPr", r#"<wp:effectExtent l="512668" t="55468" r="512668" b="55468"/><wp:docPr"#)
.replace("<q:xfrm>", r#"<q:xfrm rot="2700000">"#)
.replace(r#"<a:off x="0" y="0"/><a:ext cx="1828800" cy="914400"/>"#, r#"<a:off x="127000" y="254000"/><a:ext cx="914400" cy="457200"/>"#);
files.insert("word/document.xml".into(), body.into_bytes());
@@ -4674,6 +4821,61 @@ fn bare_turns_are_kept_through_a_save() {
assert!(!bare(&read(&anchored)));
}
/// From 45° up to (not including) 135° Word measures a turned picture's overhang against its frame
/// with width and height exchanged, so a quarter turn records no effect extent; at 135° it uses the
/// frame as it is again (and the same from 225° up to 315°). Reading must not take the turn for
/// effects room, and saving must not write the turn's overhang (Word crops a picture by the
/// negative extents that gives).
#[test]
fn turned_pictures_keep_words_effect_extent() {
// A 254 × 337 pt picture with the effect extents (pt, left / top / right / bottom) Word for
// Microsoft 365 (build 16.0.20527) saves for it at 60°, a quarter turn and on both sides of
// each boundary of the exchanged-frame range. Near the boundaries Word's own values are a few
// points uneven (33 pt right against 41 pt left at 45°); the frame changes them by about 41 pt,
// so 10 pt there still tells the frames apart.
let cases: [(i64, [f32; 4], f32); 10] = [
(60, [41.0, 68.5, 42.0, 67.5], 1.0),
(90, [0.5, 0.0, 0.0, 0.0], 1.0),
(44, [82.5, 42.0, 77.5, 41.0], 10.0),
(45, [41.0, 82.0, 33.0, 82.5], 10.0),
(134, [41.0, 82.0, 36.0, 82.5], 10.0),
(135, [82.5, 40.5, 82.0, 41.0], 1.0),
(224, [82.5, 42.0, 77.5, 41.0], 10.0),
(225, [41.0, 82.0, 33.0, 82.5], 10.0),
(314, [41.0, 82.0, 36.0, 82.5], 10.0),
(315, [82.5, 40.5, 82.0, 41.0], 1.0),
];
let effect_of = |bytes: &[u8]| paras(&craft_docx::read(bytes).unwrap())[0].objects[0].frame().unwrap().2.effect;
for (degrees, ext_pt, tolerance_pt) in cases {
let [l, t, r, b] = ext_pt.map(|v| (v * 12_700.0).round() as i64);
let body = format!(
r#"<w:p><w:r><w:drawing><wp:inline><wp:extent cx="3225800" cy="4279900"/><wp:effectExtent l="{l}" t="{t}" r="{r}" b="{b}"/><wp:docPr id="1" name="Synthetic picture"/><a:graphic><a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture"><pic:pic><pic:blipFill><a:blip r:embed="rId1"/></pic:blipFill><pic:spPr><a:xfrm rot="{}"><a:off x="0" y="0"/><a:ext cx="3225800" cy="4279900"/></a:xfrm></pic:spPr></pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing></w:r></w:p>"#,
degrees * 60_000
);
let file = docx(&body, &[("rId1", "image", "media/marker.png")], &[("word/media/marker.png", "synthetic")]);
let effect = effect_of(&file);
assert!(effect.iter().all(|e| (0.0..1.5).contains(e)), "{degrees}°: {effect:?}");
let d = craft_docx::read(&file).unwrap();
let saved_file = craft_docx::write(&d).unwrap();
let xml = text(&unzip(&saved_file), "word/document.xml");
let start = xml.find("<wp:effectExtent ").expect("effect extent");
let saved = &xml[start..start + xml[start..].find("/>").expect("end")];
for (k, want) in ["l", "t", "r", "b"].into_iter().zip([l, t, r, b]) {
let at = saved.find(&format!(" {k}=\"")).expect("attribute") + k.len() + 3;
let got: i64 = saved[at..at + saved[at..].find('"').expect("quote")].parse().expect("number");
assert!(((got - want).abs() as f32) <= tolerance_pt * 12_700.0, "{degrees}°: {saved}");
}
// Reading the saved file back finds no effects room either: the round trip is stable.
let again = effect_of(&saved_file);
assert!(again.iter().all(|e| (0.0..1.5).contains(e)), "{degrees}° saved: {again:?}");
}
// An angle the file rounds to 45° is measured against the exchanged frame, as 45° is.
let pad = |rot: f32| Float { rot, ..Float::default() }.effect_spin_pad(254.0, 337.0);
let (near, at) = (pad(44.999_996), pad(45.0));
assert!((near.0 - at.0).abs() < 0.01 && (near.1 - at.1).abs() < 0.01, "{near:?} against {at:?}");
assert!((pad(44.99).0 - at.0).abs() > 1.0);
}
/// The math namespace, declared on the math element itself (the fixture root doesn't).
const M_NS: &str = r#"xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math""#;
+186
View File
@@ -0,0 +1,186 @@
//! Theme font slots of Latin text (`w:rFonts/@w:asciiTheme`, `@w:hAnsiTheme`, ISO/IEC 29500-1
//! §17.3.2.26). Saved as the font they name, the text looked the same in Word but no longer
//! followed a change of the theme's fonts. Saving writes a slot back only while it still names the
//! text's font in the document's theme, so a font chosen later is never hidden by it.
use std::io::{Read, Write};
const THEME: &str = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="T"><a:themeElements><a:fontScheme name="T"><a:majorFont><a:latin typeface="Georgia"/><a:ea typeface=""/><a:cs typeface=""/></a:majorFont><a:minorFont><a:latin typeface="Verdana"/><a:ea typeface="SimSun"/><a:cs typeface="Arial"/><a:font script="Jpan" typeface="MS Mincho"/><a:font script="Hans" typeface="DengXian"/></a:minorFont></a:fontScheme></a:themeElements></a:theme>"#;
fn docx(body: &str, styles: &str) -> Vec<u8> {
docx_with_theme(body, styles, THEME)
}
fn docx_with_theme(body: &str, styles: &str, theme: &str) -> Vec<u8> {
let root = r#"<?xml version="1.0" encoding="UTF-8"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>"#;
let doc_rels = r#"<?xml version="1.0" encoding="UTF-8"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/><Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme" Target="theme/theme1.xml"/></Relationships>"#;
let doc = format!(
r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body>{body}</w:body></w:document>"#
);
let styles = format!(
r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">{styles}</w:styles>"#
);
let parts = [
("_rels/.rels", root.to_string()),
("word/document.xml", doc),
("word/_rels/document.xml.rels", doc_rels.to_string()),
("word/styles.xml", styles),
("word/theme/theme1.xml", theme.to_string()),
];
let mut zw = zip::ZipWriter::new(std::io::Cursor::new(Vec::new()));
for (name, xml) in &parts {
zw.start_file(*name, zip::write::SimpleFileOptions::default()).unwrap();
zw.write_all(xml.as_bytes()).unwrap();
}
zw.finish().unwrap().into_inner()
}
fn part(bytes: &[u8], name: &str) -> String {
let mut z = zip::ZipArchive::new(std::io::Cursor::new(bytes)).unwrap();
let mut s = String::new();
z.by_name(name).unwrap().read_to_string(&mut s).unwrap();
s
}
fn rfonts(xml: &str) -> Vec<String> {
xml.match_indices("<w:rFonts").map(|(i, _)| xml[i..].split('>').next().unwrap_or("").to_string()).collect()
}
// As pandoc and Word write them: the minor font in the defaults, the major one on a run.
const STYLES: &str = r#"<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:asciiTheme="minorHAnsi" w:hAnsiTheme="minorHAnsi" w:eastAsiaTheme="minorEastAsia" w:cstheme="minorBidi"/></w:rPr></w:rPrDefault></w:docDefaults>"#;
const BODY: &str = r#"<w:p><w:r><w:rPr><w:rFonts w:asciiTheme="majorHAnsi" w:hAnsiTheme="majorHAnsi"/></w:rPr><w:t>Heading text</w:t></w:r></w:p>"#;
#[test]
fn latin_theme_slots_survive_a_save() {
let d = craft_docx::read(&docx(BODY, STYLES)).unwrap();
assert_eq!(d.styles.default_chr.font.as_deref(), Some("Verdana"), "layout still reads the font the slot names");
assert_eq!(d.styles.default_chr.font_ascii_theme, Some(craft_wordmodel::props::ThemeFont::MinorHAnsi));
let run = &d.body[0].as_para().unwrap().runs[0];
assert_eq!((run.props.font.as_deref(), run.props.font_hansi_theme), (Some("Georgia"), Some(craft_wordmodel::props::ThemeFont::MajorHAnsi)));
let out = craft_docx::write(&d).unwrap();
let styles = rfonts(&part(&out, "word/styles.xml"));
assert!(styles.iter().any(|f| f.contains(r#"w:asciiTheme="minorHAnsi""#) && f.contains(r#"w:hAnsiTheme="minorHAnsi""#)), "{styles:?}");
let doc = rfonts(&part(&out, "word/document.xml"));
assert!(doc.iter().any(|f| f.contains(r#"w:asciiTheme="majorHAnsi""#) && f.contains(r#"w:hAnsiTheme="majorHAnsi""#)), "{doc:?}");
// And again after a second round trip.
let again = craft_docx::read(&out).unwrap();
assert_eq!(again.styles.default_chr.font_ascii_theme, Some(craft_wordmodel::props::ThemeFont::MinorHAnsi));
}
#[test]
fn a_font_chosen_later_is_not_hidden_by_the_slot() {
let mut d = craft_docx::read(&docx(BODY, STYLES)).unwrap();
// Set directly, as the font commands do, without touching the slots.
if let Some(craft_wordmodel::Block::Para(p)) = d.body.get_mut(0).map(std::sync::Arc::make_mut) {
p.runs[0].props.font = Some("Courier New".into());
}
let doc = rfonts(&part(&craft_docx::write(&d).unwrap(), "word/document.xml"));
assert!(doc.iter().any(|f| f.contains(r#"w:ascii="Courier New""#)), "{doc:?}");
assert!(!doc.iter().any(|f| f.contains("w:asciiTheme") || f.contains("w:hAnsiTheme")), "the slot would show Georgia in Word: {doc:?}");
}
#[test]
fn a_theme_font_change_without_the_text_drops_the_slot() {
let mut d = craft_docx::read(&docx(BODY, STYLES)).unwrap();
// The theme's minor font changes but the defaults keep Verdana: the slot no longer names it.
d.settings.minor_font = "Arial".into();
let styles = rfonts(&part(&craft_docx::write(&d).unwrap(), "word/styles.xml"));
assert!(!styles.iter().any(|f| f.contains(r#"w:asciiTheme="minorHAnsi""#)), "{styles:?}");
assert!(styles.iter().any(|f| f.contains(r#"w:ascii="Verdana""#)), "{styles:?}");
}
#[test]
fn a_named_font_overlaid_replaces_the_latin_slots() {
use craft_wordmodel::props::CharProps;
let mut base = CharProps {
font: Some("Verdana".into()),
font_ascii_theme: Some(craft_wordmodel::props::ThemeFont::MinorHAnsi),
font_hansi_theme: Some(craft_wordmodel::props::ThemeFont::MinorHAnsi),
..Default::default()
};
base.overlay(&CharProps { font: Some("Courier New".into()), ..Default::default() });
assert_eq!((base.font_ascii_theme, base.font_hansi_theme), (None, None));
let mut themed = CharProps { font: Some("Verdana".into()), ..Default::default() };
themed.overlay(&CharProps {
font: Some("Georgia".into()),
font_ascii_theme: Some(craft_wordmodel::props::ThemeFont::MajorHAnsi),
..Default::default()
});
assert_eq!(themed.font_ascii_theme, Some(craft_wordmodel::props::ThemeFont::MajorHAnsi));
}
/// The theme's East Asian, complex-script and per-script fonts are written back with it: the
/// `w:eastAsiaTheme` and `w:cstheme` slots a save keeps resolve through them in Word, and an
/// empty `a:ea` would leave them naming no font.
#[test]
fn the_themes_east_asian_and_script_fonts_survive_a_save() {
let out = craft_docx::write(&craft_docx::read(&docx(BODY, STYLES)).unwrap()).unwrap();
let theme = part(&out, "word/theme/theme1.xml");
let minor = theme.split("<a:minorFont>").nth(1).and_then(|m| m.split("</a:minorFont>").next()).unwrap_or_default();
for want in [
r#"<a:ea typeface="SimSun"/>"#,
r#"<a:cs typeface="Arial"/>"#,
r#"<a:font script="Jpan" typeface="MS Mincho"/>"#,
r#"<a:font script="Hans" typeface="DengXian"/>"#,
] {
assert!(minor.contains(want), "{want} missing from the minor font: {theme}");
}
let major = theme.split("<a:majorFont>").nth(1).and_then(|m| m.split("</a:majorFont>").next()).unwrap_or_default();
assert!(major.contains(r#"<a:ea typeface=""/>"#) && !major.contains("a:font "), "the major font keeps its empty faces: {theme}");
}
/// The minor font's part of a saved theme.
fn minor_font(out: &[u8]) -> String {
let theme = part(out, "word/theme/theme1.xml");
theme.split("<a:minorFont>").nth(1).and_then(|m| m.split("</a:minorFont>").next()).unwrap_or_default().to_string()
}
/// A per-script font for a script called `cs` stays a per-script font: it is not taken for the
/// theme's `a:cs` face.
#[test]
fn a_script_named_cs_is_not_the_cs_face() {
let theme = THEME.replace(r#"<a:font script="Jpan""#, r#"<a:font script="cs" typeface="Tahoma"/><a:font script="Jpan""#);
let minor = minor_font(&craft_docx::write(&craft_docx::read(&docx_with_theme(BODY, STYLES, &theme)).unwrap()).unwrap());
assert!(minor.contains(r#"<a:cs typeface="Arial"/>"#), "{minor}");
assert!(minor.contains(r#"<a:font script="cs" typeface="Tahoma"/>"#), "{minor}");
}
/// The 256 per-script fonts kept are 256 usable ones: empty default faces don't use them up.
#[test]
fn empty_default_faces_dont_count_against_the_script_limit() {
let scripts: String = (0..256).map(|i| format!(r#"<a:font script="S{i}" typeface="F{i}"/>"#)).collect();
let theme = THEME.replace(
r#"<a:ea typeface="SimSun"/><a:cs typeface="Arial"/><a:font script="Jpan" typeface="MS Mincho"/><a:font script="Hans" typeface="DengXian"/>"#,
&format!(r#"<a:ea typeface=""/><a:cs typeface=""/>{scripts}"#),
);
let minor = minor_font(&craft_docx::write(&craft_docx::read(&docx_with_theme(BODY, STYLES, &theme)).unwrap()).unwrap());
assert!(minor.contains(r#"<a:font script="S255" typeface="F255"/>"#), "{minor}");
}
/// Latin slots naming different faces: the model has one Latin font, the ASCII one, so only the
/// slot that still names it is written; the other is left out rather than made to name a face
/// it didn't.
#[test]
fn a_latin_slot_naming_another_face_is_not_written() {
let body = r#"<w:p><w:r><w:rPr><w:rFonts w:asciiTheme="minorHAnsi" w:hAnsiTheme="majorHAnsi"/></w:rPr><w:t>Mixed</w:t></w:r></w:p>"#;
let d = craft_docx::read(&docx(body, STYLES)).unwrap();
assert_eq!(d.body[0].as_para().unwrap().runs[0].props.font.as_deref(), Some("Verdana"));
let doc = rfonts(&part(&craft_docx::write(&d).unwrap(), "word/document.xml"));
let run = doc.iter().find(|f| f.contains("Verdana")).unwrap_or_else(|| panic!("{doc:?}"));
assert!(run.contains(r#"w:asciiTheme="minorHAnsi""#) && !run.contains("w:hAnsiTheme"), "{run}");
}
/// A long script id (a language tag, which DrawingML allows) doesn't use up a place the
/// mappings font resolution takes need: the last of 256 short ones is still saved.
#[test]
fn a_language_tag_script_doesnt_push_out_a_short_one() {
let short: String = (0..255).map(|i| format!(r#"<a:font script="S{i}" typeface="F{i}"/>"#)).collect();
let theme = THEME.replace(
r#"<a:font script="Jpan" typeface="MS Mincho"/><a:font script="Hans" typeface="DengXian"/>"#,
&format!(r#"<a:font script="zh-Hant-TW" typeface="PMingLiU"/>{short}<a:font script="Arab" typeface="Times New Roman"/>"#),
);
let minor = minor_font(&craft_docx::write(&craft_docx::read(&docx_with_theme(BODY, STYLES, &theme)).unwrap()).unwrap());
assert!(minor.contains(r#"<a:font script="Arab" typeface="Times New Roman"/>"#), "{minor}");
assert!(minor.contains(r#"<a:font script="zh-Hant-TW" typeface="PMingLiU"/>"#), "{minor}");
}
+4
View File
@@ -16,12 +16,14 @@ mod default_size;
mod drawing_payload;
mod east_asian_lang;
mod east_asian_layout;
mod element_budget;
mod emphasis_marks;
mod fixtures;
mod font_table;
mod glossary;
mod heading_levels;
mod kashida;
mod latin_theme_slots;
mod legacy_forms;
mod ligatures;
mod line_numbering;
@@ -45,8 +47,10 @@ mod section_text_direction;
mod section_valign;
mod settings_merge;
mod strict_drawings;
mod table_style_indent;
mod text_alignment;
mod text_boxes;
mod theme_font_slots;
mod toc_ranges;
mod twips_wrap;
mod undefined_style;
+8 -1
View File
@@ -68,6 +68,9 @@ fn every_char_prop_round_trips() {
let all = CharProps {
style: Some("Strong".into()),
font: Some("Georgia".into()),
// Theme slots naming Georgia in the document's theme (set below).
font_ascii_theme: Some(craft_wordmodel::props::ThemeFont::MajorHAnsi),
font_hansi_theme: Some(craft_wordmodel::props::ThemeFont::MajorAscii),
// The symbol's own font: the run is written as `w:sym` characters (#2036).
sym_font: Some("Wingdings".into()),
size: Some(10.5),
@@ -124,6 +127,8 @@ fn every_char_prop_round_trips() {
cs: Some(true),
font_cs: Some("B Nazanin".into()),
font_ea: Some("宋体".into()),
font_ea_theme: Some(craft_wordmodel::props::ThemeFont::MinorEastAsia),
font_cs_theme: Some(craft_wordmodel::props::ThemeFont::MinorBidi),
size_cs: Some(13.0),
bold_cs: Some(false),
italic_cs: Some(true),
@@ -143,7 +148,8 @@ fn every_char_prop_round_trips() {
};
let auto =
CharProps { color: Some(TextColor::Auto), highlight: Some(Highlight::None), vert_align: Some(VertAlign::Subscript), ..Default::default() };
let d = doc_with(vec![para_runs(&[("plain ", CharProps::default()), ("everything", all.clone()), (" auto", auto.clone())])]);
let mut d = doc_with(vec![para_runs(&[("plain ", CharProps::default()), ("everything", all.clone()), (" auto", auto.clone())])]);
d.settings.major_font = "Georgia".into();
let r = rt(&d);
let p = paras(&r)[0];
assert_eq!(p.text, "plain everything auto");
@@ -565,6 +571,7 @@ fn table_style_formatting_round_trips() {
borders: Some(Borders { top: Some(Border::single(1.0)), ..Default::default() }),
fill: Some(Rgb(0xDD, 0xEB, 0xF7)),
cell_margins: Some([1.0, 14.4, 0.0, 14.4]),
indent: Some(0.0),
header_chr: CharProps { italic: Some(true), ..Default::default() },
header_fill: Some(Rgb(0xFF, 0xFF, 0)),
header_borders: Some(Borders::all(Border::single(1.5))),
@@ -0,0 +1,93 @@
//! The indent of a table style (`w:tblStyle/w:tblPr/w:tblInd`, ECMA-376 §17.4.50). pandoc's
//! "Table" style sets it to 0; dropped on save, Word for Mac moved every table of a manuscript
//! about 5.4 pt to the right (it places a table whose style chain sets no indent at the margin,
//! but one set to 0 with its first cell's text at the margin).
use std::io::{Read, Write};
fn docx(body: &str, styles: &str) -> Vec<u8> {
let root = r#"<?xml version="1.0" encoding="UTF-8"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>"#;
let doc_rels = r#"<?xml version="1.0" encoding="UTF-8"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/></Relationships>"#;
let doc = format!(
r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body>{body}</w:body></w:document>"#
);
let styles = format!(
r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">{styles}</w:styles>"#
);
let parts = [
("_rels/.rels", root.to_string()),
("word/document.xml", doc),
("word/_rels/document.xml.rels", doc_rels.to_string()),
("word/styles.xml", styles),
];
let mut zw = zip::ZipWriter::new(std::io::Cursor::new(Vec::new()));
for (name, xml) in &parts {
zw.start_file(*name, zip::write::SimpleFileOptions::default()).unwrap();
zw.write_all(xml.as_bytes()).unwrap();
}
zw.finish().unwrap().into_inner()
}
fn style_xml(bytes: &[u8], id: &str) -> String {
let mut z = zip::ZipArchive::new(std::io::Cursor::new(bytes)).unwrap();
let mut s = String::new();
z.by_name("word/styles.xml").unwrap().read_to_string(&mut s).unwrap();
let key = format!(r#"w:styleId="{id}""#);
let style = s.split("<w:style ").find(|x| x.contains(&key)).unwrap_or_else(|| panic!("style {id} missing from the saved styles.xml"));
style.split("</w:style>").next().unwrap_or(style).to_string()
}
const BODY: &str = r#"<w:tbl><w:tblPr><w:tblStyle w:val="Indented"/><w:tblW w:w="0" w:type="auto"/></w:tblPr><w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid><w:tr><w:tc><w:p><w:r><w:t>Cell</w:t></w:r></w:p></w:tc></w:tr></w:tbl><w:p/>"#;
#[test]
fn a_table_style_indent_of_zero_survives_a_save() {
let styles = r#"<w:style w:type="table" w:default="1" w:styleId="Table"><w:name w:val="Table"/><w:tblPr><w:tblInd w:w="0" w:type="dxa"/><w:tblCellMar><w:left w:w="108" w:type="dxa"/><w:right w:w="108" w:type="dxa"/></w:tblCellMar></w:tblPr></w:style><w:style w:type="table" w:styleId="Indented"><w:name w:val="Indented"/><w:basedOn w:val="Table"/><w:tblPr><w:tblInd w:w="720" w:type="dxa"/></w:tblPr></w:style><w:style w:type="table" w:styleId="Plain"><w:name w:val="Plain"/><w:tblPr><w:tblCellMar><w:left w:w="108" w:type="dxa"/></w:tblCellMar></w:tblPr></w:style>"#;
let d = craft_docx::read(&docx(BODY, styles)).unwrap();
let parts = |id: &str| d.styles.get(id).and_then(|s| s.table.clone()).unwrap_or_default();
assert_eq!(parts("Table").indent, Some(0.0));
assert_eq!(parts("Indented").indent, Some(36.0));
assert_eq!(parts("Plain").indent, None, "no w:tblInd stays unset");
let out = craft_docx::write(&d).unwrap();
let table = style_xml(&out, "Table");
assert!(table.contains(r#"<w:tblInd w:w="0" w:type="dxa"/>"#), "{table}");
let indented = style_xml(&out, "Indented");
assert!(indented.contains(r#"<w:tblInd w:w="720" w:type="dxa"/>"#), "{indented}");
let plain = style_xml(&out, "Plain");
assert!(!plain.contains("w:tblInd"), "{plain}");
// ECMA-376 order in w:tblPr: w:tblInd before w:tblCellMar.
assert!(table.find("w:tblInd") < table.find("w:tblCellMar"), "{table}");
}
#[test]
fn a_table_style_indent_that_is_no_length_sets_none() {
// `pct` and `auto` are no lengths for an indent; `nil` is none.
let style = |ty: &str| {
format!(
r#"<w:style w:type="table" w:styleId="Indented"><w:name w:val="Indented"/><w:tblPr><w:tblInd w:w="720" w:type="{ty}"/></w:tblPr></w:style>"#
)
};
for (ty, want) in [("pct", None), ("auto", None), ("nil", Some(0.0)), ("dxa", Some(36.0))] {
let d = craft_docx::read(&docx(BODY, &style(ty))).unwrap();
let got = d.styles.get("Indented").and_then(|s| s.table.clone()).unwrap_or_default().indent;
assert_eq!(got, want, "w:type={ty}");
}
}
#[test]
fn a_table_style_indent_without_a_width_is_zero_and_overrides_its_base() {
// `CT_TblWidth`'s `w:w` defaults to 0, so a based-on style's indent is reset, not inherited.
let styles = r#"<w:style w:type="table" w:styleId="Base"><w:name w:val="Base"/><w:tblPr><w:tblInd w:w="720" w:type="dxa"/></w:tblPr></w:style><w:style w:type="table" w:styleId="Indented"><w:name w:val="Indented"/><w:basedOn w:val="Base"/><w:tblPr><w:tblInd w:type="dxa"/></w:tblPr></w:style>"#;
let d = craft_docx::read(&docx(BODY, styles)).unwrap();
let own_of = |d: &craft_wordmodel::Document, id: &str| d.styles.get(id).and_then(|s| s.table.clone()).unwrap_or_default().indent;
let own = |d: &craft_wordmodel::Document| own_of(d, "Indented");
assert_eq!(own_of(&d, "Base"), Some(36.0), "the base sets an indent to override");
assert_eq!(d.styles.table_style("Base").map(|s| s.parts.indent), Some(Some(36.0)));
assert_eq!(own(&d), Some(0.0));
assert_eq!(d.styles.table_style("Indented").map(|s| s.parts.indent), Some(Some(0.0)), "the base's 36 pt is overridden");
let out = craft_docx::write(&d).unwrap();
let indented = style_xml(&out, "Indented");
assert!(indented.contains(r#"<w:tblInd w:w="0" w:type="dxa"/>"#), "{indented}");
assert_eq!(own(&craft_docx::read(&out).unwrap()), Some(0.0));
}
+67
View File
@@ -0,0 +1,67 @@
//! Theme font slots of the East Asian and complex-script fonts (`w:rFonts/@w:eastAsiaTheme`,
//! `@w:cstheme`, ISO/IEC 29500-1 §17.3.2.26). Word picks those fonts through the slot, so a save
//! that drops it changes the font of East Asian punctuation and, with it, Word's line breaks.
use std::io::{Read, Write};
fn docx(body: &str, styles: &str) -> Vec<u8> {
let root = r#"<?xml version="1.0" encoding="UTF-8"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>"#;
let doc_rels = r#"<?xml version="1.0" encoding="UTF-8"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/></Relationships>"#;
let doc = format!(
r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body>{body}</w:body></w:document>"#
);
let styles = format!(
r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">{styles}</w:styles>"#
);
let parts = [
("_rels/.rels", root.to_string()),
("word/document.xml", doc),
("word/_rels/document.xml.rels", doc_rels.to_string()),
("word/styles.xml", styles),
];
let mut zw = zip::ZipWriter::new(std::io::Cursor::new(Vec::new()));
for (name, xml) in &parts {
zw.start_file(*name, zip::write::SimpleFileOptions::default()).unwrap();
zw.write_all(xml.as_bytes()).unwrap();
}
zw.finish().unwrap().into_inner()
}
fn part(bytes: &[u8], name: &str) -> String {
let mut z = zip::ZipArchive::new(std::io::Cursor::new(bytes)).unwrap();
let mut s = String::new();
z.by_name(name).unwrap().read_to_string(&mut s).unwrap();
s
}
fn rfonts(xml: &str) -> Vec<String> {
xml.match_indices("<w:rFonts").map(|(i, _)| xml[i..].split('>').next().unwrap_or("").to_string()).collect()
}
#[test]
fn theme_font_slots_survive_a_save() {
// As pandoc writes them: theme slots only, in the document defaults, and on a run.
let styles = r#"<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:asciiTheme="minorHAnsi" w:eastAsiaTheme="minorEastAsia" w:hAnsiTheme="minorHAnsi" w:cstheme="minorBidi"/><w:lang w:val="en-US" w:eastAsia="zh-CN"/></w:rPr></w:rPrDefault></w:docDefaults>"#;
let body = r#"<w:p><w:r><w:rPr><w:rFonts w:eastAsiaTheme="majorEastAsia" w:cstheme="bogus"/></w:rPr><w:t>“Quoted” text</w:t></w:r></w:p>"#;
let d = craft_docx::read(&docx(body, styles)).unwrap();
let run = &d.body[0].as_para().unwrap().runs[0];
assert_eq!(run.props.font_ea_theme, Some(craft_wordmodel::props::ThemeFont::MajorEastAsia));
assert_eq!(run.props.font_cs_theme, None, "a name outside ST_Theme is not kept");
let out = craft_docx::write(&d).unwrap();
let styles_out = rfonts(&part(&out, "word/styles.xml"));
assert!(
styles_out.iter().any(|f| f.contains(r#"w:eastAsiaTheme="minorEastAsia""#) && f.contains(r#"w:cstheme="minorBidi""#)),
"the document defaults keep their theme slots: {styles_out:?}"
);
let doc_out = rfonts(&part(&out, "word/document.xml"));
assert!(doc_out.iter().any(|f| f.contains(r#"w:eastAsiaTheme="majorEastAsia""#)), "the run keeps its slot: {doc_out:?}");
}
#[test]
fn a_named_east_asian_font_replaces_the_theme_slot() {
let mut base = craft_wordmodel::props::CharProps { font_ea_theme: Some(craft_wordmodel::props::ThemeFont::MinorEastAsia), ..Default::default() };
base.overlay(&craft_wordmodel::props::CharProps { font_ea: Some("SimSun".into()), ..Default::default() });
assert_eq!(base.font_ea.as_deref(), Some("SimSun"));
assert_eq!(base.font_ea_theme, None, "the slot would otherwise win over the font just chosen");
}
+19
View File
@@ -0,0 +1,19 @@
[package]
name = "craft-esign"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
rust-version.workspace = true
description = "What an e-sign service offers the Craft apps: envelopes, recipients and events as contracts, with no vendor and no IO"
[lints]
workspace = true
[dependencies]
craft-cloud = { workspace = true }
serde = { workspace = true }
thiserror = { workspace = true }
[dev-dependencies]
serde_json = { workspace = true }
+63
View File
@@ -0,0 +1,63 @@
//! One error type for every e-sign contract.
//!
//! Cloud failures are wrapped so a host can surface sign-in and reachability
//! the same way it already does for files. The e-sign-only cases are the ones
//! a UI acts on differently: declined, voided, expired, identity check.
use thiserror::Error;
#[derive(Debug, Error)]
pub enum Error {
/// Something the cloud contracts already classify.
#[error(transparent)]
Cloud(#[from] craft_cloud::Error),
/// A recipient refused to sign.
#[error("declined: {0}")]
Declined(String),
/// The sender voided the envelope.
#[error("voided: {0}")]
Voided(String),
/// The envelope passed its deadline without completing.
#[error("expired: {0}")]
Expired(String),
/// The provider rejected the signer's identity check.
#[error("identity check failed: {0}")]
IdentityCheck(String),
/// The chosen provider refuses this request under its policy.
#[error("provider policy: {0}")]
ProviderPolicy(String),
/// The service does not offer this at all.
#[error("this signing service does not support {0}")]
Unsupported(&'static str),
/// The answer did not match the protocol.
#[error("malformed {what}: {detail}")]
Malformed { what: &'static str, detail: String },
/// A field the caller supplied could not be used safely.
#[error("invalid {what}: {detail}")]
Invalid { what: &'static str, detail: String },
}
impl Error {
pub fn malformed(what: &'static str, detail: impl Into<String>) -> Error {
Error::Malformed { what, detail: detail.into() }
}
pub fn invalid(what: &'static str, detail: impl Into<String>) -> Error {
Error::Invalid { what, detail: detail.into() }
}
/// Whether trying again could succeed without the user doing anything.
pub fn is_transient(&self) -> bool {
matches!(self, Error::Cloud(e) if e.is_transient())
}
}
pub type Result<T> = std::result::Result<T, Error>;
+318
View File
@@ -0,0 +1,318 @@
//! What an e-sign service has to offer the Craft apps, and nothing about who
//! provides it.
//!
//! An envelope is a ceremony: a document snapshot, a set of recipients, field
//! placements, and a status. The legal audit trail, identity checks and
//! invitation mail belong to the signing service. This crate only names the
//! contracts an app needs to create, send, watch and finish that ceremony.
//!
//! Nothing in this crate opens a socket. Each trait is implemented by a host
//! (CollabCraft, a desktop adapter, a test double) that brings its own
//! transport. No type here names a vendor. No type here knows about PDF
//! structure: a document is opaque bytes plus a content hash.
//!
//! This crate sits beside `craft-cloud`. It reuses [`craft_cloud::Identity`]
//! and the idea of a contact for autocomplete, but it does not extend
//! [`craft_cloud::Provider`] or [`craft_cloud::Capability`]. Signing is not
//! file access, and a signer role is not a share permission.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
mod error;
mod types;
pub use error::{Error, Result};
pub use types::{
CompletedDocument, Envelope, EnvelopeDraft, EnvelopeEvent, EnvelopeStatus, EsignCapability, FieldPlacement, Recipient, RecipientStatus,
};
/// Creating and driving envelopes.
///
/// Methods that a minimal service may omit are defaulted to
/// [`Error::Unsupported`], the same pattern [`craft_cloud::Conversations`]
/// uses for optional cloud features.
pub trait Envelopes {
/// Create a draft from a document snapshot.
///
/// `document` is the exact byte sequence the ceremony seals. The
/// implementation hashes it and stores `content_sha256` on the envelope.
/// `idempotency_key` makes a retried create return the same envelope.
fn create(&self, draft: &EnvelopeDraft, document: &[u8], idempotency_key: &str) -> Result<Envelope>;
/// Send invitations and move the envelope to [`EnvelopeStatus::Sent`].
fn send(&self, envelope: &str) -> Result<Envelope>;
/// Current status, including per-recipient progress.
fn status(&self, envelope: &str) -> Result<Envelope>;
/// The finished document and provider evidence.
///
/// Fails unless status is [`EnvelopeStatus::Completed`]. The returned
/// [`CompletedDocument`] carries both the original document's content
/// digest and the signed artifact's digest, computed honestly rather
/// than copied from one another: the implementation must not assume the
/// provider's sealing left the bytes unchanged.
fn completed(&self, envelope: &str) -> Result<CompletedDocument>;
/// Cancel an in-flight envelope.
fn void(&self, _envelope: &str, _reason: &str) -> Result<()> {
Err(Error::Unsupported("void"))
}
/// Nudge one recipient who has not signed yet.
fn remind(&self, _envelope: &str, _recipient: &str) -> Result<()> {
Err(Error::Unsupported("reminders"))
}
/// A URL the recipient opens to sign inside the provider's UI.
fn signing_url(&self, _envelope: &str, _recipient: &str, _return_to: &str) -> Result<String> {
Err(Error::Unsupported("embedded signing"))
}
}
/// Turning provider webhooks into [`EnvelopeEvent`]s.
///
/// Server-side only. A desktop host that implements [`Envelopes`] never needs
/// a webhook secret and need not implement this beyond refusing.
pub trait EventIntake {
/// Verify authenticity and parse zero or more events from one HTTP body.
fn verify_event(&self, headers: &[(String, String)], body: &[u8]) -> Result<Vec<EnvelopeEvent>>;
}
/// Everything one signing service can do.
///
/// A service implements the capabilities it has and reports the rest as
/// absent, so a caller can hide void on a stub that only supports the happy
/// path rather than offering a control that fails on use.
pub trait SigningService: Envelopes + EventIntake {
/// A stable identifier, such as `stub` or `documenso`. Used in
/// configuration and logs, never shown to a user.
fn id(&self) -> &str;
/// What this service actually supports.
fn capabilities(&self) -> Vec<EsignCapability>;
fn supports(&self, capability: EsignCapability) -> bool {
self.capabilities().contains(&capability)
}
/// The party that holds legal and compliance responsibility for the
/// ceremony. Shown to senders before they send (upstream #2315).
fn responsible_party(&self) -> String;
}
#[cfg(test)]
mod tests {
use std::sync::Mutex;
use super::*;
use craft_cloud::Identity;
struct RefuseAll;
impl Envelopes for RefuseAll {
fn create(&self, _: &EnvelopeDraft, _: &[u8], _: &str) -> Result<Envelope> {
Err(Error::Unsupported("create"))
}
fn send(&self, _: &str) -> Result<Envelope> {
Err(Error::Unsupported("send"))
}
fn status(&self, _: &str) -> Result<Envelope> {
Err(Error::Unsupported("status"))
}
fn completed(&self, _: &str) -> Result<CompletedDocument> {
Err(Error::Unsupported("completed"))
}
}
impl EventIntake for RefuseAll {
fn verify_event(&self, _: &[(String, String)], _: &[u8]) -> Result<Vec<EnvelopeEvent>> {
Err(Error::Unsupported("webhooks"))
}
}
impl SigningService for RefuseAll {
fn id(&self) -> &str {
"refuse"
}
fn capabilities(&self) -> Vec<EsignCapability> {
Vec::new()
}
fn responsible_party(&self) -> String {
"nobody".into()
}
}
#[test]
fn defaulted_methods_are_unsupported() {
let s = RefuseAll;
assert!(matches!(s.void("e", "x"), Err(Error::Unsupported("void"))));
assert!(matches!(s.remind("e", "r"), Err(Error::Unsupported("reminders"))));
assert!(matches!(s.signing_url("e", "r", "https://example"), Err(Error::Unsupported("embedded signing"))));
assert!(!s.supports(EsignCapability::Envelopes));
assert_eq!(s.responsible_party(), "nobody");
}
#[test]
fn draft_round_trips_json() {
let draft = EnvelopeDraft {
title: "NDA".into(),
message: Some("please sign".into()),
sender: Identity { id: "u1".into(), display: "Ada".into(), email: Some("ada@example.com".into()), avatar: None },
document_id: Some("doc-1".into()),
document_etag: Some("\"abc\"".into()),
recipients: vec![Recipient {
id: "r1".into(),
name: "Bob".into(),
email: "bob@example.com".into(),
role: "Signer".into(),
required: true,
status: RecipientStatus::Pending,
}],
placements: vec![FieldPlacement {
role: "Signer".into(),
page: 0,
x: 0.1,
y: 0.2,
w: 0.3,
h: 0.05,
kind: "signature".into(),
required: true,
}],
expires: Some("2026-12-31".into()),
};
let json = serde_json::to_string(&draft).expect("serialize");
let back: EnvelopeDraft = serde_json::from_str(&json).expect("deserialize");
assert_eq!(back, draft);
}
#[test]
fn cloud_errors_wrap_and_report_transient() {
let err = Error::from(craft_cloud::Error::Unreachable("down".into()));
assert!(err.is_transient());
let err = Error::Declined("no".into());
assert!(!err.is_transient());
}
/// A non-cryptographic stand-in for a content digest. Good enough to
/// prove two byte strings differ; this crate takes no hashing
/// dependency, since hashing the document is an adapter's job.
fn fake_digest(bytes: &[u8]) -> String {
use std::hash::{Hash, Hasher};
let mut hasher = std::collections::hash_map::DefaultHasher::new();
bytes.hash(&mut hasher);
format!("{:016x}", hasher.finish())
}
/// An honest in-process double for [`Envelopes`]. It keeps the exact
/// bytes `create` was given, and on `completed` returns a "signed"
/// artifact built by appending a stub provider seal to those bytes, so
/// `original_content_sha256` and `signed_content_sha256` are computed
/// from genuinely different byte strings, the way a real provider's
/// sealing would produce them, rather than one copied from the other.
struct Double {
document: Mutex<Option<Vec<u8>>>,
}
impl Double {
fn new() -> Double {
Double { document: Mutex::new(None) }
}
}
impl Envelopes for Double {
fn create(&self, draft: &EnvelopeDraft, document: &[u8], _idempotency_key: &str) -> Result<Envelope> {
*self.document.lock().expect("lock") = Some(document.to_vec());
Ok(Envelope {
id: "env-double".into(),
title: draft.title.clone(),
message: draft.message.clone(),
sender: draft.sender.clone(),
document_id: draft.document_id.clone(),
document_etag: draft.document_etag.clone(),
content_sha256: fake_digest(document),
recipients: draft.recipients.clone(),
placements: draft.placements.clone(),
status: EnvelopeStatus::Draft,
expires: draft.expires.clone(),
created: None,
completed_at: None,
})
}
fn send(&self, envelope: &str) -> Result<Envelope> {
self.status(envelope)
}
fn status(&self, envelope: &str) -> Result<Envelope> {
let document = self.document.lock().expect("lock").clone().unwrap_or_default();
Ok(Envelope {
id: envelope.into(),
title: "Double".into(),
message: None,
sender: Identity { id: "u1".into(), display: "Ada".into(), email: None, avatar: None },
document_id: None,
document_etag: None,
content_sha256: fake_digest(&document),
recipients: Vec::new(),
placements: Vec::new(),
status: EnvelopeStatus::Completed,
expires: None,
created: None,
completed_at: None,
})
}
fn completed(&self, envelope: &str) -> Result<CompletedDocument> {
let original = self.document.lock().expect("lock").clone().unwrap_or_default();
let mut signed = original.clone();
signed.extend_from_slice(b"\0provider-seal");
Ok(CompletedDocument {
envelope_id: envelope.into(),
bytes: signed.clone(),
original_content_sha256: fake_digest(&original),
signed_content_sha256: fake_digest(&signed),
evidence: b"certificate-of-completion".to_vec(),
})
}
}
/// RFC-0021's evidence guarantee: `CompletedDocument` carries the
/// original document's digest and the signed artifact's digest as two
/// distinct, honestly computed fields, and they differ when the
/// provider's sealing changes the bytes.
#[test]
fn completed_document_keeps_original_and_signed_digests_distinct() {
let double = Double::new();
let draft = EnvelopeDraft {
title: "Contract".into(),
message: None,
sender: Identity { id: "u1".into(), display: "Ada".into(), email: None, avatar: None },
document_id: Some("doc-1".into()),
document_etag: None,
recipients: Vec::new(),
placements: Vec::new(),
expires: None,
};
let original_bytes = b"the original document bytes";
let envelope = double.create(&draft, original_bytes, "idem-1").expect("create");
let completed = double.completed(&envelope.id).expect("completed");
assert_eq!(completed.original_content_sha256, fake_digest(original_bytes));
assert_ne!(completed.bytes, original_bytes, "the signed artifact's bytes differ from the original");
assert_eq!(completed.signed_content_sha256, fake_digest(&completed.bytes));
assert_ne!(
completed.original_content_sha256, completed.signed_content_sha256,
"sealing changed the bytes, so the two digests must not be conflated"
);
let json = serde_json::to_string(&completed).expect("serialize");
let back: CompletedDocument = serde_json::from_str(&json).expect("deserialize");
assert_eq!(back, completed);
}
}
Loaded 100 of 287 files, more files were not shown because too many files have changed in this diff. Show more