AnnexCREATE · Index · Manuals · AnnexPhoto

AnnexPhoto – User Manual

1. Overview

AnnexPhoto is the raster and photo editing app of the AnnexCREATE suite for macOS. It targets freelancers, sole traders and small agencies that edit images for social media, print and web.

Core benefits:

Layer-based editing with pixel layers and adjustment layers
Non-destructive image adjustments (brightness, contrast, saturation, curves, color balance) that leave the original untouched
Layer masks with a paintable grayscale brush
On-device AI subject cutout (Apple Vision, macOS 14+)
Export as JPEG, PNG, TIFF and PSD with real layers

AnnexPhoto is part of the suite's Creative-OS idea: all apps share the design system, the common document container format, local data storage (offline-first) and combine modularly – via brandkits, the asset library, the suite clipboard and open export formats.

2. Installation & Activation

AnnexPhoto is installed via AnnexHub:

Open AnnexHub and select AnnexPhoto in the app catalog.
Wait for the download; the app lands in the Applications folder.
License activation is handled centrally in AnnexHub; offline activation is possible.

The app works offline-first: it runs fully without a server connection. Documents are stored locally; iCloud integration is not wired up.

3. Basic Workflow

Import an image: File ▸ Import… or drag a file directly onto the canvas – it is inserted as a new layer and the canvas size adapts.
Organize layers: rename, reorder, show/hide or lock layers in the sidebar.
Adjust: adjust brightness, contrast and saturation of the selected layer in the inspector – non-destructive and editable at any time.
Use adjustment layers: add curves or color balance as their own layer; they affect all layers below.
Mask: add a layer mask and paint with the brush tool (black/white/gray values).
Optionally cut out: Image ▸ Cut Out Subject masks the main subject and places it as a new layer with a transparent background.
Export: File ▸ Export… as JPEG (with quality slider), PNG, TIFF or PSD.
Save: File ▸ Save… (⌘S) stores the whole project as .axphoto.

4. Core Features

The window follows the suite design system: three columns (sidebar with assets and layers, centered canvas, inspector), a custom app header and a theme manager (light/dark/system). The menu bar contains:

File ▸ Open… (⌘O) – opens an .axphoto document
File ▸ Import… – imports a file as a layer
File ▸ Save… (⌘S) – saves as .axphoto
File ▸ Export… – opens the export dialog
File ▸ Print… (⌘P)
AnnexPhoto ▸ Settings… (⌘,)
Image ▸ Cut Out Subject – AI cutout of the selected layer
Image ▸ Correct Perspective… – guided correction of the selected pixel layer
Image ▸ CMYK Soft Proof… – print preview of the document
Image ▸ Looks – apply a built-in look or import a .cube LUT

The same actions are wired to buttons in the app header. The interface language follows the system; German, English, Spanish, French and Italian are included.

4.2 Layer Model

The document (PhotoDocument) consists of pixel layers and adjustment layers. In the layer list (sidebar), layers can be selected, renamed, deleted, reordered (move up/down) and individually shown/hidden or locked. Visibility and locking apply per layer and are honored by export.

4.3 Canvas and Tools

The canvas (PhotoCanvasView) has a freely selectable canvas size; layers are moved by drag and show a selection frame. The surface is a drop target: dragging a file onto it imports it as a layer. The toolbar (PhotoToolbar) contains four tools:

Move – position layers on the canvas
Select (rectangle selection) – shows a selection
Crop – shows a crop frame as an overlay
Brush – acts on layer masks, with floating sliders for radius and strength

Status note: rectangle selection and crop are visible; an effect on the image (e.g. applying the crop) is not yet implemented.

4.4 Non-Destructive Adjustments

Per layer, brightness, contrast and saturation (PhotoAdjustment) are available in the inspector. Each adjustment can be switched on/off individually and edited later; the original image remains unchanged. The preview renders via CIColorControls.

4.5 Adjustment Layers

Adjustment layers (AdjustmentEffect) affect all layers below them:

Curves – RGB master curve with 2–8 control points, including a preview curve in the inspector
Color Balance – separate control for shadows, midtones and highlights across three color axes

Canvas preview and export use the same render path (CIToneCurve, CIColorCube) – preview and export are pixel-consistent.

