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.
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
§License
This project is licenced under MPL 2.0.
Re-exports§
pub use camera::Camera;
pub use camera::CameraInfo;
pub use camera::DeviceControl;
pub use camera::PayloadStream;
Modules§
- This module contains types that is the main entry types of the
Cameleon
. - This module provides access to
GenApi
features ofGenICam
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§
- An error type returned from the
camera::Camera
. - An error type for device control.
- An error type related to payload streaming.
Type Aliases§
- A specialized
Result
type forcamera::Camera
. - A specialized
Result
type for device control. - A specialized
Result
type for streaming.