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

# Object detection

> Dataset template for object detection: images plus Pascal VOC XML annotations, ingest.yaml and the checks the data ingestor runs.

Draw boxes around objects. Each sample is one image plus one Pascal VOC XML file that lists the objects in it. There is **no labels CSV**: the ingestor reads the image list and the classes straight from the XML files.

## Folder layout

```text theme={null}
/data/shared/visdrone/
├── images/
│   ├── 0000001_02999_d_0000005.jpg
│   └── ...
└── annotations/
    ├── 0000001_02999_d_0000005.xml
    └── ...
```

* Both folders must have exactly these names and sit side by side.
* Images and annotations pair by **file stem**: `images/frame01.jpg` belongs to `annotations/frame01.xml`. Every image needs its XML and every XML needs its image.
* All images share one extension (`.jpg`, `.jpeg` or `.png`; default `.jpg`) and one resolution. The ingestor copies them unchanged and does not resize.

## Annotation format (Pascal VOC)

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<annotation>
    <folder>images</folder>
    <filename>frame01.jpg</filename>
    <source>
        <database>Unknown</database>
        <annotation>PASCAL VOC</annotation>
    </source>
    <size>
        <width>1920</width>
        <height>1080</height>
        <depth>3</depth>
    </size>
    <segmented>0</segmented>
    <object>
        <name>car</name>
        <pose>Unspecified</pose>
        <truncated>0</truncated>
        <difficult>0</difficult>
        <bndbox>
            <xmin>871</xmin>
            <ymin>572</ymin>
            <xmax>925</xmax>
            <ymax>664</ymax>
        </bndbox>
    </object>
    <!-- one <object> per box -->
</annotation>
```

Every element shown is required:

| Element                                   | Rule                                                                                                                                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `folder`, `filename`                      | Non-empty text.                                                                                                                                                                                   |
| `source/database`, `source/annotation`    | Non-empty text.                                                                                                                                                                                   |
| `size/width`, `size/height`, `size/depth` | Positive integers. `width` and `height` must equal the actual image dimensions.                                                                                                                   |
| `segmented`                               | `0` or `1`.                                                                                                                                                                                       |
| `object/name`                             | The class. Non-empty.                                                                                                                                                                             |
| `object/pose`                             | Non-empty text (`Unspecified` is fine).                                                                                                                                                           |
| `object/truncated`                        | `0` or `1`.                                                                                                                                                                                       |
| `object/difficult`                        | A non-negative integer. Values other than `0`/`1` are accepted with a warning.                                                                                                                    |
| `object/bndbox`                           | Integer `xmin`, `ymin`, `xmax`, `ymax` with `xmin < xmax`, `ymin < ymax`, all non-negative, and `xmax`/`ymax` within the declared image size. A box with area below 10 pixels produces a warning. |

An XML file with no `<object>` is accepted with a warning.

## ingest.yaml

```yaml theme={null}
apiVersion: tracebloc.io/v1
kind: IngestConfig
category: object_detection
table: visdrone_train
intent: train
images: /data/shared/visdrone/images/
annotations: /data/shared/visdrone/annotations/
```

| Field                         | Required            | Meaning                                                                                                                      |
| ----------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `images`                      | yes                 | The `images/` folder.                                                                                                        |
| `annotations`                 | yes                 | The `annotations/` folder. The record list comes from here.                                                                  |
| `csv`, `json`                 | **must not be set** | Object detection has no manifest; the config is rejected if either is present.                                               |
| `label`                       | leave out           | Classes come from `object/name`.                                                                                             |
| `target_size`                 | no                  | `[width, height]` every image must have. Default `[1920, 1080]`. Set it to your images' real size, for example `[448, 448]`. |
| `spec.file_options.extension` | no                  | `.jpg`, `.jpeg` or `.png`. Default `.jpg`.                                                                                   |
| `spec.file_options.min_size`  | no                  | Minimum `[width, height]`. Default `[32, 32]`.                                                                               |
| `color_mode`, `bit_depth`     | no                  | `RGB` or `grayscale`; `8` or `16`.                                                                                           |

## How records are stored

One record per **image**, not per box. The stored label of an image is its class histogram (for example `car:3 motor:1`), so the dataset summary reports class counts in boxes while the record count is the number of images. Data ids are content hashes, so re-running a failed ingest re-uses its rows.

## What the ingestor checks

| Check                   | Rejects                                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
| File type (images)      | Files under `images/` with an extension other than the configured one, or mixed extensions.                 |
| File type (annotations) | Files under `annotations/` that are not `.xml`.                                                             |
| Pascal VOC XML          | Any XML that breaks the rules in the table above.                                                           |
| File pairing            | Images without a matching `<stem>.xml`, and XML files without a matching image.                             |
| Image resolution        | Images whose size differs from `target_size`, mixed resolutions, images below `min_size`, unreadable files. |
| Label diversity         | Fewer than two distinct classes across all `object/name` values.                                            |

Plus the [checks every ingest runs](/create-use-case/templates#checks-every-ingest-runs). A record is copied only when both its image and its XML copy succeed.

## Sample dataset

The template ships one 1920×1080 aerial traffic frame from the public VisDrone dataset with its VOC annotation (classes such as `car` and `motor`). The `ingest.yaml` above ingests it with no overrides.

## Next steps

* Stage the data and run the ingest: [Prepare Data](/create-use-case/prepare-dataset)
* Shared rules for every template: [Dataset templates](/create-use-case/templates)