gronod
980b44bccb
Build Windows Packages / Build Windows (push) Successful in 7m45s
Build Linux Packages / Build Linux (push) Successful in 9m59s
Build macOS Packages / Build macOS (Intel) (push) Successful in 11m12s
Build macOS Packages / Build macOS (Apple Silicon) (push) Successful in 11m18s
Add Install Profile to System after a successful profcheck run. Copies the working-directory artefact into the platform colour store (Windows ICM, macOS ColorSync, Linux colord) without moving it. Collisions require Overwrite / Rename / Cancel; permission errors mention elevation. When printcal curves were applied (#224) the success toast records that.
173 lines
11 KiB
Markdown
173 lines
11 KiB
Markdown
# ICCery 🎨
|
||
|
||
> Modern, cross-platform native desktop application for printer profiling, powered by ArgyllCMS.
|
||
|
||
[](https://git.i3omb.com/gronod/ICCery)
|
||
[](https://git.i3omb.com/gronod/ICCery)
|
||
[](https://tauri.app)
|
||
[](LICENCE.md)
|
||
|
||
**ICCery** is a native GUI frontend designed to make creating custom ICC/ICM printer profiles seamless, visual, and reliable. It wraps the powerful color management capabilities of [ArgyllCMS](https://www.argyllcms.com/) within an intuitive, artefact-gated 5-stage wizard, with an optional printer calibration (linearization) workflow.
|
||
|
||
---
|
||
|
||
## Key Features
|
||
|
||
- 🪄 **Linear 5-Stage Wizard Workflow**:
|
||
0. **Optional — Printer Calibration (`printcal` / `applycal`)** (#224): Per-channel linearization and ink-limit discovery before a full profile. Generate a short `CAL_` chart, print and measure it with the existing Stage 2/3 engines, compute `.cal` curves, inspect channel-response plots, and toggle **Apply Calibration** so subsequent `printtarg` (`-K`) and `colprof` (`applycal`) runs consume the curves. Skip entirely for simple RGB photo printers.
|
||
1. **Stage 1 — Patch Generation (`targen`)**: Configure RGB (driver-managed) or CMYK (RIP-managed) patch sets with custom counts, profiling presets, neutral/grey axis boosting, and 11 advanced generation parameters with contextual guidance tooltips. Supports direct-resume from existing `.ti2` target files to jump straight to measurement. CMYK / RIP workflows show a reminder when no calibration is applied.
|
||
2. **Stage 2 — Target Creation & Raw Printing (`printtarg`)**: Format patch targets for handheld spectrophotometers (i1Pro, i1Pro2, ColorMunki, SpyderPrint) and automated XY tables (i1iO, SpectroScan). View high-resolution downscaled TIFF previews and print directly using native OS unmanaged pathways:
|
||
- **macOS**: Native `NSPrintPanel` driver preferences with automatic ColorSync suppression (`AP_ColorMatchingMode=AP_ApplicationColorMatching`), CUPS media type selection, and driver-specific color adjustment bypass detection (Canon `CNIJIntent2`, Epson `ColorCorrection`, Gutenprint).
|
||
- **Windows**: GDI uncorrected raw printing and DEVMODE preferences.
|
||
- **Linux**: CUPS `raw` queue and PPD media option spooling.
|
||
3. **Stage 3 — Interactive Measurement (`chartread`) & Averaging (`average`)**:
|
||
- **Automated XY Scanning Tables (#93)**: Full automated sequence for GretagMacbeth SpectroScan and X-Rite i1iO tables with multi-line prompt classification, fiducial sight alignment prompts, 4-step sequence checklist UI, and graceful head parking (`q\n`).
|
||
- **Instrument Status Feedback (#204)**: Optional `-Y l` switch support driving the dual RGB ring LEDs of the X-Rite i1Pro 2 (flashing white for calibration, flashing blue for ready/swipe, flashing red for error, flashing green for capture).
|
||
- **Interactive Controls**: Dedicated `Done & Save .ti3` (`d\n`), `Undo Strip` (`u\n`), and `Skip Strip` (`s\n`) actions.
|
||
- **Live Swatch Grid**: 135° diagonally split intended-vs-measured colour patches with live CIEDE2000 ($\Delta E_{00}$) quality indicators, white reference patch preservation, and user-configurable good/warning traffic-light thresholds persisted across sessions.
|
||
- **Noise Reduction**: Multi-pass sheet averaging (`average`) to eliminate spectrophotometer noise.
|
||
4. **Stage 4 — Profile Calculation (`colprof`)**: Generate high-precision cLUT mathematical ICC/ICM profiles with configurable algorithm quality, OBA/FWA compensation (`-f`), illuminant (`-i`) and observer (`-o`) overrides, viewing-condition transforms (`-c`, `-d`), custom ambient spectrum support, descriptions, and copyright tagging.
|
||
5. **Stage 5 — Verification, Drift Analytics & 3D Gamut (`profcheck` + `iccgamut`)**:
|
||
- **Longitudinal Printer Drift Analytics (#95)**: Historical verification logging persisted to `verification_history.json` (up to 1,000 records), an interactive dual-series SVG trend chart with shaded ICCery verification reference bands, consecutive-breach alert recommendation card (detecting drift across distinct dates or $\ge 1$ hour apart), and RFC-4180 compliant CSV export.
|
||
- **Mathematical Accuracy Report**: Peak, Average, and RMS CIEDE2000 metrics with robust parsing of both Argyll JSON summaries (`-u`) and legacy plain-text reports.
|
||
- **Interactive 3D Gamut Viewer**: CIELAB coordinate scaffold with crisp CSS2D labels, per-vertex true-colour profile gamut shading, layer visibility toggles and opacity sliders, camera reset (press **R**), touch controls, and bundled sRGB reference wireframe comparison.
|
||
- **Install Profile to System (#223)**: After a successful verification, copy the ICC/ICM into the OS colour-management store (Windows ICM Color folder, macOS ColorSync Profiles, Linux colord / `~/.local/share/icc`) without moving the working-directory artefact. Collisions prompt Overwrite / Rename / Cancel.
|
||
- 📊 **CGATS Dataset Interoperability (#94)**: Native parser for external CGATS and Argyll `.ti3` datasets with canonical normalization (0–255 scaling, field aliasing, metadata synthesis) and direct-jump workflows to Stage 4 (Profile Calculation) and Stage 5 (Verification).
|
||
- 📋 **Profiling Presets**: One-click configuration presets (Standard RGB Photo, High-Gamut CMYK Proofing, Fast RGB Draft) with custom preset export/import and security validation.
|
||
- 🍎 **macOS Universal Binary**: Native Apple Silicon (`arm64`) and Intel (`x86_64`) support with universal binary bundling and fallback resolution.
|
||
- 🐧 **Linux glibc Compatibility**: Pre-built Linux packages compiled with Ubuntu 22.04 LTS compatibility for Debian/Ubuntu environments.
|
||
- 🛡️ **Disk Artefact Gating**: Stepper navigation strictly verifies generated artefacts on disk (`.ti1` → `.ti2` → `.ti3` → `.icc`/`.icm`), preventing out-of-order execution while preserving backward navigation.
|
||
- 🌐 **Platform-Aware**: Automatic handling of platform profile conventions (`.icm` on Windows, `.icc` on macOS/Linux) and native OS printer subsystems.
|
||
- 🎛️ **Standardised UI Design**: Tiered button sizing (`.btn-sm`, `.btn-md`, `.btn-lg`, `.btn-icon-sq`) and consistent action row layouts provide a uniform, responsive interface across all stages.
|
||
- ⚖️ **Clean AGPL Boundary**: Complete isolation of AGPLv3 binaries via asynchronous tokio IPC process pipelines.
|
||
|
||
---
|
||
|
||
## Architectural Overview
|
||
|
||
ICCery is built on **Tauri v2** and **Rust**, coupled with a reactive Vanilla JavaScript frontend and **Three.js** WebGL visualization:
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
subgraph Host ["ICCery Host (Tauri + Rust + Vanilla JS)"]
|
||
UI[Wizard UI & Swatch Grid]
|
||
ThreeJS[3D CIELAB Gamut Viewer]
|
||
State[Wizard State & Artefact Verifier]
|
||
QualityStore[Verification History & Drift Analytics]
|
||
PrintEngine["Raw Print Subsystem (GDI / CUPS / NSPrintPanel)"]
|
||
ProcMgr[Async Subprocess IPC Manager]
|
||
CalStore[Calibration .cal library]
|
||
|
||
UI <--> State
|
||
State <--> ProcMgr
|
||
State <--> QualityStore
|
||
State <--> CalStore
|
||
ProcMgr --> ThreeJS
|
||
UI --> PrintEngine
|
||
QualityStore --> UI
|
||
end
|
||
|
||
subgraph Argyll ["ArgyllCMS Subprocesses (AGPLv3)"]
|
||
BIN_TAR[targen]
|
||
BIN_PRT[printtarg]
|
||
BIN_CHR[chartread]
|
||
BIN_CAL[printcal / applycal]
|
||
BIN_COL[colprof]
|
||
BIN_CHK[profcheck]
|
||
BIN_GAM[iccgamut]
|
||
end
|
||
|
||
ProcMgr -- stdin/stdout/stderr pipes --> BIN_TAR
|
||
ProcMgr -- stdin/stdout/stderr pipes --> BIN_PRT
|
||
ProcMgr -- stdin/stdout/stderr pipes --> BIN_CHR
|
||
ProcMgr -- stdin/stdout/stderr pipes --> BIN_CAL
|
||
ProcMgr -- stdin/stdout/stderr pipes --> BIN_COL
|
||
ProcMgr -- stdin/stdout/stderr pipes --> BIN_CHK
|
||
ProcMgr -- stdin/stdout/stderr pipes --> BIN_GAM
|
||
```
|
||
|
||
---
|
||
|
||
## Building from Source
|
||
|
||
### Prerequisites
|
||
- [Node.js](https://nodejs.org/) (v18 or newer)
|
||
- [Rust](https://www.rust-lang.org/) (1.78+ stable)
|
||
- Operating system dependencies:
|
||
- **macOS**: macOS 12.0 (Monterey) or newer, Xcode Command Line Tools (`xcode-select --install`).
|
||
- **Windows**: Microsoft Visual Studio C++ Build Tools & WebView2 runtime.
|
||
- **Linux (Debian/Ubuntu)**: `libwebkit2gtk-4.1-dev`, `build-essential`, `curl`, `wget`, `file`, `libxdo-dev`, `libssl-dev`, `libayatana-appindicator3-dev`, `librsvg2-dev`, `libcups2-dev`.
|
||
|
||
### Development Mode
|
||
```bash
|
||
# Clone the repository
|
||
git clone https://git.i3omb.com/gronod/ICCery.git
|
||
cd ICCery
|
||
|
||
# Install frontend dependencies
|
||
npm install
|
||
|
||
# Download ArgyllCMS sidecars for this OS (from github.com/Gronod/argyllcms/releases)
|
||
npm run fetch-argyll
|
||
|
||
# Run the development app
|
||
npm run tauri dev
|
||
```
|
||
|
||
> **Notes:**
|
||
> - Sidecars are not stored in git; `tauri build` / `tauri dev` will fail until `npm run fetch-argyll` has been run at least once.
|
||
> - You can override the downloaded ArgyllCMS release version using `ARGYLL_RELEASE_TAG=vX.Y.Z npm run fetch-argyll`.
|
||
> - On Windows, the NSIS installer package bundles the ArgyllCMS USB instrument driver suite and offers an optional driver setup step when run with administrative privileges.
|
||
|
||
### Production Build
|
||
```bash
|
||
# Download sidecars (if not already fetched)
|
||
npm run fetch-argyll
|
||
|
||
# Build desktop packages
|
||
# - macOS: .dmg / .app bundle (Intel, Apple Silicon, or Universal with --target universal-apple-darwin)
|
||
# - Windows: .exe (NSIS) / .msi installer
|
||
# - Linux: .AppImage / .deb package
|
||
npm run tauri build
|
||
```
|
||
|
||
---
|
||
|
||
## Platform support
|
||
|
||
### macOS
|
||
|
||
The packaged app declares `LSMinimumSystemVersion = 12.0`. Installers refuse Catalina and Big Sur rather than launching into a WKWebView crash loop.
|
||
|
||
| macOS | Status |
|
||
|---|---|
|
||
| 13+ (Ventura and newer), Apple Silicon | Supported |
|
||
| 13+, Intel | Supported |
|
||
| 12.7.x Monterey, Apple Silicon | Supported, WebGL best-effort |
|
||
| 12.0–12.6 Monterey, Intel | Best-effort; WebGL is deferred until Stage 5; known WKWebView GPU process crashes |
|
||
| 11 Big Sur | Not supported (installer refuses) |
|
||
| 10.15 Catalina | Not supported |
|
||
|
||
The 3D gamut viewer (Stage 5) creates a WebGL context only when that stage is shown. Stages 1–4 remain usable if WebGL is missing or the GPU process is lost.
|
||
|
||
### macOS troubleshooting
|
||
|
||
If the window flashes white and disappears, this is almost always the WKWebView **Web Content** or **GPU** helper dying — Apple Crash Reporter will not attach to `ICCery.app`.
|
||
|
||
- Launch from Terminal to see `web content process terminated`:
|
||
```text
|
||
/Applications/ICCery.app/Contents/MacOS/ICCery
|
||
```
|
||
- Check `~/Library/Logs/DiagnosticReports` for `com.apple.WebKit.WebContent` or `com.apple.WebKit.GPU`.
|
||
- ICCery log file (rotated, last 5 segments kept):
|
||
```text
|
||
~/Library/Logs/com.gronod.iccery/iccery.log
|
||
```
|
||
- Custom ColorSync display profiles can crash toolkit UIs on Monterey. Testing with the default display profile (or Safe Mode) is a valid support question.
|
||
|
||
---
|
||
|
||
## Licence
|
||
|
||
The ICCery GUI application is proprietary software licensed under the terms of the [EULA](LICENCE.md). ArgyllCMS binaries and source code are licensed under the GNU Affero General Public License (AGPLv3).
|