PyAutoscoper

Overview

PyAutoscoper is a Python library for controlling Autoscoper via a TCP socket connection. It provides a simple interface for sending commands and receiving responses from Autoscoper.

Installation

Install the latest version of PyAutoscoper from PyPI using pip:

$ pip install pyautoscoper

Usage

Connecting to Autoscoper

The AutoscoperConnection class can be created with two optional arguments:

address: The IP address of the Autoscoper server. Default is 127.0.0.1 (localhost).
verbose: If True, the methods will print out information about the connection. Default is False.

Ensure that Autoscoper is running, the class will attempt to connect to Autoscoper upon instantiation. If the connection is successful, the is_connected method will return True.

Connecting to Autoscoper

from PyAutoscoper.connect import (
    AutoscoperConnection,
    CostFunction,
    OptimizationInitializationHeuristic,
    OptimizationMethod,
)

autoscoperSocket = AutoscoperConnection()
autoscoperSocket.is_connected()

Loading a trial

This example will load the trial configuration file trial_config.cfg and the filter settings file filter_settings.vie for both cameras.

The loadTrial method takes one argument:

trial_config: The path to the trial configuration file.

The loadFilter method takes two arguments:

camera: The camera number (0-indexed).
filter_file: The path to the filter settings file.

Loading a trial

trial_config = "path/to/trial_config.cfg"
autoscoperSocket.loadTrial(trial_config)
filter_settings = "path/to/filter_settings.vie"
for camera_i in range(NUM_CAMERAS):
    autoscoperSocket.loadFilters(camera_i, filter_settings)

Loading and Saving Tracking Data

This example will load the tracking data file tracking_data.tra and save it as tracking_data_out.tra.

Note

A trial must be loaded before loading tracking data.

The loadTrackingData method takes at least two arguments:

volume: The volume index (0-indexed).
tracking_data: The path to the tracking data file.
is_matrix: If True, the tracking data will be loaded as a 4 by 4 matrix. If False, the tracking data will be loaded in xyz roll pitch yaw format. Defaults to True.
is_rows: If True, the tracking data will be loaded as rows. If False, the tracking data will be loaded as columns. Defaults to True.
is_with_commas: If True, the tracking data will be loaded with commas. If False, the tracking data will be loaded with spaces. Defaults to True.
is_cm: If True, the tracking data will be loaded in cm. If False, the tracking data will be loaded in mm. Defaults to False.
is_rad: If True, the tracking data will be loaded in radians. If False, the tracking data will be loaded in degrees. Defaults to False.
interpolate: If True, the tracking data will be interpolated with the spline method. If False, the tracking data will not be interpolated (NaN values). Defaults to False.

The saveTrackingData method takes at least two arguments:

volume: The volume index (0-indexed).
tracking_data: The path to the tracking data file.
save_as_matrix: If True, the tracking data will be saved as a 4 by 4 matrix. If False, the tracking data will be saved in xyz roll pitch yaw format. Defaults to True.
save_as_rows: If True, the tracking data will be saved as rows. If False, the tracking data will be saved as columns. Defaults to True.
save_with_commas: If True, the tracking data will be saved with commas. If False, the tracking data will be saved with spaces. Defaults to True.
convert_to_cm: If True, the tracking data will be saved in cm. If False, the tracking data will be saved in mm. Defaults to False.
convert_to_rad: If True, the tracking data will be saved in radians. If False, the tracking data will be saved in degrees. Defaults to False.
interpolate: If True, the tracking data will be interpolated with the spline method. If False, the tracking data will not be interpolated (NaN values). Defaults to False.

Loading and Saving Tracking Data

tracking_data = "path/to/tracking_data.tra"
tracking_data_out = "path/to/tracking_data_out.tra"
autoscoperSocket.loadTrackingData(0, tracking_data)
autoscoperSocket.saveTracking(0, tracking_data_out)

Changing the Current Frame and Pose

This example will change the pose on multiple frames.

Note

A trial must be loaded before changing the current frame and pose.

The setPose method takes three arguments:

