adhusch / pacer

PaCER - Precise and Convenient Electrode Reconstruction for Deep Brain Stimulation

PaCER
Precise and Convenient Electrode Reconstruction for DBS

   

Please note that PaCER is a research tool NOT intended for clinical use.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

Copyright (C) 2016-2017 Andreas Husch, Centre Hospitalier de Luxembourg, National Department of Neurosurgery and University of Luxembourg, Luxembourg Centre for Systems Biomedicine.

Background

The PaCER Toolbox is a MATLAB implementation of a robust method to fully automatically reconstruct deep brain stimulation trajectories from post operative CT imaging data. PaCER is able to fully preserving electrode bending (e.g. caused by brainshift). Further is able to detect individual contacts on high-resolution data. The PaCER toolbox is provided with means to easily visualize electrodes as well as imaging data within the MATLAB environment.

Getting Started

Requirements

The requirements to use PaCER are:

• MATLAB, including the Image Processing Toolbox
• post-operative CT image in nifti file format.

A CT slice-thickness <= 1 mm is recommended, however, PaCER will work on lower resolution data too by falling back to a less sophisticated contact detection method (yielding lower accuracy). Nifti input files are supported in compressed form (.nii.gz) as well as non-compressed (.nii).

Examples

The easiest way to learn about PaCER is to run the example files. We recommend to add the PaCER directory and all its subdirectories to your MATLAB path first. This can be archived by running the file SETUP_PACER.m in MATLAB (once). The examples include a call to SETUP_PACER.

The following examples require only a post op CT dataset - they should work out of the box for most CT scan protocols as long as the slice thickness is not toooo bad :-) Easy conversion from DICOM to NIFTI is possible dcm2nii which is included in MRIcron. Advanced example demonstrating further use-cases (e.g. visualisation of segmentations and atlas data, simple volume of tissue activated model etc.) can be found in the examples/advanced/ directory. However these examples require appropriate co-registered image modalities (e.g. atlases, segmentation). We are in the process to provide a full example dataset in the future.

• EXAMPLE_1.m - Basic PaCER call and electrode plot. Start here!
  • EXAMPLE_1_1.m - Continues EXAMPLE_1 by adding an MPR view of the CT image and demonstrating some plot customisations

How to cite?

The PaCER algorithm is described in:

A. Husch, M. V. Petersen, P. Gemmar, J. Goncalves, F. Hertel: PaCER – A fully automated method for electrode trajectory and contact reconstruction in deep brain stimulation, NeuroImage: Clinical, Volume 17, 2018, Pages 80-89, Available online 6 October 2017, ISSN 2213-1582, https://doi.org/10.1016/j.nicl.2017.10.004., [Open access fulltext].

For people interested in even more technical details, the preprocessing pipeline is described in more details here:

A. Husch, P. Gemmar, J. Lohscheller, F. Bernard, F. Hertel: Assessment of Electrode Displacement and Deformation with Respect to Pre-Operative Planning in Deep Brain Stimulation. Bildverarbeitung für die Medizin 2015, Springer Berlin Heidelberg, 2015.[ORBilu repository with fulltext request form]

An example of using PaCER within an automatic image-registration pipeline for DBS assessment is described in:

A. Husch, M. V. Petersen, P. Gemmar, J. Goncalves, N. Sunde, F. Hertel: Post-operative deep brain stimulation assessment: Automatic data integration and report generation, Brain Stimulation, Available online 1 February 2018. [Open access fulltext]

ARTENOLIS (Automated Reproducibility and Testing Environment for Licensed Software) is a general-purpose and flexible infrastructure software application that implements continuous integration for open-source software with licensed dependencies. You may cite ARTENOLIS as:

L. Heirendt, S. Arreckx, C. Trefois, Y. Jarosz, M. Vyas, V. P. Satagopam, R. Schneider, I. Thiele, R. M. T. Fleming: ARTENOLIS: Automated Reproducibility and Testing Environment for Licensed Software, abs/1712.05236, 2017.

Please acknowledge the respective papers when using the algorithm in your work.

Do you need any help?

Feel free to open an issue at https://github.com/adhusch/PaCER or drop a note to mail (at) andreashusch.de

If you need help our have trouble processing local data you are invited to open a GitHub issue. Any feedback to further improve the performance on varing datasets is very welcome.

Acknowledgements

Software tools

PaCER is packaged with some free external software libraries for convenience. Please see the “toolboxes” folder and the respective LICENSE files for details. We feel grateful to the authors of this toolboxes and scripts:

• Tools for NIfTI and ANALYZE image by Jimmy Shen
• RGB triple of color name, version 2 by Kristjan Jonasson
• GUI Layout Toolbox by David Sampson and Ben Tordoff
• in_polyhedron by Jaroslaw Tuszynski
• Cylinder Between 2 Points by Per Sundqvist
• MPR View by Florian Bernard

