core-image-processing-workflow

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