CAD-Documenter/README.md

# CAD-Documenter

**One video → Complete engineering documentation.**

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

## The Solution

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** — 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
git clone http://100.80.199.40:3000/Antoine/CAD-Documenter.git
cd CAD-Documenter

# Install with uv
uv sync

# Or with pip
pip install -e .
```

### Requirements

- Python 3.12+
- ffmpeg (for video/audio processing)
- 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
cad-doc video.mp4

# 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

# 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

```
┌─────────────────────────────────────────────────────────────────────┐
│                         CAD-DOCUMENTER                              │
│                                                                     │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
│  │  Video   │───►│  Frame   │───►│  Vision  │───►│  Struct  │     │
│  │  Input   │    │  Extract │    │ Analysis │    │  Output  │     │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
│       │              │                │               │            │
│       ▼              ▼                ▼               ▼            │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
│  │  Audio   │───►│ Whisper  │───►│ Correlate│───►│ Generate │     │
│  │  Track   │    │Transcribe│    │ Timeline │    │   Docs   │     │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
└─────────────────────────────────────────────────────────────────────┘
```

## Atomizer Integration

CAD-Documenter generates FEA optimization hints for Atomizer:

```bash
cad-doc walkthrough.mp4 --atomizer-hints
```

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 [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.