# aravisproject/aravis architecture

> Architecture diagram of the GitHub repository aravisproject/aravis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aravisproject/aravis
- Repository: https://github.com/aravisproject/aravis

## Overview

1. **Purpose and principal workflow**

Aravis is a GLib/GObject C library for acquiring video from GenICam industrial cameras over Gigabit Ethernet and USB3, with a simulator, GStreamer source, GenTL producer API, and desktop viewer. The principal interactive workflow is initiated when a **desktop user** launches the viewer: the viewer launcher initializes GTK and GStreamer, configures Aravis acquisition options, creates the viewer application, and hands execution to its application event loop; the viewer’s camera-to-display wiring is not included in the sampled source.

2. **Components**

**Applications and callers**
- **Desktop User** — path: null; launches and operates the documented simple video viewer.
- **Viewer Launcher** — `viewer/main.c`; parses acquisition/debug options, initializes GTK/GStreamer, constructs `ArvViewer`, applies network/USB policies, and runs it as a `GApplication`.
- **Viewer Application** — `viewer/arvviewer.c`; owns the viewer application/UI behavior invoked by the launcher, though its implementation was not sampled.
- **GStreamer Pipeline Application** — path: null; an external GStreamer client can instantiate the documented `aravissrc` source element.
- **GenTL Consumer Application** — path: null; an external GenTL client calls the producer-facing C API.
- **GenICam Industrial Camera** — path: null; the external camera device from which the library acquires video via Ethernet or USB3.

**Core acquisition and GenICam model**
- **Public Aravis API** — `src/arv.h`; provides the umbrella public include surface consumed by applications and extensions.
- **Camera Facade** — `src/arvcamera.c`; exposes camera-level operations such as region, pixel format, frame rate, gain, exposure, acquisition control, payload sizing, and stream creation.
- **Device Feature Access** — `src/arvdevice.c`; applies camera-device feature strings and represents lower-level device access behind the camera facade.
- **Interface and Discovery Layer** — `src/arvinterface.c`; represents camera-facing interfaces, with system-level discovery also organized in the adjacent interface/system source family.
- **Acquisition Stream** — `src/arvstream.c`; owns the generic stream abstraction into which clients provide reusable acquisition buffers.
- **Frame Buffer** — `src/arvbuffer.c`; represents payload storage, including chunk-data payloads.
- **GenICam Feature Model** — `src/arvgc.c`; constructs and evaluates the GenICam feature graph used to resolve typed camera and chunk features.
- **Chunk Metadata Parser** — `src/arvchunkparser.c`; creates an independent GenICam model from XML, attaches an acquired buffer to it, and reads typed boolean, string, integer, or float chunk values.

**Transport and device implementations**
- **GigE Vision Device Control** — `src/arvgvdevice.c`; implements the Gigabit-Ethernet camera device backend documented by the project.
- **GigE Vision Stream** — `src/arvgvstream.c`; implements Ethernet streaming behavior and exposes packet-resend/timeout settings used by the viewer and GStreamer source.
- **USB3 Vision Transport** — `src/arvuvstream.c`; provides the USB acquisition-stream backend; README documents optional libusb-based USB support.
- **Virtual V4L2 Backend** — `src/arvv4l2device.c`; provides a distinct V4L2-oriented device backend present in the library source tree.
- **Ethernet Camera Simulator** — `src/arvfakecamera.c`; provides the basic Ethernet camera simulator documented in the README.

**Interoperability**
- **GStreamer Aravis Source** — `gst/gstaravis.c`; implements the `aravissrc` `GstPushSrc`, negotiates camera capabilities, configures camera features, creates a stream, and prequeues Aravis buffers.
- **GenTL Device Adapter** — `src/gentl/dev.c`; maps GenTL device handles to `ArvCamera` objects and exposes camera IDs, remote-device ports, and GigE stream-channel information through GenTL entry points.

3. **Relationships**

- **Desktop User -> Viewer Launcher:** launches; the launcher is the executable `main` entry point.
- **Viewer Launcher -> Viewer Application:** creates, configures, and runs; it calls `arv_viewer_new`, `arv_viewer_set_options`, and `g_application_run`.
- **Viewer Launcher -> Public Aravis API:** initializes and configures acquisition policies; it includes the public API and passes register-cache, range-check, GigE, and USB options to the viewer.
- **Viewer Launcher -> GStreamer Pipeline Application:** initializes the GStreamer runtime used by the viewer process; it calls `gst_init`, but the viewer’s subsequent pipeline construction is unsampled.
- **GStreamer Pipeline Application -> GStreamer Aravis Source:** instantiates/configures; the source is documented as the `aravissrc` element.
- **GStreamer Aravis Source -> Camera Facade:** reads capabilities and configures acquisition; direct calls obtain bounds/formats and set pixel format, region, frame rate, gain, exposure, and acquisition state.
- **GStreamer Aravis Source -> Device Feature Access:** applies arbitrary configured feature strings; it obtains the camera device and calls the device feature setter.
- **GStreamer Aravis Source -> Acquisition Stream:** creates and configures; it creates a camera stream and sets GigE packet-resend behavior when applicable.
- **GStreamer Aravis Source -> Frame Buffer:** allocates and queues; it creates payload-sized buffers and pushes them onto the stream.
- **Chunk Metadata Parser -> GenICam Feature Model:** constructs and queries; it creates a GenICam model from XML and resolves requested feature nodes.
- **Chunk Metadata Parser -> Frame Buffer:** attaches payload context for chunk extraction; it sets the supplied buffer on its GenICam model before evaluating chunk values.
- **GenTL Consumer Application -> GenTL Device Adapter:** invokes the producer API; adapter functions accept GenTL device handles.
- **GenTL Device Adapter -> Camera Facade:** reads camera identity and GigE stream-channel information; it calls camera ID, device, and GigE channel APIs.
- **Camera Facade -> GenICam Industrial Camera:** controls and acquires from; this is the repository’s documented camera-acquisition role, with GigE/USB backend selection details not established in sampled call sites.
- **GigE Vision Device Control -> GenICam Industrial Camera:** communicates over Gigabit Ethernet; README documents this transport implementation.
- **USB3 Vision Transport -> GenICam Industrial Camera:** communicates over USB3; README documents this transport implementation.

