> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Image

> A class to represent an image

```python theme={null}
from grid_types import Image
```

A class to represent an image.

`img_type` describes the **semantic content** of the image ("rgb",
"depth", "segmentation", ...). `encoding_format` describes the
**wire encoding** of `data` — empty string for a raw ndarray (or a
raw pixel-buffer reshaped into one), or one of \{"jpeg", "png",
"webp"} when `data` is the encoded bytes from a camera firmware /
image-transport plugin. The two are orthogonal: a JPEG is still
semantically an RGB image after decoding.

## Fields

<ResponseField name="data" type="Union[np.ndarray, bytes]">
  image data (H x W x C ndarray for raw, or the encoded byte blob when `encoding_format` is set).
</ResponseField>

<ResponseField name="capture_params" type="dict, optional">
  the parameters of image capture.
</ResponseField>

<ResponseField name="img_type" type="str">
  semantic image type ("rgb", "depth", "segmentation", ...).
</ResponseField>

<ResponseField name="encoding_format" type="str">
  "" for raw pixel data; "jpeg" / "png" / "webp" when `data` is encoded bytes. Use `Image.decode()` to lazily turn encoded bytes into an ndarray.
</ResponseField>

<ResponseField name="shape" type="tuple, optional">
  Shape for raw bytes data (height, width, channels).
</ResponseField>

<ResponseField name="dtype" type="np.dtype, optional">
  Data type for raw bytes data.
</ResponseField>

## Constructor

```python Signature theme={null}
Image(
    data: Union[np.ndarray, bytes],
    shape: Optional[tuple] = None,
    dtype: Optional[np.dtype] = None,
    capture_params: Optional[dict] = None,
    img_type: Optional[str] = None,
    encoding_format: str = '',
)
```

## Methods

### `decode()`

```python Signature theme={null}
decode() -> np.ndarray
```

Return an RGB ndarray, decoding from JPEG/PNG/WebP if needed.

No-op (returns `self.data`) when the image is already an ndarray.

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> Image
```

Deserialize from dictionary - handles encoded formats and the legacy
ndarray + image\_data variants.

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer.

For encoded formats (JPEG/PNG/WebP) the bytes are kept as-is and
flagged with `encoding_format`; the receiver reconstructs via
`from_dict` without reshaping. For ndarrays we fall back
to the legacy raw-bytes-with-shape/dtype path.

## Example

```python theme={null}
# Create from numpy array
image = Image(img_array)
# Create from raw pixel bytes
image = Image(raw_bytes, shape=(480, 640, 3), dtype=np.uint8)
# Create from JPEG bytes (e.g. from a camera that emits
# CompressedImage). No decode happens here.
image = Image(jpeg_bytes, encoding_format="jpeg")
```


## Related topics

- [GRID Cortex Client](/models/cortex.md)
- [Sensors](/simulation/isaac/sensors.md)
- [ROS2 Communication](/simulation/isaac/comms.md)
- [CortexHubClient](/python-api/grid-cortex-client/cortexhubclient.md)
- [zoedepth](/models/cortex/zoedepth.md)