tami/gst-plugin-linescan
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add intervalometer filter for automatic exposure control

Browse Source 
Implements YASS-inspired automatic exposure control for IDS uEye cameras.
The intervalometer filter analyzes video brightness in real-time and
smoothly ramps camera exposure and gain settings during changing light
conditions - ideal for sunset/sunrise time-lapse photography.

Key features:
- Automatic exposure ramping (0.85-1.24ms configurable range)
- Automatic gain control (0-52 configurable range)
- Real-time brightness analysis (GRAY8, GRAY16, RGB, BGR, BGRA)
- YASS-inspired ramping algorithm (exposure priority, then gain)
- Configurable ramp rates (VSlow/Slow/Medium/Fast/VFast)
- Exposure compensation (±4 stops)
- CSV logging of exposure parameters
- Direct GObject property control (no message bus overhead)

Technical implementation:
- GstBaseTransform filter for in-place processing
- Discovers upstream camera element by name
- Controls camera via g_object_set() for synchronous updates
- Frame-by-frame brightness calculation with format support

Files added:
- gst/intervalometer/gstintervalometer.c: Main implementation (734 lines)
- gst/intervalometer/gstintervalometer.h: Header with structure definitions
- gst/intervalometer/CMakeLists.txt: Build configuration
- gst/intervalometer/README.md: Comprehensive documentation

Files modified:
- gst/CMakeLists.txt: Added intervalometer subdirectory
- build.ps1: Added intervalometer to build and deployment pipeline

Usage example:
  gst-launch-1.0 idsueyesrc name=cam ! \\
    intervalometer enabled=true camera-element=cam \\
      exposure-min=0.85 exposure-max=1.24 \\
      gain-min=0 gain-max=52 ramp-rate=medium ! \\
    autovideosink

Inspired by YASS (Yet Another Sunset Script) for CHDK cameras by
waterwingz, based on work by Fbonomi and soulf2.
This commit is contained in:
yair
2025-11-17 01:05:16 +02:00
parent 5fb24cb294
commit b11cd27d14
6 changed files with 1088 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

253
gst/intervalometer/README.md Normal file
View File

