Crate cameleon

source ·
Expand description

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();

let mut payload_count = 0;
while payload_count < 10 {
    match payload_rx.try_recv() {
        Ok(payload) => {
            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.
                // ...
            }
            payload_count += 1;

            // Send back payload to streaming loop to reuse the buffer. This is optional.
            payload_rx.send_back(payload);
        }
        Err(_err) => {
            continue;
        }
    }
}

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

More examples can be found here.

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.
describe zadig list option

Then install WinUSB to your device.
describe how to install WinUSB driver to your composite device

Why is frame rate so low?

Frame rate can be affected by several reasons.

  1. 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.

  1. 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.

  1. 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

License

This project is licenced under MPL 2.0.

Re-exports

Modules

  • This module contains types that is the main entry types of the Cameleon.
  • This module provides access to GenApi features of GenICam a compatible camera.
  • This module contains types related to Payload sent from the device.
  • This module provides low level API for U3V compatible devices.

Enums

Type Aliases