public final class VisionImage

Object
VisionImage

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.

Methods

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

Inherited methods

From Object

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

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 byte[]: 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 byte[]: complete encoded image, copied by this method
rotationDegrees int: 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 byte[]: pixel buffer in format, copied by this method
width int: unrotated pixel width
height int: unrotated pixel height
format FrameFormat: supported raw frame format
rotationDegrees int: 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 CameraFrame: 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 String: 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 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