@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/vision-framework/references/vision-requests.md

@@ -1,736 +1,614 @@
-# Vision Request Patterns
+# Vision request recipes
 
-Complete implementation patterns for Vision framework requests covering text
-recognition, face detection, barcode scanning, segmentation, classification,
-and video processing. All patterns target iOS 26+ with Swift 6.3 unless noted.
+Longer examples for the requests summarized in `../SKILL.md`. Swift-native
+examples need iOS 18 or later unless marked otherwise; legacy examples are
+labelled.
 
 ## Contents
-- Complete Text Recognition Pipeline
-- Face Detection with Landmarks
-- Barcode Detection with All Symbologies
-- Person Segmentation with Mask Application
-- Instance Segmentation (iOS 18+)
-- Image Classification
-- Saliency Detection
-- Rectangle Detection
-- Horizon Detection
-- Batch Processing Multiple Requests
-- Video Frame Processing with CMSampleBuffer
-- Object Tracking Across Video Frames
-- Coordinate Normalization Utilities
-- Performance Considerations
-
-## Complete Text Recognition Pipeline
-
-Full pipeline from image loading through text extraction with coordinate mapping.
 
-```swift
-import Vision
-import UIKit
+- [Text recognition pipeline](#text-recognition-pipeline)
+- [Faces with landmarks and quality](#faces-with-landmarks-and-quality)
+- [Barcodes](#barcodes)
+- [Person segmentation and background blur](#person-segmentation-and-background-blur)
+- [Classification](#classification)
+- [Saliency](#saliency)
+- [Rectangles](#rectangles)
+- [Horizon](#horizon)
+- [Several requests on one image](#several-requests-on-one-image)
+- [Camera frames from AVFoundation](#camera-frames-from-avfoundation)
+- [Tracking across frames](#tracking-across-frames)
+- [Coordinate helpers](#coordinate-helpers)
+- [Performance](#performance)
 
-@MainActor
-final class TextRecognizer {
-    func recognizeText(in image: UIImage) async throws -> [RecognizedTextBlock] {
-        guard let cgImage = image.cgImage else {
-            throw TextRecognitionError.invalidImage
-        }
+## Text recognition pipeline
 
-        var request = RecognizeTextRequest()
-        request.recognitionLevel = .accurate
-        request.recognitionLanguages = [
-            Locale.Language(identifier: "en-US"),
-        ]
-        request.usesLanguageCorrection = true
+A reusable reader that turns a `UIImage` into lines with pixel-space frames.
 
-        let observations = try await request.perform(on: cgImage)
-        let imageSize = CGSize(
-            width: cgImage.width,
-            height: cgImage.height
-        )
+```swift
+import UIKit
+import Vision
 
-        return observations.compactMap { observation in
-            guard let candidate = observation.topCandidates(1).first else { return nil }
-            let boundingBox = observation.boundingBox
-            let imageRect = VNImageRectForNormalizedRect(
-                boundingBox,
-                Int(imageSize.width),
-                Int(imageSize.height)
-            )
-            return RecognizedTextBlock(
-                text: candidate.string,
-                confidence: candidate.confidence,
-                boundingBox: imageRect
-            )
-        }
+extension RecognizedTextObservation {
+    var bestString: String? {
+        topCandidates(1).first?.string
     }
 }
 
