iamsierracharlie/contrastech_python_api_for_linux_and_windows

A working version of a Python API for Contrastech MARS model USB 3.0 Industrial Cameras which use the GeniCam standard.

ContrasTech_Python_API_for_Linux_And_Windows

Operating Systems - Windows 10, Linux (Ubuntu 20.04 and 20.10) nb: this is for Python 3.x

Architecture - X86 or Arm (Raspberry Pi 4 Tested and working)

What this is

A working version of a python API for ContrasTech MARS model USB3 Industrial cameras. This camera doesn't use the standard openCV method of grabbing an image. It conforms to the GeniCam standard (See https://www.emva.org/standards-technology/genicam/genicam-downloads/) I own a couple of ContrasTech MARS cameras http://www.contrastech.com/en/product/004000007001.html#sx and have had to use 3rd party APIs to get Windows functionality for these cameras in Python. Let me be the first to say that the one I have used has been very good for what I need, but other than Aravis, I have not been able to find anything that works for Linux for Python that allows grabbing of images in a numpy nd.array style image grab; at least not for this camera under Linux. ContrasTech was good enough to provide an example of some code that grabbed images and saved them as a BMP and I have gone from there to produce this code. This code I have written is pretty basic, but allows grabbing of a numpy nd.array style image. It should be noted that I have fumbled my way to this point to get some working code - I do not profess to be an expert. My reason for adding this repo is in the hope that some that others may be able to benefit from it as well as contribute to a better version of the code. This API uses c_types to interface with the dll which is provided by ContrasTech. I have very limited experience with c_types in Python, but this seems to work just fine - NOW IN BOTH WINDOWS AND LINUX!!!

Why use it??

The main reason is ease of use; if you have little understanding of c_types AND want to use your ContrasTech camera in Linux, then this API makes it easier to set up your USB3 Industrial camera. Getting and setting parameter values is very easy also.

Known working cameras

Tested and confirmed on the following Industrial USB3 Camera

• Mars1300-210uc
• Mars800-545um Any other Mars USB3 camera from ContrasTech should work also.

With some minor adjustments, you could probably use this for a GIG-E camera also.

If you own one of these cameras and work in Linux and can use this code, then please do so. Also, please contribute anything you feel to be of benefit.

MultiCamera Use Status

I have tested with multiple cameras using GrabDemoMultiCam.py and multicamsApi.py. I can confirm it works, but it not thoroughly tested as I do not have a use for multiple cameras at this point in time. I've tested with 2 cameras of the same type. (Mars1300-210uc)

Example use

The script 'ImageGrabDemo.py' is provided as an example to show the code working - again, very basic. Essentially, I have historically created an instance of the camera, activated the camera, grabbed an image and then deactivated it ContrasTech provided a very basic demo, and I have only used that demo to make what is provided. This code has been set up to run on a 64bit system, but you could change to 32bit with minimal effort (out of my scope)

Prerequisites

• An installation of Python on a Linux Operating System (I used Anaconda with Python 3.6 on Ubuntu) As of 2022, I am using Ubuntu 20.04 and whilst not officially supported by ContrasTech, it works without issue.
• Python Modules -> c_types, opencv2, numpy
• The ContrasTech Software Development Kit for Linux (x86) (aka iCentral) - this includes the driver required to run the camera in Linux and can be found at http://www.contrastech.com/upload/down/Mars/Linux/iCentral_Ver2.2.6_Linux_x86_Build20210705.zip or for Windows http://www.contrastech.com/upload/down/Mars/Win/iCentral_2.2.6_EN.zip
• An x86 computer 32bit or 64bit. Windows or Linux.
• Raspberry Pi - http://www.contrastech.com/en/service/005001.html as of Feb 2022, Raspberry Pi 4 is known to be working. I tested it and even though there are errors during the installation, this software still works. When I did the install of iCentral, I installed build-essential as well as linux-modules-extra-raspi. After running the iCentral.run file, as root, I did see errors complaining about missing .ko files, but running the demo worked. Need to understand that a little better but it is fundamentally working.

