Getting started

Getting started#

Installation#

From PyPI:

pip install pyGigEVision

From source:

git clone https://github.com/ladisk/pyGigEVision.git
cd pyGigEVision
pip install -e .

Requirements#

  • Python 3.10 or newer

  • NumPy 1.20 or newer

  • psutil (used to enumerate host network interfaces for multi-interface discovery)

  • A network interface that can reach the camera (usually a link-local 169.254.x.x address on a dedicated Ethernet adapter, or a routed 192.168.x.x subnet)

  • Windows Firewall (or equivalent) allowing inbound UDP for the Python process

First contact#

Discover any GigE Vision cameras on the network:

from pyGigEVision import discover

cameras = discover(timeout=2.0)
for cam in cameras:
    print(f"{cam['manufacturer']:30s} {cam['model']:30s} {cam['ip']}")

Called with no interface argument, discover() sweeps every host network interface, so cameras on secondary NICs and USB-to-GigE adapters are found by default. Each result dict includes ip, mac, and interface_ip (the host interface the camera replied on), which lets a caller bind the correct local interface when connecting.

If a camera comes up on a subnet none of your host interfaces can reach, use force_ip(mac, ip, mask) to re-home it to a reachable address:

from pyGigEVision import GVCPClient

# force_ip is a static method; it broadcasts and needs no connection.
GVCPClient.force_ip(cam["mac"], "169.254.10.50", "255.255.0.0")

If no cameras appear, see the Protocol overview page for troubleshooting network setup and packet capture.

Connecting and grabbing one frame#

The pyGigEVision.bootstrap() helper performs the standard boot sequence: open a control session, acquire control privilege, start the heartbeat thread, and fetch the GenICam XML descriptor.

from pyGigEVision import bootstrap, GVSPReceiver

client, xml = bootstrap("169.254.1.10")
print(f"Downloaded {len(xml)} bytes of GenICam XML")

# From here you configure your camera's vendor-specific registers
# (Width, Height, PixelFormat, AcquisitionStart, ...) using
# client.write_reg(), then receive frames via GVSPReceiver.

client.disconnect()

For a complete end-to-end example, see Examples.

What pyGigEVision is and is not#

pyGigEVision implements the protocol layer defined by the GigE Vision specification. It does not know which register addresses your camera uses for Width or ExposureTime; those are vendor-specific and discovered from the camera’s GenICam XML.

For a turn-key driver for a specific camera, you would either:

  • Use a vendor-specific package built on top of pyGigEVision.

  • Write your own thin vendor layer that parses the GenICam XML and wraps the relevant registers. See the Examples page for a starting point.