telegenic
Pure-Rust GenICam camera library.
Transports are pluggable, but the only backend right now is GigE Vision
(telegenic::gige), which speaks GVCP (control) and GVSP (streaming)
directly over UDP, with no vendor SDK. USB3 Vision and GenTL producers are
not supported.
use ;
let mut cam = new;
cam.connect?; // takes control and loads the feature model
cam.set_float?;
cam.set_enum?;
// Grab a single frame. The camera stays idle between captures,
// so this uses no stream bandwidth outside the snap itself.
let frame = cam.snap?;
println!;
// Or stream continuously. The guard subscribes before the camera
// starts (so the first frame isn't lost) and stops it on drop.
let acq = cam.start_acquisition?;
while let Some = acq.wait_for
acq.stop?; // or just drop it
cam.disconnect; // or just drop it
# Ok::
A camera is a plain owned value. Constructing one does no I/O and can't
fail; connect(&mut self) is where the work happens, and it doubles as the
reconnect path after a dropped link. Everything tied to a connection
(identity, capabilities, the parsed GenICam model, stats) lives only as long
as the connection, and methods return Disconnected when no link is up.
Layers
GenICamera is the top-level type and the one most code uses. It parses the
device's GenICam XML (zipped or plain) and gives string-keyed typed access
to the feature node graph, including Converter/SwissKnife formula
evaluation, register caching, and pInvalidator handling. Acquisition is
built in: start_acquisition returns an RAII guard for continuous
streaming, and snap/snapshot_session grab single frames with the camera
idle in between. Both guards borrow the camera mutably, so stopping happens
automatically and disconnecting mid-acquisition won't compile.
Underneath sits the GigE Vision backend:
gige::discoverydoes broadcast device discovery per network adapter, and Force IP for repointing a camera whose address doesn't match the local subnet (seeexamples/discover.rsandexamples/force_ip.rs).gige::GigECamerais the GVCP transport. Register and memory IO return [ResponseHandle]s that can be waited on synchronously (wait_timeout) or.awaited. It handles the heartbeat, pending-acks, retries, and message-channel events, andopen_streamopens raw GVSP channels.gige::streamis the GVSP receiver, one thread per channel. Buffers come from a preallocated pool (no allocation per packet or frame at steady state), packets are reassembled out of order with resend requests, packet size is negotiated automatically, and frames fan out asArc<Frame>over bounded channels that drop when full.
Real-time tuning
GigeConfig and StreamConfig take fast-talker
option lists, re-exported as telegenic::{ThreadOption, SocketOption}, all
empty by default. The GVSP socket always gets an 8 MiB receive buffer, so a
full frame's burst fits between two worker wakeups, unless
StreamConfig::stream_socket sets its own RecvBuffer; its other options
are applied on top of that default rather than replacing it.
use GigeConfig;
use ;
let mut cfg = new;
cfg.thread = vec!;
cfg.control_socket = vec!;
let mut cam = with_config;
cam.connect?;
let mut stream = new;
stream.thread = vec!;
stream.stream_socket = vec!;
let acq = cam.start_acquisition?;
# drop;
# Ok::
| Field | Applied to | Accepted | Refused, and why |
|---|---|---|---|
GigeConfig::thread |
the GVCP control worker, by itself during connect |
CpuAffinity, PrefaultStack, LinuxNice, UnixScheduler(Other | Batch | Idle), WinPriority below TimeCritical, WinDisablePowerThrottling, MacOsQos |
RtPriority, UnixScheduler(Fifo | RoundRobin), WinPriority(TimeCritical), WinMmcss, MacOsTimeConstraint: a real-time class on a thread that blocks on slow request/response round-trips only risks starving the rest of the system |
GigeConfig::control_socket |
the GVCP socket, before bind | RecvBuffer, BindDevice, Dscp, LinuxPriority |
the busy-poll options burn a core on a slow loop; SendBuffer, DontFragment and WinCpuAffinity don't help a request/response socket |
StreamConfig::thread |
the GVSP stream worker, by itself before the stream opens | every ThreadOption except the one refused |
MacOsTimeConstraint: it reserves a fixed computation slice per period, and the worker is a receive loop with no host-owned period |
StreamConfig::stream_socket |
the GVSP socket, before bind | RecvBuffer, BindDevice, LinuxBusyPoll, LinuxPreferBusyPoll, LinuxBusyPollBudget, WinCpuAffinity |
SendBuffer, DontFragment, Dscp, LinuxPriority only shape traffic this receive-only socket doesn't send |
Socket options are applied before the socket is bound, so BindDevice
and WinCpuAffinity take effect. A refused option, or one that fails to
apply (e.g. RtPriority without CAP_SYS_NICE), makes connect (or
opening the stream) fail, naming the option. Options for another platform,
or that this platform cannot do, are skipped with a tracing warning, so
one config works on Linux, macOS and Windows; so is an option the platform
applied with a different value, such as a RecvBuffer capped by
net.core.rmem_max. GigECamera::tuning_report() and
StreamChannel::tuning_report() list what was applied, adjusted and
skipped. On Linux, StreamStats::socket_drops counts the datagrams the
GVSP socket dropped because its receive buffer was full. Discovery and
Force IP take no options.
Process-wide settings (memory locking, cpu_dma_latency, Windows priority
class, timer resolution and working set) are the application's job: call
telegenic::fast_talker::options::ProcessOption::apply_all once at startup.
From Python the same lists are keyword arguments, in any shape fast-talker accepts:
=
=
telegenic.apply_process_options applies the process-wide ones and returns
a guard that holds them:
...
Python
The same library ships as a Python package via PyO3/maturin (the py
feature). Install with pip install telegenicam, or run maturin develop
from a checkout; the import name is telegenic either
way. The GenICam surface maps one-to-one, blocking calls release the GIL,
and frames expose their pixels as bytes for numpy.frombuffer:
=
# camera idle between snaps
=
# stops the camera again on exit
=
telegenic.discover() finds cameras on the local subnets. The package
includes type stubs and docstrings (telegenic/__init__.pyi).
Examples
Cargo features
| Feature | Enables |
|---|---|
py |
the PyO3 bindings |
abi3, abi3t |
py built against the stable ABI (abi3-py310, abi3t-py315) |
emulator |
telegenic::emulator, a socket-agnostic GigE Vision device for tests and simulators |
valuable |
valuable::Valuable on public data types and errors |
async |
nothing extra; recv_async on frame and event channels is always available |
Testing
cargo test runs the unit tests, proptest suites for the GVCP, GVSP and
GenICam decoders, and GenICam node-graph evaluation against mock registers.
The integration suites are built only under
cargo snare test --features emulator (install with
cargo install cargo-snare), which runs each one inside a deterministic
snare simulation on a virtual clock. They drive an
in-process fake camera (tests/fake_camera/) and the emulator device over
UDP, and cover GVCP semantics (retries, pending-ack, heartbeat and
control loss, reconnects), discovery and Force IP, GVSP reassembly under
packet loss, reordering, and duplication with resend replay, packet-size
negotiation, and the full GenICamera path including message-channel
events and single-frame snapshots. fuzz/ holds cargo-fuzz targets, and
py_tests/ the pytest suite for the bindings (no camera needed).
License
Licensed under the Apache License, Version 2.0. See LICENSE.