Fiducial Registration Educational Demonstration

Author: Stephen Thompson

This is the Fiducial Registration Educational Demonstration (SciKit-SurgeryFRED). This version uses a graphical user interface based on Matplotlib and has been superseded by the browser based version at SciKit-SurgeryFRED.

Fiducial Registration Educational Demonstration (SciKit-SurgeryFRED) is part of the SciKit-Surgery software project, developed at the Wellcome EPSRC Centre for Interventional and Surgical Sciences, part of University College London (UCL).

Fiducial Registration Educational Demonstration is tested with Python 3.X

Fiducial Registration Educational Demonstration is intended to be used as part of an online tutorial in using fiducial based registration. The tutorial covers the basic theory of fiducial based registration, which is used widely in image guided interventions. The tutorial aims to help the students develop an intuitive understanding of key concepts in fiducial based registration, including Fiducial Localisation Error, Fiducial Registration Error, and Target Registration Error.

python sksurgeryfred.py

Please explore the project structure, and implement your own functionality.

Citing

If you use SciKit-SurgeryFRED in your research or teaching please cite it. Individual releases can be cited via the Zenodo tag. SciKit-Surgery should be cited as:

Thompson S, Dowrick T, Ahmad M, et al. “SciKit-Surgery: compact libraries for surgical navigation.” International Journal of Computer Assisted Radiology and Surgery. 2020 May. DOI: 10.1007/s11548-020-02180-5.

Developing

Cloning

You can clone the repository using the following command:

git clone https://github.com/SciKit-Surgery/scikit-surgeryfredmatplotlib

Running tests

Pytest is used for running unit tests:

pip install pytest
python -m pytest

Linting

This code conforms to the PEP8 standard. Pylint can be used to analyse the code:

pip install pylint
pylint --rcfile=tests/pylintrc sksurgeryfredmatplotlib

Installing

You can pip install directly from the repository as follows:

pip install git+https://github.com/SciKit-Surgery/scikit-surgeryfredmatplotlib

Contributing

Please see the contributing guidelines.

Useful links

Licensing and copyright

Acknowledgements

Supported by Wellcome and EPSRC.

Requirements for Fiducial Registration Educational Demonstration

This is the software requirements file for Fiducial Registration Educational Demonstration, part of the SNAPPY project. The requirements listed below should define what Fiducial Registration Educational Demonstration does. Each requirement can be matched to a unit test that checks whether the requirement is met.

Requirements

ID	Description	Test
0000	Module has a help page	pylint, see tests/pylint.rc and tox.ini
0001	Functions are documented	pylint, see tests/pylint.rc and tox.ini
0002	Package has a version number	No test yet, handled by git.

latest

sksurgeryfredmatplotlib package

Subpackages

sksurgeryfredmatplotlib.algorithms package

Submodules

sksurgeryfredmatplotlib.algorithms.ablation module

Functions for point based registration using Orthogonal Procrustes.

class sksurgeryfredmatplotlib.algorithms.ablation.Ablator(margin)[source]

Bases: object

handles the simulated ablation for scikit-surgery fred

ablate(estimated_target)[source]: performs and ablation, returns a score.

decrease_margin()[source]: Make the margin smaller

increase_margin()[source]: Make the margin bigger

setup(target, target_radius)[source]: Setup target etc.

sksurgeryfredmatplotlib.algorithms.add_fiducial module

Functions to support MedPhys Taught Module workshop on calibration and tracking

class sksurgeryfredmatplotlib.algorithms.add_fiducial.AddFiducialMarker(fig, plotter, pbr, logger, fixed_fle_sd, moving_fle_sd, max_fids=None)[source]

Bases: object

A class to handle mouse press events, adding a fiducial marker.

reset_fiducials(mean_fle_sq)[source]: resets the fiducial markers

sksurgeryfredmatplotlib.algorithms.fit_contour module

Fit a contour to an image

sksurgeryfredmatplotlib.algorithms.fit_contour.find_outer_contour(image, alpha=0.015, beta=10.0)[source]

Fits an active contour to the outer most edge in the image :params image: the image to fit to :params alpha: Snake length shape parameter. Higher values makes

snake contract faster (default 0.015)

Params beta: Snake smoothness shape parameter. Higher values makes snake smoother (default 10.0)
Returns: the resulting contour and the initialising contour

sksurgeryfredmatplotlib.algorithms.fit_contour.to_gray(image)[source]: converts and image to grayscale if not already done :params image: The image to convert, can be gray or rgb :returns: a grayscale version

Module contents

sksurgeryfredmatplotlib.logging package

Submodules

sksurgeryfredmatplotlib.logging.fred_logger module

Class to handle sksurgeryfred logging

class sksurgeryfredmatplotlib.logging.fred_logger.Logger(config)[source]

Bases: object

Implements logging functionality for sksurgeryfred. Configuration is done by passing a dictionary on construction. Subsequent calls to log(“message”) will write to log file.

Parameters

config –

a dictionary containing configuration

