RawCull is a native macOS photo review and culling application for Sony ARW RAW files. It combines fast embedded-preview loading with focus-point extraction, sharpness analysis, visual similarity, burst grouping, ratings, and selective export.

The application is written in Swift 6 and SwiftUI. Focused Swift packages own image parsing, analysis, AI inference, shared culling models, JSON encoding, and rsync execution. RawCull owns application state, workflow, caching, persistence, and presentation.

All versions require an Apple Silicon Mac. The main difference between the macOS 26 and macOS 27 editions is the AI layer, not the basic photo-culling workflow: the macOS 26 branches use Apple's built-in Vision feature prints, whereas RawCull 3 adds local CLIP models for text-to-image search and optional similarity analysis, plus SAM 3 subject segmentation for Deep Review. RawCull 3 falls back to Vision similarity when its selected CLIP model is unavailable.

RawCull 3 is not yet published as a prebuilt download; build this branch from source until its macOS 27 release is available.

• Discover and scan supported RAW files in a selected catalog.
• Read EXIF metadata, dimensions, camera and lens information, ISO, and aperture.
• Extract normalized camera AF points from Sony MakerNotes.
• Display cached thumbnails, embedded full-size JPEG previews, or developed RAW previews.
• Render AF-point overlays and GPU-generated focus masks.
• Score image sharpness using full-frame, salient-subject, and AF-region evidence.
• Apply photo-type presets and fast, balanced, or high-precision scoring.
• Group visually similar neighboring frames into bursts and rank candidates with sharpness, similarity, confidence, and caution details.
• Search by natural-language description when a validated CLIP model is available.
• Run SAM 3 Deep Review to isolate a subject and recommend a burst winner.
• Tag, reject, or assign star ratings to selected images.
• Persist ratings, analysis results, burst decisions, and cache signatures.
• Export embedded or developed JPEG files.
• Copy tagged or rated RAW files with streaming rsync progress.
• Monitor thumbnail-cache usage and macOS memory-pressure events.

RawCull's AI-assisted culling runs locally on Apple Silicon. Photos are not uploaded to an external inference service.

• Similarity and burst grouping: CLIP image embeddings, or Vision feature prints as the fallback, measure visual similarity and help group neighboring frames for comparison.
• Semantic search: CLIP compares a text-query embedding with cached image embeddings to rank photographs by meaning.
• Sharpness and subject evidence: PhotoAnalysisKit combines sharpness, saliency, classification, focus-mask, and camera AF-point evidence to rank candidates and explain cautions.
• Deep Review: SAM 3 isolates the subject, evaluates detail inside the mask, checks whether the AF point falls within the subject, and recommends a winner with confidence and supporting reasons. Mark Winner & Close saves the winner, gives it a three-star rating, and marks the burst reviewed.
• Local caching: Embeddings, masks, scores, and burst decisions are cached so compatible results can be reused in later sessions.

Both are trained neural networks, but they produce different evidence:

CLIP

Image ── image encoder ──► vector ─┐
                                   ├─► similarity score
Text  ── text encoder  ──► vector ─┘

SAM 3

Image  ── image encoder ────────────┐
                                    ├─► detector + mask decoder ─► masks and boxes
Prompt ── text/visual encoder ──────┘

CLIP determines what an image is related to; SAM 3 determines where that thing is in the image.

CLIP image encoding runs once per photograph. Later searches reuse the cached image vectors and only run the text-query path; comparing cached vectors is ordinary mathematical computation, not another neural-network pass. SAM 3 normally runs for each image and prompt, but RawCull can cache and reuse the resulting subject mask.

• Vision feature-print similarity is built into macOS and requires no model download.
• CLIP similarity supports validated, PhotoAIKit-compatible DataComp and OpenAI CLIP Core AI model bundles. RawCull uses the model selected in Settings > AI and falls back to Vision feature prints when it is missing or invalid. Semantic search requires a valid CLIP model.
• Deep Review requires a validated, PhotoAIKit-compatible SAM 3 Core AI model bundle and remains unavailable without one.
• Each bundle must contain metadata.json, the selected .aimodel or .aimodelc asset, and all resources declared by its manifest.
• Models are not bundled with RawCull. Settings > AI > Download AI Models provides the Managed Background Assets flow for licence review, download progress, cancellation, and removal. The current server address is a non-routable placeholder, and production downloads remain blocked until licence and provenance requirements are complete.
• The first use of a portable Core AI model can take longer while macOS specializes it for the current Mac.

Manual installation remains available while model distribution is blocked. Install the resources, open Settings > AI, and select Check Again to validate them. Standard non-sandboxed locations are:

~/Library/Application Support/RawCull/Models/CLIP-DataComp/
~/Library/Application Support/RawCull/Models/CLIP-OpenAI/
~/Library/Application Support/RawCull/Models/SAM3/

Sandboxed builds use:

~/Library/Containers/no.blogspot.RawCull/Data/Library/Application Support/RawCull/Models/CLIP-DataComp/
~/Library/Containers/no.blogspot.RawCull/Data/Library/Application Support/RawCull/Models/CLIP-OpenAI/
~/Library/Containers/no.blogspot.RawCull/Data/Library/Application Support/RawCull/Models/SAM3/

Settings > AI displays the exact expected paths. To enable CLIP, select exactly one of DataComp or OpenAI, validate it, and enable Use selected CLIP model for similarity. To use SAM 3, analyze a catalog into burst groups, choose Deep Review on a burst, select the review target, and run the review.

See Model asset packs for the release blockers, licence and provenance catalogs, packaging steps, and hosting configuration.

flowchart LR
    Catalog["RAW catalog"] --> Parser["RawParserKit"]
    Parser --> Adapter["RawCull decoding adapters"]
    Adapter --> Domain["RawCullCore models"]
    Adapter --> Analysis["PhotoAnalysisKit"]
    Adapter --> PhotoAI["PhotoAIKit"]
    Models["CLIP / SAM 3 Core AI models"] --> PhotoAI
    Analysis --> Sharpness["Sharpness, focus mask, saliency"]
    PhotoAI --> Similarity["CLIP embeddings / Vision fallback"]
    PhotoAI --> Masks["SAM 3 segmentation / mask storage"]
    Domain --> Bursts["RawCullCore burst grouping"]
    Similarity --> Bursts
    Sharpness --> Ranking["RawCull ranking and review policy"]
    Bursts --> Ranking
    Masks --> DeepReview["Deep Review subject-detail evidence"]
    Sharpness --> DeepReview
    Domain --> ViewModels["@Observable view models"]
    Ranking --> ViewModels
    DeepReview --> ViewModels
    ViewModels --> UI["SwiftUI views"]
    ViewModels --> Cache["RAM and disk caches"]
    ViewModels --> Persistence["JSON and burst persistence"]
    ViewModels --> Copy["rsync copy workflow"]

RawCull keeps application-specific policy outside the packages:

• RAW source selection and decoding size
• security-scoped folder access
• settings and user preferences
• progress and cancellation presentation
• cache locations and file identity
• ratings, tagging, burst decisions, and the culling workflow

The imported packages own reusable parsing, sharpness analysis, AI inference, model validation, similarity artifacts, segmentation, mask storage, domain models, serialization, and process execution.

Requirements are pinned to exact versions or revisions in the Xcode project and recorded in Package.resolved.

1. The user selects a security-scoped catalog.
2. ScanFiles discovers supported files through RawParserKit.
3. Metadata and AF information are read concurrently.
4. RawCullCore FileItem values are created and published to the main actor.
5. Ratings and compatible persisted analysis results are restored.

RawParserKitImageLoader adapts package results to RawCull:

• RawImageLoader.metadata(for:) becomes RawCullCore ExifMetadata.
• RawImageLoader.thumbnailCGImage feeds thumbnail caching, sharpness scoring, and feature generation.
• RawImageLoader.thumbnail supplies AppKit thumbnail images.
• RawImageLoader.previewImage supplies embedded full-size previews.
• MakerNote focus coordinates become normalized CGPoint values.

RawFormatRegistry handles supported-file discovery. Diagnostic tools also call the Sony and Nikon MakerNote parsers directly to report embedded JPEG locations and focus metadata.

RawCull uses a two-tier thumbnail cache:

1. SharedMemoryCache provides the RAM layer through NSCache.
2. DiskCacheManager stores JPEG thumbnails below ~/Library/Caches/no.blogspot.RawCull/Thumbnails/.
3. RawParserKit decodes a thumbnail when both caches miss.

Full-size embedded and developed previews use a separate disk cache. A DispatchSourceMemoryPressure monitor lets RawCull reduce cache pressure while keeping diagnostics available in the Memory Console.

PhotoAnalysisKit owns the reusable focus and sharpness pipeline:

1. RawCull selects an embedded preview or a Core Image demosaiced RAW image.
2. RawCullPhotoAnalysisAdapter supplies asynchronous PhotoAnalysisInput providers.
3. PhotoAnalyzer.analyzeBatch performs bounded concurrent analysis and reports progress.
4. The package performs saliency, classification, Gaussian blur, Metal Laplacian analysis, regional scoring, and failure classification.
5. SharpnessScoringModel publishes scores, subject summaries, focus breakdowns, and estimated time to the UI.
6. PhotoAnalyzer.calibrate derives a visual focus threshold from a catalog or burst.
7. PhotoAnalyzer.focusMask and analyzeWithFocusMask render the focus overlay and its supporting evidence.

Each PhotoAnalysisInput carries ISO, aperture, and normalized AF position. Photo-type and quality choices map to SharpnessPreset and SharpnessQuality. Persistent results use PhotoAnalyzer.sharpnessDescriptor(for:), combined with RawCull's scoring source, decoded size, source-file size, and modification date so stale results are invalidated when the algorithm or input changes.

PhotoAnalysisKit does not know about FileItem, RAW formats, security-scoped URLs, application settings, cache directories, or ratings.