@@ -0,0 +1,253 @@
# GStreamer Intervalometer Filter
**Automatic Exposure Control for IDS uEye Cameras**
Inspired by [YASS (Yet Another Sunset Script)](../../yass/README.md) for CHDK cameras.
## Overview
The `intervalometer` element is a GStreamer filter that automatically adjusts camera exposure and gain settings during changing light conditions. It analyzes video brightness in real-time and smoothly ramps camera parameters to maintain optimal exposure - perfect for time-lapse photography during sunset, sunrise, or other variable lighting scenarios.
## Features
- **Automatic Exposure Ramping**: Smoothly adjusts exposure time based on scene brightness
- **Automatic Gain Control**: Increases/decreases sensor gain when exposure limits are reached
- **Configurable Ranges**: Set custom min/max values for exposure (0.85-1.24ms) and gain (0-52)
- **Multiple Ramp Rates**: Choose from VSlow/Slow/Medium/Fast/VFast adjustment speeds
- **Exposure Compensation**: Fine-tune brightness with ±4 stops of compensation
- **CSV Logging**: Optional detailed logging of all exposure parameters
- **Multiple Format Support**: Works with GRAY8, GRAY16, RGB, BGR, and BGRA video
## Requirements
- GStreamer 1.0+
- IDS uEye camera with `idsueyesrc` element
- Camera must support runtime exposure and gain property changes
## Installation
The filter is built as part of the gst-plugins-vision project. Build and install normally:
```bash
mkdir build
cd build
cmake ..
make
make install
```
## Properties
### Control Properties
| Property | Type | Range | Default | Description |
|----------|------|-------|---------|-------------|
| `enabled` | boolean | - | TRUE | Enable/disable auto-exposure |
| `target-brightness` | double | 0-255 | 128.0 | Target average brightness level |
| `compensation` | double | -4.0 to 4.0 | 0.0 | Exposure compensation in stops |
| `camera-element` | string | - | "" | Name of upstream idsueyesrc element |
### Exposure Range
| Property | Type | Range | Default | Description |
|----------|------|-------|---------|-------------|
| `exposure-min` | double | 0.01-1000.0 | 0.85 | Minimum exposure time (ms) |
| `exposure-max` | double | 0.01-1000.0 | 1.24 | Maximum exposure time (ms) |
### Gain Range
| Property | Type | Range | Default | Description |
|----------|------|-------|---------|-------------|
| `gain-min` | int | 0-100 | 0 | Minimum gain value |
| `gain-max` | int | 0-100 | 52 | Maximum gain value |
### Ramping
| Property | Type | Values | Default | Description |
|----------|------|--------|---------|-------------|
| `ramp-rate` | enum | VSlow, Slow, Medium, Fast, VFast | Medium | Speed of parameter changes |
### Logging
| Property | Type | Range | Default | Description |
|----------|------|-------|---------|-------------|
| `log-file` | string | - | "" | Path to CSV log file (empty = disabled) |
## Usage Examples
### Basic Auto-Exposure
```bash
gst-launch-1.0 idsueyesrc name=cam ! \
intervalometer enabled=true camera-element=cam ! \
videoconvert ! autovideosink
```
### Custom Range for Day/Night Transition
Configure for the typical day (0.85ms exposure, gain 52) to night (1.24ms exposure, gain 0) range:
```bash
gst-launch-1.0 idsueyesrc name=cam ! \
intervalometer enabled=true camera-element=cam \
exposure-min=0.85 exposure-max=1.24 \
gain-min=0 gain-max=52 \
ramp-rate=medium ! \
videoconvert ! autovideosink
```
### With Exposure Compensation
Adjust overall brightness with compensation:
```bash
gst-launch-1.0 idsueyesrc name=cam ! \
intervalometer enabled=true camera-element=cam \
compensation=1.0 \
target-brightness=140 ! \
videoconvert ! autovideosink
```
### With CSV Logging
Log all exposure data to a CSV file:
```bash
gst-launch-1.0 idsueyesrc name=cam ! \
intervalometer enabled=true camera-element=cam \
log-file=exposure_log.csv ! \
videoconvert ! autovideosink
```
### Complete Time-Lapse Pipeline
Record a time-lapse with auto-exposure:
```bash
gst-launch-1.0 idsueyesrc name=cam framerate=1 ! \
intervalometer enabled=true camera-element=cam \
exposure-min=0.85 exposure-max=1.24 \
gain-min=0 gain-max=52 \
ramp-rate=slow \
log-file=timelapse_exposure.csv ! \
videoconvert ! x264enc ! mp4mux ! \
filesink location=timelapse.mp4
```
## How It Works
### Exposure Control Algorithm
The filter uses a YASS-inspired algorithm:
1. **Brightness Analysis**: Calculates average brightness of each frame
2. **Error Calculation**: Compares to target brightness (with compensation)
3. **Ramping Priority**:
- When too bright: Decreases exposure first, then gain
- When too dark: Increases exposure first (up to max), then gain
4. **Smooth Ramping**: Changes are gradual based on ramp-rate setting
### Typical Behavior
- **Daytime**: Fast shutter (low exposure), high gain for noise reduction
- **Sunset/Dusk**: Gradually increases exposure time as light fades
- **Night**: Maximum exposure time, minimum gain
### CSV Log Format
When logging is enabled, the filter creates a CSV file with:
```csv
Frame,Time_s,Brightness,Exposure_ms,Gain,Target_Brightness
0,0.000,145.32,0.850,52,128.00
1,0.033,143.21,0.851,52,128.00
2,0.067,142.15,0.853,52,128.00
...
```
## Camera Property Control
The filter finds and controls the upstream `idsueyesrc` element using the `camera-element` property. It sets:
- **exposure**: Exposure time in milliseconds
- **gain**: Master gain (0-100 range)
Ensure your camera source is named and the name matches the `camera-element` property.
## Ramp Rates
| Rate | Multiplier | Best For |
|------|------------|----------|
| VSlow | 0.5x | Very slow light changes, maximum smoothness |
| Slow | 1.0x | Gradual sunset/sunrise over hours |
| Medium | 2.0x | Normal time-lapse scenarios |
| Fast | 4.0x | Faster light changes, clouds passing |
| VFast | 8.0x | Quick adaptation, testing |
## Tips for Best Results
### Time-Lapse Settings
```
exposure-min: 0.85 (or camera-specific minimum)
exposure-max: 1.24 (or 1/framerate to avoid motion blur)
gain-min: 0 (cleanest image)
gain-max: 52 (or camera's limit)
ramp-rate: slow or medium
target-brightness: 128-140
```
### Fast Changing Conditions
```
ramp-rate: fast or vfast
compensation: Adjust to preference (-1.0 for darker, +1.0 for brighter)
```
### Maximum Image Quality
```
gain-max: 20-30 (lower max gain = less noise)
ramp-rate: slow (smoother transitions)
```
## Troubleshooting
**Filter not adjusting exposure:**
- Verify `camera-element` property matches your camera source name
- Check that camera allows runtime exposure/gain changes
- Ensure `enabled=true` is set
**Changes too fast/slow:**
- Adjust `ramp-rate` property
- Check `exposure-min`/`exposure-max` range is appropriate
**Brightness not reaching target:**
- Increase `gain-max` to allow more gain
- Increase `exposure-max` if not motion-limited
- Adjust `target-brightness` or use `compensation`
**Log file not created:**
- Check file path is writable
- Verify `log-file` property is set before starting pipeline
## Comparison to YASS
| Feature | YASS (CHDK) | Intervalometer (GStreamer) |
|---------|-------------|---------------------------|
| Platform | Canon cameras with CHDK | IDS uEye cameras |
| Control | Shutter speed + ISO | Exposure time + Gain |
| Integration | Standalone Lua script | GStreamer pipeline element |
| Real-time | Script-based intervals | Frame-by-frame analysis |
| Logging | CSV to SD card | CSV to filesystem |
## License
This filter is part of gst-plugins-vision and released under the GNU Library General Public License (LGPL).
Inspired by YASS (Yet Another Sunset Script) by waterwingz, based on work by Fbonomi and soulf2, released under GPL.
## See Also
- [YASS Documentation](../../yass/README.md) - Original CHDK script that inspired this filter
- [idsueyesrc](../../sys/idsueye/gstidsueyesrc.c) - IDS uEye camera source element