Documentation
¶
Overview ¶
Package orbbec 是奥比中光 Gemini 435Le 网口深度相机的纯 Go 驱动,不依赖 OrbbecSDK 原生库,不用 cgo。
协议移植自 OrbbecSDK v2(MIT,Copyright (c) Orbbec Inc.):
- GVCP(UDP 3956):设备发现;CCP 寄存器 0x0A00 控制权的申请、保活和释放。
- 控制协议(TCP 8090):属性、结构体、V1.1 结构体列表。
- RTSP(TCP 8554 深度、8888 彩色),RTP 交织在同一连接上。
- 标定:深度/彩色内参、深度到彩色外参、基线、有效分辨率。
用法:
cam := orbbec.New(orbbec.Config{IP: "192.168.1.10"})
if err := cam.Open(); err != nil {
log.Fatal(err)
}
defer cam.Close()
frames, err := cam.RecentDepths(5, 2*time.Second, time.Second)
Index ¶
- Constants
- Variables
- type Calibration
- type Camera
- func (c *Camera) BaselineMM() float64
- func (c *Camera) Close() error
- func (c *Camera) ColorParams() *ColorParams
- func (c *Camera) DeviceInfo() DeviceInfo
- func (c *Camera) GrabColor(timeout time.Duration) (*ColorFrame, error)
- func (c *Camera) GrabDepth(timeout time.Duration) (*DepthFrame, error)
- func (c *Camera) HasColor() bool
- func (c *Camera) Intrinsics() Intrinsics
- func (c *Camera) IsAlive(maxAge time.Duration) bool
- func (c *Camera) LastError() string
- func (c *Camera) LatestColor(newerThan uint64, timeout time.Duration) (*ColorFrame, uint64)
- func (c *Camera) Open() error
- func (c *Camera) OpenContext(ctx context.Context) error
- func (c *Camera) RecentDepths(n int, timeout, maxAge time.Duration) ([]*DepthFrame, error)
- func (c *Camera) Stats() Stats
- type ColorFrame
- type ColorParams
- type Config
- type DepthCalibParam
- type DepthFrame
- type DepthPrecision
- type Device
- func (d *Device) Calibration() *Calibration
- func (d *Device) Close() error
- func (d *Device) ControlLost() bool
- func (d *Device) DepthUnitMM() float32
- func (d *Device) GetProperty(id uint32) (int32, error)
- func (d *Device) GetPropertyRange(id uint32) (PropertyRange, error)
- func (d *Device) Info() DeviceInfo
- func (d *Device) Profiles() []EffectiveProfile
- func (d *Device) SetProperty(id uint32, v int32) error
- func (d *Device) StartColor(ctx context.Context, cfg StreamConfig, onFrame func(*ColorFrame)) (*Stream, error)
- func (d *Device) StartDepth(ctx context.Context, cfg StreamConfig, onFrame func(*DepthFrame)) (*Stream, error)
- func (d *Device) Version() VersionInfo
- type DeviceError
- type DeviceInfo
- type DeviceOptions
- type DiscoveredDevice
- type EffectiveProfile
- type Extrinsic
- type FrameMetadata
- type Intrinsics
- type PropertyRange
- type Stats
- type Stream
- type StreamConfig
- type VersionInfo
Constants ¶
const ( GevStatusSuccess uint16 = 0x0000 GevStatusAccessDenied uint16 = 0x8006 GevStatusError uint16 = 0x8FFF )
GVCP 状态码。
const ( SensorIR = 1 SensorColor = 2 SensorDepth = 3 SensorIRLeft = 6 SensorIRRight = 7 SensorConfidence = 9 FormatYUYV = 0 FormatMJPG = 5 FormatY16 = 8 FormatY8 = 9 FormatI420 = 15 FormatRVL = 27 FormatY12C4 = 34 )
传感器类型和像素格式(OBSensorType / OBFormat)。
const ( PropLaserBool uint32 = 3 PropStopDepthStreamBool uint32 = 38 PropDepthAlignHardwareBool uint32 = 42 // 硬件 D2C,开着时深度被对齐到彩色视角 PropDepthPrecisionLevelInt uint32 = 75 PropStopColorStreamBool uint32 = 77 PropDisparityToDepthBool uint32 = 85 PropDeviceCommunicationTypeInt uint32 = 97 // 1 = 网口 PropDevicePIDInt uint32 = 111 PropCompatVersionInt uint32 = 237 // 1 = 彩色 JPEG 内嵌元数据 PropColorAutoExposureBool uint32 = 2000 PropIRAutoExposureBool uint32 = 2025 StructVersion uint32 = 1000 RawDataD2CAlignSupportProfileList uint32 = 4024 RawDataDepthCalibParam uint32 = 4026 RawDataAlignCalibParam uint32 = 4027 RawDataEffectiveStreamProfileList uint32 = 4035 )
属性 ID(OrbbecSDK 的 Property.h / InternalProperty.hpp)。
Variables ¶
var ( // ErrTimeout 表示在给定时间内没有等到帧。 ErrTimeout = errors.New("timed out waiting for a frame") // ErrAlreadyOpen 表示 Camera 已经打开。 ErrAlreadyOpen = errors.New("camera is already open") )
var ErrAccessDenied = errors.New("camera is controlled by another application (GVCP access denied)")
ErrAccessDenied 表示控制权在别的程序手里。持有者异常退出时,相机在心跳超时后自动释放。
var ErrClosed = errors.New("device is closed")
ErrClosed 表示设备或相机已经关闭。
Functions ¶
This section is empty.
Types ¶
type Calibration ¶
type Calibration struct {
Depth []DepthCalibParam
// contains filtered or unexported fields
}
Calibration 是从相机读出的标定数据。
func (*Calibration) BaselineMM ¶
func (c *Calibration) BaselineMM() float64
BaselineMM 返回双目基线(mm),未知时为 0。
func (*Calibration) ColorIntrinsics ¶
func (c *Calibration) ColorIntrinsics(w, h int) (Intrinsics, error)
ColorIntrinsics 返回 w×h 彩色流的内参。
func (*Calibration) DepthIntrinsics ¶
func (c *Calibration) DepthIntrinsics(w, h int) (Intrinsics, error)
DepthIntrinsics 返回 w×h 深度流的内参。
func (*Calibration) DepthToColor ¶
func (c *Calibration) DepthToColor() (Extrinsic, bool)
DepthToColor 返回深度到彩色的外参。
type Camera ¶
type Camera struct {
// contains filtered or unexported fields
}
Camera 持续接收深度和彩色并缓存最近几帧。深度流停了 IsAlive 返回 false,Close 再 Open 即可重连。 返回的帧是共享的,只读;要修改先 Clone。必须用 New 创建;Open/Close 可以和取帧方法并发调用。
func (*Camera) ColorParams ¶
func (c *Camera) ColorParams() *ColorParams
ColorParams 返回彩色内参和深度到彩色外参(副本),没有彩色流时为 nil。
func (*Camera) GrabColor ¶
func (c *Camera) GrabColor(timeout time.Duration) (*ColorFrame, error)
GrabColor 返回最新的彩色帧,没有时最多等 timeout,仍没有则返回 ErrTimeout。
func (*Camera) GrabDepth ¶
func (c *Camera) GrabDepth(timeout time.Duration) (*DepthFrame, error)
GrabDepth 返回下一帧新的深度图;超时返回 ErrTimeout,关闭返回 ErrClosed。
func (*Camera) LatestColor ¶
LatestColor 等到序号大于 newerThan 的彩色帧后返回,超时则返回当前最新帧;没有彩色帧时返回 nil。
func (*Camera) OpenContext ¶
OpenContext 同 Open,可取消;Close 也会中断正在进行的打开。
func (*Camera) RecentDepths ¶
RecentDepths 返回缓存里最近 n 帧(按时间先后)。最新一帧早于 maxAge(0 用 AliveTimeout)时等新帧, 避免离线后用旧帧。
type ColorFrame ¶
type ColorFrame struct {
Width, Height int
JPEG []byte
Seq uint64
Time time.Time
Metadata []byte // JPEG COM 段里的帧元数据
}
ColorFrame 是一帧彩色图,保留相机发来的 JPEG 字节。
func (*ColorFrame) Clone ¶
func (f *ColorFrame) Clone() *ColorFrame
Clone 深拷贝一帧(JPEG 和 Metadata 都复制)。
type ColorParams ¶
type ColorParams struct {
Intrinsics Intrinsics `json:"intr"`
DepthToRGB Extrinsic `json:"extrinsic"`
}
ColorParams 是彩色相机内参和深度到彩色的外参。
type Config ¶
type Config struct {
IP string
Logger *slog.Logger
// 端口,0 用默认值。
GVCPPort, ControlPort, DepthRTSPPort, ColorRTSPPort int
Depth StreamConfig // 默认 1280x800@10
// Color 为 nil 时用 1280x800@10;NoColor 为 true 时不开彩色流(优先于 Color)。
Color *StreamConfig
NoColor bool
DepthPrecision *DepthPrecision // 见 DeviceOptions.DepthPrecision
RingSize int // 缓存的深度帧数,默认 8
AliveTimeout time.Duration // 多久没有新深度帧算离线,默认 3 s
OpenRetries int // 默认 5
RetryWait time.Duration // 默认 3 s
FrameIdleTimeout time.Duration // 见 DeviceOptions.FrameIdleTimeout
}
Config 是 Camera 的参数,零值字段用默认值。
type DepthCalibParam ¶
type DepthCalibParam struct {
DepthMode uint32
Baseline float32
Z0 float32
FocalPix float32
Unit float32
DispOffset float32
InvalidDisp int32
}
DepthCalibParam 是深度标定参数(OBDepthCalibrationParam,28 字节)。
type DepthFrame ¶
type DepthFrame struct {
Width, Height int
Data []uint16
Seq uint64 // 本地序号,从 1 开始
DeviceSeq uint64 // 相机帧号
DeviceTimestampUs uint64
Time time.Time // 主机收到的时间
Metadata []byte // 原始帧元数据,用 ParseFrameMetadata 解析
}
DepthFrame 是一帧深度图,Data 按行存储,单位 mm,0 表示无效。
func (*DepthFrame) Clone ¶
func (f *DepthFrame) Clone() *DepthFrame
Clone 深拷贝一帧(Data 和 Metadata 都复制)。
type DepthPrecision ¶
type DepthPrecision int32
DepthPrecision 是深度精度档位,决定一个深度值代表多少 mm。
const ( Precision1mm DepthPrecision = 0 Precision0mm8 DepthPrecision = 1 Precision0mm4 DepthPrecision = 2 Precision0mm1 DepthPrecision = 3 Precision0mm2 DepthPrecision = 4 Precision0mm5 DepthPrecision = 5 Precision0mm05 DepthPrecision = 6 // PrecisionKeep 表示不改相机当前档位。 PrecisionKeep DepthPrecision = -1 )
type Device ¶
type Device struct {
// contains filtered or unexported fields
}
Device 是一台已连接的相机。方法可以并发调用;Close 后其它方法返回 ErrClosed。
func OpenDevice ¶
func OpenDevice(ctx context.Context, opts DeviceOptions) (*Device, error)
OpenDevice 连接相机并初始化,顺序和官方 SDK 一致:申请控制权 → 设通信方式和兼容版本 → 读版本、标定和有效分辨率 → 开相机端视差转深度、设深度精度。ctx 只管打开过程。
func (*Device) Calibration ¶
func (d *Device) Calibration() *Calibration
Calibration 返回从相机读出的标定(只读)。
func (*Device) GetProperty ¶
GetProperty 读一个整型/布尔属性的当前值。
func (*Device) GetPropertyRange ¶
func (d *Device) GetPropertyRange(id uint32) (PropertyRange, error)
GetPropertyRange 读一个属性的当前值和范围。
func (*Device) Info ¶
func (d *Device) Info() DeviceInfo
func (*Device) SetProperty ¶
SetProperty 写一个整型/布尔属性。改深度精度会更新 DepthUnitMM,但已在收的深度流仍按旧单位换算, 要先关流再改。
func (*Device) StartColor ¶
func (d *Device) StartColor(ctx context.Context, cfg StreamConfig, onFrame func(*ColorFrame)) (*Stream, error)
StartColor 开彩色流(MJPEG),onFrame 收到完整 JPEG。约束同 StartDepth。
func (*Device) StartDepth ¶
func (d *Device) StartDepth(ctx context.Context, cfg StreamConfig, onFrame func(*DepthFrame)) (*Stream, error)
StartDepth 开深度流(Y16),onFrame 在读循环里调用:不能阻塞,也不能调用 Close。ctx 只管起流过程。
func (*Device) Version ¶
func (d *Device) Version() VersionInfo
type DeviceError ¶
DeviceError 是相机对命令返回的错误码。
func (*DeviceError) Error ¶
func (e *DeviceError) Error() string
type DeviceInfo ¶
type DeviceInfo struct {
Name string `json:"name"`
Serial string `json:"serial"`
Firmware string `json:"firmware"`
Hardware string `json:"hardware,omitempty"`
Connection string `json:"connection"`
PID uint16 `json:"pid,omitempty"`
IP string `json:"ip,omitempty"`
MAC string `json:"mac,omitempty"`
}
DeviceInfo 是设备信息。
type DeviceOptions ¶
type DeviceOptions struct {
IP string
Logger *slog.Logger
// ReadOnly 不申请控制权、不写属性,可以和别的程序同时连着,但不能取流。
ReadOnly bool
// DepthPrecision 为 nil 时设成相机默认档(和官方 SDK 一致),PrecisionKeep 保持当前档位。
DepthPrecision *DepthPrecision
// 端口,0 用默认值。
GVCPPort, ControlPort, DepthRTSPPort, ColorRTSPPort int
// FrameIdleTimeout 内收不到流数据就认为流断了,默认 10 s。
// 另一个客户端断开同一路流时相机会停发约 5 s,所以别设得太短。
FrameIdleTimeout time.Duration
}
DeviceOptions 是打开设备的参数。
type DiscoveredDevice ¶
type DiscoveredDevice struct {
IP string
Mask string
Gateway string
MAC string
Manufacturer string
Model string
PID uint16
Firmware string
Serial string
UserName string
LocalIP string // 收到应答的本机地址
}
DiscoveredDevice 是 GVCP 发现应答里的设备信息。
type EffectiveProfile ¶
EffectiveProfile 是相机报告的一个可用流配置。
func (EffectiveProfile) String ¶
func (p EffectiveProfile) String() string
type FrameMetadata ¶
type FrameMetadata struct {
FrameCounter uint32
SensorTimestampUs int64 // 曝光起始时间
Exposure uint32
DigitalGain uint16
AnalogGain uint16
AutoExposure bool
// 仅深度帧
Width, Height uint16
GainLevel uint16
LaserPower uint16
LaserPowerLevel uint8
LaserStatus uint8
ActualFPS uint8
}
FrameMetadata 是每帧 108 字节元数据里的常用字段。
func ParseFrameMetadata ¶
func ParseFrameMetadata(b []byte, depth bool) (FrameMetadata, error)
ParseFrameMetadata 解析帧元数据,depth 为 true 时按深度帧布局解析。
type Intrinsics ¶
type Intrinsics struct {
Width int `json:"width"`
Height int `json:"height"`
Fx float64 `json:"fx"`
Fy float64 `json:"fy"`
Cx float64 `json:"cx"`
Cy float64 `json:"cy"`
}
Intrinsics 是针孔相机内参。
type PropertyRange ¶
type PropertyRange struct {
Cur, Max, Min, Def, Step int32
}
PropertyRange 是属性的当前值和范围,布尔和浮点属性也按 int32 传输。
type Stats ¶ added in v0.1.1
type Stats struct {
DepthFrames, DepthDropped int64
ColorFrames, ColorDropped int64
DepthDeviceSeq uint64
}
HasColor 表示 AliveTimeout 内收到过彩色帧。 Stats 是流的累计统计:收到的帧数、因 RTP 丢包而丢弃的帧数,以及最近一帧深度的相机帧号 (相机帧号的增量减去收到的帧数 = 相机发了但没收全的帧)。
type Stream ¶
type Stream struct {
// contains filtered or unexported fields
}
Stream 是一路正在接收的流。
func (*Stream) Close ¶
func (s *Stream) Close()
Close 结束会话并等读循环退出,可重复调用。不能在 onFrame 回调里调用(回调在读循环上执行,会死锁)。
type VersionInfo ¶
type VersionInfo struct {
Firmware, Hardware, MinSDK, DepthChip, SystemChip, Serial string
DeviceType int32
DeviceName, SubSystem string
}
VersionInfo 是设备版本信息(OBVersionInfo)。