gogige

package module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 8, 2026 License: BSD-3-Clause Imports: 14 Imported by: 0

README

gogige

Pure-Go GigE Vision client (package gige) for Huaray/Dahua 3D volume cameras.

Install

go get github.com/aaronmurniadi/gogige

Pre-commit

Once per clone, point git at the versioned hooks (runs gofmt on staged .go files, then go test ./...):

git config core.hooksPath .githooks

Quick start

dev, err := gige.Open(ctx, "192.168.1.10",
    gige.WithLogger(logger),
    gige.WithTimeout(2*time.Second),
)
defer dev.Close()

g, err := dev.StartGrabber(ctx)
defer g.Close()
sample, err := g.Grab(ctx) // Sample: JPEG + WidthMm/HeightMm/Length/PackCount

One-shot:

jpeg, err := gige.GrabJPEG(ctx, "192.168.1.10")

Discover cameras (root API):

devs, err := gige.Discover(ctx, 2*time.Second)

Live + preview (app owns the sink):

live := gige.NewLive(dev, gige.WithSink(gige.JPEGFunc(hub.Broadcast)), gige.WithLiveComponent(gige.ComponentDepth))
live.Start(ctx)
defer live.Stop()
sample := live.LatestSample() // filter/validate in the app
// live.SetComponent(gige.ComponentColor) // switch mid-stream

Package layout

Domain Package Role
Root gige Discover + re-exports (Open, NewLive, GrabJPEG, …)
Control control/camera Camera, Connect, Logger
Control control/gvcp GVCP, CCP, FetchXML, Start/StopAcquisition
Control control/genicam GenICam NodeMap
Vision vision/device Device, Open, Features, Grabber
Vision vision/session Streaming session
Vision vision/live Live preview loop
Vision vision/grab One-shot GrabJPEG
Vision vision/gvsp GVSP stream
Vision vision/bscf BSCF + Sample
Vision vision/color JPEG encode

Examples

Omit -ip to pick the first camera from GigE discovery (or pass -ip explicitly).

Logging: gige.WithLogger(...) or gige.Zerolog(z). Default is a no-op.

Documentation

Overview

Package gogige is a pure-Go GigE Vision client.

Happy path (Phase 4): 

cam, err := gogige.OpenDevice(ctx, "192.168.1.10")
defer cam.Close()
_ = cam.SetInteger("Width", 1920)
_ = cam.SetEnum("PixelFormat", "Mono8")
stream, err := cam.StartStream(ctx)
defer stream.Stop()
for frame := range stream.Frames() {
	// use frame.Data
	frame.Release()
}

Sample/JPEG path (Huaray BSCF): Device.StartGrabber → Grabber.Grab.

Protocol packages:

  • gvcp — GigE Vision Control Protocol
  • genapi — GenICam GenApi XML / node map
  • gvsp — GigE Vision Streaming Protocol

Device discovery (broadcast) lives on this root package: Discover. Preview sinks are app-owned (see examples/websocket-stream).

Index

Constants

View Source 
const (
	ComponentUnknown = gvsp.ComponentUnknown
	ComponentMono    = gvsp.ComponentMono
	ComponentDepth   = gvsp.ComponentDepth
	ComponentColor   = gvsp.ComponentColor
)

SFNC-style imaging components (BSCF ImageType wire values).

View Source 
const Version = "0.7.0"

Version is the library semver (no leading "v").

Variables

View Source 
var (
	DialGVCP                = gvcp.DialGVCP
	ParseNodeMap            = genapi.ParseNodeMap
	FetchXML                = genapi.FetchXML
	ListenStream            = gvsp.ListenStream
	SampleFromBSCF          = gvsp.SampleFromBSCF
	SampleFromBSCFComponent = gvsp.SampleFromBSCFComponent
	SampleAllFromBSCF       = gvsp.SampleAllFromBSCF
	ParseBSCF               = gvsp.ParseBSCF
	ParseComponent          = gvsp.ParseComponent
	IsBSCF                  = gvsp.IsBSCF
	EncodeJPEG              = color.EncodeJPEG
	StartAcquisition        = gvcp.StartAcquisition
	StopAcquisition         = gvcp.StopAcquisition
)

