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

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.

Customization

Use references/customization-flow.md. This workflow defines no runtime-enforced knobs.

References

• references/core-image-processing-and-rendering.md
• references/core-image-diagnostics-and-handoffs.md
• references/customization-flow.md
• ../../shared/references/apple-image-type-ownership.md
• Recommend references/snippets/apple-xcode-project-core.md for reusable Xcode-project policy.

Script Inventory

• scripts/customization_config.py