Skip to content

Commit a573ec4

Browse files
davramovdavramov
authored
Merge pull request #5 from mlexchange/dabramov-fixes
Adding install instructions for Windows users
2 parents 614e435 + 4b8a515 commit a573ec4

4 files changed

Lines changed: 717 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 128 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,145 @@
11
# Segmentation Annotation Studio
22

3-
Manual image segmentation tool for producing COCO datasets for SAM3 fine-tuning.
3+
A local, browser-based tool for drawing segmentation masks on scientific images and
4+
exporting training-ready datasets. Load data from a [Tiled](https://blueskyproject.io/tiled/)
5+
server or a local folder, annotate with a full set of drawing tools (including an
6+
in-browser AI "Magic" wand), and export to **COCO** (for SAM3 fine-tuning) or
7+
**DINOv3 / Lightly** semantic-segmentation format.
8+
9+
Everything runs on `127.0.0.1` — no data leaves your machine.
410

511
## Quick start
612

13+
You need **Node.js 18+** (`npm`) and **`curl`** on your PATH. That's it — everything
14+
else is bootstrapped for you.
15+
16+
### Node.js
17+
18+
You must have `node.js` installed on your machine. Follow the official instructions here for your operating system:
19+
https://nodejs.org/en/download
20+
21+
### Mac/Linux
722
```bash
823
chmod +x start_all.sh
924
./start_all.sh
1025
```
1126

12-
Opens:
13-
- Frontend: http://127.0.0.1:5173
14-
- Backend API: http://127.0.0.1:8002
15-
- Tiled: http://127.0.0.1:8010
27+
On first run this will automatically:
28+
29+
- install [`uv`](https://docs.astral.sh/uv/) if it's missing,
30+
- create a `.venv` with Python 3.12 and install the backend dependencies,
31+
- generate a strong Tiled API key into `backend/.env` (gitignored, never sent to the browser),
32+
- vendor the SlimSAM model in the background so the AI Magic tool works offline,
33+
- start Tiled, the backend API, the frontend dev server, and the docs site.
34+
35+
When it's ready, open the **Frontend** URL it prints. Press **Ctrl+C** to stop everything.
36+
37+
| Service | Default URL | Notes |
38+
| --------- | ----------------------- | -------------------------------------------- |
39+
| Frontend | http://127.0.0.1:5173 | The app (Vite dev server) |
40+
| Backend | http://127.0.0.1:8002 | FastAPI — `/api/*` |
41+
| Tiled | http://127.0.0.1:8010 | Data server (anonymous access is read-only) |
42+
| Docs | http://127.0.0.1:8000 | MkDocs (best-effort; the in-app Docs button) |
43+
44+
Ports are just defaults — if one is busy, `start_all.sh` automatically picks the next
45+
free port and wires the services together. You can also override them, e.g.
46+
`BACKEND_PORT=9002 ./start_all.sh`.
47+
48+
### Windows
49+
50+
On Windows, use the native PowerShell launcher instead (same behavior, no WSL/Git Bash needed).
51+
Double-click `windows\start_all.cmd`, or from a terminal:
52+
53+
```powershell
54+
powershell -ExecutionPolicy Bypass -File .\windows\start_all.ps1
55+
```
56+
57+
`$env:PROD = "1"` before running does the production build; `$env:BACKEND_PORT` etc. override
58+
ports. See [windows/README.md](windows/README.md) for details. You need **Node.js 18+** and
59+
**PowerShell 5.1+** (built into Windows 10/11); everything else is bootstrapped for you.
60+
61+
### Production build (single origin)
62+
63+
To serve the optimized SPA directly from the backend (one origin, gzip, no Vite dev
64+
server) instead of the dev setup:
65+
66+
```bash
67+
PROD=1 ./start_all.sh
68+
```
69+
70+
The frontend is built to `backend/static/` and served by FastAPI. The whole app is then
71+
available at the **Backend** URL (http://127.0.0.1:8002).
1672

17-
## Tabs
18-
1. **Connect** — pick a Tiled dataset or local folder
19-
2. **Annotate** — draw shapes (polygon, rectangle, ellipse, brush, eraser), manage classes, navigate slices
20-
3. **Export** — write COCO dataset for SAM3 fine-tuning
73+
## Workflow
2174

22-
## Output format
23-
COCO JSON adapted for SAM3: `segmentation` is always compressed RLE, `categories[].name` is the SAM3 concept phrase.
75+
The app is organized into four tabs:
76+
77+
1. **Connect** — choose a Tiled server + dataset, or point at a local folder of images
78+
(`.tif/.tiff`, `.npy`, `.png/.jpg`).
79+
2. **Browse** — explore and filter Tiled datasets by metadata, and open a sample into Annotate.
80+
3. **Reference** — author a per-dataset annotation guide: for each class a label, color,
81+
a written description, and example crops. Guide classes surface as one-click
82+
suggestions in Annotate, keeping annotators consistent.
83+
4. **Annotate** — draw and edit masks, manage classes, navigate slices, and export.
84+
85+
### Annotation tools
86+
87+
Polygon, magnetic lasso (live-wire), rectangle, ellipse, brush, fill, and a **Magic**
88+
wand backed by an in-browser SAM model (with a classic intensity wand as fallback). An
89+
eraser and a select/transform tool round out editing, with boolean clip/merge so new
90+
strokes don't overlap existing classes. A CLAHE adaptive-contrast display filter plus
91+
brightness/contrast/gamma controls help with low-contrast scientific data — display-only,
92+
never affecting exported pixels.
93+
94+
## Export formats
95+
96+
Export runs from within the Annotate tab (the download action). Two targets:
97+
98+
- **COCO (SAM3)** — COCO JSON where `segmentation` is compressed RLE and
99+
`categories[].name` is the SAM3 concept phrase, alongside the rendered images. Default.
100+
- **DINOv3 / Lightly** — a semantic-segmentation layout: `images/` + `masks/` with matching
101+
filename stems (each mask a single-channel integer PNG, pixel = class id, 0 = background)
102+
plus a `classes.json` index. For training non-SAM3 models (e.g. via LightlyTrain).
24103

25104
## Development
26105

106+
Backend (FastAPI, Python 3.11+):
107+
108+
```bash
109+
cd backend
110+
pip install -e ".[dev,test]" # or: uv pip install -e ".[dev,test]"
111+
flake8 . --max-line-length=120 --extend-ignore=E501,W503 # lint (isort enforced)
112+
pytest # tests
113+
```
114+
115+
Frontend (React + TypeScript + Vite):
116+
27117
```bash
28-
# Backend
29-
cd backend && pip install -e ".[dev,test]"
30-
pytest
31-
32-
# Frontend
33-
cd frontend && npm install
34-
npm test
35-
npm run dev
118+
cd frontend
119+
npm install
120+
npm run typecheck # tsc -b
121+
npm run test # vitest
122+
npm run build # production bundle
123+
npm run dev # dev server (start_all.sh runs this for you)
124+
```
125+
126+
These are the same checks CI runs (see `.github/workflows/ci.yml`).
127+
128+
## Security & data
129+
130+
- All services bind to `127.0.0.1` only. Do not change the host to `0.0.0.0` without
131+
reconsidering the auth posture.
132+
- Tiled anonymous access is **read-only**; writes (e.g. ingest) require the API key that
133+
`start_all.sh` generates into `backend/.env`. The key is resolved server-side and is
134+
**never** exposed to the frontend.
135+
- Annotation coordinates stay in image pixels throughout.
136+
137+
## Project layout
138+
139+
```
140+
backend/ FastAPI API, COCO/Lightly export, Tiled client, local-folder access
141+
frontend/ React SPA (Konva canvas, Zustand stores, in-browser SAM)
142+
tiled/ Local Tiled server config
143+
docs/ MkDocs Material documentation site
144+
start_all.sh One-command launcher for the full stack
36145
```

‎windows/README.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Windows launcher
2+
3+
Native Windows equivalent of the repo's `start_all.sh`. Starts Tiled, the backend API,
4+
the frontend, and the docs site together — bootstrapping everything on first run — on
5+
stock Windows 10/11 with **no WSL and no Git Bash**.
6+
7+
## Prerequisites
8+
9+
- **Node.js 18+** (`npm`) — install from <https://nodejs.org> or `winget install OpenJS.NodeJS`.
10+
- **PowerShell 5.1+** — ships with Windows 10/11 (PowerShell 7 also works).
11+
12+
Everything else (`uv`, a Python 3.12 `.venv`, backend dependencies, the SlimSAM model,
13+
the Tiled API key) is installed/generated automatically on first run.
14+
15+
## Run it
16+
17+
Easiest — **double-click** `windows\start_all.cmd`.
18+
19+
Or from a terminal, in the repo root:
20+
21+
```powershell
22+
powershell -ExecutionPolicy Bypass -File .\windows\start_all.ps1
23+
```
24+
25+
When it's ready it prints the URLs (Frontend, Backend, Tiled, Docs). Open the **Frontend**
26+
URL. Press **Ctrl+C** in the window to stop all services.
27+
28+
### Production build (single origin)
29+
30+
Build the optimized SPA and have the backend serve it (no Vite dev server); the whole app
31+
is then at the **Backend** URL:
32+
33+
```powershell
34+
$env:PROD = "1"; .\windows\start_all.ps1
35+
```
36+
37+
### Overriding ports
38+
39+
Ports auto-fall back to the next free one if a default is busy. To force specific ports:
40+
41+
```powershell
42+
$env:BACKEND_PORT = "9002"; $env:FRONTEND_PORT = "5273"; .\windows\start_all.ps1
43+
```
44+
45+
(`TILED_PORT`, `BACKEND_PORT`, `FRONTEND_PORT`, `DOCS_PORT` are all honored.)
46+
47+
## Notes & troubleshooting
48+
49+
- **Execution policy**: `start_all.cmd` and the `-ExecutionPolicy Bypass` invocation both
50+
bypass the policy for that one process only — no system-wide change.
51+
- **`uv` just installed but "not found"**: open a **new** PowerShell window (so `%USERPROFILE%\.local\bin`
52+
is on `PATH`) and re-run.
53+
- **`pycocotools` build error**: recent versions ship Windows wheels; if the install fails,
54+
install the **"Desktop development with C++"** workload from the Visual Studio Build Tools
55+
and re-run, or the launcher will retry the dependency install.
56+
- **Behavior parity**: this is a 1:1 port of `../start_all.sh` — same ports, same auto
57+
port-fallback, same Tiled key handling (anonymous access is read-only; the generated key
58+
authenticates writes and is never sent to the browser), same `PROD=1` prod-serving mode.
59+
All services bind to `127.0.0.1` only.

‎windows/start_all.cmd‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
@echo off
2+
REM Double-click launcher for Segmentation Annotation Studio on Windows.
3+
REM Runs start_all.ps1 with the execution policy bypassed for this process only
4+
REM (no global policy change). Any args are forwarded, e.g. set PROD=1 first.
5+
powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0start_all.ps1" %*

0 commit comments

Comments
 (0)