SmartSpectra OnPrem Python Examples
This directory contains Python example clients demonstrating various usage patterns for the SmartSpectra OnPrem SDK.
Quick Start
Install dependencies:
pip install -r requirements.txt
Install OnPrem wheels (from parent directory):
pip install ../physiology_edge_protobuf-*.whl
pip install ../smartspectra_protobuf-*.whl
pip install ../smartspectra_ipc-*.whl # For Redis examples
- Start physiology_server (see main README.md for full instructions)
Run an example:
python hello_world_on_prem_client.py
Examples Overview
hello_world_on_prem_client.py
Purpose: Minimal "Hello World" example
What it does:
- Connects to physiology_server via gRPC
- Captures video from webcam
- Uploads frames to server
- Prints received metrics to console
Best for: First-time users, understanding the basics
Usage:
python hello_world_on_prem_client.py
Controls:
- Press s to start/stop recording
- Press q to quit
full_example_on_prem_client.py
Purpose: Comprehensive gRPC API demonstration
What it does:
- All features from hello_world
- Manual frame upload with timestamp control
- Streaming metrics (core and edge)
- Status monitoring
- Recording control
- Processing reset
- Log streaming
- Camera exposure adjustment
Best for: Understanding the complete API, building production clients
Usage:
python full_example_on_prem_client.py
Controls:
- s - Start/stop recording
- q - Quit
- r - Reset processing (clears Core buffer)
- e - Toggle auto-exposure
- - / = - Decrease/increase exposure
- h - Show help
Command line options:
python full_example_on_prem_client.py --help
# Options: --video-device, --rotate-ccw, --assume-server-has-video, etc.
alt_ipc_example_on_prem_client.py
Purpose: Alternative IPC backends (Redis recommended, File also available)
What it does:
- Reads metrics from Redis or File IPC instead of gRPC streams
- Server captures video directly (no frame upload needed)
- Uses gRPC only for control commands
- Displays frames from IPC backend
Best for: Systems that can't use gRPC streams, distributed deployments (Redis recommended for production)
Server setup - Redis IPC (Recommended):
# Start Redis first
redis-server
# Start physiology_server
physiology_server \
--streaming_backend=redis \
--use_camera \
--redis_host=localhost \
--redis_port=6379 \
--redis_key_prefix=physiology \
--also_log_to_stderr
Usage - Redis mode (Recommended):
python alt_ipc_example_on_prem_client.py --backend=redis --redis_host=localhost
Alternative - File mode (if Redis is not available):
# Server setup
physiology_server \
--streaming_backend=file \
--use_camera \
--filesystem_ipc_config_path=./file_ipc_config.json \
--also_log_to_stderr
# Client usage
python alt_ipc_example_on_prem_client.py --backend=file --base_dir=./ipc
Controls:
- s - Start/stop recording
- q - Quit
redis_ipc_metrics_saving_client.py
Purpose: Production-grade Redis metrics collection and storage
What it does:
- Uses SmartSpectra-IPC MetricsCollector for high-level Redis interaction
- Aggregates metrics from core and edge channels
- Writes continuous JSONL file (streaming)
- Writes periodic snapshots every 30 seconds
- Writes final JSON summary (struct-of-arrays format)
- Automatic session management with session-specific file naming
- Handles timestamp resets and wraps
Best for: Production data collection, analysis pipelines, research datasets
Server setup:
# Start Redis
redis-server
# Start physiology_server with Redis backend
physiology_server \
--streaming_backend=redis \
--use_camera \
--redis_host=localhost \
--redis_port=6379 \
--redis_key_prefix=physiology \
--buffer_duration=0.2 \
--enable_phasic_bp \
--enable_eda \
--also_log_to_stderr
Usage:
# Local (physiology_server on localhost)
python redis_ipc_metrics_saving_client.py \
--port 50051 \
--combined_metrics_file ./metrics.jsonl \
--summary_file ./metrics_summary.json
# Remote/Docker (physiology_server on different host)
python redis_ipc_metrics_saving_client.py \
--host physiology-server \
--port 50051 \
--redis_host redis \
--combined_metrics_file ./metrics.jsonl \
--summary_file ./metrics_summary.json
Environment variables:
- PHYSIOLOGY_SERVER_HOST - Physiology server hostname (default: localhost)
- Can be used instead of --host argument
Output files:
- metrics_{session_id}.jsonl - Continuous stream (one JSON per line)
- metrics_{session_id}_snapshot_temp.json - Periodic snapshots (every 30s)
- metrics_{session_id}.json - Final aggregated summary (struct-of-arrays)
Controls:
- s - Start recording
- t - Stop recording
- r - Reset processing
- q - Quit and finalize
Notes:
- Session IDs are auto-generated (datetime-based) when recording starts
- Files are created with session-specific names for easy organization
- Summary JSON format is optimized for Pandas/NumPy analysis
plot_metrics.py
Purpose: Visualize collected metrics
What it does:
- Loads JSON summary from redis_ipc_metrics_saving_client.py
- Plots physiological traces (EDA, breathing, blood pressure, etc.)
- Shows z-score overlay for comparing signals
- Displays timestamp differences for quality assessment
Best for: Post-collection analysis, data quality checks, presentations
Usage:
python plot_metrics.py --summary_file ./metrics_summary.json
Output:
- Interactive plot window
- Saves metrics_plot.png (150 DPI)
Dependencies:
pip install matplotlib numpy scipy
Configuration Files
file_ipc_config.json.example
Example configuration for File IPC backend. Copy and modify:
cp file_ipc_config.json.example file_ipc_config.json
# Edit paths as needed
redis_ipc_config.json.example
Example configuration for Redis IPC backend. Copy and modify:
cp redis_ipc_config.json.example redis_ipc_config.json
# Edit connection settings as needed
Common Workflows
Workflow 1: Quick Test
# Terminal 1: Start server
physiology_server --also_log_to_stderr --port 50051 --venv_directory .venv
# Terminal 2: Run hello world
python hello_world_on_prem_client.py
Workflow 2: Data Collection for Analysis
# Terminal 1: Start Redis
redis-server
# Terminal 2: Start server with Redis backend
physiology_server \
--streaming_backend=redis \
--use_camera \
--redis_host=localhost \
--redis_port=6379 \
--enable_phasic_bp \
--enable_eda \
--also_log_to_stderr
# Terminal 3: Collect metrics
python redis_ipc_metrics_saving_client.py \
--combined_metrics_file ./experiment_data.jsonl \
--summary_file ./experiment_summary.json
# After collection: Visualize
python plot_metrics.py --summary_file ./experiment_summary.json
Workflow 2b: Replay A Recorded Capture (Same Backend)
# Terminal 1: Start Redis if needed
redis-server
# Terminal 2: Start your Redis clients so they are subscribed before playback
python redis_ipc_metrics_saving_client.py --summary_file ./replay_summary.json
# Terminal 3: Reuse the Redis backend but feed a recorded MKV
physiology_server \
--streaming_backend=redis \
--redis_host=localhost \
--redis_port=6379 \
--input_video_path=./captures/first_run/video_20250205_142155.mkv \
--input_video_time_path=./captures/first_run/video_20250205_142155_timestamps.txt \
--also_log_to_stderr
# After collection: Visualize
python plot_metrics.py --summary_file ./replay_summary.json
The server replays frames from the MKV locally, so every Redis subscriber (dashboard, metric saver, etc.) sees the session exactly as if it were live. Starting collectors first ensures they receive the very first samples.
Workflow 3: Distributed System
# Machine 1: Server with Redis backend
physiology_server \
--streaming_backend=redis \
--use_camera \
--redis_host=<redis_ip> \
--redis_key_prefix=remote_session
# Machine 2: Multiple clients reading from Redis
python alt_ipc_example_on_prem_client.py --backend=redis --redis_host=<redis_ip>
Troubleshooting
ImportError: No module named 'smartspectra'
Cause: OnPrem protobuf wheels not installed
Fix:
pip install ../smartspectra_protobuf-*.whl
pip install ../physiology_edge_protobuf-*.whl
grpc.RpcError: Connection refused
Cause: physiology_server not running
Fix:
# Start server first
physiology_server --also_log_to_stderr --port 50051 --venv_directory .venv
redis.exceptions.ConnectionError
Cause: Redis server not running
Fix:
# Start Redis
redis-server
Camera not found
Cause: Camera in use by another application or wrong device index
Fix:
# Try different device index
python hello_world_on_prem_client.py # Uses device 0 by default
# Or specify device
python full_example_on_prem_client.py --video-device 1
No metrics output
Cause: Recording not started
Fix:
- Press s to start recording after launching the client
- Metrics only flow when recording is active
Further Documentation
- Main OnPrem Guide - Installation and server setup
- Examples Guide - Detailed example documentation
- Redis IPC Backend - Redis configuration
- File IPC Backend - File configuration
- SmartSpectra-IPC Package - MetricsCollector API
See Also
