photoprism/internal/raw

PhotoPrism — RAW Image Conversion

Last Updated: June 30, 2026

Overview

internal/raw provides command builders and heuristics for converting camera RAW images (including Adobe Digital Negative, .dng) to JPEG with Darktable, RawTherapee, and ExifTool. It mirrors the internal/ffmpeg pattern: the builders return *exec.Cmd and the caller passes the binary path plus options, while the orchestration that runs the commands and accepts their output stays in internal/photoprism (Convert.JpegConvertCmds and the ToImage convert loop).

The package owns the small amount of RAW-specific knowledge that would otherwise be scattered through the converter: the command flags, the stderr patterns that mark an untrustworthy decode, and the list of formats whose embedded preview is unusable.

Builders

• DarktableCmd(DarktableOptions) (*exec.Cmd, bool) — also reports whether the command needs a global mutex (presets mode runs one instance at a time).
• TherapeeCmd(bin, rawName, jpegName, profile string, quality int) *exec.Cmd — RawTherapee render to JPEG (named without the Raw prefix to avoid a raw.RawTherapee… stutter).
• ExifToolJpgFromRawCmd / ExifToolPreviewImageCmd — extract the full-resolution / smaller embedded preview to stdout.

Converter Priority

For a RAW input, JpegConvertCmds appends commands in this order, and the convert loop accepts the first whose output passes:

1. Darktable — full RAW developer (preferred).
2. RawTherapee — full RAW developer (when Darktable is unavailable or fails).
3. Embedded camera preview via ExifTool (largest first) — the last resort.

The embedded preview is last because a full render is higher quality, but it has correct colors when the RAW developers cannot identify the sensor (e.g. very recent Canon CR3 bodies otherwise come out magenta), so it wins when the developers are unavailable or — for the gated formats described below — produce an untrustworthy render.

Conversion Gating (--disable-raw)

PHOTOPRISM_DISABLE_RAW disables both indexing and conversion of RAW, via two independent gates:

• Indexing/import/upload skip RAW entirely before it reaches the converter (index.go, mediafile_related.go, import.go, users_upload.go).
• Conversion gates only the RAW renderers (Darktable, RawTherapee, and the macOS sips path) on RawEnabled(). ExifTool preview extraction runs regardless, so an already-embedded preview can still be extracted when rendering is disabled (e.g. via the convert CLI).

Error Handling

The three tools fail differently, so they are guarded differently:

• Darktable signals an unsupported sensor with a non-zero exit code and writes no file (its diagnostics go to stdout, e.g. [libraw_open] detected unsupported image). The convert loop's exit-code check skips it, so no stderr inspection is needed.
• RawTherapee can exit 0 yet produce wrong colors (e.g. a default white balance for an unidentified sensor) while printing a dcraw-derived message to stderr. For formats in the discard set (DiscardRenderOnWarning, default .cr3) its command is tagged with ConvertCmd.WithStderrRejection(raw.DecoderErrors...); a match discards the output and the loop falls through to the embedded preview. WhiteBalanceError is the canonical case; DecoderErrors adds the other untrustworthy-decode messages (sourced from dcraw.c). Other RAW formats keep the render — see Discard-on-Warning Gate below.
• Embedded previews can be header-valid yet fail the thumbnailer (a bogus Huffman table only surfaces during shrink-on-load), so they are tagged WithImageVerification, which runs thumb.Verify to force the decode before acceptance.

Because of this, StderrRejected is RawTherapee-specific by design — Darktable does not need it (it fails via exit code, not via accepted-but-wrong output).

Discard-on-Warning Gate

DiscardRenderOnWarning(ext) decides, per RAW format, whether a RawTherapee render is discarded when its stderr matches DecoderErrors. It defaults to Canon CR3 (.cr3): recent CR3 bodies, which neither RAW developer can demosaic, render magenta, but they reliably embed a good preview to fall back to. The white-balance warning alone cannot tell a magenta render from a fine one — RawTherapee emits it for any sensor whose coefficients it cannot read, including obscure bodies whose default-WB render is perfectly fine — so the rejection is gated on the format as well as the warning.

Formats RawTherapee alone can decode (e.g. .raw, .kdc) are deliberately left out: they have no embedded preview to fall back to, so discarding the render would leave nothing to index. The set is overridable via PHOTOPRISM_RAW_DISCARD_ON_WARNING_EXT (a comma-separated list that replaces the default), an escape hatch — outside the CLI/config surface — for adding a newly found magenta-prone format without a rebuild. A gated format must allow embedded-preview extraction (PreviewExtAllowed); otherwise its render would be discarded with no fallback, so PhotoPrism logs a warning at startup if an override names such a format.

Preview-Unsafe Formats

previewUnsafeExt lists RAW extensions whose embedded JPEG preview is known to be unusable, exposed via PreviewExtAllowed(ext). Currently .mos (Leaf), whose preview is a bogus-Huffman JPEG that passes a MIME sniff but fails thumbnailing; skipping it forces a full RAW render.

PNG Output (Deferred)

RAW is not converted to PNG today: ToImage writes a .jpg sidecar for RAW, and PngConvertCmds has no RAW renderer at all (it logs and skips RAW). A lossless RAW export/preview (e.g. a future UI "export" tool) is the case that would need RAW→PNG. When that lands, build the PNG path to its own spec rather than copying JpegConvertCmds: it should render with Darktable/RawTherapee in PNG mode (RawTherapee needs -n/-b16, a new builder), and it should not use the embedded-JPEG preview fallback, which is lossy and would defeat a lossless export.

Known Gaps

• RAW→PNG is unimplemented (see PNG Output above); PngConvertCmds logs and skips RAW. RAW rendering to JPEG (Darktable, RawTherapee, sips) is gated on RawEnabled().