# layout

Python API: `modelconverter.utils.layout`

Guessing of tensor layouts from tensor shapes.

A layout is a lettercode such as `"NCHW"` naming every dimension of a tensor. Conversion needs one for each input and output -- to
know which axes are spatial, and how an image has to be laid out before it is fed to the model -- but a model rarely states it,
and the vendor toolchains reorder the dimensions along the way. The helpers here recover a plausible layout from a shape alone,
and carry a known layout over to a reordered shape.

## Functions

### guess_new_layout

```python
def guess_new_layout(old_layout: str, old_shape: list[int], new_shape: list[int]) -> str:
```

Guess the layout of the new shape.

The new shape must contain the same elements as the old one. If two values are the same, the order of their labels will be
preserved.

> **Example**
> ```pycon
>>> guess_new_layout("NCHW", [1, 3, 256, 256], [1, 256, 256, 3])
'NHWC'
```

Parameters

 * `old_layout` (`str`): Layout that describes `old_shape`.
 * `old_shape` (`list[int]`): Shape the layout is known for.
 * `new_shape` (`list[int]`): Reordering of `old_shape` to label.

Returns

 * `str`: Lettercode representation of the new layout.

Raises

 * `ValueError`: If the new shape has a different length than the old layout, or does not contain the same elements as the old shape.

### is_image_input_shape

```python
def is_image_input_shape(shape: list[int], layout: str, *, allow_batchless: bool = False) -> bool:
```

Return whether a shape and layout describe a supported image input.

Unknown channel counts are accepted for standard image layouts so they can be resolved later. Batchless layouts are accepted only when the caller has an explicit signal that the input is an image. Known channel counts must represent grayscale or color image data.

### is_interleaved_image_layout

```python
def is_interleaved_image_layout(layout: str | None) -> bool:
```

Return whether an image layout stores channels last.

### make_default_layout

```python
def make_default_layout(shape: list[int]) -> str:
```

Create a default layout for the given shape.

Tries to guess most common layouts for the given shape pattern. Otherwise, starts at `C` and gives each remaining dimension the next letter that is not in use yet.

> **Example**
> ```pycon
>>> make_default_layout([1, 3, 256, 256])
'NCHW'
>>> make_default_layout([1, 19, 7, 8])
'NCDE'
```

Parameters

 * `shape` (`list[int]`): Shape to create the layout for.

Returns

 * `str`: Lettercode representation of the layout.