4.6 Layer Masks

Each pixel layer can have an 8-bit grayscale mask (LayerMask): add, remove, invert and paint with the brush tool. The round brush paints black, white and gray values with falloff; radius and strength are controlled by the floating control.

4.7 Cut Out Subject (AI)

Image ▸ Cut Out Subject (or the toolbar button) masks the main subject of the selected layer on-device via Apple Vision (VNGenerateForegroundInstanceMaskRequest, macOS 14+) and places it as a new layer with a transparent background above. The source layer is hidden, not deleted – the action is therefore reversible (delete the new layer, show the source again). The run is asynchronous with a busy indicator; error cases (API unavailable, no subject detected, request failed, image not processable) are reported via a localized alert and AnnexLog, and the original stays unchanged. PNG export preserves the alpha channel.

4.8 Blend Modes and Opacity

Per layer, the blend modes Normal, Multiply, Screen and Overlay (PhotoBlendMode) plus an opacity slider are available in the inspector. The modes are mapped to Core Graphics (export/PSD) and the canvas rendering.

4.9 Import

Import runs through the central import engine (AnnexImportEngine, ImageImportService): images, PDF, SVG, PSD/PSB (with layers), AI and IDML are imported as layers; the canvas size adapts to the imported content. The toolbar import dialog currently limits the selection to PNG/JPEG/TIFF/images/PDF/SVG – the engine itself can handle more.

4.10 Export

File ▸ Export… opens the export dialog (PhotoExportSheet) with the formats JPEG (with quality slider), PNG, TIFF and PSD. PSD export writes real layers with opacity, visibility and masks via the PSDWriter from AnnexImportKit.

4.11 Printing

File ▸ Print… (⌘P) opens the suite's shared print pipeline (AnnexPrintSheet/AnnexPrintOperation). Printing uses the same composite pipeline as export and flattens transparency onto a white base.

4.12 Brandkits and Assets

Brandkits from AnnexAssetKit can be linked to the document in the inspector (PhotoBrandkitAssetsSection). The assets of linked brandkits appear as a grid in the asset sidebar; a click inserts them centered as a linked image layer. The link is registered in the central LinkedObjectRegistry (linkedAssetID).

4.13 Suite Clipboard

Layers can be copied and pasted between apps via the Annex-wide pasteboard payload (LayerPayload, PhotoInteropService) – with a text fallback for the system clipboard.

4.14 Looks and LUT Import

A look is a three-dimensional color table (3D LUT) applied as an adjustment layer above everything below it – non-destructive, like curves or levels. There are two sources and one application path:

Built-in looks (BuiltinLook): black and white, sepia, warm, cool, faded, punchy. Each is a recipe that becomes a 17³ table when created.
Import (ColorLUT.parseCube): Image ▸ Looks ▸ Import LUT (.cube)… reads tables in the open .cube format, the de facto standard of most look packs. Supported are 3D LUTs with LUT_3D_SIZE up to edge length 64.

The Strength slider in the inspector blends between the original (0 %) and the full table (100 %). The table is stored inside the .axphoto (as a binary blob, not as a list of numbers) – the document stays complete without the original file.

Limits: pure 1D LUTs (LUT_1D_SIZE) and tables with an edge length above 64 are rejected, with a message rather than silent no-op. .3dl, .look and other vendor formats are not read.

4.15 Correct Perspective (Guided Upright)

Image ▸ Correct Perspective… opens guided correction for the selected pixel layer (PerspectiveCorrectionSheet). Four handles sit on the image and describe a quadrilateral that should be rectangular in the scene – a facade, a door frame, a document. Apply pulls that quadrilateral axis-aligned (CIPerspectiveCorrection).

Two helpers make a suggestion without forcing it:

Detect automatically uses Apple Vision to find the largest quadrilateral (VNDetectRectanglesRequest) and places the four points on it. They remain draggable.
Level horizon determines the tilt angle (VNDetectHorizonRequest) and rotates the image by exactly that angle; the image size stays the same.

If Vision finds nothing, the dialog says so and the points stay where they are. The correction is one history step and can be undone.

4.16 Develop RAW