Re-exports of common constructors / parsers.

Functions

func ApplyControlPair 

func ApplyControlPair(c *Camera, pair string) error

ApplyControlPair sets one GenICam feature from "Name=value" string.

func GrabJPEG 

func GrabJPEG(ctx context.Context, ip string, opts ...Option) ([]byte, error)

GrabJPEG opens a short-lived device, grabs one frame, and closes. Convenience for one-shot capture; prefer Device + Grabber for continuous use.

Types

type Camera 

type Camera struct {
	IP string
	// contains filtered or unexported fields
}

Camera is a connected GigE Vision device with GenICam feature access.

func Connect 

func Connect(ip string) (*Camera, error)

Connect opens GVCP to the camera at ip, takes control, and loads GenICam XML.

func New 

func New(ip string, g *gvcp.GVCP, nodes *genapi.NodeMap, log Logger) *Camera

New builds a Camera from an already-connected GVCP client and NodeMap.

func (*Camera) BooleanFeature added in v0.7.0 

func (c *Camera) BooleanFeature(name string) (bool, error)

BooleanFeature reads the current value of a boolean GenICam feature.

func (*Camera) Close 

func (c *Camera) Close()

Close releases control and the GVCP socket.

func (*Camera) Execute 

func (c *Camera) Execute(name string) error

Execute implements gvcp.Commander.

func (*Camera) ExecuteCommand 

func (c *Camera) ExecuteCommand(name string) error

ExecuteCommand executes a GenICam command node.

func (*Camera) GVCP 

func (c *Camera) GVCP() *gvcp.GVCP

GVCP returns the underlying control client.

func (*Camera) Has 

func (c *Camera) Has(name string) bool

Has reports whether a GenICam feature exists (gvcp.Commander).

func (*Camera) Logger added in v0.2.0 

func (c *Camera) Logger() Logger

Logger returns the camera logger (never nil).

func (*Camera) NodeMap 

func (c *Camera) NodeMap() *genapi.NodeMap

NodeMap returns the loaded GenICam map.

func (*Camera) SetBooleanFeature 

func (c *Camera) SetBooleanFeature(name string, v bool) error

SetBooleanFeature sets a boolean GenICam feature.

func (*Camera) SetFloatFeature 

func (c *Camera) SetFloatFeature(name string, v float64) error

SetFloatFeature sets a float GenICam feature.

func (*Camera) SetIntFeature 

func (c *Camera) SetIntFeature(name string, v int64) error

SetIntFeature sets an integer GenICam feature.

func (*Camera) SetStringFeature 

func (c *Camera) SetStringFeature(name, v string) error

SetStringFeature sets a string or enumeration GenICam feature.

type Component added in v0.5.0 

type Component = gvsp.Component

Type aliases keep the root consumer API ergonomic for protocol types.

type Device 

type Device interface {
	IP() string
	Features() Features
	StartGrabber(ctx context.Context, opts ...GrabOption) (Grabber, error)
	Close() error
}

Device is a connected camera handle (control + ability to start streaming).

func Open 

func Open(ctx context.Context, ip string, opts ...Option) (Device, error)

Open connects to a GigE Vision camera and returns a Device.

type DeviceInfo 

type DeviceInfo struct {
	IP           string
	MAC          string
	Manufacturer string
	Model        string
	Serial       string
	UserName     string
}

DeviceInfo is a camera found via GigE Vision discovery (root API).

func Discover 

func Discover(ctx context.Context, timeout time.Duration) ([]DeviceInfo, error)

Discover broadcasts a GigE Vision DISCOVERY_CMD and collects acknowledgements. timeout bounds how long to wait for replies after the broadcast.

type Features 

type Features interface {
	SetBool(name string, v bool) error
	SetInt(name string, v int64) error
	SetFloat(name string, v float64) error
	SetString(name, v string) error
	Execute(name string) error
	Has(name string) bool
}

Features is GenICam feature access without exposing NodeMap.

type Frame 

type Frame = gvsp.Frame

