Camera & Face Detection

iOS App
  SWCameraManager (@Observable, NSObject)
    |
    |--- AVCaptureSession (session lifecycle, photo capture, zoom)
    |       |--- AVCaptureDeviceInput (front/back camera)
    |       |--- AVCapturePhotoOutput (photo capture delegate)
    |       |--- AVCaptureVideoDataOutput (frame-by-frame for Vision)
    |
    |--- Vision Framework (opt-in face tracking)
    |       |--- VNSequenceRequestHandler
    |       |--- VNDetectFaceLandmarksRequest
    |       |--- Normalized landmark coordinates -> SWFaceLandmarkGroup[]
    |
    v
  SWCameraView (photo capture UI)               SWFaceCameraView (face detection UI)
    |--- SWCameraPreview (AVCaptureSession)        |--- SWFaceCameraPreview (AVCaptureSession)
    |--- PhotosPicker (photo library)              |--- SWFaceTrackingOverlay (Canvas rendering)
    |--- Pinch-to-zoom + zoom slider               |--- Landmark toggle button
    |--- Shutter button + camera switch            |--- Shutter button + camera switch

Data Models
  SWFaceLandmarkRegion (enum) — 11 face region types
  SWFaceLandmarkGroup (struct) — region + normalized points
  SWFaceLandmarkColors (struct) — configurable color schemes

1. Add Info.plist Camera Permission

Add the camera usage description to your Info.plist (or Xcode target > Info tab):

<key>NSCameraUsageDescription</key>
<string>This app needs camera access to take photos</string>

Without this key, the app will crash on first camera access attempt.

2. Add All Four Files to Your Project

Copy the files into your Xcode project in the following order (dependency order):

1. SWFaceLandmark+iOS.swift -- data models, no dependencies
2. SWCameraManager+iOS.swift -- depends on SWFaceLandmark
3. SWCameraView+iOS.swift -- depends on SWCameraManager and the component-alert skill (SWAlertManager)
4. SWFaceCameraView+iOS.swift -- depends on SWCameraManager and SWFaceLandmark

If your app also builds for macOS, limit these files to iOS in Build Phases > Compile Sources (the +iOS suffix marks them as iOS-only).

3. Wire Up Error Handling

SWCameraView uses SWAlertManager.shared.show(...) for error display. Make sure your root view has the .swAlert() modifier attached. If you are not using the ShipSwift alert system, replace the onError callback in onAppear:

cameraManager.onError = { message in
    // Replace with your own error handling
    print("Camera error: \(message)")
}

4. Present SWCameraView

Neither camera view has a close button of its own, so give the user a way out: push the view with a NavigationLink (the back button closes it), or present it inside a NavigationStack with a close button in the toolbar. SWCameraView calls dismiss() after a capture or a library pick, which pops or dismisses it either way.

@State private var capturedImage: UIImage?
@State private var showCamera = false

Button("Take Photo") { showCamera = true }
.fullScreenCover(isPresented: $showCamera) {
    NavigationStack {
        SWCameraView(image: $capturedImage)
            .toolbar {
                ToolbarItem(placement: .cancellationAction) {
                    Button("Close") { showCamera = false }
                }
            }
    }
}

5. Present SWFaceCameraView

SWFaceCameraView stays on screen after a capture and hands each photo to onCapture, so close it yourself when you are done:

@State private var showFaceCamera = false

Button("Face Camera") { showFaceCamera = true }
.fullScreenCover(isPresented: $showFaceCamera) {
    NavigationStack {
        SWFaceCameraView { capturedImage in
            // handle the captured UIImage
            processPhoto(capturedImage)
            showFaceCamera = false
        }
        .toolbar {
            ToolbarItem(placement: .cancellationAction) {
                Button("Close") { showFaceCamera = false }
            }
        }
    }
}

Camera Permission Denied Has No Recovery

If the user denies camera permission, iOS does not allow the app to re-prompt. The only recovery path is directing the user to Settings. Both SWCameraView and SWFaceCameraView include an "Open Settings" button for this case.

Simulator Does Not Support Camera

AVCaptureDevice.default(...) returns nil on the iOS Simulator. The manager will trigger onError with "Unable to access camera". Always test camera features on a physical device.

Face Detection Performance

Vision's VNDetectFaceLandmarksRequest runs per-frame on the video data output queue. On older devices, this may cause frame drops. The implementation uses alwaysDiscardsLateVideoFrames = true and a .userInitiated QoS queue to mitigate this, but performance may vary.

Front Camera Mirroring

The front camera preview is mirrored by AVCaptureVideoPreviewLayer by default. The Vision face detection code accounts for this by using .leftMirrored orientation for front-camera frames. If you modify the preview mirroring behavior, you must also update the orientation in captureOutput(_:didOutput:from:).

Session Start Timing

SWCameraManager handles the race condition where startSession() is called before setupCamera() completes by queuing a pendingStartSession flag. You do not need to add your own delay or retry logic.

Photo Capture Format

The implementation prefers JPEG format for captured photos. If JPEG is not available on the device, it falls back to the default format. The captured UIImage is always returned via the completion handler regardless of the underlying codec.

Video Data Output Always Attached

The AVCaptureVideoDataOutput is always added to the session even when face tracking is disabled. This is by design so that face tracking can be toggled at runtime without reconfiguring the session. When faceTrackingEnabled is false, the delegate method returns immediately with negligible overhead.