Load¶

Overview¶

Loading data is a two-step process. First, load your media, then load the annotations associated with them.

You will need to have a valid Tator token to load data into the database and a configuration yaml file for your project. Configuration YAML files are available per project in ai projects doc. See the CFE lab deployments for an example.

Currently, the aidata tool supports loading images and either VOC formatted xml files, or SDCAT formatted CSV files which contain bounding box, score, class, and optionally cluster information. You can produce a compatible CSV from sdcat clustering, VSS mining scripts, or any detector as long as the columns match the SDCAT CSV Format.

What metadata is loaded from the media depends on the project configuration. The code that extracts the metadata is defined in a tap module that is designed per project per the following table. You should not need to set this - these should be captured in the project YAML configuration file "plugin" section as appropriate for the project but are listed here for reference. For example,

plugins:
  - name: "extractor"
    module: "mbari_aidata.plugins.extractors.tap_cfe_media"
    function: "extract_media"

Step 1¶

Two types of media files can be loaded: images and videos; both need to be loaded before annotation data can be loaded. Media can be loaded individually, from a directory, or from a simple text file with an absolute path listing of each media, one file per line.

Load images in a directory¶

aidata load images --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_cfe.yml --input /Volumes/CFElab/2021-07-01/ --section 2021/07

Load a single image¶

aidata load images --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_cfe.yml --input /Volumes/CFElab/2021-07-01/video.mp4 --section 2021/07

Load images from a text file¶

Suppose you have a text file images.txt with the following content:

/Volumes/CFElab/2021-07-01/image1.jpg
/Volumes/CFElab/2021-07-01/image20.jpg
/Volumes/CFElab/2021-07-01/image22.jpg

Load with:

aidata load images --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_cfe.yml --input images.txt --section 2021/07

Note that the section is optional and by default all media will be loaded into the All Media section. The section will be created if it does not exist.

Load images from a SDCAT formatted CSV¶

The image_path column of any SDCAT formatted CSV can be used as input. Only unique image paths are loaded — duplicate rows are ignored automatically.

aidata load images --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_i2map.yml --input /path/to/detections.csv --section 200m

Upload images directly (without a web-accessible mount)¶

By default images are registered in Tator by URL reference, which requires the files to be reachable via a configured mount. Use --upload to send the image bytes directly to Tator instead — no mount or web server needed. Tator will transcode the images automatically after upload.

aidata load images --upload --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_i2map.yml --input /mnt/data/200m/ --section 200m

The --upload flag works equally well with a directory, a single file, a text listing, or a SDCAT CSV.

Load and verify duplicates¶

For large image sets, skipping the duplicate check can be useful to speed up the loading process, but for small sets, this is recommended.

aidata load images --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_cfe.yml --input images.txt --section 2021/07 --check-duplicates

🎥 Load videos¶

aidata load videos --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_cfe.yml --input /Volumes/CFElab/2021-07-01/ --section 2021/07

🎥 Upload videos directly¶

Use --upload to send video bytes directly to Tator (no mount required). Transcoding is triggered automatically.

aidata load videos --upload --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_i2map.yml --input /mnt/data/videos/ --section 200m

aidata load images --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_cfe.yml --input /Volumes/CFElab/2021-07-01/ --dry-run --section 2021/07

Step 2¶

Load bounding boxes (localizations) after the corresponding media is in Tator. The usual input is an SDCAT-formatted CSV.

SDCAT CSV Format¶

Detections/localizations are exchanged as SDCAT-formatted CSV files (produced by sdcat clustering, VSS mining scripts, and consumed by aidata load boxes). One row = one box. Coordinates are normalized to [0, 1] (already normalized; loaders pass normalize=False).

Core columns (header row required):

Optional columns produced by sdcat (not required to load): area, saliency, w, h, crop_path.

Minimal example you can create by hand or from another tool:

x,y,xx,xy,score,class,cluster,image_path,image_width,image_height
0.12,0.34,0.45,0.67,0.91,Copepod,-1,/mnt/data/isiis/frame_0001.png,2048,1536

Media must already be loaded (Step 1). image_path is matched to Tator by filename, not the full path.

Load boxes from an SDCAT CSV¶

Set your Tator token, then dry-run to verify the CSV before writing to the database:

export TATOR_TOKEN=<mytoken>
aidata load boxes --config https://docs.mbari.org/internal/ai/projects/config/config_isiis_deploy.yml --version testdeployment --input localizations_v3_aidata.csv --dry-run

If the dry-run looks good, load a single box as a smoke test:

aidata load boxes --config https://docs.mbari.org/internal/ai/projects/config/config_isiis_deploy.yml --version testdeployment --input localizations_v3_aidata.csv --max-num 1

Then load the entire file:

aidata load boxes --config https://docs.mbari.org/internal/ai/projects/config/config_isiis_deploy.yml --version testdeployment --input localizations_v3_aidata.csv

🏷️ Load boxes from a directory¶

aidata load boxes --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_cfe.yml --input /Volumes/CFElab/2021-07-01/ --version Baseline

Use the --help option for more information on the available options for aidata load boxes.

Advanced¶

Load cluster data from a SDCAT formatted CSV file¶

To update the cluster data of a previously loaded ROI, you can use the following command with a CSV file containing cluster information:

image_path,class,score,area,saliency,x,y,xx,xy,w,h,cluster,image_width,image_height,crop_path
/mnt/UAV/Level-1/trinity-2_20240820T160209_Seymour/SONY_DSC-RX1RM2/trinity-2_20240820T160209_Seymour_DSC01706.JPG,Kelp,0.802138149738,537.0,205,0.8211770623742455,0.669683257918552,0.8257042253521126,0.6840120663650076,0.0045271629778671,0.0143288084464555,5,7952,5304,/mnt/ML_SCRATCH/UAV/MBARI/uav-yolov5-30k/crops/45333.jpg
/mnt/UAV/Level-1/trinity-2_20240820T160209_Seymour/SONY_DSC-RX1RM2/trinity-2_20240820T160209_Seymour_DSC01706.JPG,Kelp,0.7822825610640001,607.5,237,0.5596076458752515,0.6738310708898945,0.5674044265593562,0.6881598793363499,0.0077967806841047,0.0143288084464554,6,7952,5304,/mnt/ML_SCRATCH/UAV/MBARI/uav-yolov5-30k/crops/45334.jpg

aidata load clusters --token $TATOR_TOKEN --config https://docs.mbari.org/internal/ai/projects/config/config_uav.yml --input clusters.csv --version Baseline

This will update the clusters to 5 and 6 respectively for the corresponding localizations in the database.

Load from a REDIS queue¶

Loading of video and video annotations is also supported through a REDIS server. To load video and video annotations from a REDIS queue, you can use the following command:

aidata load queue --config https://docs.mbari.org/internal/ai/projects/config/config_i2map.yml --token $TATOR_TOKEN

To reset the queue, removing any previously cached data, use the --reset option:

aidata load queue --config https://docs.mbari.org/internal/ai/projects/config/config_cfe.yml --token $TATOR_TOKEN --reset

Overriding config YAML¶

You can download and modify the configuration file for your project if needed. For example, to specify a local mount point:

Download the configuration YAML for your project from the ai projects doc and modify the mounts section to specify the local path and host for your media. For example:

curl -o config.yml https://docs.mbari.org/internal/ai/projects/config/config_cfe.yml

Then modify the mounts section in config.yml to point to your local media path and host:

mounts:
  - name: "image"
    path: "/Volumes/CFElab"
    host: "https://mantis.shore.mbari.org"

aidata load images --token $TATOR_TOKEN --config config.yml --input /Volumes/CFElab/2021-07-01/ --section 2021/07