Type aliases keep the root consumer API ergonomic for protocol types.

type FrameSink 

type FrameSink interface {
	SendJPEG(jpeg []byte)
	Freeze()
	Resume()
}

FrameSink receives JPEG frames from Live for preview (WebSocket, MJPEG, etc.). Implement this in application code — the library does not ship a WebSocket server.

type GVCP 

type GVCP = gvcp.GVCP

Type aliases keep the root consumer API ergonomic for protocol types.

type GrabOption added in v0.4.0 

type GrabOption func(*Session)

GrabOption configures StartGrabber / Session.

func GrabComponent added in v0.5.0 

func GrabComponent(comp Component) GrabOption

GrabComponent selects which BSCF/SFNC component Session.Grab decodes.

type Grabber 

type Grabber interface {
	Grab(ctx context.Context) (Sample, error)
	GrabAll(ctx context.Context) ([]Sample, error)
	SetComponent(Component)
	Pause(ctx context.Context) error
	Resume(ctx context.Context) error
	Close() error
}

Grabber is a live GVSP acquisition stream.

type JPEGFunc 

type JPEGFunc func([]byte)

JPEGFunc adapts a callback into a FrameSink (Freeze/Resume are no-ops). Handy for wiring Live to an existing broadcast function: 

live := live.NewLive(dev, live.WithSink(JPEGFunc(hub.Broadcast)))

func (JPEGFunc) Freeze 

func (JPEGFunc) Freeze()

func (JPEGFunc) Resume 

func (JPEGFunc) Resume()

func (JPEGFunc) SendJPEG 

func (f JPEGFunc) SendJPEG(jpeg []byte)

type Live 

type Live struct {
	// contains filtered or unexported fields
}

Live keeps a Grabber open and publishes Samples (optionally to a FrameSink).

func NewLive 

func NewLive(dev Device, opts ...LiveOption) *Live

NewLive builds a Live preview/capture loop over an already-opened Device.

func (*Live) Component added in v0.5.0 

func (l *Live) Component() Component

Component returns the BSCF/SFNC component Live is decoding.

func (*Live) LatestJPEG 

func (l *Live) LatestJPEG() []byte

LatestJPEG returns a copy of the most recent JPEG, or nil.

func (*Live) LatestSample 

func (l *Live) LatestSample() Sample

LatestSample returns a copy of the most recent Sample.

func (*Live) Pause 

func (l *Live) Pause()

Pause freezes publishing and pauses the underlying Grabber when possible.

func (*Live) Restart 

func (l *Live) Restart(ctx context.Context)

Restart stops and starts again.

func (*Live) Resume 

func (l *Live) Resume()

Resume unfreezes publishing.

func (*Live) SetComponent added in v0.5.0 

func (l *Live) SetComponent(c Component)

SetComponent switches the BSCF/SFNC component for subsequent grabs (no reconnect).

func (*Live) Start 

func (l *Live) Start(ctx context.Context)

Start begins the grab loop. Safe to call again after Stop (reopens grabber).

func (*Live) Stop 

func (l *Live) Stop()

Stop ends the grab loop and closes the Grabber owned by Live.

type LiveOption 

type LiveOption func(*Live)

LiveOption configures NewLive.

func WithLiveComponent added in v0.5.0 

func WithLiveComponent(c Component) LiveOption

WithLiveComponent selects which BSCF/SFNC component Live grabs (color/depth/mono).

func WithOnSample 

func WithOnSample(fn func(Sample)) LiveOption

WithOnSample registers a callback after each published sample.

func WithSink 

func WithSink(s FrameSink) LiveOption

WithSink attaches a FrameSink for preview JPEG delivery.

type Logger 

type Logger interface {
	Debug(msg string, kv ...any)
	Info(msg string, kv ...any)
	Warn(msg string, kv ...any)
	Error(msg string, kv ...any)
}

Logger is a minimal structured logger. Default is a no-op.

func Zerolog 

func Zerolog(z zerolog.Logger) Logger

Zerolog wraps a zerolog.Logger as a Logger.

type NodeMap 

type NodeMap = genapi.NodeMap

