API Reference¶

Description

This module contains a class with methods to automatically and manually annotate longitudinal ultrasonography images and videos. When the class is initiated,a graphical user interface is opened. This is the main GUI of the DL_Track package. From here, the user is able to navigate all functionalities of the package. These extend the methods in this class. The main functionalities of the GUI contained in this module are automatic and manual evalution of muscle ultrasonography images. Inputted images or videos are analyzed and the parameters muscle fascicle length, pennation angle and muscle thickness are returned for each image or video frame. The parameters are analyzed using convolutional neural networks (U-net, VGG16). This module and all submodules contained in the /gui_helpers modality are extensions and improvements of the work presented in Cronin et al. (2020). There, the core functionalities of this code are already outlined and the comparability of the model segmentations to manual analysis (current gold standard) is described. Here, we have improved the code by integrating everything into a graphical user interface.

Functions scope

For scope of the functions see class documentation.

Notes

Additional information and usage exaples can be found in the video tutorials provided for this package.

References

[1] VGG16: Simonyan, Karen, and Andrew Zisserman. “Very deep convolutional networks for large-scale image recognition.” arXiv preprint arXiv:1409.1556 (2014) [2] U-net: Ronneberger, O., Fischer, P. and Brox, T. "U-Net: Convolutional Networks for Biomedical Image Segmentation." arXiv preprint arXiv:1505.04597 (2015) [3] DL_Track: Cronin, Neil J. and Finni, Taija and Seynnes, Olivier. "Fully automated analysis of muscle architecture from B-mode ultrasound images with deep learning." arXiv preprint arXiv:https://arxiv.org/abs/2009.04790 (2020)

`DLTrack` ¶

Bases: CTk

DLTrack Graphical User Interface for Muscle Ultrasound Analysis¶

Main UI class of the DL_Track_US package providing both automatic and manual analysis of longitudinal B-mode ultrasound images and videos. Supports annotation, model-based segmentation, result visualization, and metric export.

The GUI integrates U-Net and VGG16-based CNN models to compute fascicle length, pennation angle, and muscle thickness. Users can customize analysis parameters, calibrate scaling, and optionally flip video frames.

Dependencies

GUI: tkinter, customtkinter, CTkToolTip
Image/Video Handling: OpenCV (cv2), PIL, matplotlib
Numerical: numpy, pandas
System: os, sys, subprocess, threading, glob, json, traceback

ATTRIBUTE	DESCRIPTION
`main`	Primary GUI layout container. TYPE: `CTkFrame`
`results`	Frame for image/video and result display. TYPE: `CTkFrame`
`terminal`	Panel for figure/metric visualization. TYPE: `CTkFrame`
`analysis_type`	Current analysis mode ("image", "video", "image_manual", "video_manual"). TYPE: `StringVar`
`filetype`	File extension filter for input files. TYPE: `StringVar`
`scaling`	Chosen scaling type ("Bar", "Manual", "None"). TYPE: `StringVar`
`spacing`	Millimeter spacing used in manual calibration. TYPE: `StringVar`
`flip`	Flip option for video analysis ("flip", "no_flip"). TYPE: `StringVar`
`filter_fasc`	Option to enable fascicle filtering. TYPE: `StringVar`
`step`	Frame step interval for video analysis. TYPE: `StringVar`
`input_dir`	Directory containing input images or videos. TYPE: `str`
`apo_model`	Path to the selected aponeurosis segmentation model. TYPE: `str`
`fasc_model`	Path to the selected fascicle segmentation model. TYPE: `str`
`flipflag_dir`	Path to CSV file with flip flags for images. TYPE: `str`
`video_path`	Path to a single video file (for manual analysis). TYPE: `str`
`processed_frames`	List of currently processed image frames or matplotlib figures. TYPE: `list`
`current_frame_index`	Index of currently displayed frame. TYPE: `int`
`settings`	Dictionary of user-defined configuration parameters. TYPE: `dict`
`_lock`	Thread lock for thread-safe flags. TYPE: `Lock`
`_is_running`	Indicates whether a processing thread is active. TYPE: `bool`
`_should_stop`	Indicates whether a running thread should be interrupted. TYPE: `bool`