volume: The volume index (0-indexed).
frame: The frame index (0-indexed).
pose: The pose of the volume in the form of an array of 6 floats. Array order is [x, y, z, roll, pitch, yaw].

The getPose method takes two arguments:

volume: The volume index (0-indexed).
frame: The frame index (0-indexed).

The setFrame method takes one argument:

frame: The frame index (0-indexed).

Changing the Current Frame and Pose

import random as rand

for frame in range(10):
    autoscoperSocket.setFrame(frame)
    current_pose = autoscoperSocket.getPose(0, frame)
    # Add a random number between -1 and 1 to each pose value
    new_pose = [current_pose[i] + rand.uniform(-1, 1) for i in range(6)]
    autoscoperSocket.setPose(0, frame, new_pose)

Optimizations

There are two methods for optimizing the tracking data:

optimizeFrame: Optimizes the tracking data for a single frame.
trackingDialog: Automatically optimizes the tracking data for all given frames.

The optimizeFrame method takes eleven arguments:

volume: The volume index (0-indexed).
frame: The frame index (0-indexed).
repeats: The number of times to repeat the optimization.
max_itr: The maximum number of iterations to run the optimization.
min_lim: The minimum limit for the PSO movement.
max_lim: The maximum limit for the PSO movement.
max_stall_itr: The maximum number of iterations to stall the optimization.
dframe: The amount of frames to skip backwards for the initial guess.
opt_method: The OptimizationMethod to use.
cf_model : The CostFunction to use for evaluating the optimization.
opt_init_heuristic: The OptimizationInitializationHeuristic.

New in version 2: The opt_init_heuristic parameter.

Optimizing a single frame

autoscoperSocket.optimizeFrame(
    volume=0,
    frame=0,
    repeats=1,
    max_itr=100,
    min_lim=-1.0,
    max_lim=1.0,
    max_stall_itr=10,
    dframe=1,
    opt_method=OptimizationMethod.PARTICLE_SWARM_OPTIMIZATION,
    cf_model=CostFunction.NORMALIZED_CROSS_CORRELATION,
    opt_init_heuristic=OptimizationInitializationHeuristic.PREVIOUS_FRAME,
)

The trackingDialog method takes at least three arguments:

volume: The volume index (0-indexed).
start_frame: The starting frame index (0-indexed).
end_frame: The ending frame index (0-indexed).
frame_skip: The number of frames to skip between each optimization. Defaults to 1.
repeats: The number of times to repeat the optimization. Defaults to 1.
max_itr: The maximum number of iterations to run the optimization. Defaults to 1000.
min_lim: The minimum limit for the PSO movement. Defaults to -3.0.
max_lim: The maximum limit for the PSO movement. Defaults to 3.0.
max_stall_itr: The maximum number of iterations to stall the optimization. Defaults to 25.
opt_method: The OptimizationMethod to use. Defaults to PARTICLE_SWARM_OPTIMIZATION.
cf_model : The CostFunction to use for evaluating the optimization. Defaults to NORMALIZED_CROSS_CORRELATION.
opt_init_heuristic: The OptimizationInitializationHeuristic. Default to PREVIOUS_FRAME.

New in version 2: The opt_init_heuristic parameter.

Optimizing multiple frames

autoscoperSocket.trackingDialog(volume=0, start_frame=0, end_frame=10)

Putting it all together

We can put all of the above examples together to create a script that will load a trial, load tracking data, optimize the tracking data, and save the tracking data.

Putting it all together

import random as rand

from PyAutoscoper.connect import (
    AutoscoperConnection,
    CostFunction,
    OptimizationInitializationHeuristic,
    OptimizationMethod,
)

# Create a socket connection to Autoscoper
autoscoperSocket = AutoscoperConnection()

# Load a trial
autoscoperSocket.loadTrial("path/to/trial.cfg")
# Load filters
autoscoperSocket.loadFilters(0, "path/to/filters.vie")
autoscoperSocket.loadFilters(1, "path/to/filters.vie")
# Load initial tracking data
for volume in range(3):
    autoscoperSocket.loadTrackingData(volume, f"path/to/tracking_data_volume_{volume}.tra")