Type aliases keep the root consumer API ergonomic for protocol types.

type NopLogger 

type NopLogger struct{}

NopLogger discards all log events.

func (NopLogger) Debug 

func (NopLogger) Debug(string, ...any)

func (NopLogger) Error 

func (NopLogger) Error(string, ...any)

func (NopLogger) Info 

func (NopLogger) Info(string, ...any)

func (NopLogger) Warn 

func (NopLogger) Warn(string, ...any)

type Option 

type Option func(*openConfig)

Option configures Open / device connection.

func WithComponent added in v0.5.0 

func WithComponent(comp Component) Option

WithComponent selects which BSCF/SFNC component GrabJPEG uses (color/depth/mono). Default: ComponentColor.

func WithLogger 

func WithLogger(l Logger) Option

WithLogger sets the logger used by this device (default: NopLogger).

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets the GVCP dial / control timeout (default: 2s).

type Port 

type Port = gvcp.Port

Type aliases keep the root consumer API ergonomic for protocol types.

type Sample 

type Sample = gvsp.Sample

Type aliases keep the root consumer API ergonomic for protocol types.

type Session 

type Session struct {
	// contains filtered or unexported fields
}

Session is a persistent GVSP stream session. It implements Grabber.

func NewFromCamera 

func NewFromCamera(cam *Camera) *Session

NewFromCamera returns a Session that streams using cam without taking ownership.

func NewSession 

func NewSession() *Session

NewSession returns an empty GVSP session (Connects on Open if no camera set).

func (*Session) Close 

func (s *Session) Close() error

Close stops acquisition and releases stream resources. The Camera is closed only when the Session owns it (not when Device owns it).

func (*Session) Grab 

func (s *Session) Grab(ctx context.Context) (Sample, error)

Grab implements Grabber: receives one GVSP frame, parses BSCF, returns JPEG Sample.

func (*Session) GrabAll added in v0.4.0 

func (s *Session) GrabAll(ctx context.Context) ([]Sample, error)

GrabAll receives one GVSP frame and returns a JPEG Sample for every BSCF component (color, depth, mono, …). Non-BSCF payloads yield a single sample.

func (*Session) GrabComponents added in v0.7.0 

func (s *Session) GrabComponents(ctx context.Context) ([]Sample, error)

GrabComponents receives one GVSP frame and returns its BSCF components without JPEG encoding (raw Data, dimensions, pixel format). Non-BSCF payloads yield a single Sample with ComponentUnknown and no JPEG. Useful to probe what a camera is actually streaming beyond the JPEG color path.

func (*Session) Open 

func (s *Session) Open(ip string) error

Open connects (if needed), starts GVSP, and begins acquisition.

func (*Session) Opened 

func (s *Session) Opened() bool

Opened reports whether the session is open.

func (*Session) Pause 

func (s *Session) Pause(ctx context.Context) error

Pause implements Grabber.

func (*Session) PauseStreaming 

func (s *Session) PauseStreaming() error

PauseStreaming stops image transfer but keeps CCP, heartbeat, and GVSP socket.

func (*Session) Resume 

func (s *Session) Resume(ctx context.Context) error

Resume implements Grabber.

func (*Session) ResumeStreaming 

func (s *Session) ResumeStreaming() error

ResumeStreaming re-programs the stream channel and starts acquisition again.

func (*Session) SetComponent added in v0.5.0 

func (s *Session) SetComponent(c Component)

SetComponent selects which BSCF/SFNC component Grab returns (color/depth/mono).

type Stream 

type Stream = gvsp.Stream

Type aliases keep the root consumer API ergonomic for protocol types.

Source Files

View all Source files

Directories

Path Synopsis
cmd
gogige-discover command
gogige-discover broadcasts GigE Vision DISCOVERY_CMD and prints peers.
 gogige-discover broadcasts GigE Vision DISCOVERY_CMD and prints peers.
gogige-stream command
gogige-stream captures N frames (JPEG + BSCF measurements) from a GigE camera.
 gogige-stream captures N frames (JPEG + BSCF measurements) from a GigE camera.
internal
color

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.