parameters. If dictionary contains no “logger” entry then an empty logger is created and subsequent calls to log() will have no effect. Otherwise a logger is created according to the entries in the logger config dictionary. (“log file name”, “overwrite existing”

Raises

IOError if the user can’t write to the named log file?

log(message)[source]: If logging, passes message to logger

log_result(actual_tre, fre, expected_tre, expected_fre, mean_fle, no_fids)[source]: Writes the registration result to log file

log_score(state_string, score)[source]: Writes the registration result to log file

read_log()[source]: reads a log file and returns lists of values

Module contents

sksurgeryfredmatplotlib.plotting package

Submodules

sksurgeryfredmatplotlib.plotting.interactive_plots module

Functions to support MedPhys Taught Module workshop on calibration and tracking

class sksurgeryfredmatplotlib.plotting.interactive_plots.PlotRegStatistics(plot)[source]

Bases: object

writes the registration statistics

set_visibilities(fids_text, tre_text, exp_tre_text, exp_fre_text, fre_text, score_text, total_score_text, margin_text, repeats_text)[source]: Sets which text boxes will be visible

update_fids_stats(no_fids, mean_fle)[source]: Updates the fids stats display

update_last_score(last_score)[source]: Updates the margin text box

update_margin_stats(margin)[source]: Updates the margin text box

update_repeats(repeats)[source]: Updates the total score text box

update_stats_plot(tre, exp_tre, fre, exp_fre)[source]: Updates the statistics display

update_total_score(total_score)[source]: Updates the total score text box

class sksurgeryfredmatplotlib.plotting.interactive_plots.PlotRegistrations(fixed_plot, moving_plot, stats_plot)[source]

Bases: object

Plots the results of registrations

initialise_new_reg(img, target_point, outline)[source]: resets the registration

plot_fiducials(fixed_points, moving_points, no_fids, mean_fle)[source]: Updates plot with fiducial data

plot_registration_result(actual_tre, expected_tre, fre, expected_fre, transformed_target_2d)[source]: Plots the results of a registration

sksurgeryfredmatplotlib.plotting.plotting module

Plotting functions for scikit-surgeryFRED

sksurgeryfredmatplotlib.plotting.plotting.plot_results(logfile)[source]: Plots the results of multiple runs, from the log file.

Module contents

sksurgeryfredmatplotlib.ui package

Submodules

sksurgeryfredmatplotlib.ui.sksurgeryfred module

User interfaces for sksurgeryFRED

sksurgeryfredmatplotlib.ui.sksurgeryfred.run_demo(image)[source]: Run FRED

sksurgeryfredmatplotlib.ui.sksurgeryfred_command_line module

Command line processing

sksurgeryfredmatplotlib.ui.sksurgeryfred_command_line.main(args=None)[source]: Entry point for Fiducial Registration Educational Demonstration application

sksurgeryfredmatplotlib.ui.sksurgeryfred_game module

User interfaces for sksurgeryFRED

sksurgeryfredmatplotlib.ui.sksurgeryfred_game.run_demo(image)[source]: Run FRED game

sksurgeryfredmatplotlib.ui.sksurgeryfred_game_command_line module

Command line processing

sksurgeryfredmatplotlib.ui.sksurgeryfred_game_command_line.main(args=None)[source]: Entry point for Fiducial Registration Educational Demonstration application

sksurgeryfredmatplotlib.ui.sksurgeryfred_plotter module

User interfaces for sksurgeryFRED

sksurgeryfredmatplotlib.ui.sksurgeryfred_plotter.run_plotter(logfile)[source]: Run FRED Plotter

sksurgeryfredmatplotlib.ui.sksurgeryfred_plotter_command_line module

Command line processing

sksurgeryfredmatplotlib.ui.sksurgeryfred_plotter_command_line.main(args=None)[source]: Entry point for Fiducial Registration Educational Demonstration application

Module contents

Fiducial Registration Educational Demonstration

sksurgeryfredmatplotlib.widgets package

Submodules

sksurgeryfredmatplotlib.widgets.fred_common module

The main widget for the interactive registration part of scikit-surgeryFRED

class sksurgeryfredmatplotlib.widgets.fred_common.FredCommon(image_file_name, headless=False)[source]

Bases: object

an interactive window for doing live registration

init_reg()[source]: sets up the registration

sksurgeryfredmatplotlib.widgets.interactive_registration module

The main widget for the interactive registration part of scikit-surgeryFRED

class sksurgeryfredmatplotlib.widgets.interactive_registration.InteractiveRegistration(image_file_name, headless=False)[source]

Bases: sksurgeryfredmatplotlib.widgets.fred_common.FredCommon

an interactive window for doing live registration

initialise_registration()[source]: sets up the registration

keypress_event(event)[source]: handle a key press event

sksurgeryfredmatplotlib.widgets.registration_game module

The main widget for the interactive registration part of scikit-surgeryFRED

class sksurgeryfredmatplotlib.widgets.registration_game.RegistrationGame(image_file_name, headless=False)[source]

Bases: sksurgeryfredmatplotlib.widgets.fred_common.FredCommon

an interactive window for doing live registration

initialise_registration()[source]: sets up the registration

keypress_event(event)[source]: handle a key press event

class sksurgeryfredmatplotlib.widgets.registration_game.VisibilitySettings(buffer_size)[source]

Bases: object

randomly selects from list of visilities, has five states FLE and no fids Expected FRE Expected TRE Actual FRE

get_vis_state()[source]: returns a random visibility state

Module contents

FiducialRegistrationEducationalDemonstration

sksurgeryfredmatplotlib_game module

sksurgeryfredmatplotlib_plotter module

First notebook

You can write up experiments in notebooks, and they can be generated into Sphinx docs using tox -e docs, and for example set up to run on readthedocs.

See this and this examples.

NOTE:

Getting jupyter to run your code in this package relies on 3 things:

You must ensure you start jupyter within the tox environment.

# If not already done.
source .tox/py36/bin/activate

# Then launch jupyter
jupyter notebook

Then when you navigate to and run this notebook, select the right kernel (named after your project) from the kernel menu item, in the web browser.
Add project folder to system path, as below.

[1]:

# Jupyter notebook sets the cwd to the folder containing the notebook.
# So, you want to add the root of the project to the sys path, so modules load correctly.
import sys
sys.path.append("../../")