NUM_FRAMES = 100
frame_skip = 1
for volume in range(3):
    for frame in range(0, NUM_FRAMES, frame_skip):
        autoscoperSocket.setFrame(frame)
        current_pose = autoscoperSocket.getPose(volume, frame)
        # Add a random number between -1 and 1 to each pose value
        new_pose = [current_pose[i] + rand.uniform(-1, 1) for i in range(6)]
        autoscoperSocket.setPose(volume, frame, new_pose)

        # Optimize tracking data
        autoscoperSocket.optimizeFrame(
            volume=volume,
            frame=frame,
            repeats=1,
            max_itr=100,
            min_lim=-1.0,
            max_lim=1.0,
            max_stall_itr=10,
            dframe=1,
            opt_method=OptimizationMethod.PARTICLE_SWARM_OPTIMIZATION,
            cf_model=CostFunction.NORMALIZED_CROSS_CORRELATION,
            opt_init_heuristic=OptimizationInitializationHeuristic.CURRENT_FRAME,
        )

    autoscoperSocket.saveTracking(volume, f"path/to/tracking_data_volume_{volume}_out.tra")

autoscoperSocket.closeConnection()

Launching Autoscoper from Python

It may be useful to launch Autoscoper from Python. This can be done by using the subprocess module.

Launching Autoscoper from Python

import os
import signal
import subprocess as sp

executable = "path/to/Autoscoper.exe"

# Launch Autoscoper
AutoscoperProcess = sp.Popen([executable])

# check if Autoscoper is running
if AutoscoperProcess.poll() is None:
    print("Autoscoper is running")
else:
    print("Autoscoper is not running")

# Kill Autoscoper
os.kill(AutoscoperProcess.pid, signal.SIGTERM)

# check if Autoscoper is running
if AutoscoperProcess.poll() is None:
    print("Autoscoper is running")
else:
    print("Autoscoper is not running")

Class Reference

class PyAutoscoper.connect.AutoscoperConnection(address: str = '127.0.0.1', verbose: bool = False)

Bases: object

closeConnection() → None

Close the connection to the server.

Raises: AutoscoperConnectionError – If the connection to the server is lost

getImageCropped(volume: int, camera: int, pose: list[float]) → list[float]

Get the cropped image of the volume at the specified pose.

Parameters

volume – The volume to get the image of
camera – The camera to get the image from
pose – The pose to get the image at

Returns

The cropped image of the volume at the specified pose

Raises

AutoscoperServerError – If the server fails to get the image
AutoscoperConnectionError – If the connection to the server is lost

getNCC(volume: int, pose: list[float]) → list[float]

Get the normalized cross correlation of the volume at the specified pose.

Parameters

volume – The volume to get the NCC of
pose – The pose to get the NCC at

Returns

The NCC of the volume at the specified pose

Raises

AutoscoperServerError – If the server fails to get the NCC
AutoscoperConnectionError – If the connection to the server is lost

getNumFrames() → int

Get the number of frames in the scene.

Returns

The number of frames in the scene

Raises

AutoscoperServerError – If the server fails to get the number of frames
AutoscoperConnectionError – If the connection to the server is lost

getNumVolumes() → int

Get the number of volumes in the scene.

Returns

The number of volumes in the scene

Raises

AutoscoperServerError – If the server fails to get the number of volumes
AutoscoperConnectionError – If the connection to the server is lost

getPose(volume: int, frame: int) → list[float]

Get the pose of the volume at the specified frame.

Parameters

volume – The volume to get the pose of
frame – The frame to get the pose at

Returns

The pose of the volume at the specified frame

Raises

AutoscoperServerError – If the server fails to get the pose
AutoscoperConnectionError – If the connection to the server is lost

property is_connected: bool: Returns the status of the connection to the PyAutoscoper server.

loadFilters(camera: int, settings_file: str) → None

Load filter settings into the PyAutoscoper server.

Parameters

camera – The camera to load the filter settings into
settings_file – The path to the filter settings to load

Raises

AutoscoperServerError – If the server fails to load the filter settings
AutoscoperConnectionError – If the connection to the server is lost

