Quick Start

Get up and running with labelWise in 5 minutes

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