Manage caches
DarkRay saves work it can repeat, such as decoded RAW files and model results, so it doesn’t decode or compute them twice. These files are caches. Your edits and ratings live in the catalog, not here.
See what the caches hold
Section titled “See what the caches hold”Open File › Preferences… › Caches. The Usage card measures each cache and shows a total. Hover a size to see its file count.
| Cache | Holds | If you clear it |
|---|---|---|
| Decoded proxies | Reduced-size decodes of RAW files, so photos open and sliders drag quickly. | Rebuilt as needed, about a second per photo. |
| Lens-corrected proxies | The same, with the lens correction applied. | Rebuilt as needed. |
| Prepared images | Full-resolution results of a photo’s RAW Process denoise. | Each photo is prepared again the next time it opens in Edit. Your edits are kept. |
| Denoise results | The denoise model’s full-resolution output. | Rebuilt the next time a photo is prepared, which can take minutes. |
| Masks | The images behind AI masks and painted masks. | AI masks must be generated again. Painted masks rebuild from their strokes. |
| Depth maps | A photo’s depth, used by Atmosphere and Depth Range masks. | Computed again when needed. |
| Content search | Data for searching by what is in a photo. | Rebuilt as needed. |
| Previews (this catalog) | The grid thumbnails and larger previews, stored next to the catalog. | Rebuilt in the background. |
Clear a cache
Section titled “Clear a cache”Click Clear on its line. For Prepared images and Masks, DarkRay asks first, because the loss costs you time: “Each photo is prepared again the next time it opens in Edit, which takes a moment. Your edits are kept.” or “AI masks will need to be generated again. Painted masks rebuild from their strokes.” The sizes update when the job ends.
If a photo opens with an AI mask whose image is gone, DarkRay asks “N AI masks on this photo need regenerating” and offers Regenerate. Until then that layer has no effect.
Limit the size
Section titled “Limit the size”Size limit is the most the rebuildable caches may use, from 5 to 2000 GB, starting at 50 GB. When they go over, the least recently used files go first. The check runs at startup and after each photo is prepared.
Prepared images and Masks never count against the limit and are never removed for size. They are deleted only when no open or recent catalog uses them. Clean Up Now runs that check and the size limit immediately, and also removes outdated versions.
Move the cache folder
Section titled “Move the cache folder”Cache folder starts empty, which uses ~/.darkray/cache. Choose a large, fast drive if you
have one: a full-resolution prepared image is several hundred megabytes. The new folder is used
at once, and if the old one holds files DarkRay asks what to do with it:
- Move carries the cached files across in the background. Prepared images keep working.
- Delete removes the old cache in the background. Photos are prepared again when they next open in Edit.
- Leave It keeps the old folder untouched. DarkRay no longer uses it.
If the old folder contains folders DarkRay didn’t write, only Leave It is offered. While an image is being prepared or another cache job is running, the change is refused with “The cache stays in …”, and you can try again when it finishes.
Technical details: how the caches are stored
Each cache is a folder under the cache root, and the entries are keyed by a fingerprint of the source file’s size and contents, so a moved photo keeps its caches. Array data is stored as 16-bit half floats, which halves the size and changes a rendered pixel by at most one display code value. Changing the thumbnail resolution or the preview cache size makes existing previews stale, and they rebuild in the background.
A cache folder holds a marker file, and DarkRay deletes inside it only when that marker is present.