cameleon: A Rust repository from cameleon-rs

cameleon is a safe, fast, and flexible library for GenICam compatible cameras.

Overview

cameleon is a library for operating on GenICam compatible cameras. Our main goal is to provide safe, fast, and flexible library for GenICam cameras.

Currently, cameleon supports only USB3 Vision cameras, but it's planned to support other protocols including GigE Vision. See Roadmap for more details.

Usage

USB3 Vision cameras

You need to install libusb to use USB3 Vision cameras, see How to install libusb.

First, add dependencies like below.

[dependencies]
cameleon = { version = "0.1", features = ["libusb"] }

Then, you can enumerate all cameras connected to the host, and start streaming.

use cameleon::u3v;

// Enumerates all cameras connected to the host.
let mut cameras = u3v::enumerate_cameras().unwrap();

if cameras.is_empty() {
    println!("no camera found");
    return;
}


let mut camera = cameras.pop().unwrap();

// Opens the camera.
camera.open().unwrap();
// Loads `GenApi` context. This is necessary for streaming.
camera.load_context().unwrap();

// Start streaming. Channel capacity is set to 3.
let payload_rx = camera.start_streaming(3).unwrap();

for _ in 0..10 {
    let payload = match payload_rx.recv_blocking() {
        Ok(payload) => payload,
        Err(e) => {
            println!("payload receive error: {e}");
            continue;
        }
    };
    println!(
        "payload received! block_id: {:?}, timestamp: {:?}",
        payload.id(),
        payload.timestamp()
    );
    if let Some(image_info) = payload.image_info() {
        println!("{:?}\n", image_info);
        let image = payload.image();
        // do something with the image.
        // ...
    }

    // Send back payload to streaming loop to reuse the buffer. This is optional.
    payload_rx.send_back(payload);
}

// Closes the camera.
camera.close().unwrap();

More examples can be found here.

Project Layout

Cameleon consists of several crates.

cameleon: Provides high-level APIs to control cameras. This is the primary crate.
cameleon-genapi: Provides parser and interpreter of GenApi XML.
cameleon-device: Provides device specific protocol decoder and basic I/O operations for devices, also provides emulators.
cameleon-gentl: Provides GenTL interfaces as a C library.
cameleon-impl: Provides internal APIs for other crates. cameleon-impl is intended to be used only by cameleon project.
cameleon-impl-macros: Provides procedural macros for other crates. cameleon-impl-macros is intended to be used only by cameleon project.

FAQ

USB3 Vision

How to install `libusb`?

Linux/macOS

You need to install libusb to the place where pkg-config can find. Basically all you have to do is just installing libusb through your system package manager like sudo apt install libusb-1.0-0-dev or brew install libusb.

If you use Linux, it's probably needed to edit permissions for USB devices. You could add permissions by editing udev rules, a configuration example is found here.

Windows

You need to install libusb with vcpkg, please see here to install libusb with vcpkg.

Also, you need to install a driver for your device. You can find resource here for driver-installation.
NOTE: Make sure to install a driver to a composite device not to its child devices.
To do this, you need to list all devices connected to the host computer with zadig like below.

Then install WinUSB to your device.

Why is frame rate so low?

Frame rate can be affected by several reasons.

Parameter settings of the camera

AcquisitionFrameRate and ExposureTime directly affect frame rate. So you need to setup the parameters first to improve frame rate. Also, if DeviceLinkThroughputLimitMode is set to On, you would need to increase the value of DeviceLinkThroughputLimit.

Many devices are streaming simultaneously on the same USB host controller

In this case, it's recommended to allocate the equal throughput limit to the connected cameras, making sure that the total throughput does not exceed the maximum bandwidth of the host controller.

usbfs_memory_mb is set to low value

If you use Linux, you may need to increase usbfs_memory_mb limit. By default, USB-FS on Linux systems only allows 16 MB of buffer memory for all USB devices. This is quite low for high-resolution image streaming. We recommend you to set the value to 1000MB. You could set the value as following:

echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb

Roadmap

v0.2.0

Add support for GigE cameras
Impelment emulator
Add support for saving and loading camera parameters

v0.3.0

Implement payload chunk parser
Add support for GenTL

v0.4.0

Add support for UVC cameras

Contributing

Thank you for your interest in contributing to Cameleon! We are so happy to have you join the development.
To start developing, please refer to CONTRIBUTING.md.

Releasing

1. Publish

Check commits since the last release and determine whether they're semver-breaking.
Bump up all the crate versions and publish using cargo release <major|minor|patch>
Open a PR to reflect the changes.

2. Changelog

Create a new release on the GitHub page from the tag that cargo release has created
Use automatically generated release notes and modify it manually

License

This project is licenced under MPL 2.0.

cameleon-rs/cameleon