GXCI

Rust-based interface development for Daheng Industrial Camera GxIAPI

Introduction

gxci(Galaxy Camera Interface)是一款用Rust基于大恒工业相机GxIAPI的库进行的接口开发;

目前已实现USB单相机的HAL库封装，raw内包含着C语言接口除去网络相机的全部内容(句柄、常量、结构、枚举、回调函数等)的直接rust实现；HAL内做了硬件抽象层的封装(目前包括连接、采图、推流)，适合实际开发使用；utils内则是一些工具类函数(常用的Builder模式和Facade模式函数封装);

旧版是一个叫做gxi_hako的crate库，里面raw部分和utils部分的不完全实现，现在已经暂时弃用了;

新版也就是这一款gxci，里面包含了raw、HAL、utils三个部分的实现;

截至目前，2024年7月11日23点45分，已经完成了features=["solo"]部分的HAL库编写，多相机的feature还未实现，等再次闲下来再来更新吧(๑˃ᴗ˂)ﻭ

Gxci (Galaxy Camera Interface) is an interface developed using Rust based on the Daxi API library of Daheng Industrial Camera;

At present, HAL library encapsulation for USB single camera has been implemented, and raw contains a direct Rust implementation of all contents (handles, constants, structures, enumerations, callback functions, etc.) of the C language interface except for the network camera; HAL has encapsulated the hardware abstraction layer (currently including connections, image capture, and streaming), which is suitable for practical development and use; Inside the utilities are some utility class functions (encapsulated with commonly used Builder and Facade pattern functions);

The old version was a crate library called gxi_hako, which had incomplete implementations of the raw and utilities parts and has now been temporarily abandoned;

The new version, also known as gxci, includes the implementation of three parts: raw, HAL, and utilities;

As of 23:45 on July 11, 2024, the HAL library for the 'features=["solo"]' section has been completed, but the multi camera features have not been implemented yet. i'll update it when i have more free time (๑˃ᴗ˂)ﻭ.

Overview

You can get the sdk-dev-doc from the SDK of Daheng Imaging you have installed.

Quick Start

1. Ensure you have OpenCV Rust Bindings installed,
2. Ensure your camera version is supported by the GxIAPI SDK,and ensure you have installed the GxIAPI SDK.

the document of the environment config is follow the quick start part.

in your Cargo.toml, add the following dependencies:

[dependencies]
gxci = {version="0.1.0", features=["solo"]}

(because the 0.1.0 version has no images in Readme.md assets, it will be more lightwieght lol~)

then, you can use the following code to get a single image from the camera and save it as png.

use gxci::hal::device::*;
use gxci::hal::basement::*;
use gxci::utils::debug::print_device_info;

fn main() {
    let dll_path = "C:\\Program Files\\Daheng Imaging\\GalaxySDK\\APIDll\\Win64\\GxIAPI.dll"; // the default path of the GxIAPI.dll
    gxci_init(dll_path);

    let mut device_num = gxi_count_devices( 1000);
    println!("Device number: {}", device_num.unwrap());

    let base_info = gxi_list_devices().unwrap();
    for device in &base_info {
        print_device_info(&device);
    }
    
    gxi_open_device();

    gxi_get_image();
    
    gxi_save_image_as_png("test.png");

    gxi_close_device();

    gxci_close();
}

The terminal output should be like this:

    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.84s
     Running `target\debug\examples\hal_get_image.exe`
Device number: 1
p_device_info: 0x1ad375f3cd0, p_buffer_size: 0xaa9f0ff8d8
Vendor Name: Daheng Imaging
Model Name: MER-132-43U3M
Serial Number: FS0170060031
Display Name: MER-132-43U3M(FS0170060031)
Device ID: MER-132-43U3M(FS0170060031)
User ID:
Access Status: GX_ACCESS_STATUS_UNKNOWN
Device Class: GX_DEVICE_CLASS_U3V
-----------------------
Device handle: Some(0x1ad3738f3e0)
Successfully opened device index 1
Successfully sent command
int_value: 0xaa9f0ff250
int_value: 0xaa9f0ff258
enum_value: 0xaa9f0ff270
enum_value: 0xaa9f0ff260
int_value: 0xaa9f0ff268
p_frame_data: 0xaa9f0ff6f8
frame_data: GX_FRAME_DATA { nStatus: 0, pImgBuf: 0x1ad39635040, nWidth: 1292, nHeight: 964, nPixelFormat: 17301505, nImgSize: 9963904, nFrameID: 0, nTimestamp: 0, reserved: [17301505] }
Frame data: GX_FRAME_DATA { nStatus: 0, pImgBuf: 0x1ad39635040, nWidth: 1292, nHeight: 964, nPixelFormat: 17301505, nImgSize: 1245488, nFrameID: 0, nTimestamp: 61947717921575, reserved: [17301505] }
Successfully sent command
Successfully got image
Image saved successfully.
Device handle: Some(0x0)
Successfully closed device

