Technical Details on RawCull

Swift Concurrency in RawCull

Thu, 26 Mar 2026 00:00:00 +0000

Swift Concurrency in RawCull

A summarized document about Concurrency in RawCull.

1 Why Concurrency Matters in RawCull

RawCull is a macOS photo-culling application that works with Sony A1 ARW raw files. A single RAW file from the A1 can be 50–80 MB. When you open a folder with hundreds of shots, the app must scan metadata, extract embedded JPEG previews, decode thumbnails, and manage a multi-gigabyte in-memory cache — all while keeping the UI perfectly fluid and responsive at 60 fps. Without concurrency that would be impossible.

Sharpness Scoring

Wed, 25 Mar 2026 00:00:00 +0000

Updated Sharpness Scoring in RawCull

This document describes how RawCull computes sharpness scores, what each parameter does, and a boundary-value test procedure for validating parameter behaviour. This applies to version 1.3.7 of RawCull

How the Scoring Pipeline Works

flowchart TD
 A([ARW File]) --> B[Thumbnail decode\nthumbnailMaxPixelSize]
 A --> C[Saliency detection\nApple Vision]

 B --> D[Gaussian pre-blur\npreBlurRadius × isoFactor × resFactor]
 D --> E[Laplacian Metal kernel\nfocusLaplacian]
 E --> F[Amplify\nenergyMultiplier]
 F --> G[Border suppression\nborderInsetFraction]
 G --> H[Render to Float32 buffer]

 H --> I[Full-frame samples\nborder-inset region]
 C -->|bounding box ≥ 3% area| J[Salient-region samples\nVision bounding box]
 H --> J

 I --> K[p95 winsorized tail score\nfull-frame f]
 J --> L[p95 winsorized tail score\nsubject s]

 K --> M{Fusion}
 L --> M
 C -->|area| M

 M --> N[finalScore]
 N --> O([Badge: score / maxScore × 100])

 style A fill:#2d2d2d,color:#fff
 style O fill:#2d2d2d,color:#fff

Each ARW file goes through the following stages in detail:

Memory Cache

Tue, 17 Mar 2026 00:00:00 +0000

Cache System — RawCull

RawCull uses a three-layer cache to avoid repeated RAW decoding. Decoding an ARW file on demand is expensive — the three-layer approach ensures that most requests are served from RAM or disk rather than from source.

Layers (fastest to slowest):

Memory cache — NSCache<NSURL, DiscardableThumbnail> in RAM
Disk cache — JPEG files on disk in ~/Library/Caches/no.blogspot.RawCull/Thumbnails/
Source decode — CGImageSourceCreateThumbnailAtIndex from the ARW file

The same cache stack is shared by two paths: the bulk preload flow (ScanAndCreateThumbnails) and on-demand per-file requests (RequestThumbnail).

Thumbnails

Tue, 17 Mar 2026 00:00:00 +0000

Thumbnails and Previews — RawCull

RawCull handles Sony ARW files through two distinct image paths:

Generated thumbnails — fast, sized-down previews for browsing and culling, extracted with ImageIO and cached in RAM and on disk
Embedded JPEG previews — full-resolution embedded JPEGs extracted from the ARW binary for high-quality inspection and export

Both paths integrate with the shared three-layer cache system: RAM → disk → source decode.

1. Thumbnail Sizes and Settings

All thumbnail dimensions are configurable via SettingsViewModel and persisted to ~/Library/Application Support/RawCull/settings.json.

Scan and Thumbnail Pipeline

Wed, 25 Mar 2026 00:00:00 +0000

RawCull — Scan and Thumbnail Pipeline

This document describes the complete execution flow from the moment a user opens a catalog folder to the point where all thumbnails are visible in the grid. It covers the actors involved, the data flow between them, the concurrency model, five performance bugs that were found and fixed, and the measured results on a real catalog of 809 Sony A1 ARW files stored on an external 800 MB/s SSD.

Sony MakerNote Parser

Wed, 25 Mar 2026 00:00:00 +0000

Sony MakerNote Parser — Focus Point Extraction

Files covered:

RawCull/Enum/SonyMakerNoteParser.swift

RawCull/Model/ViewModels/FocusPointsModel.swift

RawCull/Actors/ScanFiles.swift

RawCull/Views/FocusPoints/FocusOverlayView.swift

Overview

RawCull extracts autofocus (AF) focus point coordinates directly from Sony ARW raw files without requiring any external tools such as exiftool. The parser supports the ILCE-1 (A1), ILCE-1M2 (A1 II), ILCE-7M5 (A7 V), ILCE-7RM5 (A7R V), and ILCE-9M3 (A9 III).

The focus location is stored inside the Sony proprietary MakerNote block embedded in the EXIF data of every ARW file. SonyMakerNoteParser (declared as an enum to prevent instantiation) navigates the binary TIFF structure to locate and decode this data. It also exposes helpers for locating and reading the three JPEG images embedded in every ARW file, and a verbose diagnostic walk used by the body-compatibility test suite.

Concurrency model

Tue, 17 Mar 2026 00:00:00 +0000

Concurrency Model — RawCull

Files covered:

RawCull/Model/ViewModels/RawCullViewModel.swift

RawCull/Views/RawCullSidebarMainView/extension+RawCullView.swift

RawCull/Actors/ScanFiles.swift

RawCull/Actors/ScanAndCreateThumbnails.swift

RawCull/Actors/ExtractAndSaveJPGs.swift