-struct RecognizedTextBlock: Sendable {
+struct ScannedLine: Sendable {
     let text: String
     let confidence: Float
-    let boundingBox: CGRect
+    let frame: CGRect
 }
 
-enum TextRecognitionError: Error {
-    case invalidImage
+enum ReceiptReaderError: Error {
+    case noBitmap
+}
+
+struct ReceiptReader {
+    func lines(in picture: UIImage) async throws -> [ScannedLine] {
+        guard let bitmap = picture.cgImage else { throw ReceiptReaderError.noBitmap }
+        var request = RecognizeTextRequest()
+        request.recognitionLevel = .accurate
+        request.recognitionLanguages = [Locale.Language(identifier: "en-CA")]
+        request.usesLanguageCorrection = true
+        let found = try await request.perform(on: bitmap)
+        return found.compactMap { observation in
+            guard let best = observation.topCandidates(1).first else {
+                return nil
+            }
+            let frame = VNImageRectForNormalizedRect(
+                observation.boundingBox.cgRect, bitmap.width, bitmap.height
+            )
+            return ScannedLine(text: best.string, confidence: best.confidence, frame: frame)
+        }
+    }
 }
 ```
 
-### Text Recognition with Language Hints
+The `bestString` extension is reused by later examples. `boundingBox` is a
+`NormalizedRect`; pass `.cgRect` to the C helper, or call
+`boundingBox.toImageCoordinates(size, origin: .upperLeft)` to get a top-left
+rectangle in one step.
+
+### Several languages and domain words
 
 ```swift
-func recognizeMultilingualText(in cgImage: CGImage) async throws -> [String] {
+import Vision
+
+func multilingualRequest() -> RecognizeTextRequest {
     var request = RecognizeTextRequest()
-    request.recognitionLevel = .accurate
     request.recognitionLanguages = [
+        Locale.Language(identifier: "nl-NL"),
         Locale.Language(identifier: "en-US"),
-        Locale.Language(identifier: "fr-FR"),
-        Locale.Language(identifier: "de-DE"),
+        Locale.Language(identifier: "es-ES")
     ]
-    request.usesLanguageCorrection = true
-    request.customWords = ["iOS", "SwiftUI", "Xcode"]
-
-    let observations = try await request.perform(on: cgImage)
-    return observations.compactMap { $0.topCandidates(1).first?.string }
+    request.customWords = ["visionOS", "TestFlight", "Xcode"]
+    return request
 }
 ```
 
-### Fast Text Recognition for Live Video
+List languages in priority order. `customWords` keeps the corrector from
+"fixing" product names and jargon.
+
+### Fast recognition on camera frames
 
 ```swift
-func recognizeTextFast(in sampleBuffer: CMSampleBuffer) async throws -> [String] {
+import CoreMedia
+import Vision
+
+func quickLines(in frame: CMSampleBuffer) async throws -> [String] {
     var request = RecognizeTextRequest()
     request.recognitionLevel = .fast
-    request.recognitionLanguages = [Locale.Language(identifier: "en-US")]
-
-    let observations = try await request.perform(on: sampleBuffer)
-    return observations.compactMap { $0.topCandidates(1).first?.string }
+    let found = try await request.perform(on: frame)
+    return found.compactMap(\.bestString)
 }
 ```
 
-### Legacy Text Recognition (Pre-iOS 18)
+A `CMSampleBuffer` goes straight into `perform(on:)`; no conversion needed.
+
+### Legacy version with a completion wrapper
 
 ```swift
 import Vision
 
-func recognizeTextLegacy(
-    in cgImage: CGImage,
-    completion: @escaping ([String]) -> Void
-) {
-    let request = VNRecognizeTextRequest { request, error in
-        guard error == nil,
-              let observations = request.results as? [VNRecognizedTextObservation]
-        else {
-            completion([])
-            return
-        }
-        let strings = observations.compactMap {
-            $0.topCandidates(1).first?.string
+func legacyLines(in bitmap: CGImage) async throws -> [String] {
+    try await withCheckedThrowingContinuation { continuation in
+        DispatchQueue.global(qos: .userInitiated).async {
+            let request = VNRecognizeTextRequest { finished, failure in
+                if let failure {
+                    continuation.resume(throwing: failure)
+                    return
+                }
+                let found = finished.results as? [VNRecognizedTextObservation] ?? []
+                continuation.resume(returning: found.compactMap { $0.topCandidates(1).first }.map(\.string))
+            }
+            request.recognitionLevel = .accurate
+            request.recognitionLanguages = ["en-US", "pt-BR"]
+            do {
+                try VNImageRequestHandler(cgImage: bitmap).perform([request])
+            } catch {
+                continuation.resume(throwing: error)
+            }
         }
-        completion(strings)
-    }
-    request.recognitionLevel = .accurate
-    request.recognitionLanguages = ["en-US"]
-    request.usesLanguageCorrection = true
-
-    let handler = VNImageRequestHandler(cgImage: cgImage)
-    DispatchQueue.global(qos: .userInitiated).async {
-        try? handler.perform([request])
     }
 }
 ```
 
-## Face Detection with Landmarks
+`VNRecognizeTextRequest` needs iOS 13. When `perform` throws, the completion
+does not run, so the continuation is resumed exactly once either way.
+
+## Faces with landmarks and quality
+
+Run the three requests and join the results by position. Guard every index,
+because the arrays are not guaranteed to line up in length.
 
 ```swift
 import Vision
 
-struct DetectedFace: Sendable {
-    let boundingBox: CGRect
-    let landmarks: FaceLandmarkPoints?
-    let roll: Measurement<UnitAngle>
-    let yaw: Measurement<UnitAngle>
-    let captureQuality: FaceObservation.CaptureQuality?
-}
-
-struct FaceLandmarkPoints: Sendable {
-    let leftEye: [CGPoint]
-    let rightEye: [CGPoint]
-    let nose: [CGPoint]
-    let outerLips: [CGPoint]
-    let faceContour: [CGPoint]
-}
-
-func detectFaces(in cgImage: CGImage) async throws -> [DetectedFace] {
-    // Detect face rectangles
-    let rectRequest = DetectFaceRectanglesRequest()
-    let faces = try await rectRequest.perform(on: cgImage)
-
-    // Detect landmarks for detailed features
-    let landmarkRequest = DetectFaceLandmarksRequest()
-    let landmarkFaces = try await landmarkRequest.perform(on: cgImage)
-
-    // Detect capture quality for photo selection
-    let qualityRequest = DetectFaceCaptureQualityRequest()
-    let qualityFaces = try await qualityRequest.perform(on: cgImage)
-
-    return faces.enumerated().map { index, face in
-        let landmarks: FaceLandmarkPoints?
-        if index < landmarkFaces.count,
-           let lm = landmarkFaces[index].landmarks {
-            landmarks = FaceLandmarkPoints(
-                leftEye: lm.leftEye?.normalizedPoints ?? [],
-                rightEye: lm.rightEye?.normalizedPoints ?? [],
-                nose: lm.nose?.normalizedPoints ?? [],
-                outerLips: lm.outerLips?.normalizedPoints ?? [],
-                faceContour: lm.faceContour?.normalizedPoints ?? []
-            )
-        } else {
-            landmarks = nil
-        }
-
-        let quality: FaceObservation.CaptureQuality?
-        if index < qualityFaces.count {
-            quality = qualityFaces[index].captureQuality
-        } else {
-            quality = nil
-        }
+struct FaceReport: Sendable {
+    let box: NormalizedRect
+    let eyes: [NormalizedPoint]
+    let nose: [NormalizedPoint]
+    let mouth: [NormalizedPoint]
+    let outline: [NormalizedPoint]
+    let quality: FaceObservation.CaptureQuality?
+}
 
-        return DetectedFace(
-            boundingBox: face.boundingBox,
-            landmarks: landmarks,
-            roll: face.roll,
-            yaw: face.yaw,
-            captureQuality: quality
+func faceReports(in portrait: CGImage) async throws -> [FaceReport] {
+    let boxes = try await DetectFaceRectanglesRequest().perform(on: portrait)
+    let marks = try await DetectFaceLandmarksRequest().perform(on: portrait)
+    let scores = try await DetectFaceCaptureQualityRequest().perform(on: portrait)
+
+    return boxes.indices.map { i in
+        let landmarks = i < marks.count ? marks[i].landmarks : nil
+        return FaceReport(
+            box: boxes[i].boundingBox,
+            eyes: (landmarks?.leftEye.points ?? []) + (landmarks?.rightEye.points ?? []),
+            nose: landmarks?.nose.points ?? [],
+            mouth: landmarks?.outerLips.points ?? [],
+            outline: landmarks?.faceContour.points ?? [],
+            quality: i < scores.count ? scores[i].captureQuality : nil
         )
     }
 }
 ```
 
-## Barcode Detection with All Symbologies
+`FaceObservation.CaptureQuality` exposes `score`. To match faces reliably
+instead of by index, set `inputFaceObservations` on the landmark or quality
+request to the rectangles you already found.
+
+## Barcodes
 
 ```swift
 import Vision
 
-struct DetectedBarcode: Sendable {
+struct ScannedCode: Sendable {
     let payload: String?
-    let symbology: VNBarcodeSymbology
-    let boundingBox: CGRect
+    let kind: BarcodeSymbology
+    let box: NormalizedRect
 }
 
-func detectBarcodes(
-    in cgImage: CGImage,
-    symbologies: [VNBarcodeSymbology] = [.qr, .ean13, .code128]
-) async throws -> [DetectedBarcode] {
+func codes(in label: CGImage,
+           accepting kinds: [BarcodeSymbology] = [.qr, .ean13, .code128]) async throws -> [ScannedCode] {
     var request = DetectBarcodesRequest()
-    request.symbologies = symbologies
-
-    let observations = try await request.perform(on: cgImage)
-    return observations.map { barcode in
-        DetectedBarcode(
-            payload: barcode.payloadString,
-            symbology: barcode.symbology,
-            boundingBox: barcode.boundingBox
-        )
+    request.symbologies = kinds
+    return try await request.perform(on: label).map {
+        ScannedCode(payload: $0.payloadString, kind: $0.symbology, box: $0.boundingBox)
     }
 }
 
-// Detect only QR codes with URL content
-func detectQRCodes(in cgImage: CGImage) async throws -> [URL] {
+func firstLink(in poster: CGImage) async throws -> URL? {
     var request = DetectBarcodesRequest()
     request.symbologies = [.qr]
-
-    let observations = try await request.perform(on: cgImage)
-    return observations.compactMap { barcode in
-        guard let payload = barcode.payloadString else { return nil }
-        return URL(string: payload)
-    }
+    let payload = try await request.perform(on: poster).first?.payloadString
+    return payload.flatMap(URL.init(string:))
 }
 ```
 
-### Supported Symbologies Reference
+The Swift-native type is `BarcodeSymbology`; the legacy and VisionKit APIs use
+`VNBarcodeSymbology`. Both carry the same names.
 
-```swift
-// 1D barcodes
-let linearSymbologies: [VNBarcodeSymbology] = [
-    .codabar, .code39, .code39Checksum, .code39FullASCII,
-    .code39FullASCIIChecksum, .code93, .code93i, .code128,
-    .ean8, .ean13, .gs1DataBar, .gs1DataBarExpanded,
-    .gs1DataBarLimited, .i2of5, .i2of5Checksum, .itf14,
-    .msiPlessey, .upce,
-]
-
-// 2D barcodes
-let matrixSymbologies: [VNBarcodeSymbology] = [
-    .qr, .aztec, .dataMatrix, .pdf417, .microPDF417, .microQR,
-]
-```
+Two-dimensional: `.aztec`, `.dataMatrix`, `.microPDF417`, `.microQR`,
+`.pdf417`, `.qr`.
 
-## Person Segmentation with Mask Application
+One-dimensional: `.codabar`, `.code128`, `.code39`, `.code39Checksum`,
+`.code39FullASCII`, `.code39FullASCIIChecksum`, `.code93`, `.code93i`,
+`.ean13`, `.ean8`, `.gs1DataBar`, `.gs1DataBarExpanded`, `.gs1DataBarLimited`,
+`.i2of5`, `.i2of5Checksum`, `.itf14`, `.msiPlessey`, `.upce`.
 
-### Modern API (iOS 18+)
+`supportedSymbologies` on the request lists what the current revision can read.
+
+## Person segmentation and background blur
+
+The mask comes back smaller than the photo, so scale it to the photo's extent
+before blending.
 
 ```swift
-import Vision
 import CoreImage
 import CoreImage.CIFilterBuiltins
+import Vision
 
-func segmentPerson(in cgImage: CGImage) async throws -> CIImage {
-    var request = GeneratePersonSegmentationRequest()
-    request.qualityLevel = .accurate  // .balanced, .fast
-
-    let observation = try await request.perform(on: cgImage)
-    let maskBuffer = observation.pixelBuffer
+func personMask(for photo: CGImage) async throws -> CIImage {
+    let request = GeneratePersonSegmentationRequest()
+    request.qualityLevel = .balanced
+    let segmentation = try await request.perform(on: photo)
+    let mask = CIImage(cgImage: try segmentation.cgImage)
+    let sx = CGFloat(photo.width) / mask.extent.width
+    let sy = CGFloat(photo.height) / mask.extent.height
+    return mask.transformed(by: CGAffineTransform(scaleX: sx, y: sy))
+}
 
-    let originalImage = CIImage(cgImage: cgImage)
-    let maskImage = CIImage(cvPixelBuffer: maskBuffer)
+func portraitBlur(_ photo: CGImage, blurRadius: Float = 18) async throws -> CIImage {
+    let original = CIImage(cgImage: photo)
+    let mask = try await personMask(for: photo)
 
-    // Scale mask to match original image size
-    let scaleX = originalImage.extent.width / maskImage.extent.width
-    let scaleY = originalImage.extent.height / maskImage.extent.height
-    let scaledMask = maskImage.transformed(by: CGAffineTransform(
-        scaleX: scaleX, y: scaleY
-    ))
+    let blur = CIFilter.gaussianBlur()
+    blur.inputImage = original
+    blur.radius = blurRadius
+    let softened = blur.outputImage?.cropped(to: original.extent) ?? original
 
-    return scaledMask
+    let blend = CIFilter.blendWithMask()
+    blend.inputImage = original
+    blend.backgroundImage = softened
+    blend.maskImage = mask
+    return blend.outputImage ?? original
 }
+```
 
-// Apply background blur using person mask
-func blurBackground(of cgImage: CGImage, blurRadius: Double = 20.0) async throws -> CIImage {
-    let mask = try await segmentPerson(in: cgImage)
-    let original = CIImage(cgImage: cgImage)
-
-    let blurFilter = CIFilter.gaussianBlur()
-    blurFilter.inputImage = original
-    blurFilter.radius = Float(blurRadius)
-    guard let blurredImage = blurFilter.outputImage else {
-        throw SegmentationError.noMask
-    }
+The person stays sharp because the original is the input image and the blurred
+copy is the background.
 
-    let blendFilter = CIFilter.blendWithMask()
-    blendFilter.inputImage = original         // foreground (person)
-    blendFilter.backgroundImage = blurredImage // blurred background
-    blendFilter.maskImage = mask
+Legacy mask (iOS 15+):
 
-    guard let result = blendFilter.outputImage else {
-        throw SegmentationError.noMask
-    }
-    return result
-}
+```swift
+import Vision
 
-enum SegmentationError: Error {
-    case noMask
+enum MaskError: Error {
+    case empty
 }
-```
-
-### Legacy API (Pre-iOS 18)
 
-```swift
-func segmentPersonLegacy(in cgImage: CGImage) throws -> CVPixelBuffer {
+func legacyPersonMask(for photo: CGImage) throws -> CVPixelBuffer {
     let request = VNGeneratePersonSegmentationRequest()
     request.qualityLevel = .accurate
     request.outputPixelFormat = kCVPixelFormatType_OneComponent8
-
-    let handler = VNImageRequestHandler(cgImage: cgImage)
-    try handler.perform([request])
-
-    guard let maskBuffer = request.results?.first?.pixelBuffer else {
-        throw SegmentationError.noMask
+    try VNImageRequestHandler(cgImage: photo).perform([request])
+    guard let first = request.results?.first else {
+        throw MaskError.empty
     }
-    return maskBuffer
+    return first.pixelBuffer
 }
 ```
 
-### Instance Segmentation (iOS 18+)
-
-Separate masks per person for individual effects.
+### One mask per person
 
 ```swift
-// Modern API (iOS 18+)
-func segmentIndividualPeople(in cgImage: CGImage) async throws -> [CVPixelBuffer] {
-    let request = GeneratePersonInstanceMaskRequest()
-    let observation = try await request.perform(on: cgImage)
-
-    let indices = observation.allInstances
-    return try indices.map { index in
-        try observation.generateMask(forInstances: IndexSet(integer: index))
-    }
+import Vision
+
+func individualMasks(in groupShot: CGImage) async throws -> [CVPixelBuffer] {
+    guard let result = try await GeneratePersonInstanceMaskRequest().perform(on: groupShot) else { return [] }
+    return try result.allInstances.map { try result.generateMask(for: IndexSet(integer: $0)) }
 }
-```
 
-```swift
-// Legacy API (iOS 17+)
-func segmentIndividualPeopleLegacy(in cgImage: CGImage) throws -> [CVPixelBuffer] {
+func legacyIndividualMasks(in groupShot: CGImage) throws -> [CVPixelBuffer] {
     let request = VNGeneratePersonInstanceMaskRequest()
-    let handler = VNImageRequestHandler(cgImage: cgImage)
-    try handler.perform([request])
-
-    guard let result = request.results?.first else { return [] }
-    let indices = result.allInstances
-
-    return try indices.map { index in
-        try result.generateMask(forInstances: IndexSet(integer: index))
+    try VNImageRequestHandler(cgImage: groupShot).perform([request])
+    guard let people = request.results?.first else {
+        return []
+    }
+    return try people.allInstances.map { person in
+        try people.generateMask(forInstances: [person])
     }
 }
 ```
 
-## Image Classification
+The legacy request needs iOS 17. The Swift-native observation also offers
+`generateMaskedImage(for:imageFrom:croppedToInstancesExtent:)` when you want the
+cut-out pixels rather than a mask.
+
+## Classification
 
 ```swift
 import Vision
 
-func classifyImage(_ cgImage: CGImage, maxResults: Int = 5) async throws -> [(String, Float)] {
-    let request = ClassifyImageRequest()
-    let observations = try await request.perform(on: cgImage)
-
-    return observations.prefix(maxResults).map { observation in
-        (observation.identifier, observation.confidence)
-    }
+func sceneTags(for picture: CGImage, limit: Int = 5) async throws -> [(label: String, score: Float)] {
+    let labels = try await ClassifyImageRequest().perform(on: picture)
+    return labels.prefix(limit).map { ($0.identifier, $0.confidence) }
 }
 ```
 
-## Saliency Detection
+## Saliency
 
-Identify the most visually important or attention-grabbing regions.
+Attention-based saliency predicts where people look. Objectness-based saliency
+marks things that look like distinct objects.
 
 ```swift
-// Attention-based saliency (what humans would look at)
-func detectAttentionSaliency(in cgImage: CGImage) async throws -> [CGRect] {
-    let request = GenerateAttentionBasedSaliencyImageRequest()
-    let results = try await request.perform(on: cgImage)
-    guard let saliency = results.first else { return [] }
-    return saliency.salientObjects?.map(\.boundingBox) ?? []
+import Vision
+
+func focusRegions(in picture: CGImage) async throws -> [NormalizedRect] {
+    let heat = try await GenerateAttentionBasedSaliencyImageRequest().perform(on: picture)
+    return heat.salientObjects.map(\.boundingBox)
 }
 
-// Objectness-based saliency (distinct objects)
-func detectObjectSaliency(in cgImage: CGImage) async throws -> [CGRect] {
-    let request = GenerateObjectnessBasedSaliencyImageRequest()
-    let results = try await request.perform(on: cgImage)
-    guard let saliency = results.first else { return [] }
-    return saliency.salientObjects?.map(\.boundingBox) ?? []
+func objectRegions(in picture: CGImage) async throws -> [NormalizedRect] {
+    let heat = try await GenerateObjectnessBasedSaliencyImageRequest().perform(on: picture)
+    return heat.salientObjects.map(\.boundingBox)
 }
 ```
 
-## Rectangle Detection
+`salientObjects` is a non-optional array in the Swift-native API; the legacy
+`VNSaliencyImageObservation.salientObjects` is optional. The heat map itself is
+`heat.heatMap`.
 
-Detect rectangular shapes for document edges, business cards, etc.
+## Rectangles
 
 ```swift
-func detectRectangles(in cgImage: CGImage) async throws -> [CGRect] {
-    var request = DetectRectanglesRequest()
-    request.minimumAspectRatio = 0.3
-    request.maximumAspectRatio = 1.0
-    request.minimumSize = 0.1
-    request.maximumObservations = 5
+import Vision
 
-    let observations = try await request.perform(on: cgImage)
-    return observations.map(\.boundingBox)
+func cardOutlines(in picture: CGImage) async throws -> [NormalizedRect] {
+    var request = DetectRectanglesRequest()
+    request.minimumAspectRatio = 0.5
+    request.maximumAspectRatio = 0.8
+    request.minimumSize = 0.2
+    request.maximumObservations = 3
+    return try await request.perform(on: picture).map(\.boundingBox)
 }
 ```
 
-## Horizon Detection
+Aspect-ratio bounds filter shapes (a payment card is about 0.63), `minimumSize`
+is a fraction of the image, and `maximumObservations` caps the result count.
+Each `RectangleObservation` also exposes its four corners.
 
-Detect the horizon angle for auto-straightening photos.
+## Horizon
 
 ```swift
-func detectHorizon(in cgImage: CGImage) async throws -> CGFloat? {
-    let request = DetectHorizonRequest()
-    let results = try await request.perform(on: cgImage)
-    return results.first?.angle.map { CGFloat($0) }
+import Vision
+
+func tiltCorrection(for picture: CGImage) async throws -> CGFloat? {
+    guard let horizon = try await DetectHorizonRequest().perform(on: picture) else { return nil }
+    return CGFloat(-horizon.angle.converted(to: .radians).value)
 }
 ```
 
-## Batch Processing Multiple Requests
+`angle` is a `Measurement<UnitAngle>`; convert it before using it as a
+rotation. `horizon.transform(for:)` gives a ready-made affine transform.
+
+## Several requests on one image
 
-Run multiple requests on the same image simultaneously for efficiency.
+Swift-native requests are independent values, so run them concurrently:
 
 ```swift
-func analyzeImage(_ cgImage: CGImage) async throws -> ImageAnalysisResult {
-    async let textResults = {
-        var req = RecognizeTextRequest()
-        req.recognitionLevel = .accurate
-        return try await req.perform(on: cgImage)
-    }()
-
-    async let faceResults = {
-        let req = DetectFaceRectanglesRequest()
-        return try await req.perform(on: cgImage)
-    }()
-
-    async let barcodeResults = {
-        var req = DetectBarcodesRequest()
-        req.symbologies = [.qr, .ean13]
-        return try await req.perform(on: cgImage)
-    }()
-
-    let text = try await textResults
-    let faces = try await faceResults
-    let barcodes = try await barcodeResults
-
-    return ImageAnalysisResult(
-        recognizedText: text.compactMap { $0.topCandidates(1).first?.string },
-        faceCount: faces.count,
-        barcodePayloads: barcodes.compactMap(\.payloadString)
-    )
-}
+import Vision
 
-struct ImageAnalysisResult: Sendable {
-    let recognizedText: [String]
+struct PhotoDigest: Sendable {
+    let lines: [String]
     let faceCount: Int
-    let barcodePayloads: [String]
+    let links: [String]
+}
+
+func digest(of picture: CGImage) async throws -> PhotoDigest {
+    async let text = RecognizeTextRequest().perform(on: picture)
+    async let faces = DetectFaceRectanglesRequest().perform(on: picture)
+    async let codes = DetectBarcodesRequest().perform(on: picture)
+
+    return PhotoDigest(
+        lines: try await text.compactMap(\.bestString),
+        faceCount: try await faces.count,
+        links: try await codes.compactMap(\.payloadString)
+    )
 }
 ```
 
-### Legacy Batch Processing
+`ImageRequestHandler(picture).perform(a, b, c)` is an alternative that shares
+one decoded image across requests and returns a tuple of typed results.
 
-With the legacy API, pass multiple requests to a single handler call.
+With the legacy API, give one handler all requests at once:
 
 ```swift
-func analyzeImageLegacy(_ cgImage: CGImage) throws {
-    let textRequest = VNRecognizeTextRequest { request, error in
-        // Handle text results
-    }
-    let faceRequest = VNDetectFaceRectanglesRequest { request, error in
-        // Handle face results
-    }
-    let barcodeRequest = VNDetectBarcodesRequest { request, error in
-        // Handle barcode results
-    }
+import Vision
 
-    let handler = VNImageRequestHandler(cgImage: cgImage)
-    try handler.perform([textRequest, faceRequest, barcodeRequest])
+func legacyDigest(of picture: CGImage) throws -> (VNRecognizeTextRequest, VNDetectFaceRectanglesRequest, VNDetectBarcodesRequest) {
+    let text = VNRecognizeTextRequest()
+    let faces = VNDetectFaceRectanglesRequest()
+    let codes = VNDetectBarcodesRequest()
+    try VNImageRequestHandler(cgImage: picture).perform([text, faces, codes])
+    return (text, faces, codes)
 }
 ```
 
-## Video Frame Processing with CMSampleBuffer
+## Camera frames from AVFoundation
 
-Process live camera frames from AVCaptureSession.
+The capture delegate runs on its own serial queue and hands out non-Sendable
+`CMSampleBuffer` values. Forward the newest frame into an `AsyncStream` and do
+the Vision work in a consumer task; the stream's buffering policy drops frames
+while one is being processed.
 
 ```swift
 import AVFoundation
 import Vision
 
-final class VisionVideoProcessor: NSObject, AVCaptureVideoDataOutputSampleBufferDelegate, Sendable {
-    private let processingQueue = DispatchQueue(label: "vision.processing", qos: .userInitiated)
+struct CameraFrame: @unchecked Sendable {
+    let sample: CMSampleBuffer
+}
 
-    func setupCapture(session: AVCaptureSession) {
-        let output = AVCaptureVideoDataOutput()
-        output.setSampleBufferDelegate(self, queue: processingQueue)
-        output.alwaysDiscardsLateVideoFrames = true
+final class FramePump: NSObject, AVCaptureVideoDataOutputSampleBufferDelegate {
+    let frames: AsyncStream<CameraFrame>
+    private let sink: AsyncStream<CameraFrame>.Continuation
+    private let output = AVCaptureVideoDataOutput()
+    private let queue = DispatchQueue(label: "camera.frames", qos: .userInitiated)
+
+    override init() {
+        let pair = AsyncStream.makeStream(of: CameraFrame.self, bufferingPolicy: .bufferingNewest(1))
+        frames = pair.stream
+        sink = pair.continuation
+        super.init()
+    }
 
+    func attach(to session: AVCaptureSession) {
+        output.setSampleBufferDelegate(self, queue: queue)
+        output.alwaysDiscardsLateVideoFrames = true
         if session.canAddOutput(output) {
             session.addOutput(output)
         }
     }
 
-    func captureOutput(
-        _ output: AVCaptureOutput,
-        didOutput sampleBuffer: CMSampleBuffer,
-        from connection: AVCaptureConnection
-    ) {
-        Task {
-            do {
-                var request = RecognizeTextRequest()
-                request.recognitionLevel = .fast
-                let observations = try await request.perform(on: sampleBuffer)
-                let strings = observations.compactMap {
-                    $0.topCandidates(1).first?.string
-                }
-                // Dispatch results to main actor for UI update
-                await MainActor.run {
-                    // Update UI with recognized strings
-                }
-            } catch {
-                // Handle error
-            }
-        }
+    func captureOutput(_ output: AVCaptureOutput,
+                       didOutput sampleBuffer: CMSampleBuffer,
+                       from connection: AVCaptureConnection) {
+        sink.yield(CameraFrame(sample: sampleBuffer))
+    }
+}
+
+func readLive(from pump: FramePump, show: @escaping @MainActor ([String]) -> Void) async {
+    var request = RecognizeTextRequest()
+    request.recognitionLevel = .fast
+    for await frame in pump.frames {
+        guard let found = try? await request.perform(on: frame.sample) else { continue }
+        let lines = found.compactMap(\.bestString)
+        await MainActor.run { show(lines) }
     }
 }
 ```
 
-### Object Tracking Across Video Frames
+The `@unchecked Sendable` wrapper is acceptable here because the frame is
+never touched again after it is yielded.
 
-#### Modern API (iOS 18+)
+## Tracking across frames
 
-`TrackObjectRequest` is a stateful request that maintains tracking context
-internally. No need for a separate sequence handler.
+The Swift-native tracker keeps its own history, so there is no sequence
+handler to manage. Keep the request object for as long as you track.
 
 ```swift
 import Vision
 
-final class ObjectTracker {
+final class SubjectFollower {
     private var request: TrackObjectRequest?
+    private let minimumConfidence: Float = 0.3
 
-    /// Initialize tracking with a bounding box in normalized coordinates
-    func startTracking(boundingBox: CGRect) {
-        let observation = DetectedObjectObservation(boundingBox: boundingBox)
-        var req = TrackObjectRequest(observation: observation)
-        req.trackingLevel = .accurate
-        request = req
+    func begin(at box: NormalizedRect) {
+        request = TrackObjectRequest(detectedObject: DetectedObjectObservation(boundingBox: box))
     }
 
-    /// Track object in next video frame
-    func track(in pixelBuffer: CVPixelBuffer) async throws -> CGRect? {
-        guard var req = request else { return nil }
-
-        let results = try await req.perform(on: pixelBuffer)
-        guard let tracked = results.first, tracked.confidence > 0.3 else {
-            request = nil
+    func next(_ frame: CVPixelBuffer) async throws -> NormalizedRect? {
+        guard let request else { return nil }
+        guard let hit = try await request.perform(on: frame), hit.confidence > minimumConfidence else {
+            end()
             return nil
         }
-
-        request = req  // preserve stateful tracking context
-        return tracked.boundingBox
+        return hit.boundingBox
     }
 
-    func stopTracking() {
+    func end() {
         request = nil
     }
 }
 ```
 
-#### Legacy API
+Legacy tracker with an explicit sequence handler:
 
 ```swift
-final class LegacyObjectTracker {
-    private var sequenceHandler = VNSequenceRequestHandler()
-    private var currentObservation: VNDetectedObjectObservation?
-
-    func startTracking(boundingBox: CGRect) {
-        currentObservation = VNDetectedObjectObservation(boundingBox: boundingBox)
-    }
-
-    func track(in pixelBuffer: CVPixelBuffer) throws -> CGRect? {
-        guard let observation = currentObservation else { return nil }
+import Vision
 
-        let trackRequest = VNTrackObjectRequest(detectedObjectObservation: observation)
-        trackRequest.trackingLevel = .accurate
+final class LegacySubjectFollower {
+    private let sequence = VNSequenceRequestHandler()
+    private var last: VNDetectedObjectObservation?
 
-        try sequenceHandler.perform([trackRequest], on: pixelBuffer)
+    func begin(at box: CGRect) {
+        last = VNDetectedObjectObservation(boundingBox: box)
+    }
 
-        guard let result = trackRequest.results?.first as? VNDetectedObjectObservation,
-              result.confidence > 0.3 else {
-            currentObservation = nil
+    func next(_ frame: CVPixelBuffer) throws -> CGRect? {
+        guard let seed = last else { return nil }
+        let request = VNTrackObjectRequest(detectedObjectObservation: seed)
+        request.trackingLevel = .accurate
+        try sequence.perform([request], on: frame)
+        guard let hit = request.results?.first as? VNDetectedObjectObservation, hit.confidence > 0.3 else {
+            last = nil
             return nil
         }
-
-        currentObservation = result
-        return result.boundingBox
-    }
-
-    func stopTracking() {
-        currentObservation = nil
+        last = hit
+        return hit.boundingBox
     }
 }
 ```
 
-## Coordinate Normalization Utilities
+## Coordinate helpers
+
+Normalized values run from 0 to 1 with the origin at the lower left.
 
-Vision uses normalized coordinates (0...1) with bottom-left origin. These
-utilities convert to UIKit/SwiftUI coordinate systems.
+- `VNImageRectForNormalizedRect(rect, width, height)` scales a normalized
+  rectangle to pixels.
+- `VNImagePointForNormalizedPoint(point, width, height)` does the same for a
+  point.
+- Neither flips the y axis; UIKit drawing still needs a flip.
+- Swift-native `NormalizedRect` and `NormalizedPoint` have
+  `toImageCoordinates(_:origin:)` which scales and, with `.upperLeft`, flips.
 
 ```swift
 import Vision
-import UIKit
-
-enum VisionCoordinateConverter {
-    /// Convert normalized Vision rect to image-pixel coordinates
-    static func toImageCoordinates(
-        _ normalizedRect: CGRect,
-        imageWidth: Int,
-        imageHeight: Int
-    ) -> CGRect {
-        VNImageRectForNormalizedRect(normalizedRect, imageWidth, imageHeight)
-    }
 
-    /// Convert normalized Vision point to image-pixel coordinates
-    static func toImageCoordinates(
-        _ normalizedPoint: CGPoint,
-        imageWidth: Int,
-        imageHeight: Int
-    ) -> CGPoint {
-        VNImagePointForNormalizedPoint(normalizedPoint, imageWidth, imageHeight)
-    }
-
-    /// Convert Vision rect (bottom-left origin) to UIKit rect (top-left origin)
-    static func toUIKitCoordinates(
-        _ normalizedRect: CGRect,
-        viewSize: CGSize
-    ) -> CGRect {
-        let imageRect = VNImageRectForNormalizedRect(
-            normalizedRect,
-            Int(viewSize.width),
-            Int(viewSize.height)
-        )
-        // Flip Y axis: Vision origin is bottom-left, UIKit is top-left
-        return CGRect(
-            x: imageRect.origin.x,
-            y: viewSize.height - imageRect.origin.y - imageRect.height,
-            width: imageRect.width,
-            height: imageRect.height
-        )
-    }
+func viewRect(for normalized: CGRect, in viewSize: CGSize) -> CGRect {
+    let pixelWidth = Int(viewSize.width)
+    let pixelHeight = Int(viewSize.height)
+    let scaled = VNImageRectForNormalizedRect(normalized, pixelWidth, pixelHeight)
+    return CGRect(x: scaled.minX,
+                  y: viewSize.height - scaled.minY - scaled.height,
+                  width: scaled.width,
+                  height: scaled.height)
+}
 
-    /// Convert an array of normalized points to UIKit points
-    static func toUIKitPoints(
-        _ normalizedPoints: [CGPoint],
-        viewSize: CGSize
-    ) -> [CGPoint] {
-        normalizedPoints.map { point in
-            CGPoint(
-                x: point.x * viewSize.width,
-                y: (1.0 - point.y) * viewSize.height  // flip Y
-            )
-        }
+func viewPoints(for normalized: [CGPoint], in viewSize: CGSize) -> [CGPoint] {
+    normalized.map { p in
+        CGPoint(x: p.x * viewSize.width, y: viewSize.height - p.y * viewSize.height)
     }
 }
 ```
 
-## Performance Considerations
+## Performance
 
-### Recognition Level Selection
+Ballpark costs; measure on the oldest device you support.
 
-| Use Case | Level | Typical Latency |
+| Scenario | Level | Typical cost |
 |---|---|---|
-| Live camera preview | `.fast` | ~30ms per frame |
-| Photo library scan | `.accurate` | ~200-500ms per image |
-| Batch document OCR | `.accurate` | ~200-500ms per page |
-| Barcode scanner | `.fast` or `.balanced` | ~15-50ms per frame |
+| Live camera text | `.fast` | about 30 ms per frame |
+| Photo library scan | `.accurate` | 200 to 500 ms per image |
+| Batch document OCR | `.accurate` | 200 to 500 ms per page |
+| Barcode scanning | `.fast` or `.balanced` | 15 to 50 ms per frame |
 
-### Memory Management
+Memory:
 
-- Reuse `VNSequenceRequestHandler` across video frames (do not recreate per frame)
-- For batch processing, process one image at a time to avoid memory spikes
-- Release `CVPixelBuffer` references promptly after processing
-- Use `autoreleasepool` in tight loops processing many images
+- Reuse a single `VNSequenceRequestHandler` for a whole frame sequence.
+- Work through large photo sets one image at a time so memory does not spike:
 
 ```swift
-func batchProcess(images: [CGImage]) async throws -> [[String]] {
-    var allResults: [[String]] = []
+import Vision
 
-    for image in images {
+func transcribeAll(_ pages: [CGImage]) async throws -> [[String]] {
+    var output: [[String]] = []
+    for page in pages {
         var request = RecognizeTextRequest()
         request.recognitionLevel = .accurate
-        let obs = try await request.perform(on: image)
-        let result = obs.compactMap { $0.topCandidates(1).first?.string }
-        allResults.append(result)
+        let found = try await request.perform(on: page)
+        output.append(found.compactMap(\.bestString))
     }
-    return allResults
+    return output
 }
 ```
 
-### Threading
+- Let go of `CVPixelBuffer` references as soon as you are done; wrap tight
+  synchronous loops over legacy handlers in `autoreleasepool`.
 
-- Modern API (`perform(on:)`) is async and safe to call from any context
-- Legacy API: create `VNImageRequestHandler` and call `perform` on a background queue
-- Never block the main thread with Vision requests
-- `VNSequenceRequestHandler` is not thread-safe -- use from a single serial queue
+Threading:
 
-### Request Reuse
+- Swift-native `perform(on:)` is async and can be awaited from any context.
+- Legacy `perform` is synchronous; call it from a background queue, never the
+  main thread.
+- `VNSequenceRequestHandler` has no internal locking; confine each instance to
+  a single serial queue.
 
-Modern request structs are value types and cheap to create. Do not try to cache
-and reuse them across calls -- just create a fresh one each time.
+Reuse:
 
-For the legacy API, `VNImageRequestHandler` is tied to a single image. Create a
-new handler for each image you process. `VNSequenceRequestHandler` can be reused
-across frames in a sequence.
+- Swift-native request structs are cheap values; build a fresh one per job
+  rather than caching it. Stateful request classes are the exception: keep
+  them for the sequence they track.
+- A `VNImageRequestHandler` belongs to one image; create one per image. A
+  `VNSequenceRequestHandler` is meant to be reused across a sequence.