Funding & infrastructure

This work was made possible by an Aide à la Formation Recherche (AFR) grant to Andreas Husch from the Luxembourg National Research Fund (FNR).

The Responsible and Reproducible Research (R3) of the LCSB BioCore is acknowledged for providing the ARTENOLIS infrastructure and technical expertise to ensure high quality of the present software.

           

pacer's Issues

Implement switch SPM and NiftiOOP

recostruction issue using PaCER on Lead-DBS

Dear all,
i'm using PaCER inside the toolbox matlab Lead-DBS. I usually work on CT scan, the pipe line seems to work, but I’ve run into difficulties with the recostruction steps. I got this error

Error using ea_reconstruct_trajectory (line 282)
Mask out of bounds! Must have lost trajectory...
Please try a different 'Mask window size' or try manual mode by setting 'Entrypoint for Target' to
'Manual'.

Error while evaluating UIControl Callback.

Can somebody help me?
Thanks in advace for your collaboration.
Regards,
Arianna

Coordinate System of Nifti incorrect

Hi, I've tried to use PaCER to detect DBS electrodes, however the electrode locations were always placed on the wrong end of the shank (accompanied by a warning that the length of the shank is negative).

It turns out that NiftiMod seems to incorrectly load the transformation matrix of my nifti. Replacing it with NiftiModSPM (which btw. is missing a depdency .m file that is available in leaddbs), solved the issue.

no artifacts found

Dear Andreas Husch,
I'm trying to run PaCER on a post op CT, which was initally a DICOM file.
I transfered it to nifti using dcm2nii, and then resliced it using the reslice_nii function.
When I run PaCER with mask, it detects no artifacts, with mask it detects 876, of which 0 are found to be electrodes. I think it might be because of the cc analysis, that it expects more round artifacts for electrodes. Is there a way to alter this to make it more sensitive to other shapes? Or does it mean the quality of the CT images isn't good enough?
Thank you for making your code publicly available!
Kind Regards,
Monique

Function name clash - oor and orr

Function orr is defined in oor.m, which is not coherent.

Error from documentation generation:

WARNING: [sphinxcontrib-matlabdomain] Unexpected function name: "orr". Expected "oor" in module "src.Functions".

@adhusch, what is the correct name?

cc: @Daniel-Tojal

Add support for electrodes with more than 4 (ring) contacts

PaCER preprocessing error in LeadDBS

Dear all,
i'm trying to recostruct electrode trajectory using PaCER inside the toolbox matlab Lead-DBS and I got this error:

Warning: PaCER failed with the following error:
In ea_autocoord (line 270)
In ea_run (line 96)
In lead_dbs>run_button_Callback (line 187)
In gui_mainfcn (line 95)
In lead_dbs (line 43)
In matlab.graphics.internal.figfile.FigFile/read>@(hObject,eventdata)lead_dbs('run_button_Callback',hObject,eventdata,guidata(hObject))
Identifier:
Message: PaCER returned a different number of electrodes than expected by LeadDBS! In most cases this indicates an error in PaCER preprocessing (brain mask estimation) due to untypical CT data. Please provide a brain mask to PaCER in this case using the mask parameter.
In: C:\Users\BIOING\Desktop\STUDI\lead\ea_runpacer.m
Method: ea_runpacer
Line: 17
Please check your input data carefully.
Error using ea_reconstruct_trajectory (line 282)
Mask out of bounds! Must have lost trajectory...
Please try a different 'Mask window size' or try manual mode by setting 'Entrypoint for Target' to
'Manual'.
Error while evaluating UIControl Callback.

So i tried to run the "standalone use" of PaCER using my postop_CT images (.nii) and i got this error:

Error using extractElectrodePointclouds (line 96)
NO electrode artifact found within brain mask. Did you supply a post-op brain CT image? \n Try the 'no
mask' parameter in case of phantom scans without brain. \n Try providing an externally created brain
mask using the "brainMask" parameter in other cases.
Error in extractElectrodePointclouds (line 92)
[elecsPointcloudStruct, brainMask] = extractElectrodePointclouds(niiCT, 'brainMask',
args.brainMask, 'metalThreshold', METAL_THRESHOLD * 0.8, 'medtronicXMLPlan',
args.medtronicXMLPlan);
Error in extractElectrodePointclouds (line 92)
[elecsPointcloudStruct, brainMask] = extractElectrodePointclouds(niiCT, 'brainMask',
args.brainMask, 'metalThreshold', METAL_THRESHOLD * 0.8, 'medtronicXMLPlan',
args.medtronicXMLPlan);
Error in extractElectrodePointclouds (line 92)
[elecsPointcloudStruct, brainMask] = extractElectrodePointclouds(niiCT, 'brainMask',
args.brainMask, 'metalThreshold', METAL_THRESHOLD * 0.8, 'medtronicXMLPlan',
args.medtronicXMLPlan);
Error in extractElectrodePointclouds (line 92)
[elecsPointcloudStruct, brainMask] = extractElectrodePointclouds(niiCT, 'brainMask',
args.brainMask, 'metalThreshold', METAL_THRESHOLD * 0.8, 'medtronicXMLPlan',
args.medtronicXMLPlan);
Error in extractElectrodePointclouds (line 92)
[elecsPointcloudStruct, brainMask] = extractElectrodePointclouds(niiCT, 'brainMask',
args.brainMask, 'metalThreshold', METAL_THRESHOLD * 0.8, 'medtronicXMLPlan',
args.medtronicXMLPlan);
Error in extractElectrodePointclouds (line 92)
[elecsPointcloudStruct, brainMask] = extractElectrodePointclouds(niiCT, 'brainMask',
args.brainMask, 'metalThreshold', METAL_THRESHOLD * 0.8, 'medtronicXMLPlan',
args.medtronicXMLPlan);
Error in extractElectrodePointclouds (line 92)
[elecsPointcloudStruct, brainMask] = extractElectrodePointclouds(niiCT, 'brainMask',
args.brainMask, 'metalThreshold', METAL_THRESHOLD * 0.8, 'medtronicXMLPlan',
args.medtronicXMLPlan);
Error in extractElectrodePointclouds (line 92)
[elecsPointcloudStruct, brainMask] = extractElectrodePointclouds(niiCT, 'brainMask',
args.brainMask, 'metalThreshold', METAL_THRESHOLD * 0.8, 'medtronicXMLPlan',
args.medtronicXMLPlan);
Error in PaCER (line 51)
elecPointCloudsStruct = extractElectrodePointclouds(niiCT, varargin{:}); % preprocessing

Can somebody help me? Can someone give me some explanations?
Thanks in advace for your collaboration.
Regards,
Arianna

elecModels{1}.initPlot3D coordinate space

Hello Dr. Husch,

Thank you for providing this incredible tool for DBS lead extractions. My question is related to visualizing the output of PaCER with various image modalities. Using the .initPlot3D method would I be able to visualize the electrode for any image space shared by the CT used to extract the lead model? Or would I need to compute an addtional transformation on the electrode output? That is, do I have to use the 'MPRWorldCoordinates', which appear proprietary?

Thank you!
John

Fix GUI Toolbox

.png images are missing.

Provide discretized electrode trajectory model without the tip e.g. for LeadDBS

Lead-DBS PaCER Error

Hi Team,
I have fairly consistently received this error recently when running PaCER within Lead DBS. I have used the default co-registration and normalization settings, followed by brainshift correction.

1st Pass Electrode Length within Brain Convex Hull: 61.2896mm
2nd Pass Electrode Length within Brain Convex Hull: 62.3233mm
Warning: PaCER or the LeadDBS Wrapper for PaCER failed with the following error:

In ea_autocoord (line 275)
In ea_run (line 96)
In lead_dbs>run_button_Callback (line 197)
In gui_mainfcn (line 95)
In lead_dbs (line 43)
In matlab.graphics.internal.figfile.FigFile/read>@(hObject,eventdata)lead_dbs('run_button_Callback',hObject,eventdata,guidata(hObject))
Identifier: MATLAB:UndefinedFunction
Message: Undefined function 'filtfilt' for input arguments of type 'double'.
In: /Applications/lead/ext_libs/PaCER/src/Functions/refitElec.m
Method: refitElec
Line: 81
Please check your input data carefully.
If the error persists, please consider a bug report at https://github.com/adhusch/PaCER/issues.
Error using ea_error (line 16)
PaCER failed. Potentially try running the TRAC/CORE Algorithm or a fully manual pre-reconstruction.

Error in ea_autocoord (line 283)
ea_error('PaCER failed. Potentially try running the TRAC/CORE Algorithm or a fully
manual pre-reconstruction.');

Error in ea_run (line 96)
ea_autocoord(options);

Error in lead_dbs>run_button_Callback (line 197)
ea_run('run',options);

Error in gui_mainfcn (line 95)
feval(varargin{:});

Error in lead_dbs (line 43)
gui_mainfcn(gui_State, varargin{:});

Error in
matlab.graphics.internal.figfile.FigFile/read>@(hObject,eventdata)lead_dbs('run_button_Callback',hObject,eventdata,guidata(hObject))
Error while evaluating UIControl Callback.