RawCull/Actors/ThumbnailLoader.swift

RawCull/Actors/RequestThumbnail.swift

RawCull/Actors/SharedMemoryCache.swift

RawCull/Actors/DiskCacheManager.swift

RawCull/Actors/SaveJPGImage.swift

RawCull/Enum/SonyThumbnailExtractor.swift

RawCull/Enum/JPGSonyARWExtractor.swift

Overview

RawCull uses Swift structured concurrency (async/await, Task, TaskGroup, and actor) across four primary flows:

Flow	Entry point	Core actor(s)	Purpose
Catalog scan	`RawCullViewModel.handleSourceChange(url:)`	`ScanFiles`	Scan ARW files, extract metadata, load focus points
Thumbnail preload	`RawCullViewModel.handleSourceChange(url:)`	`ScanAndCreateThumbnails`	Bulk-populate the thumbnail cache for a selected catalog
JPG extraction	`extension+RawCullView.extractAllJPGS()`	`ExtractAndSaveJPGs`	Extract embedded JPEG previews and save to disk
On-demand thumbnails	UI grid + detail views	`ThumbnailLoader`, `RequestThumbnail`	Rate-limited, cached per-file thumbnail retrieval

The two long-running operations (thumbnail preload and JPG extraction) share a two-level task pattern:

Synchronous Code

Thu, 19 Feb 2026 00:00:00 +0000

A Guide to Handling Heavy Synchronous Code in Swift Concurrency

This post explains why CPU-intensive synchronous code (such as image decoding via ImageIO) must be dispatched off the Swift Concurrency thread pool, and shows the correct patterns RawCull uses to do so.

`DispatchQueue.global(qos:)` — QoS Levels Compared

The key difference is priority and resource allocation by the system.

`.userInitiated`

Priority: High (just below .userInteractive)
Use case: Work the user directly triggered and is actively waiting for — e.g., loading a document they tapped, parsing data to display a screen
Expected duration: Near-instantaneous to a few seconds
System behavior: Gets more CPU time and higher thread priority — the system treats this as urgent
Energy impact: Higher

`.utility`

Priority: Low-medium
Use case: Long-running work the user is aware of but not blocked by — e.g., downloading files, importing data, periodic syncs, progress-bar tasks
Expected duration: Seconds to minutes
System behavior: Balanced CPU/energy trade-off; the system throttles this more aggressively under load or low battery
Energy impact: Lower (system may apply energy efficiency optimizations)

Quick Comparison

	`.userInitiated`	`.utility`
Priority	High	Low-medium
User waiting?	Yes, directly	Aware but not blocked
Duration	< a few seconds	Seconds to minutes
CPU allocation	Aggressive	Conservative
Battery impact	Higher	Lower
Thread pool	Higher-priority threads	Lower-priority threads

Rule of thumb

// User tapped "Load" and is staring at a spinner → userInitiated
DispatchQueue.global(qos: .userInitiated).async {
 let data = loadCriticalData()
}

// Background sync / download with a progress bar → utility
DispatchQueue.global(qos: .utility).async {
 downloadLargeFile()
}

If you use .userInitiated for everything, you waste battery and CPU on non-urgent work. If you use .utility for user-blocking tasks, the UI will feel sluggish because the system may deprioritize the work.

Security-Scoped URLs

Thu, 05 Feb 2026 00:00:00 +0000

Security-scoped URLs are a cornerstone of macOS App Sandbox security. RawCull uses them to gain persistent, user-approved access to source and destination folders while remaining fully sandbox-compliant. This article walks through exactly how the implementation works, tracing the code from user interaction through to file operations.

What Are Security-Scoped URLs?

A security-scoped URL is a special file URL that carries a cryptographic capability granted by macOS, representing explicit user consent to access a specific file or folder. Without it, a sandboxed app cannot read or write anything outside its own container.

Compiling RawCull

Sun, 01 Feb 2026 00:00:00 +0000

Overview

There are three methods to compile RawCull: one without an Apple Developer account and two with an Apple Developer account. Regardless of the method used, it is straightforward to compile RawCull, as it is not dependent on any third-party code or library.

The easiest method is by using the included Makefile. The default make in /usr/bin/make does the job.

Compile by make

If you have an Apple Developer account, you should open the RawCull project and replace the Signing & Capabilities section with your own Apple Developer ID before using make and the procedure outlined below.

Technical Details on RawCull

Swift Concurrency in RawCull

Swift Concurrency in RawCull

1 Why Concurrency Matters in RawCull

Sharpness Scoring

Updated Sharpness Scoring in RawCull

How the Scoring Pipeline Works

Memory Cache

Cache System — RawCull

Thumbnails

Thumbnails and Previews — RawCull

1. Thumbnail Sizes and Settings

Scan and Thumbnail Pipeline

RawCull — Scan and Thumbnail Pipeline

Sony MakerNote Parser

Sony MakerNote Parser — Focus Point Extraction

Overview

Concurrency model

Concurrency Model — RawCull

Overview

Synchronous Code

A Guide to Handling Heavy Synchronous Code in Swift Concurrency

DispatchQueue.global(qos:) — QoS Levels Compared

.userInitiated

.utility

Quick Comparison

Rule of thumb

Security-Scoped URLs

What Are Security-Scoped URLs?

Compiling RawCull

Overview

Compile by make

`DispatchQueue.global(qos:)` — QoS Levels Compared

`.userInitiated`

`.utility`