> For the complete documentation index, see [llms.txt](https://docs.tensorleap.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tensorleap.ai/tensorleap-integration/python-api/code_loader/decorators/tensorleap_custom_visualizer.md).

# @tensorleap\_custom\_visualizer

code\_loader.inner\_leap\_binder.leapbinder\_decorators.tensorleap\_custom\_visualizer

The `tensorleap_custom_visualizer` decorator registers a [**Visualizer Function**](https://docs.tensorleap.ai/tensorleap-integration/writing-integration-code/visualizer-function.md).

```python
@tensorleap_custom_visualizer(name='image_visualizer',
                              visualizer_type=LeapDataType.Image,
                              heatmap_function=None)
def image_visualizer(image: np.ndarray) -> LeapImage:
    pass
```

| Args               |                                                                                                                                                                                                                                                                                                                                                      |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | *(str)* The name of the visualizer, e.g. `image_visualizer`. Must be unique among visualizers.                                                                                                                                                                                                                                                       |
| `visualizer_type`  | *(*[*LeapDataType*](https://docs.tensorleap.ai/tensorleap-integration/python-api/code_loader/enums/leapdatatype.md)*)* The kind of visualization. The function must return the matching [visualizer class](https://docs.tensorleap.ai/tensorleap-integration/python-api/code_loader/visualizer_classes.md), e.g. `LeapDataType.Image` → `LeapImage`. |
| `heatmap_function` | *(Callable, optional)* A function that reshapes the heatmap (the model's attention on the input) so it lines up with what the visualizer draws. Needed only when the visualizer changes the shape of its input, e.g. by resizing or cropping. See [Resize Image and Heatmap](#resize-image-and-heatmap).                                             |

#### Function inputs

Any number of `np.ndarray` arguments: inputs, ground truths or model predictions. Each one has a batch axis of size 1 at position 0, so remove it (`x[0]` or `x.squeeze(0)`) before building the result.

One argument may instead be typed [`SamplePreprocessResponse`](https://docs.tensorleap.ai/tensorleap-integration/python-api/code_loader/datasetclasses/samplepreprocessresponse.md) to receive the sample's id and its `PreprocessResponse`.

#### Function output

One [visualizer object](https://docs.tensorleap.ai/tensorleap-integration/python-api/code_loader/visualizer_classes.md) of the class that matches `visualizer_type`, without a batch axis.

The function must have a return type annotation with that class (`-> LeapImage`). Without one, a warning is printed. Do not use `from __future__ import annotations` in the file that defines visualizers: it turns annotations into strings, and registration fails.

### Examples

#### Basic Usage

```python
import numpy as np
from code_loader.contract.visualizer_classes import LeapImage
from code_loader.contract.enums import LeapDataType
from code_loader.inner_leap_binder.leapbinder_decorators import tensorleap_custom_visualizer


@tensorleap_custom_visualizer(name='image_visualizer', visualizer_type=LeapDataType.Image)
def image_visualizer(image: np.ndarray) -> LeapImage:
    image = image[0]                                   # remove the batch axis
    image = (image - image.min()) / (image.max() - image.min() + 1e-8) * 255
    return LeapImage(image.astype(np.uint8))
```

The [**visualizer\_classes**](https://docs.tensorleap.ai/tensorleap-integration/python-api/code_loader/visualizer_classes.md) pages contain more examples, one per class. Full script usage can be found in [**Integration Script**](https://docs.tensorleap.ai/tensorleap-integration/writing-integration-code.md#dataset-script).

#### Resize Image and Heatmap

When the visualizer changes the shape of its input, the heatmap the platform computed for that input no longer lines up with the result. `heatmap_function` applies the same change to the heatmap:

* It takes the **same argument names** as the visualizer. Each argument receives the heatmap of the matching visualizer input, with a batch axis of size 1 at position 0.
* It may take one extra argument typed `RawInputsForHeatmap` (from `code_loader.contract.datasetclasses`) to also receive the visualizer's original inputs.
* It returns the heatmap in the shape of the visualizer's output, without a batch axis.

```python
import numpy as np
import numpy.typing as npt
import cv2
from code_loader.contract.visualizer_classes import LeapImage
from code_loader.contract.enums import LeapDataType
from code_loader.inner_leap_binder.leapbinder_decorators import tensorleap_custom_visualizer


def resized_image_heatmap(image: npt.NDArray[np.float32]) -> npt.NDArray[np.float32]:
    # `image` here is the heatmap of the visualizer's `image` input, with a batch axis
    return cv2.resize(image[0], (512, 256))   # same resize as the visualizer


@tensorleap_custom_visualizer(name='resized_image',
                              visualizer_type=LeapDataType.Image,
                              heatmap_function=resized_image_heatmap)
def resized_image(image: npt.NDArray[np.float32]) -> LeapImage:
    return LeapImage(cv2.resize(image[0], (512, 256)).astype(np.uint8))
```

#### Guides

Full examples can be found in the **Dataset Integration** section of the following guides:

* [**MNIST Guide**](https://docs.tensorleap.ai/guides/full-guides/mnist-guide.md)
* [**IMDB Guide**](https://docs.tensorleap.ai/guides/full-guides/imdb-guide.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tensorleap.ai/tensorleap-integration/python-api/code_loader/decorators/tensorleap_custom_visualizer.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
