Skip to content

Commit 98e5fc4

Browse files
yinanazhouyinanazhou
committed
docs: update
1 parent f64e8a1 commit 98e5fc4

File tree

2 files changed

+78
-62
lines changed

2 files changed

+78
-62
lines changed

‎CLAUDE.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Mothra Annotator is a browser-based image annotation tool for creating bounding box annotations on document images. It supports three annotation classes: text, music, and staves. Annotations can be exported in JSON or YOLO format. Deployed to GitHub Pages at `/mothra-annotator/`.
8+
9+
## Commands
10+
11+
- `npm run dev` — start Vite dev server with HMR
12+
- `npm run build` — type-check with `tsc -b` then build with Vite
13+
- `npm run lint` — ESLint across the project
14+
- `npm run format` — format with Prettier
15+
- `npm run format:check` — check formatting without writing
16+
- `npm run deploy` — build and deploy to GitHub Pages via gh-pages
17+
18+
## Tech Stack
19+
20+
- React 19 + TypeScript, Vite 7, Tailwind CSS 4 (via `@tailwindcss/vite` plugin)
21+
- State management: Zustand (single store at `src/store/useAppStore.ts`)
22+
- No router, no backend — single-page client-only app
23+
24+
## Architecture
25+
26+
**State**: All app state lives in a single Zustand store (`useAppStore`). Components read from the store via hooks; canvas interaction code reads via `useAppStore.getState()` for performance (avoids re-renders during drag/draw).
27+
28+
**Canvas rendering**: The annotation canvas (`src/components/AnnotationCanvas.tsx`) uses a raw `<canvas>` element with 2D context, not React-managed DOM. Drawing is triggered via `requestAnimationFrame` and a manual `requestRedraw()` callback. The canvas handles DPR scaling for crisp rendering.
29+
30+
**Interaction model**: Mouse/pointer events are handled in `src/hooks/useCanvasInteraction.ts` using refs (not state) for in-flight drawing/dragging to avoid store churn. Drawing state and drag state are committed to the store only on pointer-up. Three edit modes: `idle`, `draw` (crosshair cursor, create boxes), `select` (move/resize existing boxes via 8-handle hit testing).
31+
32+
**Coordinate system**: Annotations store bounding boxes as `[x, y, w, h]` in image-pixel coordinates. The viewport transform (zoom + pan) converts between screen and image space via `src/lib/geometry.ts` helpers (`screenToImage`, `computeFitZoom`).
33+
34+
**Persistence**: Auto-saves to localStorage (debounced 500ms) keyed by image filename. Export supports JSON (full session) and YOLO (normalized center-format, 0-indexed class IDs). Import validates JSON structure.
35+
36+
**Annotation classes** are defined in `src/lib/constants.ts`: text (id=1), music (id=2), staves (id=3). Class IDs are 1-indexed in the app but converted to 0-indexed for YOLO export.
37+
38+
## Key Files
39+
40+
- `src/store/useAppStore.ts` — central state store with all actions
41+
- `src/components/AnnotationCanvas.tsx` — canvas rendering loop
42+
- `src/hooks/useCanvasInteraction.ts` — pointer/wheel event handling, drawing, drag/resize
43+
- `src/hooks/useKeyboardShortcuts.ts` — keyboard shortcuts
44+
- `src/lib/types.ts` — core type definitions
45+
- `src/lib/constants.ts` — class definitions, zoom/size constants
46+
- `src/lib/export.ts` — JSON/YOLO export and import
47+
- `src/lib/storage.ts` — localStorage session persistence

‎README.md‎

Lines changed: 31 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,42 @@
1-
# React + TypeScript + Vite
1+
# Mothra Annotator
22

3-
This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
3+
A browser-based image annotation tool for creating bounding box annotations on document images. Built for annotating text, music, and staves regions in scanned documents and sheet music.
44

