# Package com.codename1.ai.vision

package com.codename1.ai.vision

Vendor-neutral on-device vision APIs for still images and live camera frames: barcodes and QR codes, OCR, faces, image labels, body pose, person segmentation, and document correction.

## Start at the level you need

The package is three layers deep, and most applications only ever touch the first one.

1. A finished screen. `CodeScanner` is a complete barcode and QR scanner in one call. It opens the camera, decodes, restores the form you came from, and hands back the code -- or `null` if the user backed out. This is the replacement for the old `CodeScanner` cn1lib.

    CodeScanner.scan().ready(code -> {
        if (code != null) {
            urlField.setText(code.getValue());
        }
    });

2. A live preview inside your own form. `VisionCameraView` is a component that owns the camera, streams frames through the analyzer you give it, and delivers results on the EDT. It works with every analyzer, not just barcodes.

    VisionCameraView<Face[]> view =
            new VisionCameraView<Face[]>(new FaceDetector());
    view.setFacing(CameraFacing.FRONT);
    view.setListener(new VisionPipelineListener<Face[]>() {
        public void result(Face[] faces, VisionImage source) {
            status.setText(faces.length + " face(s)");
        }
        public void error(Throwable error) {
            Log.e(error);
        }
    });
    form.add(BorderLayout.CENTER, view);

3. One image at a time. Each analyzer -- `TextRecognizer`, `BarcodeScanner`, `FaceDetector`, `ImageLabeler`, `PoseDetector`, `SelfieSegmenter`, `DocumentScanner` -- takes a `VisionImage` and returns a typed result. Create one, reuse it for a sequence, and close it.

    TextRecognizer recognizer = new TextRecognizer();
    recognizer.process(VisionImage.fromFile(path))
            .ready(result -> Log.p(result.getText()))
            .except(error -> Log.e(error));

## Reading the results

Bounds and points are normalized to 0..1 rather than pixels, so a result computed on a camera frame can be drawn over an image of any size. `VisionRect.toBounds(com.codename1.ui.Component)` and `VisionPoint.toPoint(com.codename1.ui.Component)` convert them back. Names that would otherwise be string literals -- symbologies, face landmarks, body joints -- are constants on `BarcodeFormat`, `FaceLandmarks` and `PoseLandmarks`.

## Availability

Call `isSupported()` before offering a feature: availability depends on the target, the linked backend, and the OS version. The automatic backend uses Apple Vision/Core Image on iOS and Mac Catalyst and ML Kit on Android; optional backends are selected with `VisionBackends`. In the simulator the results are whatever you scripted under Simulate > Vision, so a scanner screen can be built without a device.

Each analyzer is a separate build-time feature. Referencing one causes the builder to retain only its platform adapter and native dependency, so a barcode app does not carry the pose and OCR models.

- Related Packages
  Package
  Description
  com.codename1.ai
  Codename One's AI / LLM client surface plus the value types, streaming primitives, and chat-binding helpers that sit on top of it.
  com.codename1.ai.inference
  Reusable on-device inference sessions for `.tflite` models.
  com.codename1.ai.language
  Vendor-neutral on-device language identification, translation, and smart reply.
- Class
  Description
  Barcode
  Portable barcode observation with normalized geometry.
  BarcodeFormat
  The normalized symbology names `Barcode.getFormat()` reports, as constants instead of literals.
  BarcodeScanner
  Decodes barcodes and QR codes out of a still image or a camera frame.
  CodeScanner
  A ready-made full-screen barcode and QR scanner.
  CodeScannerOptions
  Configuration for `CodeScanner.scan(CodeScannerOptions)`.
  DocumentScanner
  Finds a page in a photo and returns it flattened, with the perspective corrected.
  DocumentScanResult
  Corrected document pages returned as encoded image data.
  Face
  Portable face observation.
  FaceDetector
  Finds faces, their bounding boxes, their head angles, and -- where the backend supports it -- whether they are smiling.
  FaceLandmarks
  The keys `Face.getLandmarks()` uses, as constants instead of literals.
  ImageLabel
  Portable ranked image-classification label.
  ImageLabeler
  Classifies what an image contains, as ranked labels with confidences.
  Pose
  Portable body-pose result.
  Pose.Landmark
  One named body joint with normalized position and confidence.
  PoseDetector
  Locates body joints, for rep counting, form feedback, or gesture input.
  PoseLandmarks
  The joint names `Pose.Landmark.getName()` reports, as constants instead of literals.
  SegmentationMask
  Dense per-pixel foreground confidence mask.
  SelfieSegmenter
  Separates a person from the background, for background replacement or blur.
  TextRecognitionResult
  OCR output containing the complete recognized text and portable block-level geometry.
  TextRecognitionResult.TextBlock
  One recognized text block with confidence and normalized bounds.
  TextRecognizer
  Reads the text in an image.
  TextScript
  Writing system selectors for `TextRecognizer`.
  VisionAnalyzer<T>
  Reusable, closable on-device analyzer for still images or camera frames.
  VisionBackend
  Identifies a vision implementation.
  VisionBackends
  Vision backend selectors.
  VisionCameraView<T>
  A live camera preview that runs an analyzer over its frames.
  VisionException
  Failure reported by an on-device vision backend.
  VisionFeature
  Features understood by the shared vision backend.
  VisionImage
  Immutable input for encoded still images or raw camera pixels.
  VisionMetadata
  Optional backend identity and backend-specific diagnostic strings attached to a vision result.
  VisionOptions
  Common analyzer configuration.
  VisionPipeline<T>
  Connects a camera frame stream to a reusable analyzer with keep-only-latest backpressure.
  VisionPipelineListener<T>
  Receives live vision results and recoverable analysis failures on the EDT.
  VisionPoint
  Immutable point in a normalized, top-left-origin coordinate space.
  VisionRect
  Immutable normalized rectangle using a top-left origin.