# Images
Last updated:
October 18, 2026
\| 6 minutes read
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[](#work-with-plain-images "Direct link to 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[](#work-with-vector-images "Direct link to 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[](#image-type-comparison "Direct link to 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](https://base64.guru/converter/decode/image).
## Render images[](#render-images "Direct link to 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[](#use-the-direct-method "Direct link to Use the direct method")
```dart
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[](#use-getrenderableimagebytes "Direct link to Use getRenderableImageBytes")
```dart
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[](#use-getrenderableimage "Direct link to Use getRenderableImage")
```dart
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.