b4l-project-template/docs/images/README.md

# /docs/images

Documentation images, diagrams, photos, and figures.

## Purpose
This directory contains all visual documentation for the project including diagrams, photos, screenshots, and illustrations used in documentation, assembly guides, and technical references.

## File Organization
Images should be organized by type and purpose for easy reference:

```
images/
├── schematics/
│   ├── IMG_schematic-block-diagram_v1.0.0_2024-08-11.svg
│   ├── IMG_power-supply-schematic_v1.2.0_2024-08-11.png
│   └── IMG_signal-flow-diagram_v2.0.0_2024-08-11.pdf
├── pcb-layouts/
│   ├── IMG_pcb-layout_top-view_v1.0.0_2024-08-11.png
│   ├── IMG_pcb-layout_bottom-view_v1.0.0_2024-08-11.png
│   └── IMG_pcb-3d-render_assembled_v1.0.0_2024-08-11.jpg
├── assembly/
│   ├── IMG_assembly-photo_step-1_2024-08-11.jpg
│   ├── IMG_assembly-photo_step-2_2024-08-11.jpg
│   └── IMG_assembly-diagram_exploded-view_2024-08-11.png
├── mechanical/
│   ├── IMG_enclosure-design_front-view_v2.0.0_2024-08-11.png
│   ├── IMG_mounting-bracket_dimensions_v1.1.0_2024-08-11.pdf
│   └── IMG_mechanical-assembly_3d-view_v1.0.0_2024-08-11.jpg
├── testing/
│   ├── IMG_test-setup_functional_2024-08-11.jpg
│   ├── IMG_oscilloscope-capture_signal-analysis_2024-08-11.png
│   └── IMG_measurement-results_performance_2024-08-11.png
└── user-interface/
    ├── IMG_gui-screenshot_main-window_v1.0.0_2024-08-11.png
    ├── IMG_display-layout_status-screen_v1.0.0_2024-08-11.jpg
    └── IMG_control-panel_button-layout_2024-08-11.png
```

## CI Auto-Sort System
To enable automatic organization by CI bots, use the **IMG_** prefix for all image files:

### Naming Convention
```
IMG_[subject]_[description]_[version]_[date].extension
```

### Examples
```
IMG_pcb-layout_top-view_v1.0.0_2024-08-11.png
IMG_assembly-photo_step-3_2024-08-11.jpg
IMG_schematic-block-diagram_v2.1.0_2024-08-11.svg
IMG_test-results_frequency-response_2024-08-11.png
IMG_enclosure-design_front-panel_v1.2.0_2024-08-11.pdf
```

### How It Works
1. **Upload anywhere**: Place image files with IMG_ prefix anywhere in the project
2. **CI detection**: CI bot automatically detects files starting with IMG_
3. **Auto-move**: Files are automatically moved to `docs/images/` directory
4. **Organization**: Files can be further organized into subdirectories manually or by additional CI rules

## Supported File Types
- **PNG**: Preferred for diagrams, screenshots, and technical illustrations
- **JPG/JPEG**: Best for photographs and complex images
- **SVG**: Vector graphics for scalable diagrams and schematics
- **PDF**: Vector documents and technical drawings
- **GIF**: Animated demonstrations (use sparingly)
- **WEBP**: Modern format for web optimization (when supported)

## Image Categories

### Schematic Diagrams
- Block diagrams showing system architecture
- Circuit schematics and sub-circuits
- Signal flow and timing diagrams
- Electrical connection diagrams

### PCB and Layout Images
- PCB layout views (top, bottom, internal layers)
- 3D renderings of assembled boards
- Component placement diagrams
- Routing and trace illustrations

### Assembly Documentation
- Step-by-step assembly photos
- Component identification images
- Tool and equipment photos
- Before/after assembly comparisons

### Mechanical Designs
- CAD renderings and technical drawings
- Enclosure and housing designs
- Mounting and installation diagrams
- Dimensional drawings and specifications

### Testing and Validation
- Test setup photographs
- Oscilloscope captures and measurements
- Performance graphs and charts
- Compliance testing results

### User Interface
- GUI screenshots and mockups
- Display layouts and screen designs
- Control panel and button layouts
- User interaction flows

## Best Practices
- **Always use IMG_ prefix** for automatic CI sorting
- **Use descriptive names** that clearly identify the image content
- **Include version numbers** for design-related images
- **Optimize file sizes** without compromising quality
- **Use appropriate formats** (PNG for diagrams, JPG for photos)
- **Include date** when image was created or captured
- **Maintain consistent naming** across related images
- **Document image sources** and creation methods

## Image Quality Guidelines
- **Resolution**: Use appropriate resolution for intended use
  - Screenshots: Native resolution or 1920x1080 max
  - Photos: 1920x1080 to 4K depending on detail needed
  - Diagrams: Vector format (SVG) when possible
- **Compression**: Balance file size with quality
- **Color space**: Use sRGB for web compatibility
- **File size**: Keep under 5MB per image when possible

## Creation Tools
- **Screenshots**: Built-in OS tools, Greenshot, LightShot
- **Diagrams**: Draw.io, Lucidchart, Visio, Inkscape
- **Photo editing**: GIMP, Photoshop, Paint.NET
- **CAD renders**: KiCad 3D viewer, FreeCAD, SolidWorks
- **Vector graphics**: Inkscape, Illustrator, SVG editors

## Integration with Documentation
Images should be referenced in documentation:
- Use relative paths in markdown: `![Description](../images/IMG_filename.png)`
- Include alt text for accessibility
- Reference images by filename in assembly guides
- Maintain links when reorganizing files
- Update documentation when images are updated

## Version Control
- **Commit images** with related design changes
- **Use Git LFS** for large image files (>10MB)
- **Tag versions** when images represent specific design iterations
- **Document changes** when updating existing images
- **Maintain history** of design evolution through images

## File Size Management
- **Optimize images** before committing to reduce repository size
- **Use appropriate compression** for different image types
- **Consider external hosting** for very large images
- **Regular cleanup** of outdated or unused images
- **Monitor repository size** and use Git LFS when necessary