4. **Coverage limits**

The sampled files do not include `ArvViewer` implementation, generic camera/device/stream internals, or the omitted portions of `gstaravis.c` that deliver completed frames downstream. Therefore, exact viewer UI-to-camera/pipeline wiring, discovery ordering, protocol selection, simulator startup paths, and V4L2 behavior cannot be established conclusively.

Main entry points: [`gst/gstaravis.c`](https://github.com/aravisproject/aravis/blob/main/gst/gstaravis.c) (GStreamer Aravis Source), [`viewer/main.c`](https://github.com/aravisproject/aravis/blob/main/viewer/main.c) (Viewer Launcher), [`src/arvcamera.c`](https://github.com/aravisproject/aravis/blob/main/src/arvcamera.c) (Camera Facade), [`src/arvchunkparser.c`](https://github.com/aravisproject/aravis/blob/main/src/arvchunkparser.c) (Chunk Metadata Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_applications["Applications and Callers"]
  node_desktop_user(("Desktop User<br/>external actor"))
  node_viewer_launcher["Viewer Launcher<br/>application entry point"]
  node_viewer_application["Viewer Application<br/>[arvviewer.c]"]
  node_gstreamer_pipeline_app["GStreamer Pipeline Application<br/>external application"]
  node_gentl_consumer_app["GenTL Consumer Application<br/>external application"]
end

subgraph group_core["Core Acquisition Model"]
  node_public_api["Public Aravis API<br/>public API"]
  node_camera_facade["Camera Facade<br/>camera API"]
  node_device_feature_access["Device Feature Access<br/>device API"]
  node_acquisition_stream["Acquisition Stream<br/>stream abstraction"]
  node_frame_buffer["Frame Buffer<br/>payload storage"]
  node_genicam_feature_model["GenICam Feature Model<br/>[arvgc.c]"]
  node_chunk_metadata_parser["Chunk Metadata Parser<br/>[arvchunkparser.c]"]
end

subgraph group_transport["Transport Backends"]
  node_industrial_camera(("GenICam Industrial Camera<br/>external device"))
  node_gige_device_control["GigE Vision Device Control<br/>Ethernet device backend"]
  node_usb3_transport["USB3 Vision Transport<br/>USB acquisition backend"]
end

subgraph group_interop["Interoperability"]
  node_gstreamer_source["GStreamer Aravis Source<br/>GstPushSrc"]
  node_gentl_device_adapter["GenTL Device Adapter<br/>GenTL producer API"]
end

node_desktop_user -->|"launches"| node_viewer_launcher
node_viewer_launcher -->|"creates and runs"| node_viewer_application
node_viewer_launcher -->|"configures policies"| node_public_api
node_viewer_launcher -->|"initializes runtime"| node_gstreamer_pipeline_app
node_gstreamer_pipeline_app -->|"instantiates"| node_gstreamer_source
node_gstreamer_source -->|"configures acquisition"| node_camera_facade
node_gstreamer_source -->|"sets features"| node_device_feature_access
node_gstreamer_source -->|"creates and configures"| node_acquisition_stream
node_gstreamer_source -->|"allocates and queues"| node_frame_buffer
node_chunk_metadata_parser -->|"constructs and queries"| node_genicam_feature_model
node_chunk_metadata_parser -->|"attaches payload"| node_frame_buffer
node_gentl_consumer_app -->|"invokes API"| node_gentl_device_adapter
node_gentl_device_adapter -->|"reads camera data"| node_camera_facade
node_camera_facade -->|"controls and acquires"| node_industrial_camera
node_gige_device_control -->|"communicates over Ethernet"| node_industrial_camera
node_usb3_transport -->|"communicates over USB3"| node_industrial_camera

click node_viewer_launcher "https://github.com/aravisproject/aravis/blob/main/viewer/main.c"
click node_viewer_application "https://github.com/aravisproject/aravis/blob/main/viewer/arvviewer.c"
click node_public_api "https://github.com/aravisproject/aravis/blob/main/src/arv.h"
click node_camera_facade "https://github.com/aravisproject/aravis/blob/main/src/arvcamera.c"
click node_device_feature_access "https://github.com/aravisproject/aravis/blob/main/src/arvdevice.c"
click node_acquisition_stream "https://github.com/aravisproject/aravis/blob/main/src/arvstream.c"
click node_frame_buffer "https://github.com/aravisproject/aravis/blob/main/src/arvbuffer.c"
click node_genicam_feature_model "https://github.com/aravisproject/aravis/blob/main/src/arvgc.c"
click node_chunk_metadata_parser "https://github.com/aravisproject/aravis/blob/main/src/arvchunkparser.c"
click node_gige_device_control "https://github.com/aravisproject/aravis/blob/main/src/arvgvdevice.c"
click node_usb3_transport "https://github.com/aravisproject/aravis/blob/main/src/arvuvstream.c"
click node_gstreamer_source "https://github.com/aravisproject/aravis/blob/main/gst/gstaravis.c"
click node_gentl_device_adapter "https://github.com/aravisproject/aravis/blob/main/src/gentl/dev.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop_user,node_viewer_launcher,node_viewer_application,node_gstreamer_pipeline_app,node_gentl_consumer_app toneBlue
class node_public_api,node_camera_facade,node_device_feature_access,node_acquisition_stream,node_frame_buffer,node_genicam_feature_model,node_chunk_metadata_parser toneAmber
class node_industrial_camera,node_gige_device_control,node_usb3_transport toneMint
class node_gstreamer_source,node_gentl_device_adapter toneRose
```

## Components

### Applications and Callers

- **Desktop User**: external actor
- [Viewer Launcher](https://github.com/aravisproject/aravis/blob/main/viewer/main.c): application entry point · `viewer/main.c`
- [Viewer Application](https://github.com/aravisproject/aravis/blob/main/viewer/arvviewer.c): application · Viewer implementation was not sampled. · `viewer/arvviewer.c`
- **GStreamer Pipeline Application**: external application
- **GenTL Consumer Application**: external application

### Core Acquisition Model

- [Public Aravis API](https://github.com/aravisproject/aravis/blob/main/src/arv.h): public API · `src/arv.h`
- [Camera Facade](https://github.com/aravisproject/aravis/blob/main/src/arvcamera.c): camera API · `src/arvcamera.c`
- [Device Feature Access](https://github.com/aravisproject/aravis/blob/main/src/arvdevice.c): device API · `src/arvdevice.c`
- [Acquisition Stream](https://github.com/aravisproject/aravis/blob/main/src/arvstream.c): stream abstraction · `src/arvstream.c`
- [Frame Buffer](https://github.com/aravisproject/aravis/blob/main/src/arvbuffer.c): payload storage · `src/arvbuffer.c`
- [GenICam Feature Model](https://github.com/aravisproject/aravis/blob/main/src/arvgc.c): feature model · `src/arvgc.c`
- [Chunk Metadata Parser](https://github.com/aravisproject/aravis/blob/main/src/arvchunkparser.c): metadata parser · `src/arvchunkparser.c`

### Transport Backends

- **GenICam Industrial Camera**: external device
- [GigE Vision Device Control](https://github.com/aravisproject/aravis/blob/main/src/arvgvdevice.c): Ethernet device backend · `src/arvgvdevice.c`
- [USB3 Vision Transport](https://github.com/aravisproject/aravis/blob/main/src/arvuvstream.c): USB acquisition backend · `src/arvuvstream.c`

### Interoperability

- [GStreamer Aravis Source](https://github.com/aravisproject/aravis/blob/main/gst/gstaravis.c): GstPushSrc · `gst/gstaravis.c`
- [GenTL Device Adapter](https://github.com/aravisproject/aravis/blob/main/src/gentl/dev.c): GenTL producer API · `src/gentl/dev.c`

## Connections

- Desktop User → Viewer Launcher: launches · Viewer executable main entry point.
- Viewer Launcher → Viewer Application: creates and runs
- Viewer Launcher → Public Aravis API: configures policies
- Viewer Launcher → GStreamer Pipeline Application: initializes runtime · Initializes GStreamer for the viewer process.
- GStreamer Pipeline Application → GStreamer Aravis Source: instantiates · Uses the documented aravissrc element.
- GStreamer Aravis Source → Camera Facade: configures acquisition
- GStreamer Aravis Source → Device Feature Access: sets features
- GStreamer Aravis Source → Acquisition Stream: creates and configures
- GStreamer Aravis Source → Frame Buffer: allocates and queues
- Chunk Metadata Parser → GenICam Feature Model: constructs and queries
- Chunk Metadata Parser → Frame Buffer: attaches payload · Sets the supplied buffer for chunk extraction.
- GenTL Consumer Application → GenTL Device Adapter: invokes API
- GenTL Device Adapter → Camera Facade: reads camera data · Reads camera identity and GigE stream-channel information.
- Camera Facade → GenICam Industrial Camera: controls and acquires
- GigE Vision Device Control → GenICam Industrial Camera: communicates over Ethernet
- USB3 Vision Transport → GenICam Industrial Camera: communicates over USB3
