gige

package module
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 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)))
live.Start(ctx)
defer live.Stop()
sample := live.LatestSample() // filter/validate in the app

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 gige is a pure-Go GigE Vision client.

Happy path (root package): 

dev, err := gige.Open(ctx, "192.168.1.10")
defer dev.Close()
g, err := dev.StartGrabber(ctx)
defer g.Close()
sample, err := g.Grab(ctx)

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 (
	ImageUnknown = gvsp.ImageUnknown
	ImageMono    = gvsp.ImageMono
	ImageDepth   = gvsp.ImageDepth
	ImageColor   = gvsp.ImageColor
)

BSCF image kinds (Huaray Frame.h ImageType).

View Source 
const Version = "0.4.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
	SampleFromBSCFKind = gvsp.SampleFromBSCFKind
	SampleAllFromBSCF  = gvsp.SampleAllFromBSCF
	ParseBSCF          = gvsp.ParseBSCF
	ParseImageKind     = gvsp.ParseImageKind
	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) 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 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 GrabImageKind added in v0.4.0 

func GrabImageKind(k ImageKind) GrabOption

GrabImageKind selects which BSCF image block Session.Grab decodes.

type Grabber 

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

Grabber is a live GVSP acquisition stream.

type ImageKind added in v0.4.0 

type ImageKind = gvsp.ImageKind

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

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) 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) 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 WithLiveImageKind added in v0.4.0 

func WithLiveImageKind(k ImageKind) LiveOption

WithLiveImageKind selects which BSCF image 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 WithImageKind added in v0.4.0 

func WithImageKind(k ImageKind) Option

WithImageKind selects which BSCF image block GrabJPEG uses (color/depth/mono). Default: ImageColor.

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 image block (color, depth, mono, …). Non-BSCF payloads yield a single sample.

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) SetImageKind added in v0.4.0 

func (s *Session) SetImageKind(k ImageKind)

SetImageKind selects which BSCF image block 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.