First Steps

Importing tisgrabber dll

Python ctypes is used for importing DLLs into a Python script. For use of tisgrabber some basic lines of code must be done in any project:

import ctypes

ic = ctypes.cdll.LoadLibrary("./tisgrabber_x64.dll")

Many functions of the tisgrabber.dll have “complex” parameters and and return values. Therefore, these functions must be declared. This is done in the file tisgrabber.py. This tisgrabber.py must be imported:

import tisgrabber as tis

The declaration of the functions is done by a call to

tis.declareFunctions(ic)

Thus, a Python script that uses the tisgrabber.dll needs always following lines at the start:

import ctypes
import tisgrabber as tis

ic = ctypes.cdll.LoadLibrary("./tisgrabber_x64.dll")
tis.declareFunctions(ic)

ic.InitLibrary(0)

The next line, which is always necessary is the ic.InitLibrary(0) call.

All functions of the tisgrabber.dll are now in the “ic” namespace.

HGRABBER

The class HGRABBER mirrors a structure of tisgrabber dll, which contains a pointer to the internal grabber object. The grabber object communicates with the camera. This object is passed as pointer to all functions of the DLL, so the functions know, which camera to communicate with. It is defined in the tisgrabber.py as follows:

class HGRABBER(ctypes.Structure):
   '''
   This class is used to handle the pointer to the internal
   Grabber class, which contains the camera.
   A pointer to this class is used by tisgrabber DLL.
   '''
   _fields_ = [('unused', ctypes.c_int)]

For each camera to be used in the Python script an own HGRABBER object must be created.

Strings

The tisgrabber dll handles strings as simple char* only. If a Python string is passed to any function, it must be encoded as utf-8. For example:

hello = "Hello World"
ic.IC_MsgBox( hello.encode("utf-8"),"Greeting".encode("utf-8"))

For convenience the tisgrabber.py contains the function “T” for encode and “D” for encode:

hello = "Hello World"
ic.IC_MsgBox( tis.t(hello),tis.T("Greeting"))

Simple Live Video

Code : 01-Live.py

The first sample is the 01-Live.py. It shows how to select a video capture device with the built in device selection dialog and how to start and stop the live stream.

hGrabber = ic.IC_ShowDeviceSelectionDialog(None)

The IC_ShowDeviceSelectionDialog() shows a device selection dialog. It returns a grabber object handle, therefore the C like name hGrabber

IC_IsDevValid checks, whether the passed hGrabber handle uses a valid video capture device. If so, we can start and stop the live video stream:

if( ic.IC_IsDevValid(hGrabber)):
   ic.IC_StartLive(hGrabber,1)
   ic.IC_MsgBox(tis.T("Click OK to stop"), tis.T("Simple Live Video"))

   ic.IC_StopLive(hGrabber)
else:
   ic.IC_MsgBox(tis.T("No device opened"), tis.T("Simple Live Video"))

All programs should release the hGrabber handle in order to clean up memory. Thus, this is the last line of the sample:

ic.IC_ReleaseGrabber(hGrabber)