optictriage 0.1.0__tar.gz

optictriage-0.1.0/.aidevops.json

@@ -0,0 +1,39 @@
+{
+  "version": "3.20.59",
+  "initialized": "2026-06-13T23:35:44Z",
+  "init_scope": "minimal",
+  "agent_source": false,
+  "features": {
+    "planning": true,
+    "git_workflow": true,
+    "code_quality": true,
+    "time_tracking": true,
+    "database": true,
+    "beads": true,
+    "sops": false,
+    "security": true
+  },
+  "time_tracking": {
+    "enabled": true,
+    "prompt_on_commit": true,
+    "auto_record_branch_start": true
+  },
+  "database": {
+    "enabled": true,
+    "schema_path": "schemas",
+    "migrations_path": "migrations",
+    "seeds_path": "seeds",
+    "auto_generate_migration": true
+  },
+  "beads": {
+    "enabled": true,
+    "sync_on_commit": false,
+    "auto_ready_check": true
+  },
+  "sops": {
+    "enabled": false,
+    "backend": "age",
+    "patterns": ["*.secret.yaml", "*.secret.json", "configs/*.enc.json", "configs/*.enc.yaml"]
+  },
+  "plugins": []
+}

optictriage-0.1.0/.beads/.gitignore

@@ -0,0 +1,40 @@
+# Database
+*.db
+*.db-journal
+*.db-shm
+*.db-wal
+
+# Lock files
+*.lock
+
+# Temporary
+last-touched
+*.tmp
+
+# Local history backups
+.br_history/
+
+# Sync state (local-only, per-machine)
+.sync.lock
+sync_base.jsonl
+
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+sync-state.json
+
+# Worktree redirect file
+redirect
+
+# bv (beads viewer) lock file
+.bv.lock

optictriage-0.1.0/.beads/config.yaml

@@ -0,0 +1,4 @@
+# Beads Project Configuration
+# issue_prefix: optictriage
+# default_priority: 2
+# default_type: task

optictriage-0.1.0/.beads/metadata.json

@@ -0,0 +1,4 @@
+{
+  "database": "beads.db",
+  "jsonl_export": "issues.jsonl"
+}

optictriage-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Opt out of AI model training
+* ai-training=false

optictriage-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-executables:
+    name: Build OS Installers
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev] pyinstaller
+
+      - name: Build with PyInstaller
+        run: pyinstaller optictriage.spec
+
+      - name: Compress Linux/macOS
+        if: runner.os != 'Windows'
+        run: |
+          cd dist
+          tar -czvf ../optictriage-${{ runner.os }}.tar.gz optictriage
+        shell: bash
+
+      - name: Compress Windows
+        if: runner.os == 'Windows'
+        run: |
+          Compress-Archive -Path dist/optictriage -DestinationPath optictriage-Windows.zip
+        shell: powershell
+
+      - name: Upload Release Asset
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            optictriage-*.tar.gz
+            optictriage-*.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build-executables
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/optictriage
+    permissions:
+      id-token: write
+      contents: read
+    
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tool
+        run: python -m pip install build
+
+      - name: Build Source Distribution and Wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

optictriage-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.gitnexus
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+venv/
+optictriage.db
+test.db
+.agents/
+.claude/
+.windsurf/
+.ctx/
+docs/Implementation docs/
+*.log

optictriage-0.1.0/AGENTS.md

