# Class VisionImage

java.lang.Object
com.codename1.ai.vision.VisionImage

public final class VisionImage extends Object

Immutable input for encoded still images or raw camera pixels. Factory methods defensively copy their arrays. In particular, `fromCameraFrame(CameraFrame)` detaches from callback-owned buffers that a camera backend may recycle when the callback returns.

Pick the factory that matches where the image came from:

    // A file: the gallery, or CapturedPhoto.getFilePath()
    VisionImage.fromFile(photo.getFilePath());

    // An image already in memory
    VisionImage.fromImage(label.getIcon());

    // Bytes you decoded or downloaded yourself
    VisionImage.encoded(jpegBytes);

    // A live camera frame, which also carries the frame's rotation
    VisionImage.fromCameraFrame(frame);

Only `encoded(byte[], int)` needs a rotation argument, and only when the stored pixels are not already upright -- this class does not read EXIF.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static VisionImage`
  `encoded(byte[] bytes)`
  Creates an encoded JPEG or PNG input whose stored pixels are already upright.
  `static VisionImage`
  `encoded(byte[] bytes, int rotationDegrees)`
  Creates an encoded JPEG or PNG input with display orientation metadata.
  `static VisionImage`
  `fromCameraFrame(CameraFrame frame)`
  Copies the buffer selected by the camera frame's format, together with its timestamp and orientation.
  `static VisionImage`
  `fromFile(String path)`
  Reads a JPEG or PNG file from `FileSystemStorage` and wraps it for analysis.
  `static VisionImage`
  `fromImage(Image image)`
  Wraps an in-memory Codename One image for analysis.
  `byte[]`
  `getEncodedBytes()`
  `FrameFormat`
  `getFormat()`
  `int`
  `getHeight()`
  `byte[]`
  `getPixels()`
  `int`
  `getRotationDegrees()`
  `long`
  `getTimestampNanos()`
  `int`
  `getWidth()`
  `static VisionImage`
  `pixels(byte[] bytes, int width, int height, FrameFormat format, int rotationDegrees)`
  Creates raw NV21 or RGBA8888 input with display orientation metadata.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### encoded

    public static VisionImage encoded(byte[] bytes)
    Creates an encoded JPEG or PNG input whose stored pixels are already upright. This method does not inspect EXIF orientation metadata. Use `encoded(byte[], int)` when the encoded image needs a clockwise display rotation before analysis.
    Parameters:
      `bytes` - complete encoded image, copied by this method
    Returns:
      immutable image input
    Throws:
      `IllegalArgumentException` - if `bytes` is `null` or empty

  - ### encoded

    public static VisionImage encoded(byte[] bytes, int rotationDegrees)
    Creates an encoded JPEG or PNG input with display orientation metadata. The rotation describes how the stored pixels must be rotated clockwise to appear upright; for example, pass `90` for a portrait JPEG whose pixels are stored in landscape orientation. Decoders on Android and Apple platforms receive this value directly, so detected bounds and points use the displayed orientation. This method does not parse EXIF; callers loading an image outside `fromCameraFrame(CameraFrame)` must supply the EXIF-derived rotation when it is relevant.
    Parameters:
      `bytes` - complete encoded image, copied by this method
      `rotationDegrees` - clockwise display rotation; only 0, 90, 180, or 270 degrees are supported
    Returns:
      immutable image input
    Throws:
      `IllegalArgumentException` - if `bytes` is `null` or empty, or if the rotation is not a quarter turn

  - ### pixels

    public static VisionImage pixels(byte[] bytes, int width, int height, FrameFormat format, int rotationDegrees)
    Creates raw NV21 or RGBA8888 input with display orientation metadata.
    Parameters:
      `bytes` - pixel buffer in `format`, copied by this method
      `width` - unrotated pixel width
      `height` - unrotated pixel height
      `format` - supported raw frame format
      `rotationDegrees` - clockwise display rotation; only 0, 90, 180, or 270 degrees are supported
    Returns:
      immutable image input
    Throws:
      `IllegalArgumentException` - if the data or dimensions are empty, if `format` is not `FrameFormat.NV21` or `FrameFormat.RGBA8888`, or if the rotation is not a quarter turn

  - ### fromCameraFrame

    public static VisionImage fromCameraFrame(CameraFrame frame)
    Copies the buffer selected by the camera frame's format, together with its timestamp and orientation. JPEG frames copy only `CameraFrame.getJpegBytes()`; NV21 and RGBA8888 frames copy only `CameraFrame.getRawBytes()` when the port supplies that buffer. If a port cannot supply the requested raw format, this method copies the always-available JPEG fallback instead. This preserves the raw pipeline without creating an empty image on JPEG-only camera ports.
    Parameters:
      `frame` - callback-owned frame
    Returns:
      detached immutable input safe for asynchronous analysis
    Throws:
      `IllegalArgumentException` - if the frame reports a rotation other than 0, 90, 180, or 270 degrees

  - ### fromFile

    public static VisionImage fromFile(String path) throws IOException

    Reads a JPEG or PNG file from `FileSystemStorage` and wraps it for analysis. This is the usual bridge from the image picker or from `CapturedPhoto.getFilePath()` to an analyzer.

    Like `encoded(byte[])` this assumes the stored pixels are already upright and does not parse EXIF. Use `encoded(byte[], int)` when a rotation has to be applied.

    Parameters:
      `path` - a FileSystemStorage path
    Returns:
      immutable image input
    Throws:
      `IOException` - if the file cannot be read
      `IllegalArgumentException` - if the file is empty

  - ### fromImage

    public static VisionImage fromImage(Image image)

    Wraps an in-memory Codename One image for analysis.

    An `EncodedImage` passes its original JPEG or PNG bytes straight through, which is both cheaper and higher fidelity than re-encoding. Any other image is read as RGBA pixels. Either way the caller's image is left untouched.

    Parameters:
      `image` - the image to analyze
    Returns:
      immutable image input
    Throws:
      `NullPointerException` - if `image` is `null`
      `IllegalArgumentException` - if the image has no pixels

  - ### getEncodedBytes

    public byte[] getEncodedBytes()
    Returns:
      a defensive copy of encoded bytes, or `null` for raw input

  - ### getPixels

    public byte[] getPixels()
    Returns:
      a defensive copy of raw pixels, or `null` for encoded input

  - ### getWidth

    public int getWidth()
    Returns:
      raw pixel width, or zero for encoded input

  - ### getHeight

    public int getHeight()
    Returns:
      raw pixel height, or zero for encoded input

  - ### getRotationDegrees

    public int getRotationDegrees()
    Returns:
      normalized clockwise rotation: 0, 90, 180, or 270

  - ### getTimestampNanos

    public long getTimestampNanos()
    Returns:
      capture timestamp in nanoseconds, or zero for manual input

  - ### getFormat

    public FrameFormat getFormat()
    Returns:
      encoded/raw frame format