Code for Modeling, Simulation, GUI and Statistical Analysis of a Robot-guided Needle Placement
Resources and extra documentation for the manuscript "Needle Placement for Robot-assisted 3D Ultrasound-guided Breast Biopsy: A Preliminary Study" published in IEEE Latin America Transactions. The code is organized by the type of programming language used in the project in the following order
Python -> Matlab -> R. The project hierarchy and folders description is as follows
- PYTHON\BreastDimension: For a geometrical model of woman breast and basic dimensions for a breast holder device
getRootDirectory.m. Script for loading current working directory.
startup.m. Script for adding all folder paths to Matlab.
- Breast. Breast models for A, B, and C-cup sizes.
- Devices. Needle devices for core and fine needle biopsies.
- Matlab_models. Scripts for robot modeling (forward and inverse kinematics), breast modeling, trajectory generation, a collision-free path algorithm and multiple simulation.
- Data: Trajectory data for joint trajectory testing.
- ForApp. Function scripts for implementing the GUI application.
- ForMatlab. Function scripts for all Matlab-based simulations.
- ForSimulink. Functions script for all Simulink-based simulations.
- ModernRobotics. Based on Modern robotics toolbox by Kevin Lynch and Frank Park.
- rvctools. Robotics Toolbox for MATLAB or RVC by Peter Corke.
- Simulink_models. For implementing a robot-assisted biopsy environment based on Simscape and Stateflow-Flowcharts. Simulation settings: Ode23t Solver.
.matfiles for the GUI application, target biopsy points, breast holder models, Finite element breast models, breast dimensions, robot dimensions, robot kinematics, end effector waypoints and Simulink model workspace.
- Extra. Figures for GUI application.
- GUI. For designing a Graphical User Interface (GUI) for setting the basic configurations of a robot-assisted needle placement before a complete simulation (
- Results. Outputs for multiple simulation (
.xlsfiles) and target biopsy points for each breast-cup size (
- Scripts. For computing multiple simulations (
.m) and biopsy targets samplings (
.m) based on factorial-method design.
- SIM. Simulation models (
.slx) for GUI application and multiple simulation.
- work. For simulation cache in Simulink.
- R\SimulationAnalysis. For a statistical analysis and curves plotting.
- ProjectImages. Some manuscript images, figures and animation for the
- Matlab 2020b or later. All additional packages (only needed codes) were uploaded in this repository.
- Robotics Toolbox for MATLAB or RVC from Robotics, Vision and Control Fundamental algorithms in MATLAB: Second Edition by Peter Corke.
- Modern robotics toolbox from Modern Robotics: Mechanics, Planning, and Control (Kevin Lynch and Frank Park, Cambridge University Press 2017 and 2019).
- Python 9.6
- R 2.1 or later
- Optional. Solidworks 2019 for CAD modeling and exporting files into Matlab
Instructions for running the GUI
startup.mto add all paths to Matlab and run without problems
biopsyControl.mlappto open the application.
The GUI lets you select randoms biopsy targets, define needle insertion avoiding collisions, generate robot trajectory and save all data in order to simulate a particular biopsy case in Simulink.
The application use is interactively easy to follow. The bottoms were sequentially ordered according to: Get biopsy target, define needle insertion, set needle device, generate robot trajectory for the preplacement stage, save data, reload model Simulink variables, simulate and get errors report.
This robot environment in Simulink can be opened in the option
Open Modelinside the third tab (
Postplacement stage) or directly by going to
Simulink_models\SIM\breastBiopsyApp.slx. Then, playing the option
Simulateto initialize and showing a visual simulation window (based on Simscape multibody toolbox).
NOTE When opening the
breastBiopsyApp.slxdirectly without running the application before, there will be a warning message about a failed load of model workspace variables. To avoid this, run all the application steps to create the correct file
simulinkWorkSpace.matand reload all needed model variables. Finally, go to
Model Explorer -> Model Hierarchy -> breastBiopsyApp -> Model Workspcae -> Workspace datain Simulink, browse for the
simulinkWorkSpace.matfile and save the model. This will eliminate the warning message, and the
breastBiopsyApp.slxmodel can also be able to run with the previous loaded variables any time.
Instructions for running a multiple simulation
- Open the
- The results will be saved in
Simulink_models\Results\in Excel files (i.e.
simulationA_FNAwas created by simulating a breast holder of A-size cup and a fine needle).
The Simulink file associated to
breastBiopsyMulti.slxand always run in second plane. Therefore, there will be not a visual simulation. However, this could be modified.
The same repository can be found on GitLab.