Getting this API to work

Review and/or run ImageGrabDemo.py with a ContrasTech USB3 Camera such as the Mars 1300-201uc, and it should work. There are examples on how to send commands to the camera. It is recommended you review the ContrasTech SDK for commands that work; as well as the iCentral program supplied by ContrasTech. Another useful place is the XML file stored on the camera (every camera keeps a file on it that provides its functionality). Review the ImageGrabDemo.py file and the XML file in conjunction. You can set properties or get property values by first creating a camera instance and then calling the 'property_getset' command. Where the second argument is populated, the function will attempt to set a value for the property in question. If you call 'property_getset' without a value, then it will get the stored value. This API DOES work in Windows AND I've tested it; although there are a few little buggy issues that need work.

Known Issues

• For Linux, the software and driver from ContrasTech is confirmed to work up to Ubuntu 20.04. On October 2020, I checked with ContrasTech support. Their feedback is that they only supported up to 16.04, but I currently run on 20.04 (as of Feb 2022) and haven't noticed any issues.
• Works in Windows; although I've found on occasion that the API fails to get the software trigger to go. As a result, image grab fails. The workaround seems to be to close your IDE and try again or restart. I will provide a fix when I confirm the issue and have some more time.
• Linux - Program may stop working when the Kernel is updated. You need to reinstall the driver to the current kernel for it to work properly. A giveaway for this issue is that the program may complain that it is unable to load the driver.
  The fix is to reinstall iCentral which will compile the module and install again.
• my code writing is crap - yes I know. I cannot commit the time I want to for these things, but I'm working on it.
  Constructive criticisms is always appreciated...

Feedback

If you own this camera or use this API, please provide feedback. If you want to collaborate on this or your own work, I'm happy to offer a hand. I admit I am no expert, but am always keen on seeing the development of an API for this camera as there is not a huge amount of info out there for this.

Future plans

• my reason for this code was that I took high speed images on a production line for quality checks using Tensorflow. I ran this in Windows for the most part due to this driver issue. I did have success in getting my program to work in Linux, although I never put it into production. I plan to make some changes to this code so that the camera will accept a signal from an external sensor to time the image grabs as opposed to just grabbing an image every N seconds. Timing is everything on a production line! If you are doing something similar, I'd be keen to hear about it!
• I am hoping to develop high level and low level functions. I'm finding that certain commands need to be run in a certain order to work properly. High level functions will assemble low level functions in the correct order and offer better error handling for users. Examples of this could be setting the image dimensions. High level commands could check for validity before applying them and return a failure if the dimensions were not within correct parameters.....

Working Example

Here is my dog Pip

contrastech_python_api_for_linux_and_windows's Issues

Multiple camera connection Failed

Hi, When i am trying to access frames from multiple(3) Mars-usb3 vision cams, the program fails and only be able to capture frame from ONLY one of the Cam.
** Even in the camsAPI you have mentioned "Multiple cameras - Ive not encountered this in my setup"
Can you give me any reference or guide me where to look for or where to do code change, so that i can access frames from multiple cameras.

General questions about project

Hello,

First of all I would like to thank You for providing this solution to the community!

As I am trying to acquire images from contrastech camera I found Your solution and would very much like to try it out, I just have a couple of questions if You would be so kind to answer.

1. Is Ubuntu version 16.04 necessary or would it be possible to run it on Ubuntu version 18.04?

2. Do I need to install anything, like drivers from contrastech and such, or I can just download You project and run it?

3. Is there a way to test whether the program works on my machine without having the camera plugged in?

4. Can I use the latest version of openCV, namely 4.x.x instead of version 2.x.x because version 2.x.x cannot be installed via pip anymore?

