1. ภาพรวมและขอบเขต

Box & Center Annotation Studio (ชื่อในสเปก: Unified Box & Center Annotator) เป็น single-page app ที่รันในเบราว์เซอร์ล้วน ๆ สำหรับ annotate ภาพด้วย bounding box และ center point / aiming guide ผลลัพธ์คือไฟล์ canonical เพียงไฟล์เดียวคือ annotations.json ที่เป็น single source of truth สำหรับ pipeline detection และ pose ปลายทาง

ไม่มี backend, ไม่มี bundler, ไม่มี runtime network dependency — ทุกอย่างทำงานในเบราว์เซอร์ ตัวแอปเองมี Content-Security-Policy ที่จำกัด origin ไว้ที่ตัวเองเท่านั้น

หลักการออกแบบที่ควรรู้ก่อนใช้

2. การเข้าใช้งาน (GitHub Pages / Local)

เนื่องจากแอปนี้เป็น Single-page application แบบ 100% Client-side จึงสามารถใช้งานได้ 2 รูปแบบหลัก:

2.1 ใช้งานผ่าน GitHub Pages (Static Hosting)

หากนำโค้ดขึ้น GitHub และเปิดใช้งาน GitHub Pages คุณสามารถเข้า URL ของโปรเจกต์ (เช่น https://<username>.github.io/<repo>/) เพื่อใช้งานได้ทันที โดย File System Access API สำหรับเซฟไฟล์ตรงเข้าเครื่องจะทำงานได้สมบูรณ์เนื่องจากทำงานบน HTTPS

2.2 ใช้งานแบบ Local (Docker)

สำหรับการรันในเครื่อง โปรเจกต์นี้ใช้ Docker ในการ serve ไฟล์ โดยไม่ต้องติดตั้ง Python หรือ Node.js (ใช้ python:3.9-slim สำหรับ serve ไฟล์ และ annotator-dev:latest สำหรับรันเทสต์)

รันแอป (serve)

รันจาก project root แล้วเปิด http://localhost:8080 — คำสั่ง copy/paste ได้เลย (PowerShell):

docker run --rm `
  -p 8080:8080 `
  -v "${PWD}:/workspace:ro" `
  -w /workspace `
  python:3.9-slim `
  python -m http.server 8080 --bind 0.0.0.0

ความหมายของแต่ละ argument

Build test image (ทำครั้งเดียว)

docker build -f Dockerfile.dev -t annotator-dev:latest .

รันเทสต์

ใช้ Node built-in runner (node --test) กับ ES modules — ไม่มี bundler และไม่มี test dependency ภายนอก:

docker run --rm -v "${PWD}:/workspace" -w /workspace annotator-dev:latest node --test

รัน suite เดียว:

docker run --rm -v "${PWD}:/workspace" -w /workspace annotator-dev:latest node --test tests/downstream.test.js

2.3 รองรับเบราว์เซอร์ใด

ออกแบบสำหรับเบราว์เซอร์ตระกูล Chromium (Chrome / Edge) ที่รองรับ File System Access API เพื่อ save แบบ in-place เบราว์เซอร์อื่นใช้ได้ผ่าน path สำรอง folder picker + download เน้น desktop-first (≥ 1024 px) — บนจอแคบ grid จะยุบเหลือคอลัมน์เดียว รองรับ touch ผ่าน Pointer Events แต่การ annotate แม่นยำบน touch ไม่ใช่เป้าหมายของรุ่นนี้

3. เริ่มต้นใช้งานใน 5 นาที

วงจรการทำงานหลักมี 4 ขั้น: Open → Annotate → Validate → Save

4. หน้าจอและเครื่องมือ

4.1 Header toolbar (แถวบนสุด)

4.2 Secondary toolbar (แถวรอง)

ประกอบด้วยกลุ่มควบคุม: Tool (Select/Box/Center/Pan), Class + ปุ่ม Manage Classes, Guide (โผล่เฉพาะตอนใช้ Center tool), Filter, pagination + Rows/Columns, และกลุ่ม Batch

ตัวเลือก Filter

กลุ่ม Batch

Batch Box… / Batch Center… ตั้งสถานะ task ให้ภาพทุกใบ ที่ตรง filter ปัจจุบัน พร้อมกัน (เลือกได้เฉพาะ pending / negative หรือ not_visible / skipped — completed ตั้งแบบ batch ไม่ได้เพราะต้องมี item) ส่วน Clean Orphans ลบ record ที่หาไฟล์ภาพไม่เจอออกจาก dataset

4.3 Status bar

แถบสถานะแสดง: Folder (path), Images (จำนวนรวม), Box Progress และ Center Progress (เสร็จ/ทั้งหมด), Orphans, Issues (badge) และ badge Unsaved Changes เมื่อมีการแก้ที่ยังไม่ save

5. เปิดโฟลเดอร์ & Image identity

เมื่อเปิดโฟลเดอร์ แอปจะอ่านไฟล์นามสกุล .png, .jpg, .jpeg (case-insensitive) จากทั้งโฟลเดอร์และ subfolder ทุกชั้น

Image identity = normalized path สัมพัทธ์กับ root ของโฟลเดอร์ ดังนั้น basename เดียวกันที่อยู่คนละ subfolder จะ ไม่ชนกัน — เช่น a/img.jpg กับ b/img.jpg เป็นคนละ image_id

ลำดับการค้นหาไฟล์ annotation

1. ถ้าพบ annotations.json → parse + validate แล้วโหลด
2. ถ้าไม่พบ แต่เจอ boxes.json และ/หรือ center.json → สร้าง migration preview (modal Import) ให้ยืนยันก่อน merge
3. ภาพที่มี record แต่ไม่พบไฟล์จริงในรอบนี้ จะถูกทำเครื่องหมายเป็น orphan

6. การ Annotate

6.1 Tools

6.2 พิกัด (coordinate contract)

พิกัดเป็น integer pixel บน raster ที่ผู้ใช้เห็นจริง (oriented) origin ที่มุมซ้ายบน

• Box = x, y, width, height (มุมซ้ายบน + ขนาดบวก) ขั้นต่ำ MIN_BOX_SIZE = 3 px และ clamp ให้อยู่ในขอบภาพ
• Center = x, y

6.3 สถานะของแต่ละ task

งาน box และ center มีชุดสถานะแยกกัน และสถานะที่บ่งบอก "ไม่มี/ข้าม" ต้องมี item เป็นศูนย์เสมอ:

6.4 Undo / Redo

Ctrl/Cmd+Z undo และ Ctrl/Cmd+Y redo ครอบคลุม add/move/resize/delete, เปลี่ยนสถานะ, guide, class, batch, copy/paste และ import merge (เป็น 1 command อะตอมมิก ไม่ว่าจะกระทบกี่ภาพก็ตาม) รองรับอย่างน้อย 100 ขั้น

6.5 Manage Classes & Expected Counts

ปุ่ม Manage Classes เปิด modal สำหรับ เพิ่ม/ลบ/เปลี่ยนชื่อ/จัดลำดับ class ของ box และ center และตั้ง Expected Counts Policy (min/max ของจำนวน box และ center) ค่า default คือ box {min:1, max:2} และ center {min:1, max:1} — ใช้ตรวจตอน task เป็น completed ถ้าจำนวนหลุดช่วงจะได้ ERR_EXPECTED_COUNT

7. Aiming guides

center ทุกจุดเก็บ guide ไว้เสมอ crosshair/midpoint จะอยู่ตรง center.x/y เป๊ะ ขนาด guide เป็น native pixel และ ไม่เปลี่ยนตาม zoom

8. Focus editor

เปิด Focus จาก tile เพื่อแก้แบบ zoom/pan ละเอียด มี loupe (แว่นขยาย) ช่วยเล็งพิกัด sidebar ขวาแบ่งเป็นสองส่วน: Workflow Actions และ Selection Details

Workflow Actions

ปุ่ม Previous Image, Next Incomplete (primary), Next Image, Copy Annotations, Paste Annotations และ dropdown ตั้งสถานะ Box Task / Center Task โดยตรง

Selection Details

เมื่อเลือก object หนึ่ง จะแก้ค่าได้ละเอียดผ่านช่อง input:

• X, Y และ (box) W, H — พิกัด/ขนาดเป็น integer pixel
• Class — เปลี่ยน class ของ object
• Guide (center) — point/circle/horizontal_span พร้อมช่อง Radius (min 12) หรือ Span (min 24)
• Link Box (center) — ผูก center เข้ากับ box ในภาพเดียวกัน (ถ้าผูกแล้ว center ต้องอยู่ในกรอบ box นั้น)

9. Import & merge

ปุ่ม Import เลือกไฟล์ JSON มา merge ระบบจะแสดง preview จำนวนภาพ/box/center, class ใหม่ที่จะถูกสร้าง และรายการภาพที่ขัดแย้ง

นโยบายแก้ conflict

เลือกได้ รายภาพ หรือใช้ Apply-to-all mirror ค่าลงทุกภาพพร้อมกัน การกด Cancel ต้องไม่มีผลต่อ state ที่ใช้งานอยู่

10. Validate & error codes

Validate ตรวจทั้ง dataset (root, class, path, asset, expected-count, geometry, status ฯลฯ) ผลแบ่งเป็น 2 ระดับ: error และ warning คลิกแต่ละ issue ในรายงานเพื่อกระโดดไปยังภาพที่เกี่ยวข้องได้

error = block การ save แบบ canonical ทั้งหมด ต้องแก้ก่อน  ·  warning = save ผ่านได้ แต่ต้องกดยืนยันรับทราบก่อน

10.1 Error codes (block save)

10.2 Warning codes (save ผ่านได้หลังยืนยัน)

11. Save / Download / Autosave

11.1 ลำดับการ Save

1. ถ้ามี error > 0 → block และเปิดรายงาน validation
2. ถ้ามีแต่ warning → ถามยืนยัน "Save anyway?" ก่อน
3. ถ้ามี writable directory handle → เขียน annotations.json กลับโฟลเดอร์
4. ถ้าไม่มี handle → fallback เป็น Blob download

11.2 Autosave & Recovery

Autosave เป็น opt-in (default ปิด) checkpoint metadata ของ annotation ลง IndexedDB ผูกกับ identity ของ dataset (hash ของ dataset.name + dataset.created_at) เมื่อเปิด dataset เดิม อีกครั้งและพบ checkpoint ที่ใหม่กว่าไฟล์ที่เพิ่งโหลด จะมี dialog ให้เลือก:

12. Dimension mismatch

ถ้าภาพที่โหลดมีมิติจริง (decoded) ไม่ตรงกับมิติที่เก็บไว้ใน annotation (และ task ไม่ใช่ pending) แอปจะเปิด dialog ให้เลือกวิธีแก้อย่างชัดเจน 3 ทาง:

13. Keyboard shortcuts

14. Downstream output (YOLO)

โมดูล js/downstream.js อ่าน canonical file โดยตรงเพื่อแปลงเป็น label YOLO (ไม่ใช่ปุ่มใน UI แต่เป็นส่วนของ contract สำหรับสาย data/ML) ค่าทุกตัว normalize ด้วยมิติภาพ ที่ precision 6 ตำแหน่ง

14.1 Detection

convertCanonicalToDetection — emit 1 บรรทัดต่อ box รูปแบบ "<class_id> <xc> <yc> <w> <h>" เฉพาะภาพที่ box task เป็น completed หรือ negative โดยภาพ negative ได้ label set ว่าง (ไม่มี box) class index มาจาก classes.boxes[].id ผ่าน label → name → id

14.2 Pose

convertCanonicalToPose — emit center เป็น keypoint เดียวบน full-image box รูปแบบ "<class_id> 0.5 0.5 1 1 <kx> <ky> 2" เฉพาะ center task ที่ completed

หมายเหตุ: adapter ทรง legacy (convertLegacyBoxesToDetection, convertLegacyCenterToPose) มีไว้เพื่อ regression parity เท่านั้น legacy file ไม่เคยเป็น source คู่ขนาน

15. โครงสร้าง annotations.json

ไฟล์ถูก serialize แบบ deterministic (natural sort, indent 2 ช่อง, timestamp เป็น UTC ...Z) ทำให้ parse แล้ว re-serialize ได้ผลเหมือนเดิมแบบ byte-identical ตัวอย่างย่อ (จาก fixture จริง):

{
  "schema_version": "1.0.0",
  "app": { "name": "box-center-annotator", "version": "0.1.0" },
  "dataset": {
    "name": "test",
    "center_guide_default": "point_crosshair",
    "expected_counts": { "boxes": { "min": 1, "max": 2 }, "centers": { "min": 1, "max": 3 } },
    "created_at": "2026-06-27T10:00:00Z",
    "updated_at": "2026-06-27T10:00:00Z",
    "coordinate_frame": "oriented_image_pixels",
    "orientation_policy": "browser_from_image"
  },
  "classes": {
    "boxes":   [ { "id": 0, "name": "Target" } ],
    "centers": [ { "id": 0, "name": "Center" } ]
  },
  "images": {
    "completed.jpg": {
      "image_id": "completed.jpg",
      "file_name": "completed.jpg",
      "relative_path": "completed.jpg",
      "image_width": 100,
      "image_height": 100,
      "box_task": {
        "status": "completed",
        "items": [ { "id": "box_1", "label": "Target", "x": 10, "y": 10, "width": 20, "height": 20 } ],
        "last_updated": "2026-06-27T10:00:00Z"
      },
      "center_task": {
        "status": "completed",
        "items": [ {
          "id": "center_1", "label": "Center", "x": 20, "y": 20,
          "box_id": "box_1", "guide": { "type": "point_crosshair" }
        } ],
        "last_updated": "2026-06-27T10:00:00Z"
      }
    }
  }
}

16. Privacy & data boundary

• ไม่มี analytics, telemetry, remote font, CDN หรือ external API — CSP meta tag จำกัด origin ไว้ที่ตัวแอป
• ภาพอยู่ใน memory ของเบราว์เซอร์และ ไม่เคยถูกฝังลงใน annotations.json
• localStorage เก็บเฉพาะ UI preference เท่านั้น: app-theme, app-grid-layout, app-autosave-enabled — ไม่มีชื่อไฟล์/พิกัด/ข้อมูลภาพ
• Autosave (opt-in) เก็บ metadata (รวมชื่อไฟล์และพิกัด) ใน IndexedDB เท่านั้น ผูกกับ dataset identity ไม่มี image bytes / object URL / file handle และมีคำสั่งล้างได้

17. ค่า default ของระบบ

สกัดจาก js/config.js และ js/geometry.js:

18. ข้อจำกัดที่ทราบ

• การ save in-place ต้องใช้เบราว์เซอร์ Chromium ที่รองรับ File System Access API — ที่อื่นต้องใช้ download fallback แล้วย้ายไฟล์เข้าโฟลเดอร์ dataset เอง
• การ download สำเร็จไม่ได้ยืนยันว่าไฟล์ถูกวางถูกที่ — dirty state คงอยู่จนกว่าจะเขียน canonical จริงสำเร็จ
• การ annotate แม่นยำบน touch อยู่นอกขอบเขตของรุ่นนี้
• แอปไม่ทำ de-identification และไม่ตีความเชิงคลินิก/วินิจฉัยใด ๆ

19. Glossary