repository·master·Indexed 20 days ago
https://github.com/genicam/harvestersA Python-based image acquisition engine that leverages the GenTL standard to provide a unified interface for interacting with GenICam compliant cameras across different transport layers. It enables loading GenTL Producers (.cti files), enumerating devices, manipulating GenICam feature nodes, and acquiring images as NumPy arrays.
Harvester is a Python library designed to simplify the image acquisition process in computer vision applications. It acts as an image acquisition engine that gathers image data from GenTL Producers and stores it in buffers.
Key capabilities include:
Understanding the relationship between these components is key to using Harvester:
Harvester requires a GenTL Producer to acquire images from GenICam compliant cameras.
.cti extension.mvGenTL_Acquire, formerly mvIMPACT_Acquire) is a reliable option that does not block cameras from other competitors.For detailed setup and workflow instructions, refer to the following documentation files:
docs/INSTALL.rst for installing Harvester and its prerequisites.docs/TUTORIAL.rst for a guide on a typical image acquisition workflow.A standard image acquisition workflow using Harvester follows these five steps in order:
Harvester and load one or more .cti files using add_file().update() to populate the device list.ImageAcquirer object using create().start() and retrieve images via fetch() or try_fetch().stop(), destroy the acquirer with destroy(), and reset the Harvester object with reset().from harvesters.core import Harvester
h = Harvester()
h.add_file('path/to/foo.cti')
h.update()
ia = h.create(0)
ia.start()
# ... acquire images ...
ia.stop()
ia.destroy()
h.reset()To prevent resource leaks, always release hardware and software handles:
ia.stop(): Stops the acquisition process.ia.destroy(): Disconnects the device from the acquirer. You must call h.create() again to reconnect to this device.h.reset(): Releases all resources held by the Harvester object.Best Practice: Use Python's with statement for both Harvester and ImageAcquirer. This ensures destroy() and reset() are called automatically even if errors occur.
from harvesters.core import Harvester
# Recommended pattern using context managers
with Harvester() as h:
h.add_file('path/to/foo.cti')
h.update()
with h.create(0) as ia:
ia.start()
# ... acquire images ...
ia.stop()
# ia.destroy() is called automatically here
# h.reset() is called automatically hereTo use Harvester, you typically follow these steps:
Harvester instance..cti) using add_file().update() to populate device_info_list.ImageAcquirer using create(index).ia.remote_device.node_map.ia.start().ia.fetch() as a context manager.ia.stop() and ia.destroy().h.reset().from harvesters.core import Harvester
import numpy as np
h = Harvester()
h.add_file('/path/to/your_producer.cti')
h.update()
# Create an acquirer for the first device found
ia = h.create(0)
# Configure GenICam nodes
ia.remote_device.node_map.Width.value = 8
ia.remote_device.node_map.Height.value = 8
ia.remote_device.node_map.PixelFormat.value = 'Mono8'
ia.start()
try:
with ia.fetch() as buffer:
# Access the first image component in the payload
component = buffer.payload.components[0]
# Convert 1D data to 2D NumPy array
image_2d = component.data.reshape(component.height, component.width)
print(f'Average: {np.average(image_2d)}')
finally:
ia.stop()
ia.destroy()
h.reset()You can install the harvesters package via PyPI. Note that the package name is harvesters (plural), not harvester.
Installing via pip will automatically install required dependencies such as numpy and genicam if they are not already present in your environment.
# Standard installation
$ pip install harvesters
# Upgrade existing installation
$ pip install --upgrade harvesters
# OR
$ pip install -U harvesters
# Install without using cached packages
$ pip install -U --no-cache-dir harvestersTo use Harvester, ensure your system meets the following requirements:
genicam package. If your CPython version is not supported by genicam, Harvester will not be available.To install the latest development version of Harvester, clone the repository from GitHub and use setup.py.
$ git clone https://github.com/genicam/harvesters.git && cd harvesters && python setup.py installIt is highly recommended to use an isolated environment (e.g., via Anaconda/Conda) to avoid corrupting your system Python.
To create and use an environment named genicam with Python 3.6, follow these steps:
conda create -n genicam python=3.6conda activate genicampython --versionconda deactivate# Create environment
$ conda create -n genicam python=3.6
# Activate environment
$ conda activate genicam
# Verify Python version
$ python --version
# Install IPython (optional)
$ conda install ipython
# Deactivate
$ conda deactivateHarvester returns acquired images as 1D NumPy arrays to avoid imposing a specific shape that might limit downstream algorithms. To use the image in applications like VisPy or OpenCV, you must reshape the array using the metadata provided by the component.
For monochrome images, reshape using height and width:
content = component.data.reshape(height, width)For color images, you must include the number of components per pixel. Note that component.num_components_per_pixel returns a float, so you must cast it to an int to avoid NumPy errors.
If the format is bgr_formats, you may need to swap the R and B channels to convert to RGB:
content = component.data.reshape(
height,
width,
int(component.num_components_per_pixel)
)
if data_format in bgr_formats:
content = content[:, :, ::-1]from harvesters.util.pfnc import mono_location_formats, rgb_formats, bgr_formats, rgba_formats, bgra_formats
payload = buffer.payload
component = payload.components[0]
width = component.width
height = component.height
data_format = component.data_format
if data_format in mono_location_formats:
content = component.data.reshape(height, width)
elif data_format in rgb_formats or data_format in rgba_formats or data_format in bgr_formats or data_format in bgra_formats:
content = component.data.reshape(
height, width,
int(component.num_components_per_pixel)
)
if data_format in bgr_formats:
content = content[:, :, ::-1]