Add comprehensive documentation and examples

- docs/USAGE.md: Full usage guide with CLI options, Python API, troubleshooting - docs/ATOMIZER_INTEGRATION.md: Guide for FEA/Atomizer integration - examples/sample_config.toml: Annotated configuration example - README.md: Expanded with installation, usage, architecture
2026-01-27 20:18:28 +00:00
parent 148180c12e
commit ca51b10c45
7 changed files with 1010 additions and 191 deletions
--- a/README.md
+++ b/README.md
@@ -2,61 +2,132 @@

 **One video → Complete engineering documentation.**

-Transform video walkthroughs of CAD models into comprehensive, structured documentation — ready for CDRs, FEA setups, and integration with the Atomaste engineering ecosystem.
+Transform video walkthroughs of CAD models into comprehensive, structured documentation — ready for CDRs, FEA setups, and client deliverables.
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

 ## The Problem

- Documentation is tedious — Engineers spend hours documenting CAD models manually
- Knowledge lives in heads — Verbal explanations during reviews aren't captured
- CDR prep is painful — Gathering images, writing descriptions, creating BOMs
- FEA setup requires context — Atomizer needs model understanding that's often verbal
+- **Documentation is tedious** — Engineers spend hours documenting CAD models manually
+- **Knowledge lives in heads** — Verbal explanations during reviews aren't captured
+- **CDR prep is painful** — Gathering images, writing descriptions, creating BOMs
+- **FEA setup requires context** — Atomizer needs model understanding that's often verbal

 ## The Solution

-### Input
- 📹 Video of engineer explaining a CAD model
- Optional: CAD file references, existing P/N databases
+Record yourself explaining your CAD model. CAD-Documenter:
+
+1. **Extracts key frames** at scene changes (smart, not fixed intervals)
+2. **Transcribes your explanation** via Whisper
+3. **Analyzes visually** using GPT-4o or Claude vision
+4. **Correlates visual + verbal** to identify components
+5. **Generates documentation** with images, BOM, and Atomizer hints

 ### Output
+
 - 📄 **Markdown documentation** — Structured, version-controlled
- 📊 **Bill of Materials** — With standardized P/N
- 🔧 **Component registry** — Parts, functions, materials, specs
- 🎯 **Atomizer hints** — Parameters, constraints, objectives for FEA
- 📑 **CDR-ready PDF** — Via Atomaste Report Standard
+- 📊 **Bill of Materials** — CSV with components, materials, functions
+- 🔧 **Component registry** — Detailed specs per component
+- 🎯 **Atomizer hints** — FEA objectives, constraints, parameters
+- 📑 **PDF** — Professional output via Atomaste Report Standard

 ## Installation

 ```bash
-# Clone the repo
+# Clone
 git clone http://100.80.199.40:3000/Antoine/CAD-Documenter.git
 cd CAD-Documenter

-# Install dependencies (using uv)
+# Install with uv
 uv sync
+
+# Or with pip
+pip install -e .
 ```

 ### Requirements
+
 - Python 3.12+
 - ffmpeg (for video/audio processing)
- Whisper (for transcription)
+- OpenAI or Anthropic API key (for vision analysis)
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# Windows (with chocolatey)
+choco install ffmpeg
+```
+
+## Quick Start
+
+```bash
+# Set API key
+export OPENAI_API_KEY="sk-your-key"
+
+# Run
+uv run cad-doc walkthrough.mp4
+
+# With all features
+uv run cad-doc walkthrough.mp4 --bom --atomizer-hints --pdf
+```

 ## Usage

 ```bash
-# Basic documentation
+# Basic
 cad-doc video.mp4

-# Full pipeline with all integrations
-cad-doc video.mp4 \
-  --output docs/my_assembly/ \
-  --atomizer-hints \
-  --bom \
-  --pdf
+# Custom output directory
+cad-doc video.mp4 --output ./my_docs/
+
+# Full pipeline
+cad-doc video.mp4 --bom --atomizer-hints --pdf

 # Just extract frames
