Images

_|

Images are represented in an abstract form that requires conversion before displaying on the UI. The SDK provides the following image classes: Img, AbstractGeometryImg, LaneImg, SignpostImg, and RoadInfoImg.

All image classes provide these methods and properties:

• uid - Gets the unique ID of the image. Identical images share the same UID, allowing you to optimize UI redraws by triggering updates only when the image changes
• isValid - Verifies if the image data is valid. Invalid images return null from rendering methods
• getRenderableImageBytes - Returns a Uint8List that can be displayed using the Image.memory constructor. Returns null if invalid
• getRenderableImage - Returns a RenderableImg containing the image size and Uint8List for UI rendering. Returns null if invalid

---

Work with plain images

The Img class represents plain (usually non-vector) images. These images have a recommended size and aspect ratio but can be resized to any dimension (with possible quality loss).

You can instantiate an Img class using:

• Constructor - Pass Uint8List image data and format
• fromAsset method - Pass the asset key (and optionally a custom bundle)

---

Work with vector images

The AbstractGeometryImg, LaneImg, SignpostImg, and RoadInfoImg classes represent vector images generated by the SDK. They provide customizable rendering options and do not have a default size or aspect ratio.

The LaneImg, SignpostImg, and RoadInfoImg classes render best at specific aspect ratios depending on content. To render images at a suitable size chosen by the SDK, set the allowResize parameter to true in the getRenderableImage or getRenderableImageBytes methods. When set to false, rendering uses your exact specified size (which may cause distortion).

Tip

Use getRenderableImage instead of getRenderableImageBytes when setting allowResize to true. This provides the actual rendered image size within the RenderableImg class.

Image type comparison

Class	Size and aspect ratio	Customizable render options	The size of the renderable image returned by the getRenderableImage/getRenderableImageBytes methods	Instantiable by the user
Img	Usually fixed and retrievable via the size and aspectRatio getters.	Not available	Will always render at the size specified by the user if provided, or the recommended size for the particular image otherwise.	Yes, via the provided constructor and the fromAsset static method. It can be also provided by the SDK.
AbstractGeometryImg	Generated by the SDK. Size and aspect ratio not retrievable.	Yes, via AbstractGeometryImageRenderSettings	Will always render at the size specified by the user if provided, or the SDK default image size otherwise.	No. Can only be provided by the SDK.
LaneImg	Generated by the SDK. Size and aspect ratio not retrievable.	Yes, via LaneImageRenderSettings	Will render at the size specified by the user if the allowResize parameter is false. If allowResize is true, the SDK will render at an aspect ratio suitable for the particular image based on the size provided by the user.	No. Can only be provided by the SDK.
SignpostImg	Generated by the SDK. Size and aspect ratio not retrievable.	Yes, via SignpostImageRenderSettings	Will render at the size specified by the user if the allowResize parameter is false. If allowResize is true, the SDK will render at an aspect ratio suitable for the particular image based on the size provided by the user.	No. Can only be provided by the SDK.
RoadInfoImg	Generated by the SDK. Size and aspect ratio not retrievable.	Background color customizable via Color	Will render at the size specified by the user if the allowResize parameter is false. If allowResize is true, the SDK will render at an aspect ratio suitable for the particular image based on the size provided by the user.	No. Can only be provided by the SDK.

Tip

For debugging, encode Uint8List images as Base64 strings using base64Encode and view them on a Base64 image decoding website.

---

Render images

The following approaches show how to get images in Uint8List format from the SDK, illustrated using the lane image from NavigationInstruction. The same principles apply to all image types.

Use the direct method

Uint8List? imageData = instruction.getLaneImage(
    size: const Size(200, 100),
    format: ImageFileFormat.png,
);

This approach is simple with minimal code. However, it has limitations:

• Images always render at your explicitly requested size (automatic resizing not available)
• Recommended image size based on content is not retrievable
• Image UID is not accessible

The getLaneImage method returns null if the image is invalid.

Use getRenderableImageBytes

LaneImg laneImage = instruction.laneImg;
Uint8List? imageData = laneImage.getRenderableImageBytes(
    size: const Size(200, 100), 
    format: ImageFileFormat.png, 
    allowResize: true
);

// Access the image UID
int uid = laneImage.uid;

This approach allows you to configure the allowResize parameter but does not provide metadata about the Uint8List image:

• When allowResize is true - The image may be resized to a more suitable size that differs from your requested dimensions. However, the actual size is not exposed
• When allowResize is false - The image renders at your exact requested size, though it may have an improper aspect ratio

You can use the image UID to optimize redraws efficiently.

The getRenderableImageBytes method returns null if the image is invalid.

Use getRenderableImage

LaneImg laneImage = instruction.laneImg;
RenderableImg? renderableImage = laneImage.getRenderableImage(
    size: const Size(200, 100), 
    format: ImageFileFormat.png, 
    allowResize: true
);
Uint8List? imageData = renderableImage?.bytes;

// Access the image UID
int uid = laneImage.uid;

// Get the actual rendered size
int? width = renderableImage?.width;
int? height = renderableImage?.height;

This approach provides the most flexibility by allowing you to configure the allowResize parameter and access metadata about the Uint8List image:

• When allowResize is true - The image may be resized to a more suitable size that differs from your original request. Access the actual dimensions via the RenderableImg object
• When allowResize is false - The image renders at your exact requested size, though it may have an unsuitable aspect ratio

You can leverage the image UID to optimize redraw operations efficiently.

The getRenderableImage method returns null if the image is invalid.