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

# Oval

> Draws elliptical footprints at the bottom of detected objects.

## Overview

Creates ground-plane footprint visualization by drawing partial ellipses at the bottom center of each bounding box. The elliptical shape provides a natural representation of object presence on the ground plane, making it ideal for spatial awareness, shadow effects, and ground-based tracking visualizations.

## Function Signature

```python theme={null}
oval(
    image: np.ndarray,
    detections: Detections,
    thickness: Optional[int] = None,
    start_angle: int = default,
    end_angle: int = 235,
    colors: Optional[List[Tuple[int, int, int]]] = None
) -> np.ndarray
```

## Parameters

<ParamField path="image" type="np.ndarray" required>
  Input image array with shape (H, W, 3) in BGR color format.
</ParamField>

<ParamField path="detections" type="Detections" required>
  PixelFlow detections object containing bounding boxes. Each detection must have a `.bbox` attribute with (x1, y1, x2, y2) coordinates.
</ParamField>

<ParamField path="thickness" type="Optional[int]" optional default="None">
  Line thickness for ellipse drawing in pixels. If None, automatically adapts based on image size (typically 1-4 pixels). Default is None.
</ParamField>

<ParamField path="start_angle" type="int" optional default="default">
  Starting angle of the ellipse arc in degrees. Range: -180 to 180. Default is -45 (bottom-left quadrant).
</ParamField>

<ParamField path="end_angle" type="int" optional default="235">
  Ending angle of the ellipse arc in degrees. Range: -180 to 360. Default is 235 (bottom-right, creating bottom arc spanning \~280 degrees).
</ParamField>

<ParamField path="colors" type="Optional[List[Tuple[int, int, int]]]" optional default="None">
  List of BGR color tuples (B, G, R) where each value is 0-255. Colors are mapped to unique class\_ids in order of appearance. If None, uses default ColorManager colors.
</ParamField>

## Returns

<ResponseField name="result" type="np.ndarray">
  Image array with elliptical footprints drawn at the bottom center of each detected object. Original image is modified in-place.
</ResponseField>

## Examples

<CodeGroup>
  ```python Example theme={null}
  import cv2
  import pixelflow as pf
  from ultralytics import YOLO

  # Load image and model
  image = cv2.imread("pedestrians.jpg")
  model = YOLO("yolo11n.pt")
  outputs = model.predict(image)
  results = pf.results.from_ultralytics(outputs)

  # Basic footprint annotation with adaptive sizing
  annotated = pf.annotators.oval(image, results)

  # Custom thickness and colors for specific visualization
  custom_colors = [(0, 255, 255), (255, 0, 255), (255, 255, 0)]  # Cyan, Magenta, Yellow
  annotated = pf.annotators.oval(image, results, thickness=3, colors=custom_colors)

  # Full ellipse instead of bottom arc
  full_ellipse = pf.annotators.oval(image, results, start_angle=0, end_angle=360)

  # Narrow bottom arc for subtle ground indication
  subtle_footprint = pf.annotators.oval(image, results, start_angle=30, end_angle=150)

  ```
</CodeGroup>

## Error Handling

<Warning>
  This function may raise the following exceptions:

  * **AssertionError**: If image is not a numpy.ndarray.
  * **AttributeError**: If detections object doesn't have required bbox attributes.
  * **ValueError**: If angle parameters are invalid or cause OpenCV drawing errors.
</Warning>

## Notes

<Note>
  * Ellipse width automatically matches the full width of each bounding box
  * Ellipse height is set to 25% of the width for natural ground-plane proportions
  * Center point is positioned at the bottom-center of each bounding box (x\_center, y2)
  * Uses anti-aliased line drawing (cv2.LINE\_AA) for smooth curves
  * Thickness automatically adapts to image resolution when not specified
  * Colors cycle through the provided list if there are more detections than colors
  * Angles follow OpenCV convention: 0° = right, 90° = down, 180° = left, 270° = up
</Note>