5-
Currently, two official plugins are available:
5+
**Live demo:** [https://ddmal.ca/mothra-annotator/](https://ddmal.ca/mothra-annotator/)
66

7-
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
8-
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
7+
## Key Features
98

10-
## React Compiler
9+
- **Bounding box annotation** — Draw, move, and resize bounding boxes directly on images
10+
- **Three annotation classes** — Text, Music, and Staves, each with a distinct color and keyboard shortcut (`1`, `2`, `3`)
11+
- **Draw and Select modes** — Switch between creating new boxes (`D`) and selecting/editing existing ones (`V`)
12+
- **Resize handles** — 8-handle hit testing for precise box adjustments
13+
- **Zoom and pan** — Scroll to pan, Shift+Scroll to zoom, or use `+`/`-` keys; press `0` to reset view
14+
- **Class filter toggles** — Show or hide annotations by class
15+
- **Label visibility toggle** — Press `L` to show/hide annotation labels
16+
- **Undo support** — `Ctrl/Cmd+Z` to undo actions
17+
- **Auto-save** — Annotations persist to localStorage automatically
18+
- **Export formats** — Export as JSON (full session) or YOLO (normalized center-format with 0-indexed class IDs), with ZIP support for batch export
19+
- **Import** — Load previously exported JSON annotations
20+
- **Quick save** — `Ctrl/Cmd+S` to download annotations as JSON
21+
- **Keyboard-driven workflow** — Shortcuts for class selection, mode switching, deletion (`Delete`/`Backspace`), and more
1122

12-
The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
23+
## Tech Stack
1324

14-
## Expanding the ESLint configuration
25+
React 19, TypeScript, Vite 7, Tailwind CSS 4, Zustand
1526

16-
If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
27+
## Getting Started
1728

18-
```js
19-
export default defineConfig([
20-
globalIgnores(['dist']),
21-
{
22-
files: ['**/*.{ts,tsx}'],
23-
extends: [
24-
// Other configs...
25-
26-
// Remove tseslint.configs.recommended and replace with this
27-
tseslint.configs.recommendedTypeChecked,
28-
// Alternatively, use this for stricter rules
29-
tseslint.configs.strictTypeChecked,
30-
// Optionally, add this for stylistic rules
31-
tseslint.configs.stylisticTypeChecked,
32-
33-
// Other configs...
34-
],
35-
languageOptions: {
36-
parserOptions: {
37-
project: ['./tsconfig.node.json', './tsconfig.app.json'],
38-
tsconfigRootDir: import.meta.dirname,
39-
},
40-
// other options...
41-
},
42-
},
43-
]);
29+
```bash
30+
npm install
31+
npm run dev
4432
```
4533

46-
You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
34+
## Scripts
4735

48-
```js
49-
// eslint.config.js
50-
import reactX from 'eslint-plugin-react-x';
51-
import reactDom from 'eslint-plugin-react-dom';
52-
53-
export default defineConfig([
54-
globalIgnores(['dist']),
55-
{
56-
files: ['**/*.{ts,tsx}'],
57-
extends: [
58-
// Other configs...
59-
// Enable lint rules for React
60-
reactX.configs['recommended-typescript'],
61-
// Enable lint rules for React DOM
62-
reactDom.configs.recommended,
63-
],
64-
languageOptions: {
65-
parserOptions: {
66-
project: ['./tsconfig.node.json', './tsconfig.app.json'],
67-
tsconfigRootDir: import.meta.dirname,
68-
},
69-
// other options...
70-
},
71-
},
72-
]);
73-
```
36+
| Command | Description |
37+
| -------------------- | ---------------------------------------- |
38+
| `npm run dev` | Start Vite dev server with HMR |
39+
| `npm run build` | Type-check and build for production |
40+
| `npm run lint` | Run ESLint |
41+
| `npm run format` | Format with Prettier |
42+
| `npm run deploy` | Build and deploy to GitHub Pages |

0 commit comments

Comments
 (0)