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
This commit is contained in:
Mario Lavoie
182
docs/ATOMIZER_INTEGRATION.md
Normal file
182
docs/ATOMIZER_INTEGRATION.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# Atomizer Integration Guide
|
||||
|
||||
CAD-Documenter generates FEA optimization hints that integrate with Atomizer, the Atomaste optimization framework.
|
||||
|
||||
## Overview
|
||||
|
||||
When you explain your CAD model in a video walkthrough, CAD-Documenter extracts:
|
||||
|
||||
1. **Optimization objectives** - What you want to minimize/maximize
|
||||
2. **Design constraints** - Limits and requirements
|
||||
3. **Design parameters** - Variables that could be optimized
|
||||
4. **Critical regions** - Areas requiring careful FEA attention
|
||||
|
||||
## Verbal Cues → Atomizer Hints
|
||||
|
||||
### Objectives
|
||||
|
||||
| What You Say | Generated Objective |
|
||||
|--------------|---------------------|
|
||||
| "minimize the weight" | `{"name": "mass", "direction": "minimize"}` |
|
||||
| "maximize stiffness" | `{"name": "stiffness", "direction": "maximize"}` |
|
||||
| "reduce stress" | `{"name": "stress", "direction": "minimize"}` |
|
||||
| "keep the frequency high" | `{"name": "frequency", "direction": "maximize"}` |
|
||||
| "minimize deflection" | `{"name": "displacement", "direction": "minimize"}` |
|
||||
|
||||
### Constraints
|
||||
|
||||
| What You Say | Generated Constraint |
|
||||
|--------------|---------------------|
|
||||
| "must fit in 200mm" | `{"type": "envelope", "value": "200mm"}` |
|
||||
| "under 500 grams" | `{"type": "limit", "value": "500g"}` |
|
||||
| "frequency above 100 Hz" | `{"type": "minimum", "value": "100 Hz"}` |
|
||||
| "stress cannot exceed 150 MPa" | `{"type": "maximum", "value": "150 MPa"}` |
|
||||
|
||||
### Parameters
|
||||
|
||||
Mentioning these terms adds them to potential design parameters:
|
||||
|
||||
- thickness, wall thickness
|
||||
- radius, fillet radius
|
||||
- diameter, hole size
|
||||
- length, width, height
|
||||
- angle, spacing, count
|
||||
- rib dimensions
|
||||
|
||||
### Critical Regions
|
||||
|
||||
| What You Mention | FEA Concern |
|
||||
|-----------------|-------------|
|
||||
| "this fillet is important" | Stress concentration |
|
||||
| "corner stress" | Stress concentration |
|
||||
| "bearing load here" | Contact stress |
|
||||
| "weld joint" | Fatigue concern |
|
||||
| "interface between parts" | Contact analysis |
|
||||
|
||||
## Output Format
|
||||
|
||||
### atomizer_hints.json
|
||||
|
||||
```json
|
||||
{
|
||||
"assembly_name": "Motor Bracket Assembly",
|
||||
"generated": "2026-01-27T20:15:00",
|
||||
|
||||
"model_understanding": {
|
||||
"components": [
|
||||
{
|
||||
"name": "Main Bracket",
|
||||
"material": "Aluminum 6061-T6",
|
||||
"function": "Motor mounting",
|
||||
"features": ["M6 holes", "fillet radii"]
|
||||
}
|
||||
],
|
||||
"materials_mentioned": ["Aluminum 6061-T6", "Steel"]
|
||||
},
|
||||
|
||||
"optimization_hints": {
|
||||
"objectives": [
|
||||
{"name": "mass", "direction": "minimize", "source": "Mentioned 'lightweight' in transcript"},
|
||||
{"name": "stiffness", "direction": "maximize", "source": "Mentioned 'stiff' in transcript"}
|
||||
],
|
||||
"constraints": [
|
||||
{"type": "envelope", "value": "200mm", "raw_match": "must fit in (\\d+)"},
|
||||
{"type": "minimum", "value": "100 Hz", "raw_match": "greater than (\\d+)"}
|
||||
],
|
||||
"parameters": ["thickness", "fillet_radius", "rib_count"]
|
||||
},
|
||||
|
||||
"fea_hints": {
|
||||
"critical_regions": [
|
||||
{"feature": "fillet", "concern": "stress_concentration"},
|
||||
{"feature": "interface", "concern": "contact_analysis"}
|
||||
],
|
||||
"study_suggestions": [
|
||||
"Modal analysis recommended - frequency/vibration mentioned",
|
||||
"Topology optimization could reduce mass while maintaining performance"
|
||||
]
|
||||
},
|
||||
|
||||
"transcript_summary": "This assembly provides structural support for a NEMA 23 motor..."
|
||||
}
|
||||
```
|
||||
|
||||
## Using with Atomizer
|
||||
|
||||
### 1. Generate Hints
|
||||
|
||||
```bash
|
||||
cad-doc walkthrough.mp4 --atomizer-hints
|
||||
```
|
||||
|
||||
### 2. Load in Atomizer
|
||||
|
||||
```python
|
||||
# In Atomizer study setup
|
||||
from atomizer import Study
|
||||
import json
|
||||
|
||||
with open("walkthrough_docs/atomizer_hints.json") as f:
|
||||
hints = json.load(f)
|
||||
|
||||
study = Study.from_hints(hints)
|
||||
|
||||
# Hints pre-populate:
|
||||
# - Objective functions
|
||||
# - Constraints
|
||||
# - Suggested parameters
|
||||
# - Critical regions for mesh refinement
|
||||
```
|
||||
|
||||
### 3. Review and Refine
|
||||
|
||||
The hints are suggestions, not final configurations:
|
||||
|
||||
- Verify objectives match your actual goals
|
||||
- Add specific constraint values
|
||||
- Map parameters to CAD model variables
|
||||
- Adjust mesh refinement regions
|
||||
|
||||
## Best Practices
|
||||
|
||||
### During Recording
|
||||
|
||||
1. **State objectives clearly**
|
||||
- "The goal is to minimize weight while maintaining stiffness"
|
||||
- "We need to keep the first natural frequency above 100 Hz"
|
||||
|
||||
2. **Quantify constraints**
|
||||
- "Maximum envelope is 200mm by 150mm by 100mm"
|
||||
- "Weight budget is 500 grams"
|
||||
- "Stress must stay below 150 MPa"
|
||||
|
||||
3. **Point out critical features**
|
||||
- "This fillet is critical for stress concentration"
|
||||
- "The bearing surface here sees high contact stress"
|
||||
|
||||
4. **Mention what could be optimized**
|
||||
- "The wall thickness could potentially be reduced"
|
||||
- "These rib dimensions are candidates for optimization"
|
||||
|
||||
### After Generation
|
||||
|
||||
1. Review `atomizer_hints.json` for accuracy
|
||||
2. Add missing numerical values
|
||||
3. Map parameters to your CAD model
|
||||
4. Use critical regions to guide mesh refinement
|
||||
5. Run initial FEA to validate hints
|
||||
|
||||
## Example Workflow
|
||||
|
||||
1. **Record walkthrough** explaining bracket design
|
||||
2. **Run CAD-Documenter** with `--atomizer-hints`
|
||||
3. **Review hints** in generated JSON
|
||||
4. **Import into Atomizer** for optimization study
|
||||
5. **Iterate** based on FEA results
|
||||
|
||||
## Limitations
|
||||
|
||||
- Hints are extracted from verbal/visual cues only
|
||||
- Numerical values may need refinement
|
||||
- Complex multi-objective problems need manual setup
|
||||
- Material properties should be verified against database
|
||||
220
docs/USAGE.md
Normal file
220
docs/USAGE.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# CAD-Documenter Usage Guide
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
cad-doc video.mp4
|
||||
```
|
||||
|
||||
Creates `video_docs/` with:
|
||||
- `documentation.md` - Main documentation
|
||||
- `frames/` - Extracted keyframes
|
||||
|
||||
### With All Features
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
cad-doc --init-config
|
||||
```
|
||||
|
||||
Creates `~/.cad-documenter.toml` with defaults.
|
||||
|
||||
### Config Options
|
||||
|
||||
```toml
|
||||
[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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user