/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

Upload anywhere: Place image files with IMG_ prefix anywhere in the project
CI detection: CI bot automatically detects files starting with IMG_
Auto-move: Files are automatically moved to docs/images/ directory
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