BossyPaints

BossyPaints is a web-based 3D volumetric annotation tool designed for dense painting and proofreading of neuroscience datasets. It enables efficient annotation workflows using a task-based approach with small, manageable volumes, implementing the "small-and-many" proofreading strategy described in Bishop et al. (2020).

Features

• 🎨 Interactive 3D Painting: Intuitive lasso-based annotation tools for volumetric data
• 📊 BossDB Integration: Native support for BossDB cloud storage and retrieval
• ⚡ Collaboration: Task-based workflow with user assignment and progress tracking
• 🔄 Multi-resolution Support: Efficient rendering across different zoom levels
• 💾 Automatic Checkpointing: Save progress incrementally with background processing
• 🎯 Neuroglancer Integration: Generate links to view annotations in Neuroglancer
• 📱 Touch Support: Optimized for both desktop and tablet workflows

Architecture

BossyPaints consists of two main components:

• Frontend: SvelteKit-based web application with TypeScript
• Backend: FastAPI server with Python for data processing and task management

Frontend Stack

• SvelteKit - Web framework
• TypeScript - Type safety
• p5.js - Canvas rendering and interaction
• Tailwind CSS - Styling

Backend Stack

• FastAPI - API framework
• uvicorn - ASGI server
• intern - BossDB Python client
• zmesh - 3D mesh generation

Development

Prerequisites

• Python 3.11 or higher
• Node.js 18 or higher
• uv (recommended Python package manager)

Installation

1. Clone the repository

   git clone https://github.com/aplbrain/bossypaints.git
   cd bossypaints

2. Set up the backend

   cd server
   # Install uv if not already installed
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install dependencies and run server
   uv run uvicorn server:app --reload

3. Set up the frontend (in a new terminal)

   cd bossypaints
   npm install
   npm run dev

4. Access the application

   Open your browser and navigate to http://localhost:5173

Docker Deployment

For production deployment, use the provided Docker configuration:

docker-compose up -d

📖 Usage

Getting Started

1. Obtain BossDB API Token: Visit BossDB Token Management to generate your API token

2. Create a Task:

   • Navigate to "Create New Task"
   • Enter your BossDB collection, experiment, and channel details
   • Define the region of interest (ROI) for annotation
   • Specify destination collection for storing annotations

3. Start Annotating:

   • Use the paint brush tool to create regions
   • Hit backspace to subtract from regions
   • Use keyboard shortcuts for efficient workflow

Keyboard Shortcuts

Key	Action
Space	Toggle between paint and pan modes
Backspace	Subtract current annotation
, / .	Navigate between Z layers
n / b	Next/previous segment ID
d	Delete current annotation
ESC	Reset view to task center
Alt + S	Save checkpoint
Alt + Shift + S	Final submission

API Endpoints

The backend provides a RESTful API for task management:

• GET /api/tasks - List all tasks
• POST /api/tasks/create - Create new annotation task
• GET /api/tasks/{task_id} - Get specific task details
• POST /api/tasks/{task_id}/checkpoint - Save annotation checkpoint
• POST /api/tasks/{task_id}/save - Final task submission

🔧 Configuration

Environment Variables

Create a .env file in the server directory:

KEYCLOAK_URL=<your-keycloak-url>
KEYCLOAK_CLIENT_ID=<your-client-id>
#KEYCLOAK_CLIENT_SECRET=<your-client-secret>
PUBLIC_BOSSYPAINTS_API_URL=""

Frontend Configuration

Modify bossypaints/src/lib/webpaint/config.ts for application settings:

export default {
    debug: false,
    fixedChunkSize: {
        width: 512,
        height: 512,
        depth: 16,
    },
    chunkLoading: {
        radius: 2,
        prioritizeCenter: true,
    },
};

Development Setup

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Style

• Frontend: Follow Prettier and ESLint configurations
• Backend: Follow PEP 8 with Black formatting
• Use TypeScript for all frontend code
• Include type hints for Python functions

Issue Reporting

Found a bug? Please report it on our Issues page with:

• Operating system and browser version
• Steps to reproduce the issue
• Expected vs actual behavior
• Screenshots if applicable

🙏 Acknowledgments

• Bishop et al. (2020) for the small-and-many proofreading methodology
• BossDB team for cloud infrastructure
• Neuroglancer for visualization integration
• The neuroscience open-source community

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Made with 💙 at