-cad-doc video.mp4 --frames-only --output frames/
+cad-doc video.mp4 --frames-only
+
+# Use Anthropic instead of OpenAI
+cad-doc video.mp4 --api-provider anthropic
+
+# Better transcription (slower)
+cad-doc video.mp4 --whisper-model medium
 ```

+## Configuration
+
+Create a config file:
+
+```bash
+cad-doc --init-config
+# Creates ~/.cad-documenter.toml
+```
+
+Or set environment variables:
+
+```bash
+export OPENAI_API_KEY="sk-..."      # Required for OpenAI
+export ANTHROPIC_API_KEY="sk-..."   # Required for Anthropic
+export CAD_DOC_PROVIDER="anthropic" # Override default provider
+```
+
+See [docs/USAGE.md](docs/USAGE.md) for full configuration options.
+
+## Recording Tips
+
+For best results when recording:
+
+1. **Spin slowly** — Give the AI time to see each angle
+2. **Name components** — "This is the main bracket..."
+3. **Mention materials** — "Made of 6061 aluminum"
+4. **Describe functions** — "This holds the motor"
+5. **Note constraints** — "Must fit within 200mm"
+6. **Point out features** — "These fillets reduce stress"
+
 ## Architecture

 ```
@@ -76,18 +147,77 @@ cad-doc video.mp4 --frames-only --output frames/
 └─────────────────────────────────────────────────────────────────────┘
 ```

-## Integrations
+## Atomizer Integration

- **Atomizer** → FEA setup instructions from verbal explanations
- **Part Manager** → Standardized P/N lookup
- **Atomaste Report Standard** → Professional PDF generation
+CAD-Documenter generates FEA optimization hints for Atomizer:

-## Project Status
+```bash
+cad-doc walkthrough.mp4 --atomizer-hints
+```

-🚧 **Phase 1: Core Pipeline (MVP)** — In Progress
+Output `atomizer_hints.json`:
+```json
+{
+  "objectives": [{"name": "mass", "direction": "minimize"}],
+  "constraints": [{"type": "frequency", "value": ">100 Hz"}],
+  "parameters": ["thickness", "fillet_radius"],
+  "critical_regions": [{"feature": "fillet", "concern": "stress_concentration"}]
+}
+```

-See [ROADMAP.md](ROADMAP.md) for full implementation plan.
+See [docs/ATOMIZER_INTEGRATION.md](docs/ATOMIZER_INTEGRATION.md) for details.
+
+## Python API
+
+```python
+from cad_documenter.pipeline import DocumentationPipeline
+
+pipeline = DocumentationPipeline(
+    video_path="walkthrough.mp4",
+    output_dir="./docs"
+)
+
+results = pipeline.run_full_pipeline(
+    atomizer_hints=True,
+    bom=True,
+    pdf=True
+)
+```
+
+## Project Structure
+
+```
+CAD-Documenter/
+├── src/cad_documenter/
+│   ├── cli.py              # Command-line interface
+│   ├── pipeline.py         # Main orchestrator
+│   ├── config.py           # Configuration management
+│   ├── video_processor.py  # Frame extraction
+│   ├── audio_analyzer.py   # Whisper transcription
+│   ├── vision_analyzer.py  # AI vision analysis
+│   └── doc_generator.py    # Output generation
+├── prompts/                # AI prompts
+├── templates/              # Jinja2 templates
+├── tests/                  # Test suite
+├── docs/                   # Documentation
+└── examples/               # Example configs
+```
+
+## Roadmap
+
+- [x] Core pipeline (frames, transcription, vision)
+- [x] Configuration system
+- [x] Atomizer hints extraction
+- [x] BOM generation
+- [ ] Part Manager integration (P/N lookup)
+- [ ] Interactive review mode
+- [ ] Gitea auto-publish
+- [ ] SolidWorks add-in

 ## License

 MIT
+
+## Credits
+
+Built by [Atomaste](https://atomaste.ca) for the engineering community.