Python scripting in CamTool¶

CamTool lets you write custom Python scripts to control the camera, process acquired images and visualize results.
Inside a script you can also use common Python libraries such as NumPy, pandas and Plotly.

Python scripting in CamTool

Running a Python script¶

To run a Python script, go to Plugins -> Script Editor... and select Python.

The camtool module and the xiAPI keywords for parameter names and values (for example XI_PRM_IMAGE_DATA_FORMAT, XI_MONO8) are available in the script without an explicit import.

The Python interface is similar to the Lua interface, written in Python style (for example app.WaitForNextFrame in Lua is camtool.wait_for_next_frame in Python).

Requirements¶

CamTool does not include its own Python. It uses the Python installed on your computer, so the Python DLL must be on the system PATH for the script plugin to load. Python 3.12 or newer is required.

External packages are imported with the usual import statement and must be installed in that Python, for example:

pip install numpy pandas plotly

Tested packages: NumPy, pandas, Plotly.

Basic objects and functions¶

The examples below use the following objects and functions:

Object / function	Description
`camtool.Camera()`	Creates a camera object.
`cam.open_device(index)`	Opens the camera with the given index (`0` = first connected camera).
`cam.set_exposure(us)`	Sets the exposure time in microseconds (`100000` = 100 ms).
`cam.set_param(param, value)`	Sets any xiAPI parameter, e.g. `cam.set_param(XI_PRM_IMAGE_DATA_FORMAT, XI_MONO8)`.
`cam.start_acquisition()`	Starts image acquisition and shows it in a view. Returns the view ID.
`cam.stop_acquisition()`	Stops image acquisition.
`camtool.wait_for_next_frame(timeout, view_id)`	Waits for the next frame in the given view.
`camtool.get_view_image(view_id)`	Returns the current image from the given view.
`img.measure_rect()`	Returns image statistics, e.g. `stats[0]['mean']` is the mean value.
`np.array(img)`	Converts a CamTool image to a NumPy array. NumPy functions also accept the image directly, e.g. `np.mean(img)`.
`camtool.Graph()`	Creates a new graph.
`gr.add_series()`	Adds a data series to the graph. Returns the series index.
`gr.series_add_point(series, x, y)`	Adds a point to a data series.
`gr.draw_into_image(img)`	Draws the graph into an image.
`camtool.Image()` / `img.alloc(width, height, channels, bits)`	Creates a new image and allocates its buffer, e.g. `alloc(400, 300, 3, 8)` for a 400x300 RGB 8-bit image.
`camtool.new_view_with_image(img, title)`	Shows the image in a new view with the given title.

Example scripts¶

Mean grey value graph¶

This script captures 10 images, calculates the mean grey value of each image and draws the values into a graph. The graph is shown in a new view in CamTool.

cam = camtool.Camera()
cam.open_device(0)        # open 1st connected camera
cam.set_exposure(100000)  # set exposure to 100ms
cam.set_param(XI_PRM_IMAGE_DATA_FORMAT, XI_MONO8)  # set any xiAPI parameter

view_id = cam.start_acquisition()

gr = camtool.Graph()      # new graph
gr_idx = gr.add_series()  # new data series in the graph

# capture 10 images
for i in range(10):
    camtool.wait_for_next_frame(1000, view_id)
    img = camtool.get_view_image(view_id)
    stats = img.measure_rect()
    #print(stats)
    mean = stats[0]['mean']
    gr.series_add_point(gr_idx, i+1, mean)

cam.stop_acquisition()

# draw graph into RGB image with 400x300 dimensions
img_graph = camtool.Image()
img_graph.alloc(400, 300, 3, 8)
gr.draw_into_image(img_graph)

camtool.new_view_with_image(img_graph, 'Mean Graph')

Mean grey value with NumPy¶

The same as the previous script, but the mean value is calculated with NumPy.

import numpy as np

cam = camtool.Camera()
cam.open_device(0)        # open 1st connected camera
cam.set_exposure(100000)  # set exposure to 100ms
cam.set_param(XI_PRM_IMAGE_DATA_FORMAT, XI_MONO8)  # set any xiAPI parameter

view_id = cam.start_acquisition()

gr = camtool.Graph()      # new graph
gr_idx = gr.add_series()  # new data series in the graph

# capture 10 images
for i in range(10):
    camtool.wait_for_next_frame(1000, view_id)
    img = camtool.get_view_image(view_id)

    np_img = np.array(img)
    mean = np.mean(np_img)

    # can also be written without explicit conversion to np.array
    #mean = np.mean(img)

    gr.series_add_point(gr_idx, i+1, mean)

cam.stop_acquisition()

# draw graph into RGB image with 400x300 dimensions
img_graph = camtool.Image()
img_graph.alloc(400, 300, 3, 8)
gr.draw_into_image(img_graph)

camtool.new_view_with_image(img_graph, 'Mean Graph')

Mean grey value with pandas and Plotly¶

The same measurement, but the values are stored in a pandas DataFrame and the graph is drawn with Plotly.

import numpy as np
import plotly.express as px
import pandas as pd

cam = camtool.Camera()
cam.open_device(0)        # open 1st connected camera
cam.set_exposure(100000)  # set exposure to 100ms
cam.set_param(XI_PRM_IMAGE_DATA_FORMAT, XI_MONO8)  # set any xiAPI parameter

view_id = cam.start_acquisition()

# this list will contain mean grey values for each image
values = list()

# capture 10 images
for i in range(10):
    camtool.wait_for_next_frame(1000, view_id)
    values.append(np.mean(camtool.get_view_image(view_id)))

cam.stop_acquisition()

df = pd.DataFrame(dict(
    frame_no = range(1, 11),
    mean_value = values
))
#print(df)

fig = px.line(df, x="frame_no", y="mean_value", title="Mean values from 10 frames")
fig.show()

ximea