@@ -0,0 +1,50 @@
+<!-- gitnexus:start -->
+# OpticTriage — Session Startup
+
+> **Pre-read at session start:** Before any other work, review the Implementation Plan
+> at `docs/Implementation docs/01_Implementation_Plan_Synthesis.md` to understand
+> the current phase, completed milestones, and immediate next tasks.
+> This ensures every session is aligned with the project roadmap.
+
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **optictriage** (132 symbols, 131 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/optictriage/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/optictriage/clusters` | All functional areas |
+| `gitnexus://repo/optictriage/processes` | All execution flows |
+| `gitnexus://repo/optictriage/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

optictriage-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-06-15
+
+### Added
+- **Core Engine:** Built a multiprocessing-enabled framework for evaluating image quality across CPU-bound operations.
+- **Color Normalization:** Non-destructive color correction module using cv2.mcc ColorCheckers and CIE 2000 ΔE metrics.
+- **Quality Analysis:** Exposure clipping detection (shadows and highlights) and HSI-based veiling glare scoring.
+- **Blur Detection:** Laplacian variance grid analysis to detect out-of-focus imagery.
+- **Near-Duplicates:** Sequential perceptual hashing (dhash) with dynamic temporal ordering to flag hovering drone duplicate frames.
+- **Targets:** Automatic identification of ArUco and ChArUco markers, exporting subpixel coordinate detections.
+- **Exporters:** Seamless CSV manifest generation, COLMAP database seeding (`database.db`), WebODM `gcp_list.txt` formatting, and Metashape `run_metashape.py` Python automation scripts.
+- **Testing:** Comprehensive end-to-end `pytest` suite simulating drone flights, synthetic metadata injections, and full pipeline permutations.

optictriage-0.1.0/CLAUDE.md

@@ -0,0 +1,50 @@
+<!-- gitnexus:start -->
+# OpticTriage — Session Startup
+
+> **Pre-read at session start:** Before any other work, review the Implementation Plan
+> at `docs/Implementation docs/01_Implementation_Plan_Synthesis.md` to understand
+> the current phase, completed milestones, and immediate next tasks.
+> This ensures every session is aligned with the project roadmap.
+
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **optictriage** (132 symbols, 131 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/optictriage/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/optictriage/clusters` | All functional areas |
+| `gitnexus://repo/optictriage/processes` | All execution flows |
+| `gitnexus://repo/optictriage/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

optictriage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpticTriage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

optictriage-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: optictriage
+Version: 0.1.0
+Summary: A lightweight, non-destructive diagnostic utility that pre-processes batches of field photographs before they enter SfM pipelines.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: gpxpy>=1.6.0
+Requires-Dist: imagehash>=4.3.1
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pyexiv2>=2.14.0
+Requires-Dist: pyproj>=3.6.0
+Requires-Dist: pyqt6>=6.5.0
+Requires-Dist: pyturbojpeg>=1.7.0
+Requires-Dist: rawpy>=0.19.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: shapely>=2.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-qt>=4.2.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OpticTriage
+
+OpticTriage is an advanced pre-processing and quality control pipeline for large-scale drone photogrammetry datasets. It filters out blurry, glary, or poorly-overlapped images, extracts EXIF/RTK telemetry, detects ArUco/ChArUco/ColorChecker targets, and exports instantly ready structures for Metashape, OpenDroneMap, and COLMAP.
+
+## Installation
+
+### Dependencies
+OpticTriage relies on several system binaries which must be installed:
+- **ExifTool**: Required for writing corrected telemetry back into DJI files.
+- **libexiv2**: C++ library underneath pyexiv2 for fast EXIF extraction.
+- **libjpeg-turbo**: Required for PyTurboJPEG to extract embedded raw previews quickly.
+
+Ensure these are accessible in your system `PATH`.
+If using the bundled version (via PyInstaller), the appropriate ExifTool binary is included in the `bin/` directory.
+
+### Quick Start
+```bash
+# Clone the repository
+git clone https://github.com/your-org/optictriage.git
+cd optictriage
+
+# Install dependencies (uv recommended)
+uv pip install -e .
+
+# Run the app
+python src/optictriage/app.py
+```
+
+## Workflow Tutorial
+1. **Import Stage**: Select your raw image directory and an output destination. OpticTriage utilizes SHA-256 chunked hashing to instantly flag duplicate files.
+2. **Metadata & RTK**: Scans DJI/Autel XMP payloads. Automatically corrects the `GPSAltitude` EXIF tag by utilizing RelativeAltitude + Base Station Elevation, directly rewriting the source file to prevent vertical bowing in SfM reconstructions. Flags any images with lost RTK Fixed states (Float/Single Point).
+3. **Quality Stage**: Assesses focus/blur via a Gridded Laplacian (top 5% sharpest patches), exposure clipping, and glare estimation via true HSI color conversion. Images falling below your thresholds are flagged.
+4. **Target Detection**: Runs a computer vision pipeline (LAB CLAHE equalisation, Bilateral Filtering) to locate ArUco, ChArUco, and ColorChecker targets. Corners are refined to subpixel precision (`cornerSubPix`) and serialized.
+5. **Export & Finalize**: Copies images non-destructively to `passed/` and `flagged/` folders. It generates a Python script to instantly spin up Agisoft Metashape, prepares `image_groups.txt` and `cameras.json` for ODM, and scaffolds `database.db` with an exact 64-byte OPENCV parameter blob for COLMAP.
+
+## GPU Acceleration
+OpticTriage will probe your system on launch. If an Nvidia GPU with CUDA is detected (via OpenCV), it will engage a two-tier GPU path:
+- **Tier 1 (Compute Heavy)**: Grayscale/LAB conversion, Laplacian filters, and CLAHE.
+- **Tier 2 (Filtering)**: Bilateral Edge-Preserving noise reduction.
+
+*Note: The first GPU call permanently reserves approximately 100MB of VRAM for the CUDA context. Please terminate OpticTriage before launching downstream pipelines like Metashape or COLMAP to fully release this VRAM back to your solver.*
+
+## Hardware Guidance
+
+**Minimum:**
+- CPU: Intel Core i7 / AMD Ryzen 7
+- RAM: 32 GB 
+- GPU: Nvidia RTX 3060
+- Storage: 1TB NVMe Gen3
+
+**Recommended:**
+- CPU: Intel Core i9 / AMD Ryzen 9
+- RAM: 64 GB
+- GPU: Nvidia RTX 4080 (Desktop or 150W+ Laptop Chassis. *Note: Thin laptop chassis variants running at 80W TGP will drastically underperform on CUDA pipelines*).
+- Storage: 2TB NVMe Gen4

optictriage-0.1.0/README.md

@@ -0,0 +1,55 @@
+# OpticTriage
+
+OpticTriage is an advanced pre-processing and quality control pipeline for large-scale drone photogrammetry datasets. It filters out blurry, glary, or poorly-overlapped images, extracts EXIF/RTK telemetry, detects ArUco/ChArUco/ColorChecker targets, and exports instantly ready structures for Metashape, OpenDroneMap, and COLMAP.
+
+## Installation
+
+### Dependencies
+OpticTriage relies on several system binaries which must be installed:
+- **ExifTool**: Required for writing corrected telemetry back into DJI files.
+- **libexiv2**: C++ library underneath pyexiv2 for fast EXIF extraction.
+- **libjpeg-turbo**: Required for PyTurboJPEG to extract embedded raw previews quickly.
+
+Ensure these are accessible in your system `PATH`.
+If using the bundled version (via PyInstaller), the appropriate ExifTool binary is included in the `bin/` directory.
+
+### Quick Start
+```bash
+# Clone the repository
+git clone https://github.com/your-org/optictriage.git
+cd optictriage
+
+# Install dependencies (uv recommended)
+uv pip install -e .
+
+# Run the app
+python src/optictriage/app.py
+```
+
+## Workflow Tutorial
+1. **Import Stage**: Select your raw image directory and an output destination. OpticTriage utilizes SHA-256 chunked hashing to instantly flag duplicate files.
+2. **Metadata & RTK**: Scans DJI/Autel XMP payloads. Automatically corrects the `GPSAltitude` EXIF tag by utilizing RelativeAltitude + Base Station Elevation, directly rewriting the source file to prevent vertical bowing in SfM reconstructions. Flags any images with lost RTK Fixed states (Float/Single Point).
+3. **Quality Stage**: Assesses focus/blur via a Gridded Laplacian (top 5% sharpest patches), exposure clipping, and glare estimation via true HSI color conversion. Images falling below your thresholds are flagged.
+4. **Target Detection**: Runs a computer vision pipeline (LAB CLAHE equalisation, Bilateral Filtering) to locate ArUco, ChArUco, and ColorChecker targets. Corners are refined to subpixel precision (`cornerSubPix`) and serialized.
+5. **Export & Finalize**: Copies images non-destructively to `passed/` and `flagged/` folders. It generates a Python script to instantly spin up Agisoft Metashape, prepares `image_groups.txt` and `cameras.json` for ODM, and scaffolds `database.db` with an exact 64-byte OPENCV parameter blob for COLMAP.
+
+## GPU Acceleration
+OpticTriage will probe your system on launch. If an Nvidia GPU with CUDA is detected (via OpenCV), it will engage a two-tier GPU path:
+- **Tier 1 (Compute Heavy)**: Grayscale/LAB conversion, Laplacian filters, and CLAHE.
+- **Tier 2 (Filtering)**: Bilateral Edge-Preserving noise reduction.
+
+*Note: The first GPU call permanently reserves approximately 100MB of VRAM for the CUDA context. Please terminate OpticTriage before launching downstream pipelines like Metashape or COLMAP to fully release this VRAM back to your solver.*
+
+## Hardware Guidance
+
+**Minimum:**
+- CPU: Intel Core i7 / AMD Ryzen 7
+- RAM: 32 GB 
+- GPU: Nvidia RTX 3060
+- Storage: 1TB NVMe Gen3
+
+**Recommended:**
+- CPU: Intel Core i9 / AMD Ryzen 9
+- RAM: 64 GB
+- GPU: Nvidia RTX 4080 (Desktop or 150W+ Laptop Chassis. *Note: Thin laptop chassis variants running at 80W TGP will drastically underperform on CUDA pipelines*).
+- Storage: 2TB NVMe Gen4

optictriage-0.1.0/TODO.md

@@ -0,0 +1,100 @@
+---
+mode: subagent
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
+# TODO
+
+Project task tracking with time estimates, dependencies, and TOON-enhanced parsing.
+
+Compatible with [todo-md](https://github.com/todo-md/todo-md), [todomd](https://github.com/todomd/todo.md), [taskell](https://github.com/smallhadroncollider/taskell), and [Beads](https://github.com/steveyegge/beads).
+
+## Format
+
+**Human-readable:**
+
+<!-- GH#17804: Format examples wrapped in HTML comment to prevent parsers
+     from extracting them as real tasks during upgrade-planning migrations.
+- [ ] t001 Task description @owner #tag ~30m risk:low logged:2025-01-15
+- [ ] t002 Dependent task blocked-by:t001 ~15m risk:med
+- [ ] t001.1 Subtask of t001 ~10m
+- [x] t003 Completed task ~30m actual:25m logged:2025-01-10 completed:2025-01-15
+- [-] Declined task
+-->
+
+Format: `- [ ] tNNN Description @owner #tag ~estimate risk:level logged:date`
+
+**Task IDs:**
+- `t001` - Top-level task
+- `t001.1` - Subtask of t001
+- `t001.1.1` - Sub-subtask
+
+**Dependencies:**
+- `blocked-by:t001` - This task waits for t001
+- `blocked-by:t001,t002` - Waits for multiple tasks
+- `blocks:t003` - This task blocks t003
+
+**Time fields:**
+- `~estimate` - AI-assisted execution time (~15m trivial, ~30m small, ~1h medium, ~2h large, ~4h major — see `reference/planning-detail.md`)
+- `actual:` - Actual active time spent (from session-time-helper.sh)
+- `logged:` - When task was added
+- `started:` - When branch was created
+- `completed:` - When task was marked done
+
+**Risk (human oversight needed):**
+- `risk:low` - Autonomous: fire-and-forget, review PR after
+- `risk:med` - Supervised: check in mid-task, review before merge
+- `risk:high` - Engaged: stay present, test thoroughly, potential regressions
+
+<!--TOON:meta{version,format,updated}:
+1.1,todo-md+toon,{{DATE}}
+-->
+
+## Ready
+
+<!-- Tasks with no open blockers - run /ready to refresh -->
+
+<!--TOON:ready[0]{id,desc,owner,tags,est,risk,logged,status}:
+-->
+
+## Backlog
+
+<!--TOON:backlog[0]{id,desc,owner,tags,est,risk,logged,status}:
+-->
+
+## In Progress
+
+<!--TOON:in_progress[0]{id,desc,owner,tags,est,risk,logged,started,status}:
+-->
+
+## In Review
+
+<!-- Tasks with open PRs awaiting merge -->
+
+<!--TOON:in_review[0]{id,desc,owner,tags,est,pr_url,started,pr_created,status}:
+-->
+
+## Done
+
+<!--TOON:done[0]{id,desc,owner,tags,est,actual,logged,started,completed,status}:
+-->
+
+## Declined
+
+<!-- Tasks that were considered but decided against -->
+
+<!--TOON:declined[0]{id,desc,reason,logged,status}:
+-->
+
+<!--TOON:dependencies-->
+<!-- Format: child_id|relation|parent_id -->
+<!--/TOON:dependencies-->
+
+<!--TOON:subtasks-->
+<!-- Format: parent_id|child_ids (comma-separated) -->
+<!--/TOON:subtasks-->
+
+<!--TOON:summary{total,ready,pending,in_progress,in_review,done,declined,total_est,total_actual}:
+0,0,0,0,0,0,0,,
+-->

optictriage-0.1.0/USER_GUIDE.md

@@ -0,0 +1,38 @@
+# OpticTriage User Guide
+
+OpticTriage is a lightweight, non-destructive diagnostic utility designed to pre-process large batches of field photographs (e.g., from drone surveys) before they enter computationally expensive Structure-from-Motion (SfM) pipelines like COLMAP, WebODM, or Agisoft Metashape.
+
+## Features
+
+- **Quality Screening:** Automatically detect and flag blurred, overexposed, or glare-affected images using adjustable thresholds.
+- **Near-Duplicate Detection:** Prevents unnecessary SfM processing by flagging sequential near-duplicate frames caused by hovering drones.
+- **Color Normalization:** Non-destructively apply ColorChecker matrix transformations based on keyframe observations.
+- **Target Detection:** Export high-precision subpixel coordinates for ArUco and ChArUco markers in the field.
+- **Direct SfM Exports:** Generate pre-seeded `database.db` for COLMAP, `gcp_list.txt` for WebODM, and Python scripts for one-click Agisoft Metashape ingestion.
+
+## Installation
+
+### Standalone Executable
+You can download the pre-compiled standalone executable for your operating system (Windows, macOS, Linux) from the GitHub Releases page. No Python installation is required.
+
+### Python Package (PyPI)
+If you prefer to run OpticTriage in your own Python environment:
+```bash
+pip install optictriage
+```
+
+## Workflow
+
+1. **Import:** Select a folder containing your raw or JPEG drone photographs. Choose an output destination.
+2. **Settings:** Adjust quality thresholds in the UI (Blur, Exposure, Glare). Toggle specific SfM exporters (WebODM, COLMAP, Metashape).
+3. **Execute:** Run the pipeline. OpticTriage will use multiprocessing to rapidly analyze imagery and extract telemetry/EXIF data.
+4. **Review:** Once complete, check the export directory. 
+   - Good images are soft-linked or copied into the `passed/` directory.
+   - Poor quality images are isolated in the `flagged/` directory.
+   - You will find a master `optictriage_manifest.csv` and specific subdirectories containing files ready for direct import into your chosen photogrammetry software.
+
+## Integrations
+
+- **COLMAP:** OpticTriage outputs an initialized `colmap/database.db` file. The database is pre-seeded with all cameras, EXIF focal length priors, and passed images. You can immediately launch COLMAP and proceed to Feature Extraction without importing files manually.
+- **WebODM:** OpticTriage outputs an `odm/gcp_list.txt` file containing the precise subpixel coordinate matches for any detected ArUco/ChArUco targets.
+- **Metashape:** Run the `metashape/run_metashape.py` file from within the Agisoft Metashape application via `Tools -> Run Script` to automatically create a chunk, import photos, set the coordinate system (WGS84), and bind GCP markers.