# fomo_visualizer

Python API: `luxonis_train.attached_modules.visualizers.fomo_visualizer`

Draws the points a FOMO head predicts, and the target boxes.

## Classes

### FOMOVisualizer

Visualize FOMO heatmap detections as points and optional boxes.

The predicted points in a parking lot. Each class has its own color.

 * `Inputs:`: * `prediction_canvas`, `target_canvas` (`Tensor`): [B, 3, H, W]
    * `keypoints` (`list[Tensor]`): [Ki, 1, 4] per image, `(x, y, prob, class)`, pixels
    * `target_boundingbox` (`Tensor | None`): [N, 6], `[batch, class, x, y, w, h]`, `xywh` normalized
 * `Outputs:`: * `Tensor | tuple[Tensor, Tensor]`: [B, 3, H, W], a pair when targets are given

> **References**
> * Source: This project.
 * License: Apache-2.0 (this project)

> **Notes**
> Reuses bounding box target drawing and keypoint rendering for decoded FOMO predictions.

> **Example**
> Attached to a `FOMOHead` in `model.nodes`:

```yaml
- name: FOMOHead
  inputs: [EfficientRep]
  visualizers:
    - name: FOMOVisualizer
```

 * `Compatible with:`: * Used by:
   [FOMOModel](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/fomo/v1/model.md)
    * Nodes:
      [FOMOHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/fomo_head.md)

#### Methods

##### init

```python
def __init__(visibility_threshold: float = 0.5, radius: int = 5, **kwargs):
```

Initialize the visualizer and store the point options.

Parameters

 * `visibility_threshold` (`float`): Minimum probability of a point.
   [draw_predictions_per_class](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/fomo_visualizer.md)
   skips a point below it.
   [forward](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/fomo_visualizer.md)
   ignores it for points with three values. Defaults to `0.5`.
 * `radius` (`int`): Radius of a drawn point, in pixels. Defaults to `5`.
 * `**kwargs`: Keyword arguments forwarded to
   [BBoxVisualizer](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/bbox_visualizer.md),
   such as `labels`, `colors`, `scale`, and `node`.

##### draw_predictions_per_class

```python
def draw_predictions_per_class(canvas: Tensor, predictions: list[Tensor]) -> Tensor:
```

Draw the predicted points of a batch, colored by class.

For each image, the method scales the coordinates by the `scale` factor and keeps the points with a probability of at least
`visibility_threshold`. Then it clamps them into the image and draws them with `torchvision.utils.draw_keypoints`. A class takes
the color of its name in `colors`, and white when the name has no color.

> **Example**
> ```pycon
>>> import torch
>>> visualizer = FOMOVisualizer(labels=["cat"], colors=["red"])
>>> canvas = torch.zeros(1, 3, 8, 8, dtype=torch.uint8)
>>> points = [torch.tensor([[[4.0, 4.0, 0.9, 0.0]]])]
>>> viz = visualizer.draw_predictions_per_class(canvas, points)
>>> bool((viz[0, 0] == 255).any()), bool((viz[0, 1] == 255).any())
(True, False)
>>> faint = [torch.tensor([[[4.0, 4.0, 0.1, 0.0]]])]
>>> bool(
...     visualizer.draw_predictions_per_class(canvas, faint).any()
... )
False
```

Parameters

 * `canvas` (`Tensor`): `uint8` images of shape `[B, 3, H, W]`. The method does not modify it.
 * `predictions` (`list[Tensor]`): One tensor per image, of shape `[K_i, 1, 4]` with rows `(x, y, prob, class)` in pixels.

Returns

 * `Tensor`: A copy of `canvas` with the points drawn.

##### forward

```python
def forward(prediction_canvas: Tensor, target_canvas: Tensor, keypoints: list[Tensor], target_boundingbox: Tensor | None) ->
tuple[Tensor, Tensor] | Tensor:
```

Draw the predicted points, and the target boxes when given.

When every tensor in `keypoints` has three values per point, the method draws the points in red with [KeypointVisualizer.draw_predictions](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/keypoint_visualizer.md) and `radius`. That call ignores `visibility_threshold` and the `scale` factor. It draws a point with a probability of at least `0.5` at its coordinates, and any other point at the top-left corner. Otherwise the method calls [draw_predictions_per_class](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/fomo_visualizer.md), which colors the points by class and applies `visibility_threshold` and the `scale` factor. [FOMOHead](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/fomo_head.md) always produces four values per point, so its output takes the second path.

> **Example**
> ```pycon
>>> import torch
>>> visualizer = FOMOVisualizer(labels=["cat"], colors=["red"])
>>> canvas = torch.zeros(1, 3, 8, 8, dtype=torch.uint8)
>>> points = [torch.tensor([[[4.0, 4.0, 0.9, 0.0]]])]
>>> visualizer(canvas, canvas, points, None).shape
torch.Size([1, 3, 8, 8])
>>> boxes = torch.tensor([[0, 0, 0.25, 0.25, 0.5, 0.5]])
>>> len(visualizer(canvas, canvas, points, boxes))
2
```

Parameters

 * `prediction_canvas` (`Tensor`): `uint8` images of shape `[B, 3, H, W]` to draw the points on.
 * `target_canvas` (`Tensor`): `uint8` images of shape `[B, 3, H, W]` to draw the target boxes on.
 * `keypoints` (`list[Tensor]`): One tensor per image, of shape `[K_i, 1, 4]` with rows `(x, y, prob, class)` in pixels, or of
   shape `[K_i, 1, 3]` without the class.
 * `target_boundingbox` (`Tensor | None`): Boxes of shape `[N, 6]` with rows `[batch_index, class, x, y, w, h]`, `xywh` normalized
   to `[0, 1]`. `None` when the batch has no `boundingbox` labels.

Returns

 * `tuple[Tensor, Tensor] | Tensor`: The pair `(targets, predictions)` of drawn images when `target_boundingbox` is not `None`;
   otherwise only the predictions image.

#### Attributes

##### supported_tasks