摄像头

从连接到 Lager Box 的摄像头串流视频，用于目视检查、自动化视觉测试和远程监视。

导入

from lager import Net, NetType

方法

方法	说明
`start(box_ip)`	启动一路摄像头串流
`stop()`	停止该摄像头串流
`get_info(box_ip)`	获取该串流的信息
`get_url(box_ip)`	只获取该串流的 URL
`is_active()`	检查串流当前是否正在运行
`snapshot(raw=False)`	从运行中的串流取一帧 JPEG
`frame(raw=True)`	从运行中的串流取一帧，返回 numpy 数组
`controls()`	摄像头的图像控制项，含当前值和范围
`set_control(name, value)`	设置一个摄像头控制项，并为该 Net 保存
`lock_controls(**overrides)`	关闭所有自动模式，并保持每个控制项的当前值

方法参考

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

按名称获取一个摄像头 Net。

from lager import Net, NetType

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

参数：

参数	类型	说明
`name`	`str`	摄像头 Net 的名称
`type`	`NetType`	必须为 `NetType.Webcam`

返回： 摄像头 Net 实例

`start(box_ip)`

启动一路摄像头视频串流。

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']}")

参数：

参数	类型	说明
`box_ip`	`str`	用于生成 URL 的 Lager Box IP 地址

返回： 一个 dict，包含以下键：

url - 完整的串流 URL（例如 http://<BOX_IP>:8086/）
port - 该串流的端口号
already_running - 布尔值，表示该串流是否本就在运行

抛出： 设备已被占用或未找到时抛出 RuntimeError

`stop()`

停止该摄像头串流。

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")

返回： bool - 成功停止为 True，原本未运行为 False

`get_info(box_ip)`

获取该串流的信息。

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")

参数：

参数	类型	说明
`box_ip`	`str`	Lager Box 的 IP 地址

返回： dict 或 None - 串流信息字典；未运行时为 None。该字典包含以下键：

url - 完整的串流 URL
port - 该串流的端口号
video_device - 视频设备路径，例如 /dev/video0
source - 启动该串流的工具：本 Python API 为 'api'，lager webcam 为 'cli'。没有记录来源的串流为 None。
started_by - 启动工具所给出的用户。从本 Python API 启动的串流为 None。

`get_url(box_ip)`

只获取该串流的 URL。

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}")

参数：

参数	类型	说明
`box_ip`	`str`	Lager Box 的 IP 地址

返回： str 或 None - 串流 URL；未运行时为 None

