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 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