Webcam

Stream video from webcams attached to the Lager Box for visual inspection, automated vision testing, and remote monitoring.

Import

from lager import Net, NetType

Methods

Method	Description
`start(box_ip)`	Start a webcam stream
`stop()`	Stop the webcam stream
`get_info(box_ip)`	Get info about the stream
`get_url(box_ip)`	Get just the URL for the stream
`is_active()`	Check if stream is currently active
`snapshot(raw=False)`	One JPEG frame from the running stream
`frame(raw=True)`	One frame from the running stream, as a numpy array
`controls()`	The camera’s image controls, with their values and ranges
`set_control(name, value)`	Set one camera control, and keep it for this net
`lock_controls(**overrides)`	Turn every auto mode off and keep every control as it is
`video_device`	Property: the camera’s `/dev/video` node now, found from the net’s address
`get_config()`	Return a copy of the net’s raw configuration dict

Method Reference

`Net.get(name, type=NetType.Webcam)`

Get a webcam net by name.

from lager import Net, NetType

webcam = Net.get('camera1', type=NetType.Webcam)

Parameters:

Parameter	Type	Description
`name`	`str`	Name of the webcam net
`type`	`NetType`	Must be `NetType.Webcam`

Returns: Webcam Net instance

`start(box_ip)`

Start a webcam video stream.

from lager import Net, NetType

webcam = Net.get('camera1', type=NetType.Webcam)
result = webcam.start(box_ip='<BOX_IP>')

print(f"Stream URL: {result['url']}")
print(f"Port: {result['port']}")

Parameters:

Parameter	Type	Description
`box_ip`	`str`	Lager Box IP address for URL generation

Returns: dict with keys:

url - Full stream URL (e.g., http://<BOX_IP>:8086/)
port - Port number for the stream
already_running - Boolean indicating if stream was already active

Raises: RuntimeError if device is already in use or not found

`stop()`

Stop the webcam stream.

from lager import Net, NetType

webcam = Net.get('camera1', type=NetType.Webcam)
stopped = webcam.stop()

if stopped:
    print("Stream stopped")
else:
    print("Stream was not running")

Returns: bool - True if stopped successfully, False if not running

`get_info(box_ip)`

Get information about the stream.

from lager import Net, NetType

webcam = Net.get('camera1', type=NetType.Webcam)
info = webcam.get_info(box_ip='<BOX_IP>')

if info:
    print(f"URL: {info['url']}")
    print(f"Port: {info['port']}")
    print(f"Device: {info['video_device']}")
else:
    print("Stream not active")

Parameters:

Parameter	Type	Description
`box_ip`	`str`	Lager Box IP address

Returns: dict or None - Stream info dict or None if not running. The dict has these keys:

url - Full stream URL
port - Port number for the stream
video_device - Video device path, such as /dev/video0
source - The tool that started the stream: 'api' for this Python API, 'cli' for lager webcam. None for a stream with no recorded origin.
started_by - The user that the starting tool named. None for a stream started from this Python API.

`get_url(box_ip)`

Get just the URL for the stream.

from lager import Net, NetType

webcam = Net.get('camera1', type=NetType.Webcam)
url = webcam.get_url(box_ip='<BOX_IP>')

if url:
    print(f"Stream at: {url}")

Parameters:

Parameter	Type	Description
`box_ip`	`str`	Lager Box IP address

Returns: str or None - Stream URL or None if not running

`is_active()`

Check if the stream is currently active.

from lager import Net, NetType

webcam = Net.get('camera1', type=NetType.Webcam)
if webcam.is_active():
    print("Stream is running")
else:
    print("Stream is stopped")

Returns: bool - True if the stream is active, False otherwise

`snapshot(raw=False)`

One JPEG frame from the running stream.

from lager import Net, NetType

webcam = Net.get('camera1', type=NetType.Webcam)
webcam.start(box_ip='<BOX_IP>')
with open('bench.jpg', 'wb') as f:
    f.write(webcam.snapshot())

The frame comes from the stream’s own capture, so it never competes with the stream, or a browser watching it, for the camera. Parameters:

Parameter	Type	Description
`raw`	`bool`	`True` for the frame as the camera delivered it. `False` (the default) for the picture the viewer page shows, after its rotation, flips and zoom

Returns: bytes - the JPEG Raises: RuntimeError if the stream is stopped, or has no frame within 5 seconds

`frame(raw=True)`

One frame from the running stream, decoded for analysis.

from lager import Net, NetType

webcam = Net.get('camera1', type=NetType.Webcam)
webcam.start(box_ip='<BOX_IP>')
image = webcam.frame()          # height x width x 3, BGR
print(image.shape, image.mean())

Parameters:

Parameter	Type	Description
`raw`	`bool`	`True` (the default) for the frame as the camera delivered it, before the viewer’s rotation, flips and zoom

Returns: numpy.ndarray - height x width x 3, in BGR order as OpenCV uses Raises: RuntimeError as snapshot() does

Use frame() in a lager python script rather than opening the camera with cv2.VideoCapture. While a stream runs it holds the camera, and a second capture of the same device gets no frames.

`controls()`

The camera’s image controls, each with its current value and range. Works with the stream started or stopped.

from lager import Net, NetType

webcam = Net.get('camera1', type=NetType.Webcam)
for name, control in webcam.controls().items():
    print(name, control['value'], control['min'], control['max'])

Returns: dict of control name to {"value", "min", "max", "step", "default"}, with a key only for a control the camera has. See Camera controls for the names. Three values have an auto mode: exposure, white_balance_temperature and focus. Each also has auto: True, False, or None when the camera has no auto mode for it. power_line_frequency also has options, a list of {"value", "label"}.

`set_control(name, value)`

Set one camera control, and keep it for this net. Works with the stream started or stopped.

from lager import Net, NetType

webcam = Net.get('camera1', type=NetType.Webcam)
webcam.set_control('focus_auto', False)
webcam.set_control('focus', 383)

Parameters:

Parameter	Type	Description
`name`	`str`	One of the names in Camera controls
`value`	`bool` or `int`	A `bool` for `exposure_auto`, `white_balance_auto` and `focus_auto`. Otherwise a number, clamped to the camera’s range. `power_line_frequency` takes one of its `options`

Returns: bool - True if the camera took the value Raises: ValueError for a name that is not a camera control. VideoDeviceNotFound, a RuntimeError, when the camera is not connected. controls() raises it too.

`lock_controls(**overrides)`

Fix every image control, for pictures that compare from frame to frame and from run to run. Turns auto exposure, auto white balance and autofocus off. Keeps every other control at its current value unless you override it. Saves them all for this net, then reads the camera back.

from lager import Net, NetType

webcam = Net.get('led_cam', type=NetType.Webcam)
report = webcam.lock_controls(exposure=312, white_balance_temperature=4600,
                              power_line_frequency=2)
if not report['ok']:
    for name, r in report['controls'].items():
        if r['wanted'] != r['actual']:
            print(f"{name}: wanted {r['wanted']}, camera has {r['actual']}")

Parameters:

Parameter	Type	Description
`**overrides`		Control name to value, as `set_control` takes them

Returns: dict with:

ok - True if every control reads back as wanted
controls - {name: {"wanted", "actual"}} for every control the camera has. A value outside the camera’s range is clamped, so it reads back different and ok is False

Raises: RuntimeError if the camera’s controls cannot be read; ValueError for an unknown name

Camera controls

Name	What it is
`exposure_auto`	Auto exposure on or off (`bool`)
`exposure`	Exposure time, in the camera’s units. On Linux UVC cameras that is 100 microseconds: 312 is 31.2 ms
`gain`	Sensor gain
`white_balance_auto`	Auto white balance on or off (`bool`)
`white_balance_temperature`	Color temperature, in kelvin
`focus_auto`	Continuous autofocus on or off (`bool`)
`focus`	Focus distance, in the camera’s units
`brightness`, `contrast`, `saturation`, `hue`, `gamma`, `sharpness`, `backlight_compensation`	Picture adjustments
`power_line_frequency`	Anti-flicker: 0 disabled, 1 for 50 Hz, 2 for 60 Hz

Every range is the camera’s own. Brightness, for example, is 0 to 255 on some cameras and -64 to 64 on others. A value outside the range is clamped, and the net keeps the clamped value. A manual exposure can hold the frame rate below the mode’s. The camera still accepts the mode, so mode_error stays empty: read /api/fps for the real rate. One global-shutter camera, for example, runs about 60 fps at exposure=312 in a 90 fps mode, and about 89 fps at exposure=100. Lager changes only the controls you set. A stream start leaves the rest as the camera has them, so settings made with another tool survive it. The controls you set through set_control, lock_controls or the viewer page are kept for the net. They are put back each time its stream starts, and after the stream reopens the camera for a new mode. That also covers a camera that forgets its settings when it loses power: start the stream, or call lock_controls again.

Windows tools such as DirectShow give exposure as a power of two in seconds: -5 is 2^-5 s, 31.25 ms. The Linux value is 10000 * 2**n, so -5 is exposure=312.

Examples

Start Multiple Cameras

from lager import Net, NetType

# Lager Box IP
BOX_IP = '<BOX_IP>'

# Start multiple camera streams
cameras = ['overview', 'microscope', 'solder_station']

for name in cameras:
    try:
        webcam = Net.get(name, type=NetType.Webcam)
        result = webcam.start(BOX_IP)
        print(f"{name}: {result['url']}")
    except RuntimeError as e:
        print(f"{name}: Failed - {e}")

Stream Management

from lager import Net, NetType

BOX_IP = '<BOX_IP>'

def start_camera(name):
    """Start a camera stream."""
    try:
        webcam = Net.get(name, type=NetType.Webcam)
        result = webcam.start(BOX_IP)
        if result['already_running']:
            print(f"Stream '{name}' was already running at {result['url']}")
        else:
            print(f"Started '{name}' at {result['url']}")
    except RuntimeError as e:
        print(f"Failed to start '{name}': {e}")

def stop_camera(name):
    """Stop a camera stream."""
    webcam = Net.get(name, type=NetType.Webcam)
    if webcam.stop():
        print(f"Stopped '{name}'")
    else:
        print(f"Stream '{name}' was not running")

def check_camera(name):
    """Check camera status."""
    webcam = Net.get(name, type=NetType.Webcam)
    if webcam.is_active():
        info = webcam.get_info(BOX_IP)
        print(f"{name}: Running at {info['url']}")
    else:
        print(f"{name}: Stopped")

# Usage
start_camera('main')
check_camera('main')
stop_camera('main')

Visual Inspection Test

from lager import Net, NetType
import time

BOX_IP = '<BOX_IP>'

def visual_inspection_test(camera_name, inspection_callback):
    """
    Start camera stream and wait for operator inspection.

    Args:
        camera_name: Webcam net name
        inspection_callback: Function to handle the stream URL

    Returns:
        bool: True if inspection passed
    """
    # Start stream
    webcam = Net.get(camera_name, type=NetType.Webcam)
    result = webcam.start(BOX_IP)
    stream_url = result['url']

    print(f"Visual inspection stream: {stream_url}")

    # Notify external system (could open browser, send to UI, etc.)
    inspection_callback(stream_url)

    # Wait for inspection (in real usage, this would wait for operator input)
    print("Waiting for visual inspection...")
    time.sleep(10)  # Placeholder

    # Stop stream
    webcam.stop()

    # Return result (would come from operator in real usage)
    return True

# Usage
def handle_url(url):
    print(f"Open in browser: {url}")

result = visual_inspection_test('inspection_cam', handle_url)
print(f"Inspection result: {'PASS' if result else 'FAIL'}")

Camera Discovery and Testing

from lager import Net, NetType
import os

BOX_IP = '<BOX_IP>'

def discover_cameras():
    """Find all available video devices."""
    cameras = []
    for i in range(10):  # Check video0 through video9
        device = f'/dev/video{i}'
        if os.path.exists(device):
            cameras.append(device)
    return cameras

def test_camera(net_name):
    """Test if a camera net works."""
    try:
        webcam = Net.get(net_name, type=NetType.Webcam)
        result = webcam.start(BOX_IP)
        print(f"{net_name}: OK - {result['url']}")
        webcam.stop()
        return True
    except RuntimeError as e:
        print(f"{net_name}: FAIL - {e}")
        return False

# Discover and test all cameras
print("Discovering cameras...")
devices = discover_cameras()
print(f"Found {len(devices)} video devices")

# Test configured nets (assumes you have webcam nets configured)
test_camera('camera1')
test_camera('camera2')

Already Running Detection

from lager import Net, NetType

BOX_IP = '<BOX_IP>'

webcam = Net.get('camera1', type=NetType.Webcam)

# Start stream first time
result1 = webcam.start(BOX_IP)
print(f"First start: already_running = {result1['already_running']}")

# Try to start again - should detect it's already running
result2 = webcam.start(BOX_IP)
print(f"Second start: already_running = {result2['already_running']}")

# Check if active
print(f"Is active: {webcam.is_active()}")

# Cleanup
webcam.stop()

Web Interface

Each stream serves a viewer page at its URL. It uses the same layout and colors as the oscilloscope page (lager scope NET stream web):

A header. Its Net picker moves to another stream on the box. It shows the camera’s model and device, and the frame rate, size and zoom. Its status is LIVE, STALLED (no frame for 3 seconds), WAITING (no frame yet) or OFFLINE (the stream does not answer)
The live picture, with a clock and the zoom level over it. When zoomed in, drag the picture or use the arrow keys to pan. Double-click a point to zoom in on it, or once zoomed, to centre on it
A sidebar with:
- Resolution: the size and frame rate, from the modes the camera offers. If the camera cannot stream the size you pick, it keeps the old one, and the page says why. Too little USB bandwidth is one cause
- View: zoom (slider, Out, Reset, In), Centre for the pan, Rotate (0, 90, 180 or 270 degrees) and Flip (left-right, top-bottom)
- Focus: Auto or Manual with a distance slider, in the camera’s own range. The switch shows only on a camera with autofocus
- Image: exposure (Auto exposure or Manual with a slider), gain and brightness. Also white balance (Auto white balance or Manual with a color temperature), and sliders for the other image controls. Each shows only on a camera that has it, with the camera’s range. While auto exposure is on, the camera sets the gain itself
Hide sidebar hides it, and the page remembers the choice
Full screen shows the picture alone
Snapshot, which saves one frame as <net>-<timestamp>.jpg
At the foot of the sidebar, who started the stream, its device and its port

Every setting is kept for the net on the box. Everyone who views the stream sees the same picture, and the settings come back when the stream restarts. Larger sizes cost the box more CPU to encode: the frame rate in the header shows what the box keeps up with. On an access-gated box, when the browser’s session ends the page says SIGNED OUT and tells you to run lager webcam url for a new link.

API Endpoints

Endpoint	Method	Description
`/`	GET	The viewer page
`/static/webcam.css`, `/static/webcam.js`	GET	The viewer page’s style and script
`/stream`	GET	Raw MJPEG video stream
`/api/info`	GET	The stream’s net, device, camera model, port, origin, fps, zoom, frame size, and seconds since the last frame (`frame_age`, `null` before the first)
`/snapshot`	GET	One JPEG frame, as the viewer shows it. `?raw=1` for the frame as the camera delivered it, before rotation, flips and zoom. Returns 503 if no frame arrives within 5 seconds
`/api/zoom`	GET	Get current zoom level
`/api/zoom/in`	POST	Increase zoom
`/api/zoom/out`	POST	Decrease zoom
`/api/zoom/reset`	POST	Reset zoom to 1.0x
`/api/zoom/set`	POST	Set zoom: `{"zoom": 2.0}` (1.0 to 4.0)
`/api/focus`	GET	Focus `mode` (`"auto"`, `"manual"`, or `null` for a camera without autofocus), `value`, `min`, `max` and `step`. `value` is `null` for a camera without focus
`/api/focus/auto`	POST	Turn on autofocus
`/api/focus/manual`	POST	Manual focus: `{"value": 383}`, in the camera’s range. Without a value, the current distance is kept
`/api/brightness`	GET	Brightness `value`, `min`, `max` and `step`
`/api/brightness/set`	POST	Set brightness: `{"value": 0}`, clamped to the camera’s range
`/api/pan/set`	POST	Pan a zoomed picture: `{"x": 0.3, "y": 0.7}`, the centre of the view as fractions of the picture
`/api/orientation/set`	POST	Any of `{"rotate": 90, "flip_h": true, "flip_v": false}`. Rotation is clockwise: 0, 90, 180 or 270
`/api/modes`	GET	The sizes and frame rates the camera offers (MJPEG), the current mode, and why the last change failed, if it did
`/api/mode/set`	POST	Change the mode: `{"width": 1920, "height": 1080, "fps": 30}`. Answers 400 for a mode the camera does not list
`/api/controls`	GET	The camera controls the camera has, as `controls()` returns them
`/api/controls/set`	POST	`{"control": "exposure_auto", "value": false}`, or any other camera control name with its value
`/api/fps`	GET	Get current FPS
`/api/streams`	GET	List all active streams
`/test`	GET	Health check endpoint

Hardware Requirements

Requirement	Description
USB Webcams	UVC-compatible cameras
Video Devices	`/dev/video*` device files
OpenCV	Required for video capture

lager nets add-all offers a net for any USB video class (UVC) camera. A model Lager has no name for is listed as UVC_Camera. HDMI capture cards are not offered as cameras. A net finds its camera again each time it starts, so it keeps working when /dev/video* numbers change.

Some cameras have no serial number, or share one with another camera on the box. Lager addresses these by USB port, as usb-port:1-1.4. Their nets follow the port: if you plug the camera into a different port, the net reports an error. The ELP global-shutter camera reports the same serial, 01.00.00, on every unit, so two on one box use port addresses.

Notes

A webcam net is configured by the camera’s address, its serial number or a usb-port: path. The net finds the camera’s video device from that address each time it is used
Streams run on ports starting from 8086
Each stream uses a separate port, automatically allocated
Streams persist until explicitly stopped or the process dies
Dead stream processes are automatically cleaned up
Only one stream can use a video device at a time
Default resolution is 640x480 at 30 FPS. Some cameras offer more: the ELP global-shutter camera offers 90 FPS at every size. The box re-encodes every frame, and at large sizes it can fall behind. The frame rate on the viewer page shows what it delivers
JPEG quality is set to 80 for bandwidth/quality balance
Streams are reachable over HTTP at the Lager Box IP address. On an access-gated box, a request needs a sign-in token, and the url from start() carries none. Use lager webcam url for a link that carries your token
Zoom is digital (crop and scale), not optical

Getting Started

Development

Power & Simulation

Measurement

I/O & Communication

Utilities

Import

Methods

Method Reference

`Net.get(name, type=NetType.Webcam)`

`start(box_ip)`

`stop()`

`get_info(box_ip)`

`get_url(box_ip)`

`is_active()`

`snapshot(raw=False)`

`frame(raw=True)`

`controls()`

`set_control(name, value)`

`lock_controls(**overrides)`

Camera controls

Examples

Start Multiple Cameras

Stream Management

Visual Inspection Test

Camera Discovery and Testing

Already Running Detection

Web Interface

API Endpoints

Hardware Requirements

Notes

​Import

​Methods

​Method Reference

​Net.get(name, type=NetType.Webcam)

​start(box_ip)

​stop()

​get_info(box_ip)

​get_url(box_ip)

​is_active()

​snapshot(raw=False)

​frame(raw=True)

​controls()

​set_control(name, value)

​lock_controls(**overrides)

​Camera controls

​Examples

​Start Multiple Cameras

​Stream Management

​Visual Inspection Test

​Camera Discovery and Testing

​Already Running Detection

​Web Interface

​API Endpoints

​Hardware Requirements

​Notes

Import

Methods

Method Reference

`Net.get(name, type=NetType.Webcam)`

`start(box_ip)`

`stop()`

`get_info(box_ip)`

`get_url(box_ip)`

`is_active()`

`snapshot(raw=False)`

`frame(raw=True)`

`controls()`

`set_control(name, value)`

`lock_controls(**overrides)`

Camera controls

Examples

Start Multiple Cameras

Stream Management

Visual Inspection Test

Camera Discovery and Testing

Already Running Detection

Web Interface

API Endpoints

Hardware Requirements

Notes