Skip to main content

​
Get Started in 5 Minutes

This guide will walk you through setting up labelWise and creating your first annotation.
1

Clone the Repository

First, clone the labelWise repository to your local machine:
git clone https://github.com/yourusername/labelWise.git
cd labelWise
Make sure you have Git installed on your system. If not, download it from git-scm.com.
2

Install Dependencies

Install all required packages using npm:
npm install
This will install all dependencies listed in package.json, including:
  • React 19
  • TypeScript
  • Vite
  • Tailwind CSS v4
  • lucide-react, sileo, and other UI libraries
The installation typically takes 1-2 minutes depending on your internet connection.
3

Start the Development Server

Launch the app in development mode:
npm run dev
Vite will start the development server and display the local URL:
VITE v7.3.1  ready in 543 ms

➜  Local:   http://localhost:5173
➜  Network: use --host to expose
Open your browser and navigate to http://localhost:5173 to see the app running.
4

Upload Your First Image

In the labelWise interface:
  1. Click the “Cargar imágenes” button in the top-right header
  2. Select one or more image files from your computer (JPEG, PNG, etc.)
  3. The images will appear in the left sidebar under “Lista”
// The app filters for valid image files automatically
const onlyImages = files.filter((file) => file.type.startsWith("image/"))
You’ll see a toast notification confirming how many images were loaded.
5

Create Your First Label

Before drawing annotations, you need to create labels:
  1. In the right sidebar under “Etiquetas”, find the input field labeled “Nueva etiqueta”
  2. Type a label name (e.g., “car”, “person”, “dog”)
  3. Click “Agregar” or press Enter
Bulk Import: You can also paste multiple labels separated by commas or newlines into the “Lote” textarea and click “Agregar lote”. For example:
car, person, bicycle, truck, traffic light
The label will appear in the list below and become the active label (highlighted).
6

Draw Your First Annotation

Now you’re ready to annotate:
  1. Ensure “Dibujar” mode is selected (not “Mover”)
  2. Click and drag on the image to draw a bounding box
  3. Release the mouse to create the annotation
// Minimum bounding box size is enforced
const MIN_BOX_SIZE = 8

if (width < MIN_BOX_SIZE || height < MIN_BOX_SIZE) return
The bounding box will be labeled with your active label and appear in your chosen color.

​
Edit Annotations

  • Move: Click and drag a bounding box to reposition it
  • Resize: Click a bounding box to select it, then drag the corner handles
  • Multi-select: Hold Ctrl/Cmd and click multiple boxes
  • Copy/Paste: Select boxes and use Ctrl/Cmd + C to copy, Ctrl/Cmd + V to paste
  • Delete: Select a box and remove it from the list in the right sidebar
7

Export Your Annotations as CSV

Once you’ve created annotations, export them:
  1. Click “Exportar CSV” in the top-right header
  2. A CSV file will download with the naming pattern: annotations-YYYY-MM-DD.csv
The exported CSV follows this schema:
label_name,bbox_x,bbox_y,bbox_width,bbox_height,image_name,image_width,image_height
"car",2660,2640,757,241,"image_001.png",3613,10821
"person",2660,2904,757,217,"image_001.png",3613,10821

// Export implementation in App.tsx:477
const exportCsv = () => {
  const rows = ["label_name,bbox_x,bbox_y,bbox_width,bbox_height,image_name,image_width,image_height"]
  // ... rows are built from annotations
  const blob = new Blob([rows.join("\n")], { type: "text/csv;charset=utf-8;" })
  // ... download is triggered
}

​
Additional Features to Explore

Now that you’ve created your first annotation, try these advanced features:

​
Zoom & Pan

  • Use the + and - buttons to zoom in/out (50% to 300%)
  • Click “Mover” mode and drag to pan across large images
  • Click “Reset” to return to 100% zoom

​
Grid Guide

  • Toggle “Guía” to show/hide a grid overlay
  • Grid spacing is 32 pixels for consistent alignment
// Grid is rendered with CSS background pattern
const GRID_SIZE = 32

​
CSV Table View

  • Click the “CSV” button in the center panel header
  • View all annotations in table format
  • Edit coordinates and labels directly in the table
  • Click any row to jump to that annotation

​
Import Existing Annotations

  • Click “Importar CSV” in the header
  • Select a CSV file matching the schema
  • Annotations are automatically mapped to images by filename
// CSV import maps annotations by image_name column
const parsedByImage = new Map<string, AnnotationBox[]>()
// ... parsing logic matches image.file.name

​
Next Steps

Installation Guide

Learn about production builds, deployment options, and environment setup

Introduction

Dive deeper into labelWise features and use cases

Build docs developers (and LLMs) love

Get started for freeTalk to us