`is_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")

返回： bool - 串流正在运行为 True，否则为 False

`snapshot(raw=False)`

从运行中的串流取一帧 JPEG。

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())

这一帧取自串流自己的采集，因此不会与串流或正在查看它的浏览器争用摄像头。 参数：

参数	类型	说明
`raw`	`bool`	`True` 返回摄像头送出的原始帧。`False`（默认）返回查看页面显示的画面，即经过旋转、翻转和变焦之后的画面

返回： bytes - 该 JPEG 异常： 串流已停止，或 5 秒内没有帧时抛出 RuntimeError

`frame(raw=True)`

从运行中的串流取一帧，并解码以供分析。

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())

参数：

参数	类型	说明
`raw`	`bool`	`True`（默认）返回摄像头送出的原始帧，即查看页面旋转、翻转和变焦之前的帧

返回： numpy.ndarray - 高 x 宽 x 3，按 OpenCV 使用的 BGR 顺序 异常： 与 snapshot() 相同的 RuntimeError

在 lager python 脚本中请使用 frame()，不要用 cv2.VideoCapture 打开摄像头。串流运行时会占用摄像头，对同一设备的第二个采集得不到任何帧。

`controls()`

摄像头的图像控制项，每项含当前值和范围。串流启动或停止时都可使用。

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'])

返回： 控制项名称到 {"value", "min", "max", "step", "default"} 的 dict，只包含摄像头具备的控制项。名称见摄像头控制。有三个值带自动模式：exposure、white_balance_temperature 和 focus。它们还各有 auto：True、False，摄像头没有对应自动模式时为 None。power_line_frequency 还有 options，为 {"value", "label"} 列表。

`set_control(name, value)`

设置一个摄像头控制项，并为该 Net 保存。串流启动或停止时都可使用。

from lager import Net, NetType

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

参数：

参数	类型	说明
`name`	`str`	摄像头控制中的名称之一
`value`	`bool` 或 `int`	`exposure_auto`、`white_balance_auto` 和 `focus_auto` 取 `bool`。其余取数值，并限制在摄像头的范围内。`power_line_frequency` 取其 `options` 之一

返回： bool - 摄像头接受该值时为 True 异常： 名称不是摄像头控制项时抛出 ValueError

`lock_controls(**overrides)`

固定所有图像控制项，使画面在帧与帧之间、运行与运行之间可比较。关闭自动曝光、自动白平衡和自动对焦。除非您覆盖，其余控制项都保持当前值。全部为该 Net 保存，然后从摄像头读回。

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']}")

参数：

参数	类型	说明
`**overrides`		控制项名称到值，与 `set_control` 的取值相同

返回： dict，包含：

ok - 每个控制项读回的值都符合要求时为 True
controls - 摄像头每个控制项的 {name: {"wanted", "actual"}}。超出摄像头范围的值会被限制，因此读回不同，ok 为 False

异常： 无法读取摄像头控制项时抛出 RuntimeError；名称未知时抛出 ValueError

摄像头控制

名称	含义
`exposure_auto`	自动曝光开或关（`bool`）
`exposure`	曝光时间，单位由摄像头决定。Linux UVC 摄像头的单位是 100 微秒：312 即 31.2 ms
`gain`	传感器增益
`white_balance_auto`	自动白平衡开或关（`bool`）
`white_balance_temperature`	色温，单位为开尔文
`focus_auto`	连续自动对焦开或关（`bool`）
`focus`	对焦距离，单位由摄像头决定
`brightness`, `contrast`, `saturation`, `hue`, `gamma`, `sharpness`, `backlight_compensation`	画面调节
`power_line_frequency`	防闪烁：0 为关闭，1 为 50 Hz，2 为 60 Hz

每个范围都是摄像头自己的。例如亮度在某些摄像头上是 0 到 255，在另一些上是 -64 到 64。超出范围的值会被限制，Net 保存的是限制后的值。手动曝光可能让帧率低于模式的帧率。摄像头仍接受该模式，因此 mode_error 为空：实际帧率请读取 /api/fps。例如，一台全局快门摄像头在 90 fps 模式下，exposure=312 时约为 60 fps，exposure=100 时约为 89 fps。 Lager 只更改您设置的控制项。启动串流时，其余控制项保持摄像头当前的值，因此用其他工具做的设置不受影响。通过 set_control、lock_controls 或查看页面设置的控制项会为该 Net 保存。每次启动其串流时，以及串流为新模式重新打开摄像头之后，都会重新应用它们。这也适用于断电后会忘记设置的摄像头：启动串流，或再次调用 lock_controls。

DirectShow 等 Windows 工具把曝光表示为以秒为单位的 2 的幂：-5 即 2^-5 s，31.25 ms。Linux 的值为 10000 * 2**n，因此 -5 对应 exposure=312。

示例

启动多台摄像头

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}")

串流管理

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')

目视检查测试

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'}")

摄像头发现与测试

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')

检测串流是否已在运行

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 界面

每一路串流在它的 URL 上提供一个查看页面。它的布局和配色与示波器页面（lager scope NET stream web）相同：

页头。其中的 Net 选择器可切换到 Box 上的另一路串流。页头显示摄像头的型号和设备，以及帧率、尺寸和变焦倍数。状态为 LIVE、STALLED（3 秒内没有帧）、WAITING（还没有帧）或 OFFLINE（串流没有响应）
实时画面，上面叠加时钟和变焦倍数。放大后，拖动画面或使用方向键即可平移。双击某一点可放大到该点；已放大时，双击则以该点为中心
侧边栏，包含：
- Resolution：尺寸和帧率，取自摄像头提供的模式。如果摄像头无法以所选尺寸串流，它会保持原来的模式，页面会说明原因。USB 带宽不足是原因之一
- View：变焦（滑块、Out、Reset、In）、用于平移的 Centre、Rotate（0、90、180 或 270 度）和 Flip（左右、上下）
- Focus：Auto 或 Manual，带距离滑块，使用摄像头自己的范围。只有带自动对焦的摄像头才显示该开关
- Image：曝光（Auto exposure 或带滑块的 Manual）、增益和亮度。还有白平衡（Auto white balance 或带色温的 Manual），以及其他图像控制项的滑块。每项只在摄像头具备时显示，并使用摄像头的范围。开启自动曝光时，增益由摄像头自行设置
Hide sidebar 可隐藏侧边栏，页面会记住这个选择
Full screen 只显示画面
Snapshot 把一帧保存为 <net>-<timestamp>.jpg
侧边栏底部显示串流的启动者、设备和端口

每项设置都为该 Net 保存在 Box 上。所有查看该串流的人看到的是同一画面，串流重启后设置也会恢复。尺寸越大，Box 编码所需的 CPU 越多：页头中的帧率显示 Box 能跟上的速度。在启用访问网关的 Box 上，浏览器会话结束后，页面显示 SIGNED OUT，并提示运行 lager webcam url 获取新链接。

API 端点

端点	方法	说明
`/`	GET	查看页面
`/static/webcam.css`, `/static/webcam.js`	GET	查看页面的样式和脚本
`/stream`	GET	原始 MJPEG 视频流
`/api/info`	GET	串流的 Net、设备、摄像头型号、端口、来源、FPS、变焦倍数、帧尺寸，以及距上一帧的秒数（`frame_age`，第一帧之前为 `null`）
`/snapshot`	GET	一帧 JPEG，即查看页面显示的画面。`?raw=1` 返回摄像头送出的原始帧，即旋转、翻转和变焦之前的帧。5 秒内没有帧到达时返回 503
`/api/zoom`	GET	获取当前变焦倍数
`/api/zoom/in`	POST	放大
`/api/zoom/out`	POST	缩小
`/api/zoom/reset`	POST	把变焦重置为 1.0x
`/api/zoom/set`	POST	设置变焦：`{"zoom": 2.0}`（1.0 到 4.0）
`/api/focus`	GET	对焦 `mode`（`"auto"`、`"manual"`，摄像头没有自动对焦时为 `null`）、`value`、`min`、`max` 和 `step`。摄像头没有对焦时 `value` 为 `null`
`/api/focus/auto`	POST	开启自动对焦
`/api/focus/manual`	POST	手动对焦：`{"value": 383}`，使用摄像头的范围。不带值时保持当前距离
`/api/brightness`	GET	亮度 `value`、`min`、`max` 和 `step`
`/api/brightness/set`	POST	设置亮度：`{"value": 0}`，限制在摄像头的范围内
`/api/pan/set`	POST	平移放大的画面：`{"x": 0.3, "y": 0.7}`，即视野中心占画面的比例
`/api/orientation/set`	POST	`{"rotate": 90, "flip_h": true, "flip_v": false}` 中的任意字段。旋转为顺时针：0、90、180 或 270
`/api/modes`	GET	摄像头提供的尺寸和帧率（MJPEG）、当前模式，以及上次切换失败的原因（如有）
`/api/mode/set`	POST	切换模式：`{"width": 1920, "height": 1080, "fps": 30}`。摄像头未列出的模式返回 400
`/api/controls`	GET	摄像头具备的摄像头控制项，与 `controls()` 的返回相同
`/api/controls/set`	POST	`{"control": "exposure_auto", "value": false}`，或任一其他摄像头控制项名称加其值
`/api/fps`	GET	获取当前 FPS
`/api/streams`	GET	列出全部活动串流
`/test`	GET	健康检查端点

硬件要求

要求	说明
USB 摄像头	兼容 UVC 的摄像头
视频设备	`/dev/video*` 设备文件
OpenCV	视频采集所需

lager nets add-all 会为以下摄像头提供 Net：

Logitech BRIO、BRIO HD、BRIO 4K Stream、4K Pro、C930e、C925e、C922 Pro、C920、C615、C270 和 StreamCam
ELP 全局快门摄像头（AR0234 传感器，USB ID 32e4:0234）

ELP 全局快门摄像头每一台都报告相同的序列号 01.00.00。Lager 会把同一 Box 上的两台列为一台摄像头，带两个视频设备。请手动添加第二台摄像头的 Net，并指定它自己的 /dev/video* 设备。

说明

摄像头 Net 必须在 Lager Box 上配置，并指定视频设备路径
串流使用从 8086 开始的端口
每一路串流使用一个独立端口，由系统自动分配
串流会一直保持，直到被显式停止或其进程结束
已死亡的串流进程会被自动清理
同一时刻只能有一路串流使用某个视频设备
默认分辨率为 640x480，30 FPS。有些摄像头支持更高：ELP 全局快门摄像头在每种尺寸下都支持 90 FPS。Box 会重新编码每一帧，尺寸较大时可能跟不上。查看页面上的帧率显示实际送出的速度
JPEG 质量设为 80，以平衡带宽和画质
串流通过 HTTP 在 Lager Box 的 IP 地址上提供。在访问受控的 Box 上，请求需要携带登录令牌，而 start() 返回的 url 不带令牌。请用 lager webcam url 获取带有您令牌的链接
变焦是数字变焦（裁剪并缩放），不是光学变焦

入门

开发

电源与仿真

测量

I/O 与通信

实用工具

导入

方法

方法参考

`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)`

摄像头控制

示例

启动多台摄像头

串流管理

目视检查测试

摄像头发现与测试

检测串流是否已在运行

Web 界面

API 端点

硬件要求

说明

​导入

​方法

​方法参考

​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)

​摄像头控制

​示例

​启动多台摄像头

​串流管理

​目视检查测试

​摄像头发现与测试

​检测串流是否已在运行

​Web 界面

​API 端点

​硬件要求

​说明

导入

方法

方法参考

`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)`

摄像头控制

示例

启动多台摄像头

串流管理

目视检查测试

摄像头发现与测试

检测串流是否已在运行

Web 界面

API 端点

硬件要求

说明