/core-image-processing-workflow

name: core-image-processing-workflow
description: Guide Core Image implementation and repair across CIImage processing graphs, CIContext rendering, built-in and custom filters, RAW development, color management, HDR, regions of interest, Core Video and Metal destinations, and performance diagnostics. Use when Apple-platform image work changes, generates, composites, or renders pixels rather than decoding files or recognizing image content.

Core Image Processing Workflow

Purpose

Guide Core Image processing and rendering without turning `CIImage` into a bitmap wrapper or mixing transformation with file decoding, visual recognition, or display-container ownership. Preserve Core Image, Core Graphics, Core Video, and Metal types until an explicit output boundary.

When To Use

• Use for Core Image filter chains, compositing, RAW development, custom kernels, color or HDR processing, render destinations, and Core Image performance or correctness repair.
• Recommend `apple-image-representation-workflow` when decoding, encoding, metadata, or platform image-container behavior is primary.
• Recommend the Vision workflow when the requested outcome is recognition or analysis rather than pixel transformation.

Single-Path Workflow

1. Classify the request:

• built-in filter chain
• compositing, masking, scaling, or geometry
• RAW development
• custom kernel or processor
• color, HDR, or alpha repair
• render destination or interop
• performance or correctness diagnosis

2. Apply the Apple docs gate:

• read current Core Image documentation before proposing implementation changes
• state the documented behavior relied on
• apply `../../shared/references/apple-image-type-ownership.md`
• use `references/core-image-processing-and-rendering.md` for graph, context, color, render, and performance decisions
• use `references/core-image-diagnostics-and-handoffs.md` for repair probes and ownership handoffs

3. Define the graph and ownership:

• identify the source image, extent, orientation state, color space, alpha semantics, and dynamic range
• build immutable `CIImage` transformations and keep mutable `CIFilter` instances task-local
• choose one deliberately scoped, reusable `CIContext`
• select the output bounds, format, color space, and destination before rendering

4. Repair common failure modes:

• treating `CIImage` as already-rendered pixels
• creating a new `CIContext` per frame or filter application
• sharing mutable `CIFilter` instances across concurrent work
• losing orientation, extent, alpha, color-space, HDR, or auxiliary-data meaning during conversion
• forcing CPU readback between Core Image, Core Video, and Metal without a concrete boundary
• rendering infinite or unexpectedly expanded extents without an explicit crop
• using Core Image as a recognition framework instead of handing analysis to Vision

5. Return one recommendation with:

• processing class and documented behavior
• source and output type ownership
• graph, context, color, extent, and render-destination plan
• concurrency, cancellation, memory, and performance plan
• repair findings and runtime validation handoff

Inputs

• `request`: image-processing task or code under repair.
• `processing_goal`: `filter`, `composite`, `raw`, `kernel`, `color`, `hdr`, `render`, `interop`, or `repair`.
• `platform_context`: `ios`, `ipados`, `macos`, `tvos`, `visionos`, or `mixed-apple`.
• Defaults:
• prefer current Xcode or Apple documentation
• preserve `CIImage`, `CIContext`, `CIFilter`, `CIFormat`, `CGColorSpace`, `CVPixelBuffer`, `IOSurface`, and Metal types
• preserve lazy evaluation until a real render boundary
• prefer Core Image before a custom Metal pipeline when Core Image expresses the requirement

Outputs

• `status`: `success`, `handoff`, or `blocked`.
• `path_type`: `primary` when Core Image owns the operation, `fallback` when another framework owns the next step.
• `output`: documented behavior, graph and type ownership, render plan, diagnostics, validation, and handoff.

Guards and Stop Conditions

• Do not claim a `CIImage` is rendered pixel storage; it describes an image and its processing recipe until rendered.
• Do not create generic image managers, filter coordinators, or custom pixel wrappers when framework types and direct composition express the requirement.
• Do not share mutable `CIFilter` state across concurrent tasks.
• Do not silently discard orientation, scale, metadata, color space, alpha, dynamic range, extent, or auxiliary data.
• Do not claim GPU, Metal, HDR, RAW, real-time, or zero-copy behavior is verified without runtime or profiling evidence.
• Stop when the source representation, output destination, color requirements, or device capability needed for a correct recommendation is unavailable.

Fallbacks and Handoffs

• Recommend `apple-image-representation-workflow` for Image I/O decode/encode, metadata, `CGImage`, `NSImage`, `NSImageRep`, `NSBitmapImageRep`, or `UIImage` ownership.
• Recommend `vision-image-analysis-workflow` for recognition, detection, tracking, segmentation, or feature analysis.
• Recommend `camera-capture-depth-workflow` for camera and depth capture.
• Recommend `avfoundation-media-pipeline-workflow` for capture-session, reader, writer, export, or video pipeline ownership.
• Recommend `video-codec-processing-workflow` for low-level codec and pixel-buffer work.
• Recommend `photos-library-editing-workflow` for PhotosUI selection, PhotoKit assets/resources, library changes, and nondestructive editing.
• Recommend `xcode-build-run-workflow` for project integration, Metal toolchain, build, run, device, or Instruments follow-through.
• Recommend `xcode-testing-workflow` for fixtures, image comparisons, performance baselines, or regression tests.
• Recommend `explore-apple-swift-docs` when documentation lookup is the real need.

References

• `references/core-image-processi