loadTrackingData(volume: int, tracking_data: str, is_matrix: bool = True, is_rows: bool = True, is_with_commas: bool = True, is_cm: bool = False, is_rad: bool = False, interpolate: bool = False) → None

Load tracking data into the PyAutoscoper server.

Parameters

volume – The volume to load the tracking data into
tracking_data – The path to the tracking data to load
is_matrix – Optional - If true, the tracking data will be loaded as a 4 by 4 matrix. If false, the tracking data will be loaded in xyz roll pitch yaw format. Defaults to true.
is_rows – Optional - If true, the tracking data will be loaded as rows. If false, the tracking data will be loaded as columns. Defaults to true.
is_with_commas – Optional - If true, the tracking data will be loaded with commas. If false, the tracking data will be loaded with spaces. Defaults to true.
is_cm – Optional - If true, the tracking data will be loaded in cm. If false, the tracking data will be loaded in mm. Defaults to false.
is_rad – Optional - If true, the tracking data will be loaded in radians. If false, the tracking data will be loaded in degrees. Defaults to false.
interpolate – Optional - If true, the tracking data will be interpolated using the spline method. If false, the tracking data will be saved as is (with NaN values). Defaults to false.

Raises

AutoscoperServerError – If the server fails to load the tracking data
AutoscoperConnectionError – If the connection to the server is lost

loadTrial(trial_file: str) → None

Load a trial file into the PyAutoscoper server.

Parameters

trial_file – The path to the trial file to load

Raises

AutoscoperServerError – If the server fails to load the trial file
AutoscoperConnectionError – If the connection to the server is lost

optimizeFrame(volume: int, frame: int, repeats: int, max_itr: int, min_lim: float, max_lim: float, max_stall_itr: int, dframe: int, opt_method: OptimizationMethod, cf_model: CostFunction, opt_init_heuristic: OptimizationInitializationHeuristic) → None

Optimize the pose of the volume at the specified frame.

Parameters

volume – The volume to optimize
frame – The frame to optimize
repeats – The number of times to repeat the optimization
max_itr – The maximum number of iterations to run
min_lim – The minimum limit of the optimization
max_lim – The maximum limit of the optimization
max_stall_itr – The maximum number of iterations to stall
dframe – The amount of frames to skip
opt_method – The optimization method to use.
cf_model – The cost function to use. NORMALIZED_CROSS_CORRELATION for Bone Models, SUM_OF_ABSOLUTE_DIFFERENCES for Implant Models.
opt_init_heuristic – The heuristic to initialize the optimization. See OptimizationInitializationHeuristic.

Raises

AutoscoperServerError – If the server fails to optimize the frame
AutoscoperConnectionError – If the connection to the server is lost
ValueError – If parameters accepting an enum value are incorrectly specified.

New in version 2: The opt_init_heuristic parameter.

saveFullDRR() → None

Save the full DRR.

Raises

AutoscoperServerError – If the server fails to save the full DRR
AutoscoperConnectionError – If the connection to the server is lost

saveTracking(volume: int, tracking_file: str, save_as_matrix: bool = True, save_as_rows: bool = True, save_with_commas: bool = True, convert_to_cm: bool = False, convert_to_rad: bool = False, interpolate: bool = False) → None

Save tracking data from the PyAutoscoper server.

Parameters

volume – The volume to save the tracking data from
tracking_file – The path to the tracking data to save
save_as_matrix – Optional - If true, the tracking data will be saved as a 4 by 4 matrix. If false, the tracking data will be saved in xyz roll pitch yaw format. Defaults to true.
save_as_rows – Optional - If true, the tracking data will be saved as rows. If false, the tracking data will be saved as columns. Defaults to true.
save_with_commas – Optional - If true, the tracking data will be saved with commas. If false, the tracking data will be saved with spaces. Defaults to true.
convert_to_cm – Optional - If true, the tracking data will be converted to cm. If false, the tracking data will be saved in mm. Defaults to false.
convert_to_rad – Optional - If true, the tracking data will be converted to radians. If false, the tracking data will be saved in degrees. Defaults to false.
interpolate – Optional - If true, the tracking data will be interpolated using the spline method. If false, the tracking data will be saved as is (with NaN values). Defaults to false.