METHOD	DESCRIPTION
`__init__`	Initializes GUI layout, variables, buttons, and bindings.
`run_code`	Launches appropriate analysis pipeline in a background thread.
`do_break`	Interrupts the currently running analysis thread.
`check_processing_complete`	Monitors thread execution and invokes callback on completion.
`display_frame`	Displays either an image frame or a matplotlib figure in the canvas.
`display_results`	Plots fascicle length medians across frames and embeds in GUI.
`calibrateDistanceManually`	Initializes interactive calibration interface.
`calibrate_distance`	Computes and displays pixel-to-mm scaling from two points.
`mclick`	Captures mouse positions during manual calibration.
`get_input_dir`	File dialog utilities for selecting inputs.
`get_flipfile_path`	Select paths for flip flag CSV or single video.
`change_analysis_type`	Dynamically enables/disables GUI components based on analysis type.
`change_spacing`	Enables calibration button only for manual scaling.
`update_frame_by_slider`	Slider controls for frame navigation.
`load_settings`	Loads persistent analysis settings from JSON file.
`open_settings`	Opens editable JSON settings file in default system editor.

Notes

Intended to be launched via python -m DL_Track_US_GUI or integrated into apps.
Processing callbacks are executed asynchronously to preserve UI responsiveness.
Uses external functions from gui_helpers and gui_modules.AdvancedAnalysis.

`is_running` `property` `writable` ¶

Instance method to define the is_running property getter method. By defining this as a property, is_running is treated like a public attribute even though it is private.

This is used to stop the analysis process running in a seperate thread.

RETURNS	DESCRIPTION
`is_running`	Boolean variable to check whether the analysis process started from the GUI is running. The process is only stopped when is_running = True. TYPE: `bool`

`should_stop` `property` `writable` ¶

Instance method to define the should_stop property getter method. By defining this as a property, should_stop is treated like a public attribute even though it is private.

This is used to stop the analysis process running in a seperate thread.

RETURNS	DESCRIPTION
`should_stop`	Boolean variable to decide whether the analysis process started from the GUI should be stopped. The process is stopped when should_stop = True. TYPE: `bool`

`init(*args, **kwargs)` ¶

`calibrateDistanceManually()` ¶

Function to manually calibrate an image to convert measurements in pixel units to centimeters.

`calibrate_distance()` ¶

Calculate the distance between two points and display the result.

`change_analysis_type(*args)` ¶

Unified instance method to display the required parameters based on the selected analysis type.

`change_spacing(*args)` ¶

Enable the spacing button only when the scaling type is set to "Manual".

`check_processing_complete(thread, callback)` ¶

Checks if the processing thread has finished.

`display_frame(item)` ¶

Display the current frame or figure on the GUI canvas.

`display_results(input_df_raw, input_df_filtered, input_df_medians)` ¶

Instance method that displays all analysis results in the output terminal using Pandastable. Input must be a Pandas dataframe.

Executed trough functions with calculated anylsis results.

PARAMETER	DESCRIPTION
`input_df_raw`	Dataftame containing the raw analysis results. TYPE: `DataFrame`
`input_df_filtered`	Dataftame containing the filtered analysis results. TYPE: `DataFrame`
`input_df_medians`	Dataftame containing the filtered median results. TYPE: `DataFrame`

`do_break()` ¶

Instance method to break the analysis process when the button "break" is pressed.

This changes the instance attribute self.should_stop to True, given that the analysis is already running. The attribute is checked befor every iteration of the analysis process.

`get_apo_model_path()` ¶

Instance method to ask the user to select the apo model path. This must be an absolute path and the model must be a .h5 file.

`get_fasc_model_path()` ¶

Instance method to ask the user to select the fascicle model path. This must be an absolute path and the model must be a .h5 file.

`get_flipfile_path()` ¶

Instance method to ask the user to select the flipfile path. The flipfile should contain the flags used for flipping each image. If 0, the image is not flipped, if 1 the image is flipped. This must be an absolute path.

`get_input_dir()` ¶

