Skip to content

static-image

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

static-image

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
test
test
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
config_schema.json
config_schema.json
 
 
manager.py
manager.py
 
 
manifest.json
manifest.json
 
 
requirements.txt
requirements.txt
 
 

README.md

Connect with ChuckBuilds

Static Image Display Plugin

Display static images on your LED matrix with automatic scaling, aspect ratio preservation, and transparency support.

Features

  • Multiple Format Support: PNG, JPG, BMP, GIF, and more
  • Automatic Scaling: Fit images to your display dimensions
  • Aspect Ratio Preservation: Keep images looking correct
  • Transparency Support: Handle PNG alpha channels
  • Configurable Background: Set custom background colors
  • High-Quality Scaling: LANCZOS resampling for best quality

Configuration

Single image

{
  "enabled": true,
  "images": [
    { "id": "logo", "path": "assets/static_images/my_logo.png" }
  ],
  "fit_to_display": true,
  "preserve_aspect_ratio": true,
  "background_color": [0, 0, 0],
  "display_duration": 10
}

Multiple images with rotation

{
  "enabled": true,
  "images": [
    { "id": "logo_a", "path": "assets/static_images/logo_a.png" },
    { "id": "logo_b", "path": "assets/static_images/logo_b.png" },
    { "id": "logo_c", "path": "assets/static_images/logo_c.png" }
  ],
  "image_config": {
    "mode": "multiple",
    "rotation_mode": "sequential"
  },
  "rotation_settings": {
    "sequential_loop": true
  },
  "image_rotation_interval": 15,
  "fit_to_display": true,
  "preserve_aspect_ratio": true,
  "background_color": [0, 0, 0],
  "display_duration": 30
}

Configuration Options

The full schema lives in config_schema.json — the web UI form is generated from it. Key options:

Key Default Notes
enabled false Master switch
images [] Array of image entries (each an object with a path and an optional per-image schedule), managed via the file-upload widget. See Per-Image Scheduling below.
image_config.mode "single" How images are presented: "single" or "multiple"
image_config.rotation_mode "sequential" Order when showing multiple images: "sequential", "random", "time_based" (advance on a wall-clock interval), or "date_based" (one image per day)
rotation_settings.sequential_loop true Loop back to the first image after the last
rotation_settings.random_seed null Optional fixed seed for reproducible random order
rotation_settings.time_intervals.enabled false Tie image changes to wall-clock intervals
rotation_settings.time_intervals.interval_seconds 3600 Wall-clock interval when enabled
image_rotation_interval 15 Seconds between images during rotation
fit_to_display true Scale image to display dimensions
preserve_aspect_ratio true Don't stretch when scaling
background_color [0, 0, 0] RGB fill behind transparent pixels
display_duration 10 Seconds the plugin holds the screen each rotation

Per-Image Scheduling

Each entry in images can carry an optional schedule so an image only shows at certain times (e.g. a "good morning" board, or business-hours signage):

Schedule key Default Notes
schedule.enabled false Turn scheduling on for this image
schedule.mode "always" "always" (any time), "time_range" (same window every day), or "per_day" (a different window per weekday)
schedule.start_time / schedule.end_time "08:00" / "18:00" Window bounds (HH:MM, 24-hour) for time_range mode
schedule.days.<weekday> — Per-weekday enabled + start_time/end_time, used when mode is "per_day"

When several images are eligible at the same time, they rotate per image_config.rotation_mode.

Usage

Basic Setup

  1. Place your image in a directory (e.g., assets/static_images/)
  2. Configure the plugin with the image path
  3. Enable the plugin
  4. The image will display automatically during rotation

Image Guidelines

Recommended:

  • Use PNG format for best quality and transparency support
  • Size images close to your display resolution for best performance
  • For 64x32 displays: 64x32 or 128x64 images work well
  • Use transparency to blend with background

Supported Formats:

  • PNG (recommended for transparency)
  • JPG/JPEG
  • BMP
  • GIF
  • TIFF

Tips for Best Results

  1. For Logos: Use PNG with transparent background
  2. For Photos: Use JPG for smaller file size
  3. For Pixel Art: Use PNG at native resolution
  4. For Icons: Scale to exact display size

Advanced Usage

Dynamic Image Updates

Change images programmatically via the Web UI or API:

# Via plugin manager
plugin.set_image_path("assets/static_images/new_image.png")
plugin.reload_image()

Multiple Images

Put all the images you want to cycle through into the images array (see the multi-image example above) and set image_config.mode to "multiple".

Troubleshooting

Image not displaying:

  • Check that image path is correct
  • Verify image file exists
  • Check file permissions
  • Review logs for error messages

Image looks distorted:

  • Enable preserve_aspect_ratio
  • Check image dimensions vs display size
  • Verify image isn't corrupted

Image appears cropped:

  • Enable fit_to_display
  • Check image size matches display

Transparency not working:

  • Use PNG format with alpha channel
  • Verify background_color is set correctly

Examples

Logo Display

{
  "enabled": true,
  "images": [
    { "id": "company_logo", "path": "assets/static_images/company_logo.png" }
  ],
  "fit_to_display": true,
  "preserve_aspect_ratio": true,
  "background_color": [0, 0, 0]
}

Pixel Art

{
  "enabled": true,
  "images": [
    { "id": "pixel_art", "path": "assets/static_images/pixel_art.png" }
  ],
  "fit_to_display": false,
  "preserve_aspect_ratio": true,
  "background_color": [0, 0, 50]
}

Full Screen Photo

{
  "enabled": true,
  "images": [
    { "id": "photo", "path": "assets/static_images/photo.jpg" }
  ],
  "fit_to_display": true,
  "preserve_aspect_ratio": false,
  "background_color": [0, 0, 0]
}

License

GPL-3.0 License - see main LEDMatrix repository for details.