b4l-project-template/docs/images

/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