5. When trying to run image_grab_demo.py without the camera connected I get the following error (as my camera has not yet arrived I have no way of testing with the camera plugged in)
   Traceback_ (most recent call last):
   File__ "/home/Contrastech_Python_SDK_for_Linux-master/image_grab_demo.py", line 2, in _
   import linux_cams_sdk
   File "/home/Contrastech_Python_SDK_for_Linux-master/linux_cams_sdk.py", line 2, in
   from MVSDK import * # only for the contrastech camera
   File "/home/Contrastech_Python_SDK_for_Linux-master/MVSDK.py", line 18, in
   MVSDKdll = cdll.LoadLibrary("./dll/x64/libMVSDK.so")
   File "/usr/lib/python3.6/ctypes/init.py", line 426, in LoadLibrary
   return self._dlltype(name)
   File "/usr/lib/python3.6/ctypes/init.py", line 348, in init
   self._handle = _dlopen(self._name, mode)
   OSError: libGCBase_gcc421_v3_0.so: cannot open shared object file: No such file or directory

Process finished with exit code 1

I have installed ctypes as following pip3 install ctypes-callable

Thanks in advance,
Marko

General questions

Hi there,

I've been playing around with this and have found it to be very helpful with our Contrastech line scan cameras. Apologies if this is not the right forum to ask, but would you be interested in a contract gig? I haven't been able to find contact information.

Principals around camera commands

As I've spent more time getting various commmands to work, I've come to realise that some commands require others to be run first. For example, you cannot perform a reset of the camera when it is capturing frames. You would need to stop the capturing first. This will be a list of all the things I've found in my investigation thus far. Some of these things may appear obvious, but are helpful for people who are just starting out working in this.

Contrastech Mars2000_150u camera getting weird images/frames

Hi, first of all Thank you a lot for such a help. Now i am able to use this both on ubuntu and windows.
But the issue i am facing is, I am getting weird frames, not the actual images.
Can you please guide me on 'what specific camera property should i manipulate to get the actual images'.
I have tried Exposure, brightness. Etc, those are working well.

Windows - software trigger fails

SoftTrigger getFrame fail! timeOut [1000]ms

Traceback (most recent call last):
  File "C:\Users\steve\PycharmProjects\Contrastech_Python_API_for_Linux\ImageGrabDemo.py", line 56, in <module>
    image = camera.grab_image()
  File "C:\Users\steve\PycharmProjects\Contrastech_Python_API_for_Linux\linuxCamsApi.py", line 359, in grab_image
    self.image_source.contents.release(self.image_source)
OSError: exception: access violation reading 0xFFFFFFFFFFFFFFFF

Fur investigation when I get some spare time

Windows_error

Hey IamSierraCharlie,
Thanks for your great work!!!
I also own a contrastech mars800-545um and want to make it work on windows.
I tried your code but I have no experience with ctypes.
As you mentioned i run in the same error to get the software trigger to go.
'''SoftTrigger getFrame fail! timeOut [1000]ms -> -1
Not catastrophic so continuing
You should only see this at the start of image grabbing
OSError: exception: access violation reading 0x0000023D01959FF0'''
I am trying to get familiar with cytpes and will also continue with youre work....

General questions about the repo

Stumbled on this repo through fortuitous Googling, thanks so much for putting this together!

I had a couple follow-up questions as I'm figuring out how best to use the Contrastech camera I have.

1. Did you ever try to get the camera working on a Raspberry Pi? They're support said it should work as long as the Pi is 64-bit Linux
2. In the Readme you mentioned third party APIs that worked with the camera on Windows - which were you using? I was playing around with Harvester and the MATRIX VISION GenTL producer but had no luck getting it working. The camera is picked up but isn't able to be controlled.

Thanks again!

• Joe

How to capture the Live feed from mars2000 150u area scan cams in WINDOWS.

Hi,
I have a very similar scenario like you had explained. And as you mentioned that, you had already got success with Windows machine by help of some 3rd party tools.
I am curious to know which 3rd party tool you have used and how you connected to it and were you able to get the LIVE video stream captured at the programming end(python script).
Do you have any suggestion where to look for the resource (python related solution or example). Thanks.