CAD-Documenter/docs/USAGE.md

CAD-Documenter Usage Guide

Quick Start

# Install
cd /path/to/CAD-Documenter
uv sync

# Set API key
export OPENAI_API_KEY="sk-your-key"

# Run
uv run cad-doc your_video.mp4

Basic Commands

Generate Documentation

cad-doc video.mp4

Creates video_docs/ with:

• documentation.md - Main documentation
• frames/ - Extracted keyframes

With All Features

cad-doc video.mp4 --bom --atomizer-hints --pdf

Creates additional:

• bom.csv - Bill of Materials
• atomizer_hints.json - FEA setup hints
• documentation.pdf - PDF version

Custom Output Directory

cad-doc video.mp4 --output ./my_docs/

Recording Tips

For best results when recording your CAD walkthrough:

Video

• Use 1080p or higher resolution
• 30 FPS is sufficient
• Record the CAD viewport directly (not your whole screen)
• Spin the model slowly and steadily
• Pause briefly when showing details

Audio

• Use a decent microphone
• Speak clearly and at normal pace
• Name each component explicitly: "This is the main bracket..."
• Mention materials: "Made of 6061 aluminum"
• Describe functions: "This holds the motor in place"
• Note constraints: "Must fit within 200mm envelope"
• Call out features: "These fillets reduce stress concentration"

Structure

1. Start with an overview (assembly name, purpose)
2. Go through major components
3. Show details and features
4. Discuss assembly relationships
5. Mention any constraints or requirements

Configuration

Create Config File

cad-doc --init-config

Creates ~/.cad-documenter.toml with defaults.

Config Options

[api]
provider = "openai"  # or "anthropic"
# api_key = "sk-..."  # Or use env var

[processing]
whisper_model = "base"  # tiny/base/small/medium/large
use_scene_detection = true
max_frames = 15

[output]
include_bom = true
include_atomizer_hints = true

Environment Variables

export OPENAI_API_KEY="sk-..."      # For OpenAI
export ANTHROPIC_API_KEY="sk-..."   # For Anthropic
export CAD_DOC_PROVIDER="anthropic" # Override provider
export CAD_DOC_WHISPER_MODEL="medium" # Override Whisper model

CLI Options

Usage: cad-doc [OPTIONS] VIDEO

Options:
  -o, --output PATH           Output directory
  --frames-only               Only extract frames, skip analysis
  --atomizer-hints            Generate Atomizer FEA hints
  --bom                       Generate Bill of Materials
  --pdf                       Generate PDF output
  --frame-interval FLOAT      Seconds between frames
  --whisper-model [tiny|base|small|medium|large]
                              Whisper model size
  --api-provider [openai|anthropic]
                              Vision API provider
  --config PATH               Config file path
  --init-config               Create default config file
  -v, --verbose               Verbose output
  --version                   Show version
  --help                      Show this message

Python API

from cad_documenter.pipeline import DocumentationPipeline

# Simple usage
pipeline = DocumentationPipeline(
    video_path="walkthrough.mp4",
    output_dir="./docs"
)

results = pipeline.run_full_pipeline(
    atomizer_hints=True,
    bom=True,
    pdf=True
)

print(f"Documentation: {results['documentation']}")
print(f"Components: {results['components']}")

With Progress Callback

def on_progress(progress):
    print(f"[{progress.stage.value}] {progress.message} ({progress.progress:.0%})")

pipeline = DocumentationPipeline(
    video_path="walkthrough.mp4",
    output_dir="./docs",
    progress_callback=on_progress
)

results = pipeline.run()

Atomizer Integration

The atomizer_hints.json output is designed for use with Atomizer FEA optimization:

{
  "assembly_name": "Motor Bracket Assembly",
  "optimization_hints": {
    "objectives": [
      {"name": "mass", "direction": "minimize"},
      {"name": "stiffness", "direction": "maximize"}
    ],
    "constraints": [
      {"type": "envelope", "value": "200mm"},
      {"type": "frequency", "value": ">100 Hz"}
    ],
    "parameters": ["thickness", "fillet_radius", "rib_count"]
  },
  "fea_hints": {
    "critical_regions": [
      {"feature": "fillet", "concern": "stress_concentration"}
    ],
    "study_suggestions": [
      "Modal analysis recommended - frequency/vibration mentioned"
    ]
  }
}

Troubleshooting

"No API key found"

Set your API key:

export OPENAI_API_KEY="sk-..."

Or add to config file.

"No frames extracted"

• Check video file is valid
• Try different frame_interval
• Ensure ffmpeg is installed

"No components detected"

• Ensure video clearly shows the model
• Speak component names clearly
• Try larger Whisper model: --whisper-model medium
• Check API key has sufficient credits

"Transcription failed"

• Video may have no audio track
• Use --frames-only to skip transcription
• Check ffmpeg can extract audio: ffmpeg -i video.mp4 -vn audio.wav

PDF generation fails

• Install pandoc: apt install pandoc texlive-xetex
• Or use Typst with Atomaste Report Standard