Fal Label Tool

🏷️ Professional image labeling tool for VS Code - Create datasets for computer vision with bounding boxes, attributes, and export to COCO/YOLO formats.

Perfect for machine learning engineers, data scientists, and researchers working with computer vision datasets.

Features

• Custom Editor Integration: Opens images directly in VS Code with a dedicated labeling interface
• 🤖 AI-Powered Auto-Labeling: Automatic object detection using Fal API with smart deduplication
• Flexible Schema System: Define your own classes and attributes via scheme.json files
• Bounding Box Annotation: Draw, select, move, and resize bounding boxes
• Attribute Editing: Dynamic form generation based on your schema
• Export Capabilities: Export to COCO and YOLO formats
• Undo/Redo Support: Full history tracking with keyboard shortcuts
• Zoom & Pan: Smooth navigation for detailed work
• Sidecar Files: Non-destructive labeling using .labels.json files

Installation

Install directly from the VS Code Marketplace:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Fal Label Tool"
4. Click Install

Or install via command line:

code --install-extension yourpublishername.fal-label-tool

Quick Start

1. Open an Image

Right-click any image file (PNG, JPG, JPEG, BMP, WebP, GIF) and select "Open With..." → "Fal Label Tool"

2. Create a Schema File

Click "⚙️ Edit Scheme" to create a scheme.json file next to your image. Example:

{
  "version": 1,
  "FAL_KEY": "your-fal-api-key-here",
  "autoLabel": {
    "enabled": true,
    "objects": ["person", "car", "cat", "dog"]
  },
  "project": "Image Labeling Project",
  "imageLevel": {
    "classes": [
      "positive",
      "negative",
      "unknown"
    ]
  },
  "bbox": {
    "enabled": true,
    "classes": [
      "cat",
      "dog"
    ],
    "attributes": [
      {
        "name": "occluded",
        "type": "boolean",
        "default": false
      },
      {
        "name": "difficulty",
        "type": "enum",
        "options": [
          "easy",
          "medium",
          "hard"
        ],
        "default": "easy"
      },
      {
        "name": "note",
        "type": "string",
        "default": ""
      }
    ]
  }
}

3. Start Labeling

• Pan Tool (1): Navigate around the image
• BBox Tool (2): Draw new bounding boxes
• Select Tool (3): Select and move existing boxes
• Use the sidebar to manage boxes and edit attributes
• Press Ctrl+S / Cmd+S to save

4. Auto-Labeling (Optional)

To enable AI-powered object detection:

1. Get a Fal API Key: Sign up at fal.ai and get your API key
2. Add to Schema: Include FAL_KEY and autoLabel configuration in your scheme.json
3. Open Images: Auto-labeling will run automatically when you open images
4. Manual Trigger: Click the "🤖 Auto-Label" button for manual detection

Features:

• ⚡ Async batch processing - Detects multiple object types simultaneously
• 🧹 Smart deduplication - Uses Non-Maximum Suppression to remove overlapping boxes
• 🚀 Fast polling - Results appear as soon as detection completes
• 🎯 Accurate results - Powered by Fal's object detection API

Schema Format

The scheme.json file defines your labeling configuration:

Image-Level Classification

{
  "imageLevel": {
    "classes": ["cat", "dog", "other"]
  }
}

Bounding Box Configuration

{
  "bbox": {
    "enabled": true,
    "classes": ["person", "vehicle"],
    "attributes": [
      {
        "name": "visible",
        "type": "boolean",
        "default": true
      },
      {
        "name": "pose",
        "type": "enum",
        "options": ["standing", "sitting", "lying"],
        "default": "standing"
      },
      {
        "name": "count",
        "type": "number",
        "default": 1
      },
      {
        "name": "description",
        "type": "string",
        "default": ""
      }
    ]
  }
}

Attribute Types

• boolean: Checkbox input
• string: Text input (textarea for fields named "note" or containing "description")
• number: Number input
• enum: Dropdown with predefined options

Label File Format

Labels are saved as .labels.json files next to your images:

{
  "image": "photo.jpg",
  "updatedAt": "2025-01-27T10:30:00Z",
  "imageWidth": 1920,
  "imageHeight": 1080,
  "imageLevel": {
    "class": "positive"
  },
  "boxes": [
    {
      "id": "box_1706123456789_abc123",
      "class": "person",
      "x": 100,
      "y": 200,
      "width": 150,
      "height": 300,
      "attributes": {
        "visible": true,
        "pose": "standing",
        "count": 1,
        "description": "Person walking"
      }
    }
  ]
}

Keyboard Shortcuts

• 1: Switch to Pan tool
• 2: Switch to BBox tool
• 3: Switch to Select tool
• Ctrl/Cmd + Z: Undo
• Ctrl/Cmd + Shift + Z or Ctrl/Cmd + Y: Redo
• Ctrl/Cmd + S: Save labels
• Delete/Backspace: Delete selected box

Export Formats

COCO Format

Use the command "Image Labeler: Export to COCO" to generate a coco_export.json file with:

• Standard COCO structure (images, annotations, categories)
• Bounding box format: [x, y, width, height]
• Custom attributes preserved in annotation objects

YOLO Format

Use the command "Image Labeler: Export to YOLO" to generate:

• classes.txt: List of class names
• {image_name}.txt: YOLO format annotations (one per image)
• Normalized coordinates: class_id center_x center_y width height

Advanced Features

Multi-Image Workflow

Use "Image Labeler: Open All Images in Folder" to open all images in the current directory.

Live Schema Updates

Edit your scheme.json file in VS Code - changes are applied immediately to open labeling sessions.

History & Undo

Full undo/redo support with 50-level history. All operations (drawing, moving, deleting, attribute changes) are tracked.

Zoom & Navigation

• Mouse wheel to zoom in/out
• Pan tool for navigation
• Auto-fit on image load

Development

Building

npm install
npm run compile

Watch Mode

npm run watch

Testing

npm test

File Structure

vscode-image-labeler/
├── src/
│   ├── extension.ts          # Main extension entry point
│   ├── ImageLabelEditor.ts   # Custom editor provider
│   └── web/
│       ├── main.js          # Webview JavaScript
│       └── styles.css       # Webview styling
├── package.json
├── tsconfig.json
└── README.md

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Troubleshooting

Images not opening

• Ensure the image file extension is supported
• Check that the file is not corrupted
• Try "Open With..." and select "Image Labeler" explicitly

Scheme changes not applying

• Ensure the scheme.json file is valid JSON
• Check the VS Code output panel for error messages
• Try closing and reopening the image

Performance issues with large images

• Consider resizing very large images before labeling
• Use the zoom controls to focus on specific areas
• Close unused editor tabs to free memory

Export issues

• Ensure you have labeled images in your workspace
• Check that all .labels.json files are valid
• Verify write permissions in your workspace folder