Raises

AutoscoperServerError – If the server fails to save the tracking data
AutoscoperConnectionError – If the connection to the server is lost

setBackground(threshold: float) → None

Set the background threshold.

Parameters

threshold – The background threshold

Raises

AutoscoperServerError – If the server fails to set the background threshold
AutoscoperConnectionError – If the connection to the server is lost

setFrame(frame: int) → None

Set the frame to be used for the next acquisition.

Parameters

frame – The frame to be used for the next acquisition

Raises

AutoscoperServerError – If the server fails to set the frame
AutoscoperConnectionError – If the connection to the server is lost

setPose(volume: int, frame: int, pose: list[float]) → None

Set the pose of the volume at the specified frame.

Parameters

volume – The volume to set the pose of
frame – The frame to set the pose at
pose – The pose to set the volume to

Raises

AutoscoperServerError – If the server fails to set the pose
AutoscoperConnectionError – If the connection to the server is lost

setVolumeVisibility(volume: int, visible: bool) → None

Sets the visibility of the given volume

Parameters

volume – The ID of the volume.
visible – If True makes the volume visible. If False make the volume invisible.

Raises

AutoscoperServerError – If the server fails to get the number of frames
AutoscoperConnectionError – If the connection to the server is lost

trackingDialog(volume: int, start_frame: int, end_frame: int, frame_skip: int = 1, repeats: int = 1, max_itr: int = 1000, min_lim: float = -3.0, max_lim: float = 3.0, max_stall_itr: int = 25, opt_method: OptimizationMethod = OptimizationMethod.PARTICLE_SWARM_OPTIMIZATION, cf_model: CostFunction = CostFunction.NORMALIZED_CROSS_CORRELATION, opt_init_heuristic: OptimizationInitializationHeuristic = OptimizationInitializationHeuristic.PREVIOUS_FRAME) → None

Automatically tracks the volume across the given frames.

Parameters

volume – The id of the volume to be tracked
start_frame – The frame to start the tracking on
end_frame – The frame to end the tracking on
frame_skip – The amount of frames to skip over during tracking
repeats – The number of times to repeat the optimization
max_itr – The maximum number of iterations to run
min_lim – The minimum limit of the optimization
max_lim – The maximum limit of the optimization
max_stall_itr – The maximum number of iterations to stall
opt_method – The optimization method to use.
cf_model – The cost function to use. NORMALIZED_CROSS_CORRELATION for Bone Models, SUM_OF_ABSOLUTE_DIFFERENCES for Implant Models.
opt_init_heuristic – The heuristic to initialize the optimization. See OptimizationInitializationHeuristic.

Raises

AutoscoperServerError – If the server fails to track the volume
AutoscoperConnectionError – If the connection to the server is lost
ValueError – If parameters accepting an enum value are incorrectly specified.

New in version 2: The opt_init_heuristic parameter.

exception PyAutoscoper.connect.AutoscoperConnectionError

Bases: Exception

Exception raised when the connection to the server is lost.

exception PyAutoscoper.connect.AutoscoperServerError

Bases: Exception

Exception raised when the server reports an error.

exception PyAutoscoper.connect.AutoscoperServerVersionMismatch(server_version: int)

Bases: Exception

Exception raised when the client attempt to connect to an unsupported server.

class PyAutoscoper.connect.CostFunction(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum for the different cost functions available in PyAutoscoper.

NORMALIZED_CROSS_CORRELATION = 0

SUM_OF_ABSOLUTE_DIFFERENCES = 1

class PyAutoscoper.connect.OptimizationInitializationHeuristic(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum for the different optimization initialization heuristics available in PyAutoscoper.

CURRENT_FRAME = 0

LINEAR_EXTRAPOLATION = 2

PREVIOUS_FRAME = 1

SPLINE_INTERPOLATION = 3

class PyAutoscoper.connect.OptimizationMethod(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum for the different optimization methods available in PyAutoscoper.

DOWNHILL_SIMPLEX = 1

PARTICLE_SWARM_OPTIMIZATION = 0