RawCull imports six PhotoAIKit products: PhotoAIContracts, PhotoAIWorkflows, PhotoAIStorage, CoreAICLIPBackend, CoreAISAM3Backend, and VisionFeaturePrintBackend.

• CoreAICLIPProvider creates normalized CLIP image embeddings and cosine distances.
• VisionFeaturePrintBackend creates and compares Codable Vision feature prints.
• CoreAISAM3Provider performs in-process subject segmentation with a validated SAM 3 Core AI model.
• SegmentationService and SubjectMaskSelector acquire and select masks; PhotoAIStorage supplies their memory and disk stores.
• Persisted settings select one DataComp or OpenAI CLIP bundle and enable it when available. Non-finite output is retried once, then retried with a replacement provider; unresolved images are excluded from automatic burst analysis.

For burst analysis, RawParserKit supplies 512-pixel thumbnails, PhotoAIKit creates and validates CLIP artifacts or uses Vision, and RawCull passes adjacent distances to BurstGroupingEngine.group. RawCullCore groups the ordered images; RawCull ranks the candidates and caches the artifacts and decisions. Deep Review adds SAM 3 subject masks and subject-detail evidence to that workflow.

RawCullAIIntegration validates the model bundles, selects CLIP or the Vision fallback, constructs SAM 3 mask services, and injects narrow services into the application models. RawCull retains ownership of RAW decoding, model locations, settings, subject-detail scoring, recommendation policy, ratings, and review state.

RawCullCore contains application-neutral domain types. RawCull aliases its central models:

typealias FileItem = RawCullFileItem
typealias ARWSourceCatalog = RawCullSourceCatalog
typealias ExifMetadata = RawCullCore.ExifMetadata

RawCullCore also owns the burst-grouping contracts and algorithm. RawCull stores and presents its groups, candidate scores, confidence, cautions, and review state.

Ratings, tags, saliency labels, sharpness signatures, and manual burst winners are stored in:

~/Library/Application Support/RawCull/savedfiles.json

Settings are stored separately in:

~/Library/Application Support/RawCull/settings.json

DecodeGeneric loads the saved Codable array, and EncodeGeneric creates the data written atomically to Application Support.

The RAW copy workflow uses three rsync packages, coordinated by RawCull:

1. RsyncArguments builds the base argument list.
2. RawCull adds a NUL-separated --files-from list of selected tagged or rated filenames and the security-scoped source and destination paths.
3. RsyncProcessStreaming executes /usr/bin/rsync, streams progress, and supports cancellation.
4. ParseRsyncOutput converts the final output into file counts, transferred sizes, created and deleted counts, and display-ready statistics.

Vision and Metal sharpness analysis are encapsulated by PhotoAnalysisKit. Core AI inference, AI-side Vision feature prints, and subject-mask storage are encapsulated by PhotoAIKit.

• View models are @Observable, final, and @MainActor.
• Background concerns use actor-per-responsibility isolation.
• Package-boundary values and providers conform to Sendable.
• Dynamic parallel work uses structured task groups with bounded concurrency.
• Long-running scans, analysis, extraction, grouping, and copy operations support cooperative cancellation.
• Results are committed to observable state only after successful completion.
• Superseded similarity and grouping generations cannot publish stale results.

Important actors include:

RawCull/
├── Actors/                 Background scanning, caching, extraction, and persistence
├── Main/                   App entry point and shared type aliases
├── Model/
│   ├── AIIntegration/      Model validation, inference, downloads, and Deep Review
│   ├── Cache/              Cache configuration and diagnostics
│   ├── Diagnostics/        RAW, ImageIO, and similarity diagnostics
│   ├── Handlers/           App and streaming callbacks
│   ├── JSON/               Codable persistence models
│   ├── ParametersRsync/    RAW copy configuration and execution
│   └── ViewModels/         MainActor application and workflow state
├── Resources/              AI model licence notices
└── Views/                  SwiftUI catalog, grid, comparison, settings, and zoom UI

RawCullModelDownloader/     Managed Background Assets extension
ModelAssets/                Model manifests, notices, and provenance catalogs
RawCullTests/               Swift Testing suites and test architecture notes

Debug build without notarization:

make debug

Release archive, signing, notarization, stapling, and DMG generation:

make build

Clean generated build output:

make clean

The Xcode scheme builds for Apple Silicon:

xcodebuild \
  -project RawCull.xcodeproj \
  -scheme RawCull \
  -destination 'platform=OS X,arch=arm64'

Tests use Apple's Swift Testing framework. Run fast package-integration and critical smoke coverage with:

make test-smoke

Run the full suite with Thread Sanitizer:

make test-full

Run performance and extreme-concurrency coverage:

make test-performance

The suites cover package and AI integration, model download validation, semantic search, Deep Review, sharpness and focus metrics, structured cancellation, latest-run-wins behavior, memory-cache counters, security-scoped access, disk caches, burst persistence, RAW parsing adapters, and copy startup and cleanup.