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.

  • 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

    • 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