Importing (or opening) a RAW file brings up the development dialog (RAWDevelopSheet) instead of a finished image – a RAW file holds sensor data, not a picture. The starting values come from the shot itself ("as shot"), not from a preset. Exposure, temperature, tint, contrast, sharpness and noise reduction are adjustable. The preview renders downscaled (long edge 1200 px); Import develops at full resolution and adds the result as a pixel layer.

What the RAW foundation is – and is not. Decoding runs through the macOS RAW decoder (CIRAWFilter), the same one Preview and Photos use. Supported is exactly what macOS knows about camera models; AnnexPhoto has no sensor database of its own. Whether a file is really readable is decided by the decoder, not by the file extension – a .dng of unknown origin can be rejected despite a matching extension and then goes through the normal import path.

Not available: no re-development after import (the parameters are applied at import time and not carried as a layer), no lens correction, no camera profiles, no batch development.

4.17 CMYK Soft Proof

Image ▸ CMYK Soft Proof… runs the composited document through an installed CMYK ICC profile and back to RGB (SoftproofService). The dialog shows screen and print simulation side by side and states the share of pixels that cannot be reproduced in the chosen profile. Gamut warning marks those pixels magenta. The profile list comes from the three macOS ColorSync folders (system, machine, user).

Limits, stated plainly: this is a simulation on an uncalibrated screen and not a contract proof. And it is not CMYK output – export stays RGB.

4.18 Smart Objects

Convert a pixel layer into a Smart Object to scale and filter it non-destructively: Image ▸ Convert to Smart Object (or via the layer context menu). The Smart Object stores the original content internally; transformations and filters are applied as an editable list without altering the original.

Smart Filters can be applied to Smart Objects – e.g. blur, sharpen or noise. Each filter appears in the layers list as its own, always-editable entry. Double-clicking the Smart Object opens its content in a separate editing window; changes there affect every instance of the Smart Object in the document.

Limits: Smart Objects use more memory than ordinary pixel layers because the original content is retained. Not every filter is available as a Smart Filter; unsupported filters report this when applied.

4.19 Generative Fill (Content-Aware / Generative Fill)

Image ▸ Generative Fill… fills a selection or area based on the surrounding image. The dialog offers a prompt field for text-based control and a preview with Apply/Discard. Processing runs locally via AnnexAIKit / ComfyUI inpainting – no internet connection required.

Typical workflow: create a selection (e.g. with the Rectangle selection), remove or extend an area, add an optional prompt and click Apply. The result lands as a new layer or mask variant so the original is preserved.

Limits: Quality depends on the image material; homogeneous, textured areas (sky, grass, walls) work better than areas with complex details or sharp edges. Prompts are a control tool, not a guarantee of a specific result.

4.20 Layer Styles

The Layer Styles panel in the inspector adds non-destructive effects to a layer:

Style	Effect
Drop Shadow	Soft or hard shadow behind the image content.
Glow	Inner or outer glow around edges and areas.
Bevel & Emboss	Emboss effect with light and shadow edges.
Color Overlay	Tint the layer with an opacity slider.
Gradient Overlay	Fill with a linear or radial gradient.
Pattern Overlay	Lay a repeating pattern over the layer.

Multiple styles can be combined and toggled or edited at any time. Layer styles work on pixel layers, Smart Objects and groups.

Limits: Layer styles are rendered into the export (JPEG/PNG/PSD); in PSD export they remain as layer effects where the target format supports them.

5. Formats & Interoperability

Native format .axphoto: container based on the .axd format from AnnexCoreKit. The document stores a JSON snapshot (photo.json) with canvas size, layers (image as Base64 PNG), adjustments, blend modes, masks and linked brandkits. Open (⌘O or header button) and Save (⌘S) are wired in the app UI.

Import: PNG, JPEG, TIFF, HEIC, WebP, GIF (image adapter), SVG, PDF, AI (PDF-compatible), IDML and PSD/PSB (layer import for uncompressed RGBA layers). The toolbar import dialog currently limits the selection to PNG/JPEG/TIFF/images/PDF/SVG.

Export: JPEG (.jpg), PNG (.png), TIFF (.tiff), PSD (.psd, with layer structure).

Suite integration:

Exchange layers between apps via the suite clipboard (AnnexInteropKit)
Brandkits and asset library via AnnexAssetKit; linked objects (asset ↔ layer) via the LinkedObjectRegistry
On save, the document is written best-effort into the shared version index (SharedVersionIndexStore) and thus appears in AnnexHub's central search
iCloud/sync is not wired up – documents stay local

6. MCP Control

The MCP host runs in AnnexHub and speaks JSON-RPC 2.0 via STDIO (started via AnnexHub). This makes the app's actions automatable by local AI agents.

Suite-wide tools (all apps):

list_apps – lists all Annex apps with installation status and version
open_app – opens an Annex app by its ID
open_document – opens a file in a given app
get_active_document – returns information about the active document
get_license_status – license status of a product
search_assets – searches the central asset library by name or tags

App-specific tool:

photo.open_image – opens an image in AnnexPhoto for editing (parameter path: absolute path to the image file)

Suite-wide skills (templates for agents): suite.discover (explore the suite) and brandkit.apply (apply brandkit).

7. Diagnostics & Privacy

AnnexPhoto logs errors and actions locally via AnnexLog (AnnexDiagnosticsKit) into rotating JSON log files under ~/Library/Logs/AnnexCREATE/AnnexPhoto/, mirrored to os_log (subsystem com.annexcreative.annexphoto). The logs contain no personally identifiable information (PII filter; no paths, file names or email addresses in details). Diagnostics is enabled by default during the development phase and can be switched off in Settings (Privacy); nothing is transmitted. Telemetry runs strictly opt-in (default off) and can be toggled at any time in Settings. The app itself needs no server connection to operate.

8. FAQ

In which format does AnnexPhoto save? As an .axphoto container with the complete project state (layers, adjustments, masks, brandkit links) – locally on the Mac.

Can I export PSD with layers? Yes. PSD export writes real layers including opacity, visibility and masks.

Is there undo/redo? Not yet. Until then, non-destructive adjustments, hideable source layers and deletable result layers are the model-native way back.

Why doesn't cropping change the image? Rectangle selection and crop currently show a selection or overlay; applying them to the image is not yet implemented.

What happens to my original when cutting out a subject? The source layer is hidden, not deleted. To undo, delete the new layer and show the source again.

Does "Cut Out Subject" need an internet connection? No. Subject selection runs on-device via Apple Vision (macOS 14+).

Does the app work offline? Yes. AnnexPhoto is offline-first; documents live locally, no cloud integration is wired up.

Where do I find logs when something goes wrong? Under ~/Library/Logs/AnnexCREATE/AnnexPhoto/ (rotating JSON logs).

Layers, Zoom and Pixel-Accurate Work

Layers Panel

The Layers panel in the sidebar shows all layers of the document as a nested list. Each layer can be selected, renamed, deleted or reordered. The icons on the right control visibility, lock and printability per layer.

AnnexPhoto distinguishes two layer types:

Pixel layers contain image data, masks and layer styles.
Adjustment layers affect all layers below them non-destructively (e.g. Curves, Color Balance, Looks).

Layers can be grouped. Groups are nestable and behave like Photoshop groups: a group acts as a container for its contents, and transformations and opacity apply to the group as a whole. Use the context menu or layer menu commands to group layers and to ungroup groups.

The panel supports expanding and collapsing groups and drag & drop to move layers within the hierarchy or drop them into groups.

Compact Palettes

The Layers panel uses the suite's shared palette component (AnnexPaletteRow). All rows have a uniform height of 20 pt and share the same icon set, so layers, assets, channels and similar lists look even and compact.

Zoom

Canvas zoom is continuous from 10 % to 3200 %. The zoom control offers a logarithmic slider and percentage buttons for common values (e.g. 100 %, Fit, 200 %).

At every zoom factor, hit tolerance and controls such as handles remain proportionally scaled, so precise work is possible even at very high or very low zoom levels.

Pixel-Accurate Positioning

At zoom levels of 100 % or higher, layer position and size are rounded to whole pixels. Snapping (PhotoSnapService) helps align layers precisely to canvas edges, canvas center, and edges and centers of other layers.

The property bar shows current values as integer pixels while zoom is 100 % or higher, so the visual impression can be checked directly against the numeric values.