Instance method to ask the user to select the input directory. All image files (of the same specified filetype) in the input directory are analysed.

`get_video_path()` ¶

Instance method to ask the user to select the video path for manual video analysis. This must be an absolute path.

`load_settings()` ¶

Instance Method to load the setting file for.

Executed each time when the GUI or a toplevel is openened. The settings specified by the user will then be transferred to the code and used.

`mclick(event)` ¶

Instance method to detect mouse click coordinates in image.

`on_processing_complete()` ¶

Callback to execute after processing completes. Updates the slider range based on the processed frames or figures.

`open_settings()` ¶

Instance Method to open the setting file for.

Executed when the button "Settings" in master GUI window is pressed. A python file is openend containing a dictionary with relevant variables that users should be able to customize.

`resource_path(relative_path)` ¶

Get absolute path to resource (for dev and PyInstaller)

`run_code()` ¶

Instance method to execute the analysis process when the "run" button is pressed.

Which analysis process is executed depends on the user selection. By pressing the button, a seperate thread is started in which the analysis is run. This allows the user to break any analysis process. Moreover, the threading allows interaction with the main GUI during ongoing analysis process. This function handles most of the errors occuring during specification of file and analysis parameters. All other exeptions are raised in other function of this package.

RAISES	DESCRIPTION
`AttributeError`	The execption is raised when the user didn't specify the file or training parameters correctly. A tk.messagebox is openend containing hints how to solve the issue.
`FileNotFoundError`	The execption is raised when the user didn't specify the file or training parameters correctly. A tk.messagebox is openend containing hints how to solve the issue.
`PermissionError`	The execption is raised when the user didn't specify the file or training parameters correctly. A tk.messagebox is openend containing hints how to solve the issue.

`update_frame_by_slider(value)` ¶

Update the displayed frame based on the slider position.

`update_slider_range()` ¶

Updates the slider to match the number of processed frames or figures.

`runMain()` ¶

Function that enables usage of the gui from command promt as pip package.

Notes

The GUI can be executed by typing 'python -m DL_Track_US_GUI.py' in a terminal subsequtently to installing the pip package and activating the respective library.

It is not necessary to download any files from the repository when the pip package is installed.

For documentation of DL_Track see top of this module.

API Reference¶

DLTrack ¶

DLTrack Graphical User Interface for Muscle Ultrasound Analysis¶

is_running property writable ¶

should_stop property writable ¶

__init__(*args, **kwargs) ¶

calibrateDistanceManually() ¶

calibrate_distance() ¶

change_analysis_type(*args) ¶

change_spacing(*args) ¶

check_processing_complete(thread, callback) ¶

display_frame(item) ¶

display_results(input_df_raw, input_df_filtered, input_df_medians) ¶

do_break() ¶

get_apo_model_path() ¶

get_fasc_model_path() ¶

get_flipfile_path() ¶

get_input_dir() ¶

get_video_path() ¶

load_settings() ¶

mclick(event) ¶

on_processing_complete() ¶

open_settings() ¶

resource_path(relative_path) ¶

run_code() ¶

update_frame_by_slider(value) ¶

update_slider_range() ¶

runMain() ¶

`DLTrack` ¶

`is_running` `property` `writable` ¶

`should_stop` `property` `writable` ¶

`init(*args, **kwargs)` ¶

`calibrateDistanceManually()` ¶

`calibrate_distance()` ¶

`change_analysis_type(*args)` ¶

`change_spacing(*args)` ¶

`check_processing_complete(thread, callback)` ¶

`display_frame(item)` ¶

`display_results(input_df_raw, input_df_filtered, input_df_medians)` ¶

`do_break()` ¶

`get_apo_model_path()` ¶

`get_fasc_model_path()` ¶

`get_flipfile_path()` ¶

`get_input_dir()` ¶

`get_video_path()` ¶

`load_settings()` ¶

`mclick(event)` ¶

`on_processing_complete()` ¶

`open_settings()` ¶

`resource_path(relative_path)` ¶

`run_code()` ¶

`update_frame_by_slider(value)` ¶

`update_slider_range()` ¶

`runMain()` ¶