Skip to main content

​
Overview

labelWise uses a standardized CSV format for importing and exporting bounding box annotations. This format is compatible with common computer vision workflows and can be easily integrated into ML pipelines.

​
CSV Schema

​
Column Definitions

Column NameData TypeRequiredDescription
label_namestringYesThe label/class name for the annotation (converted to lowercase)
bbox_xnumberYesX coordinate of the top-left corner of the bounding box (in pixels)
bbox_ynumberYesY coordinate of the top-left corner of the bounding box (in pixels)
bbox_widthnumberYesWidth of the bounding box (in pixels, must be > 0)
bbox_heightnumberYesHeight of the bounding box (in pixels, must be > 0)
image_namestringYesExact filename of the image (case-sensitive, must match loaded image)
image_widthnumberOptionalWidth of the source image in pixels
image_heightnumberOptionalHeight of the source image in pixels
All column names are case-insensitive during import. The parser converts them to lowercase before matching.

​
Export Format

When you export annotations from labelWise, the CSV is generated with the following characteristics:

​
Header Row

label_name,bbox_x,bbox_y,bbox_width,bbox_height,image_name,image_width,image_height

​
Data Rows

  • Quoted strings: label_name and image_name are always wrapped in double quotes
  • Escaped quotes: Internal quotes in filenames are escaped as ""
  • Numeric precision: Coordinates are rounded to integers using .toFixed(0)
  • Empty values: image_width and image_height are empty strings if dimensions are unknown

​
Example Export

label_name,bbox_x,bbox_y,bbox_width,bbox_height,image_name,image_width,image_height
"car",120,200,150,100,"street_photo.jpg",1920,1080
"person",450,180,80,220,"street_photo.jpg",1920,1080
"dog",50,300,90,75,"park_scene.png",1280,720
"bicycle",200,250,120,140,"park_scene.png",1280,720

​
Import Behavior

​
Parsing Process

The parseCsv function implements a custom CSV parser with the following features:
  1. Quote handling: Supports double-quoted fields with internal commas
  2. Escaped quotes: Recognizes "" as an escaped double quote
  3. Line endings: Handles both \n and \r\n line endings
  4. Whitespace: Automatically trims whitespace from cells

​
Validation Rules

During import, each row is validated: 
// Row is skipped if any of these conditions fail:
- imageName must be non-empty after trimming
- label must be non-empty after trimming
- x, y, width, height must all be finite numbers
- width must be > 0
- height must be > 0

​
Image Matching

Annotations are matched to loaded images by exact filename comparison: 
const imported = parsedByImage.get(image.file.name)
Critical: The image_name column must exactly match the filename of a loaded image, including:
  • File extension (.jpg, .png, etc.)
  • Letter casing
  • Spaces and special characters
Annotations for unmatched images are ignored silently.

​
Label Creation

During import:
  • All label_name values are converted to lowercase
  • New labels are automatically added to your label list
  • Existing labels are preserved and merged with imported labels
  • Label colors are auto-generated for new labels

​
Import Success Feedback

After import, labelWise displays:
  • Valid rows: Number of rows that passed validation
  • Matched images: Number of loaded images that received annotations
  • Imported boxes: Total number of annotations added

​
Common CSV Examples

​
Single Object Per Image

label_name,bbox_x,bbox_y,bbox_width,bbox_height,image_name,image_width,image_height
"cat",150,200,120,100,"photo1.jpg",800,600
"dog",200,150,100,120,"photo2.jpg",800,600

​
Multiple Objects Per Image

label_name,bbox_x,bbox_y,bbox_width,bbox_height,image_name,image_width,image_height
"person",100,50,80,200,"crowd.jpg",1920,1080
"person",300,60,75,190,"crowd.jpg",1920,1080
"person",500,80,85,210,"crowd.jpg",1920,1080

​
Without Image Dimensions

label_name,bbox_x,bbox_y,bbox_width,bbox_height,image_name,image_width,image_height
"tree",50,100,150,200,"forest.png",,
"tree",250,120,140,180,"forest.png",,

​
Filenames with Special Characters

label_name,bbox_x,bbox_y,bbox_width,bbox_height,image_name,image_width,image_height
"car",100,200,150,100,"My Photo (1).jpg",1920,1080
"sign",50,80,60,40,"Image ""quoted"".png",800,600

​
Integration with labelWise

​
Pre-Import Checklist

  1. ✅ Load all images into labelWise first
  2. ✅ Verify image filenames match exactly (check spaces, extensions)
  3. ✅ Ensure CSV has all required columns
  4. ✅ Validate that coordinates are within image bounds
  5. ✅ Check that width and height are positive numbers

​
Import Process

  1. Click Importar CSV button
  2. Select your CSV file
  3. labelWise validates the format and columns
  4. Annotations are matched to loaded images by filename
  5. New labels are created automatically
  6. Existing annotations are replaced (not merged)
Important: Importing a CSV replaces all existing annotations for matched images. There is no undo.

​
Export Process

  1. Annotate your images
  2. Click Exportar CSV
  3. File downloads as annotations-YYYY-MM-DD.csv
  4. Only images with at least one annotation are included

​
Troubleshooting CSV Issues

See the Troubleshooting guide for common CSV import problems and solutions.

Build docs developers (and LLMs) love

Get started for freeTalk to us