if your camera is as the following:

then you will get a test.png as

more codes just see the examples.

Example

Here 5 raw-examples and 3 hal-example are provided, they are:

• raw-examples
  • raw_open_device_by_index
  • raw_open_device_by_sn
  • raw_list_device_info
  • raw_get_image
  • raw_capture_callback
• hal-examples
  • hal_list_device_info
  • hal_get_image
  • hal_capture_callback

you can run them like:

cargo run --example hal_list_device_info

Dependencies

OpenCV Environment

The OpenCV lib here is used to easily matlization the image and provide a GUI to show the image.

Anyway I think OpenCV is exactly a necessary lib in image processing region.

But the shortcoming is that the OpenCV is a little bit heavy, I'm trying to find a lighter lib to replace it in a feature like no-opencv. But it's also need time.

(Now the newest OpenCV is 4.10.0, but I haven't try it yet. So here is a 4.9.0 tutorial)

Install LLVM and OpenCV 4.9.0

In Windows 10/11, I would like using choco as the following command to install LLVM and OpenCV 4.9.0:

choco install llvm opencv

Following are the websites:

• LLVM
• OpenCV
• choco

Add the path environment variable

You can add the following path to the path environment variable:

• opencv bin path ...\opencv\build\bin
• opencv x64 bin path ...\opencv\build\x64\vc16\bin
• choco bin path C:\ProgramData\chocolatey\bin
• LLVM bin path C:\Program Files\LLVM\bin

Here is an example:

D:\ProgramUnsigned\Embedded\opencv\build\bin 
D:\ProgramUnsigned\Embedded\opencv\build\x64\vc16\bin
C:\ProgramData\chocolatey\bin
C:\Program Files\LLVM\bin

Add opencv environment variable(System Variable)

OPENCV_INCLUDE_PATHS ...\opencv\build\include OPENCV_LINK_LIBS opencv_world490 OPENCV_LINK_PATHS ...\opencv\build\x64\vc16\lib

here is an example:

OPENCV_INCLUDE_PATHS D:\ProgramUnsigned\Embedded\opencv\build\include
OPENCV_LINK_LIBS opencv_world490
OPENCV_LINK_PATHS D:\ProgramUnsigned\Embedded\opencv\build\x64\vc16\lib

Copy opencv_world490.dll to the target directory (if needed)

Sometimes, you need to copy the opencv_world490.dll to the target directory, which is the same as the exe file.

GxIAPI Environment

You also need to install the GxIAPI SDK, which can be downloaded from the official website.

Just install the SDK for your platform.

Camera Environment

You need to connect the camera to your computer's USB, and make sure the camera is powered on.

Then all the environment is ready.

Camera Support

• USB3.0 Camera
  • Mer Camera (Mono8, Mono10)
• Gige Camera

Platform Support

Now, is Windows only.

Licensing

Licensed under the MIT License.

Contributing

Uhmmm... placeholder，I think i will do this solo in a part of time.

if you have some problem,just issue it.

other ways you can contact me by email: zoneherobrine@gmail.com;

or by Tencent QQ: 2212540603 (with related information in the friend request)

Acknowledgments

GXCI(GalaXy Camera Interface)的命名要感谢MoonWX同学的建议，这是一个简洁明确并且很帅的名字ヽ(・∀・)ﾉ；

同时也感谢同专业李同学的帮助，在gx_enum的冗长的类型转换中，他与我协力在十分钟之内完成了C枚举到Rust枚举的转换(￣ω￣)；

同时也感谢OpenAI的GPT模型DELTA·E绘制的炫酷LOGO :D

he naming of GXCI (GalaXy Camera Interface) is thanks to MoonWX's suggestion, which is a concise, clear, and handsome nameヽ(・∀・)ﾉ;

Also, I would like to express my gratitude to fellow student Li for his assistance in the lengthy type conversion process at gx-enum. Together with me, we were able to complete the conversion from the C enum to the Rust enum within ten minutes(￣ω￣);

Also again, I would like to thank OpenAI's GPT model DELTA · E for creating a cool logo :D

Todolist

• The feature of multi camera
• The feature of no-opencv
• 补全网络相机(Gige)相关的函数

HAL Functions implemented status

• basement
  • gxi_check()
  • gxci_init()
  • gxci_close()
• device
  • gxi_count_devices()
  • gxi_list_devices()
  • gxci_open_device() // solo feature
  • gxci_close_device() // solo feature
  • gxi_send_command() // solo feature
  • gxi_get_image() // solo feature
  • gxi_open_stream() // solo feature
  • gxi_open_stream_interval() // solo feature
  • gxi_close_stream() // solo feature
• config
  • todo!()
• event
  • todo!()
• network
  • todo!()

DLL RAW implemented status

• 302 0 0001C020 GXCloseDevice
• 101 1 0001BBC0 GXCloseLib
• 700 2 0001E9E0 GXExportConfigFile
• 707 3 0001EA50 GXExportConfigFileW ?在开发文档里面没介绍这个函数
• 602 4 0001E920 GXFlushEvent
• 505 5 0001E6E0 GXFlushQueue
• 201 6 0001BDE0 GXGetAllDeviceBaseInfo
• 414 7 0001D5F0 GXGetBool
• 419 8 0001E080 GXGetBuffer
• 418 9 0001DF50 GXGetBufferLength
• 205 A 0001BE80 GXGetDeviceIPInfo
• 423 B 0001C0B0 GXGetDevicePersistentIpAddress
• 411 C 0001D3C0 GXGetEnum
• 410 D 0001CF50 GXGetEnumDescription
• 409 E 0001CE20 GXGetEnumEntryNums
• 506 F 0001E970 GXGetEventNumInQueue
• 422 10 0001C1E0 GXGetFeatureName
• 408 11 0001CCF0 GXGetFloat
• 406 12 0001C960 GXGetFloatRange
• 504 13 0001E670 GXGetImage
• 404 14 0001C730 GXGetInt
• 403 15 0001C590 GXGetIntRange
• 204 16 0001BC40 GXGetLastError
• 709 17 0001F370 GXGetOptimalPacketSize (Windows Only)
• 416 18 0001DAA0 GXGetString
• 415 19 0001D820 GXGetStringLength
• 425 1A 0001D970 GXGetStringMaxLength
• 705 1B 0001EEF0 GXGigEForceIp
• 704 1C 0001ECC0 GXGigEIpConfiguration
• 706 1D 0001F170 GXGigEResetDevice
• 701 1E 0001EAC0 GXImportConfigFile
• 708 1F 0001EB40 GXImportConfigFileW ?在开发文档里面没介绍这个函数
• 100 20 0001BB70 GXInitLib
• 400 21 0001C260 GXIsImplemented
• 401 22 0001C370 GXIsReadable
• 402 23 0001C480 GXIsWritable
• 301 24 0001BFB0 GXOpenDevice
• 300 25 0001BF10 GXOpenDeviceByIndex
• 702 26 0001EBC0 GXReadRemoteDevicePort
• 710 27 0001F3E0 GXReadRemoteDevicePortStacked
• 500 28 0001E5B0 GXRegisterCaptureCallback
• 600 29 0001E730 GXRegisterDeviceOfflineCallback
• 603 2A 0001E820 GXRegisterFeatureCallback
• 421 2B 0001E480 GXSendCommand
• 507 2C 0001F100 GXSetAcqusitionBufferNumber
• 413 2D 0001D720 GXSetBool
• 420 2E 0001E350 GXSetBuffer
• 424 2F 0001C160 GXSetDevicePersistentIpAddress
• 412 30 0001D4F0 GXSetEnum
• 407 31 0001CBE0 GXSetFloat
• 405 32 0001C860 GXSetInt
• 417 33 0001DDC0 GXSetString
• 501 34 0001E620 GXUnregisterCaptureCallback
• 601 35 0001E7B0 GXUnregisterDeviceOfflineCallback
• 604 36 0001E8B0 GXUnregisterFeatureCallback
• 206 37 0001BD70 GXUpdateAllDeviceList
• 200 38 0001BD00 GXUpdateDeviceList
• 703 39 0001EC40 GXWriteRemoteDevicePort
• 711 3A 0001F450 GXWriteRemoteDevicePortStacked (Windows Only)