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.

Ingest with the CLI

Lay out each split as shown in Folder layout, then ingest the training set and the test set:

tracebloc data ingest ./visdrone-train --task object_detection --name visdrone_train --intent train
tracebloc data ingest ./visdrone-test --task object_detection --name visdrone_test --intent test

There is no --label-column: the classes come from the XML files. In a guided run, the CLI asks for the image resolution: press Enter to read it from the first image, or type it as WxH with the letter x, for example 1920x1080. Every image is checked against it. Pass --target-size WxH to set it without the question. To read an image’s size on macOS, run sips -g pixelWidth -g pixelHeight <file> or use the file’s Get Info; see Image resolution. The [1920, 1080] default in the ingest.yaml table below applies only to Helm ingests.

Folder layout

/data/shared/visdrone/
├── images/
│   ├── 0000001_02999_d_0000005.jpg
│   └── ...
└── annotations/
    ├── 0000001_02999_d_0000005.xml
    └── ...

With the CLI, the dataset folder is on your machine (./visdrone-train). With Helm, it sits on the shared volume (/data/shared/...).
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, with no spaces and no `:` (`traffic_light`, not `traffic light`); one such name fails the whole ingest. Class names are case-sensitive at ingest, so `Car` and `car` count as two classes: spell each class the same way in every file.
`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, but its image is skipped: it is not ingested and does not act as a background (negative) example.

Labeling tools such as CVAT and Label Studio often export float coordinates (871.5). The ingestor rejects them, so round every coordinate to an integer before you ingest. pose, truncated and difficult must be valid, but training ignores them: it reads only name, bndbox and size.

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]` (Helm only; the CLI reads it from your first image). 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). It must fit in 255 characters; an image with so many distinct classes that it does not fails the ingest. Because records are per image, 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. The training set and the test set are checked separately.

Plus the checks every ingest runs. A record is copied only when both its image and its XML copy succeed.

Training and test sets

Ingest the training set and the test set separately (--intent train and --intent test). The classes in the test set must be a subset of the classes in the training set. If the test set has a class the training set lacks, it does not appear in the test dataset list when you define the use case. The ingest does not catch this. Each split must also have at least two classes on its own.

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

Ingest with the CLI

Folder layout

Annotation format (Pascal VOC)

ingest.yaml

How records are stored

What the ingestor checks

Training and test sets

Size limit

Sample dataset

Next steps

​Ingest with the CLI

​Folder layout

​Annotation format (Pascal VOC)

​ingest.yaml

​How records are stored

​What the ingestor checks

​Training and test sets

​Size limit

​Sample dataset

​Next steps

Ingest with the CLI

Folder layout

Annotation format (Pascal VOC)

ingest.yaml

How records are stored

What the ingestor checks

Training and test sets

Size limit

Sample dataset

Next steps