Object detection

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

/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 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

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. A record is copied only when both its image and its XML copy succeed.

Size limit

One tracebloc data ingest takes at most 1 GiB in total and 500 MiB per file. If your dataset is larger:

Save the images as JPEG instead of PNG.
Lower the resolution: resize every image to one smaller size, and scale the box coordinates in the XML files to match.
Use fewer images.

For datasets that stay above the limit, see Size limit.

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

Ingest the data: Prepare Data
Shared rules for every template: Dataset templates

Overview

Create a Use Case

Join a Use Case

Environment Setup

Tools & Help

Releases

Folder layout

Annotation format (Pascal VOC)

ingest.yaml

How records are stored

What the ingestor checks

Size limit

Sample dataset

Next steps

​Folder layout

​Annotation format (Pascal VOC)

​ingest.yaml

​How records are stored

​What the ingestor checks

​Size limit

​Sample dataset

​Next steps

Folder layout

Annotation format (Pascal VOC)

ingest.yaml

How records are stored

What the ingestor checks

Size limit

Sample dataset

Next steps