Thor camera interface

The client Thor camera interface. It runs thorcam.camera_dot_net as a separate process and sends and receives from it all camera requests, such as configuration and images.

ThorCam provides the basic implementation for interacting with the camera. ThorCam provides a example implementation using ThorCam that interacts with the camera.

If the Thor .NET dlls are not provided in their default path, or to overwrite them with a different version, see ThorCamClient.thor_bin_path.

exception thorcam.camera.EndConnection

Bases: Exception

Class that represents connection exceptions raised by thorcam package.

class thorcam.camera.ThorCam

Bases: ThorCamClient

A example implementation of ThorCamClient that handles the messages and provides user friendly methods to interact with the camera.

cam_open = False

After requesting that a camera be opened/closed, when the server responds that it is open/closed in received_camera_response() this is set here.

cam_playing = False

After requesting that a camera start/stop playing, when the server responds that it is/is not playing in received_camera_response() this is set here.

close_camera()

Requests that the camera be closed.

got_image(image, count, queued_count, t)

Called when we get an image from the server.

Parameters

• image – The image object

• count – The frame number starting from 0 as given by the camera.

• queued_count – How many more frames are on the hardware queue.

• t – The frame timestamp.

handle_exception(e, exc_info)

Called by the client thread when an exception happens in the server or client.

Parameters

• e – The error.

• exc_info – The exc_info represented as a string.

open_camera(serial)

Requests that the camera be opened.

Parameters

serial – The camera’s serial number string.

play_camera()

Requests that the camera start playing frames.

received_camera_response(msg, value)

Called by the client thread to handle a message received from the server. Subclass should overwrite this to handle the messages.

Parameters

• msg – A string with the message name

• value – The message content.

refresh_cameras()

Requests that we be sent the list of attached cameras (their serial numbers).

serials = []

After requesting the list of available camera serials, it is stored here upon the server response in received_camera_response().

set_setting(name, value)

Requests that the setting should be changed for the camera.

Parameters

• name – The setting name to be changed. E.g. "exposure_ms".

• value – The new setting value.

stop_playing_camera()

Requests that the camera stop playing frames.

class thorcam.camera.ThorCamBase

Bases: object

Base class with all the config options that the scientific Thor cams may support.

binning_x = 0

The x binning value to use.

binning_x_range = [0, 0]

The supported exposure range.

binning_y = 0

The y binning value to use.

binning_y_range = [0, 0]

The supported exposure range.

black_level = 0

The black level value to use.

black_level_range = [0, 100]

The supported exposure range.

color_gain = [1, 1, 1]

The color gain for each red, green, and blue channel.

exposure_ms = 5

The exposure value in ms to use.

exposure_range = [0, 100]

The supported exposure range in ms.

frame_queue_size = 1

The max number of image frames to be allowed on the camera’s hardware queue. Once exceeded, the frames are dropped.

freq = '20 MHz'

The frequency to use.

gain = 0

The gain value to use.

gain_range = [0, 100]

The supported exposure range.

num_queued_frames = 0

The number of image frames currently on the camera’s hardware queue.

play_settings = ['exposure_ms', 'gain', 'black_level', 'color_gain']

All the settings that can be set while the camera is playing.

roi_height = 0

The height after the y start position of the ROI in pixels, to use.

roi_width = 0

The width after the x start position of the ROI in pixels, to use.

roi_x = 0

The x start position of the ROI in pixels.

roi_y = 0

The y start position of the ROI in pixels.

sensor_size = [0, 0]

The size of the sensor in pixels.

settings = ['exposure_ms', 'binning_x', 'binning_y', 'roi_x', 'roi_y', 'roi_width', 'roi_height', 'trigger_type', 'trigger_count', 'frame_queue_size', 'gain', 'black_level', 'freq', 'taps', 'color_gain']

All the possible settings that the camera may support.

supported_freqs = ['20 MHz']

The supported frequencies.

supported_taps = ['1']

The supported taps.

supported_triggers = ['SW Trigger', 'HW Trigger']

The trigger types supported by the camera.

supports_color = False

Whether the camera supports color.

taps = '1'

The tap to use.

trigger_count = 1

The number of frames to capture in response to the trigger.

trigger_type = 'SW Trigger'

The trigger type of the camera to use.

class thorcam.camera.ThorCamClient

Bases: ThorCamBase

The Thor camera client interface. This is the class to be used to control the camera.

cam_process()

The thread that runs the camera server process.

client_exited()

Called internally when the client thread exits.

client_run(to_server_queue)

The thread that runs the client connection to the server.

create_image_from_msg(msg_value)

Takes the value from the server that contains image data, constructs the image and returns it and its metadata.

It returns a 4-tuple of img, count, queued_count, t). Where img is the image. count is the image number as provided by the camera. queued_count is the number of frames the camera still has to process (i.e. need to be send from the hardware). t is the image timestamp.

decode_data(msg_buff, msg_len)

Decodes binary message from the server.

handle_exception(e, exc_info)

Called by the client thread when an exception happens in the server or client.

Parameters

• e – The error.

• exc_info – The exc_info represented as a string.

port = None

The server port to open in the internal server. When None, we find a not in use port.

process_connected = False

A bool that is True after start_cam_process() is called, only if we have started the second process that controls the camera and we have a connection to it.

process_connection_timeout = 10

How long to wait after starting the internal process, without being able to communicate with it before timing out.

process_exited(e=None, exc_info=None)

Called internally when the camera server process exits.

Parameters

• e – If provided, the error with which the process exited.

• exc_info – If provided, the stderr string of the process.

read_msg(sock, msg_len, msg_buff)

Reads data from the server and decodes it.

received_camera_response(msg, value)

Called by the client thread to handle a message received from the server. Subclass should overwrite this to handle the messages.

Parameters

• msg – A string with the message name

• value – The message content.

send_camera_request(msg, value=None)

Sends a request to the server and camera.

See thorcam.camera_dot_net.ThorCamServer for messages that the client may send to the server.

Parameters

• msg – The message name.

• value – The message value to be sent.

send_msg(sock, msg, value)

Sends message to the server.

server = 'localhost'

The server address to use to start the internal server.

start_cam_process()

Starts the server in its own process. This must be called before any camera operations can start.

stop_cam_process(join=False, kill_delay=None)

Requests that the server and client threads/process close. If join, we block here until the threads/process exit. If kill_delay is not None, then we join for that long and terminate the process afterwards if it’s not completed.

Returns True only if the process was terminated manually, otherwise it returns False.

thor_bin_path = ''

The full path to where the Thor .NET binaries are located.

We use this path to locate and load the .NET interface to the camera. This path must contain at least the following two dlls: Thorlabs.TSI.TLCamera.dll and Thorlabs.TSI.TLCameraInterfaces.dll.

It defaults to the path in thorcam.dep_bins because that’s where the python wheel stores the dlls.

timeout = 0.01

How long to wait wait on network requests, before checking the queues.

to_server_queue = None

The queue we use to send requests to the server.

thorcam.camera.connection_errors = (<class 'thorcam.camera.EndConnection'>, <class 'ConnectionAbortedError'>, <class 'ConnectionResetError'>)

Tuple of possible connections errors that may be raised, so we can catch all of them.

thorcam.camera.yaml_dumps(value)

Encodes the value using yaml and returns it as string.

thorcam.camera.yaml_loads(value)

Decodes the string representing a yaml value and returns the original objects.