Skip to content
This repository has been archived by the owner on Sep 27, 2020. It is now read-only.

Home

Jump to bottom
Robert Grupp edited this page Sep 16, 2020 · 43 revisions

WIKI IS STILL UNDER CONSTRUCTION

Table of Contents

  1. Introduction
  2. Walkthrough
  3. Frequently Asked Questions (FAQ)
  4. File Formats
  5. Code and Programs for Related Publications

Introduction

This wiki is intended to help people use the xReg repository, ranging from basic usage of the compiled executables to more advanced topics, such as using xReg as a library in order to provide new capabilities.

Walkthrough

This section outlines a walkthrough, or tutorial, of the basic functionality of the xReg software and how it may be applied to solve common computer assisted surgery workflow tasks, ranging from preoperative planning to intraoperative navigation. All data used in the workflow is either obtained from freely available online sources, such as The Cancer Imaging Archive (TCIA), derived by processing the TCIA data, simulating new data, or some combination therein. Links to all of the derived and simulated data files are provided here.

The walkthrough provides examples of calling the executable programs and does not delve into lower-level usage of xReg as a library. Users that wish to use, or modify, the xReg library should also examine the appropriate source code as they proceed through the walkthrough.

Walkthrough Outline:

  1. Obtaining the tools
  2. Preoperative planning
    1. DICOM conversion and resampling
    2. Volume cropping
    3. Bone segmentation
    4. Mesh creation
    5. PAO planning and fragment creation
  3. Simulated data
    1. Random PAO fragment and femur movements
    2. Volumetric modeling of PAO fragment and femur poses
    3. Insertion of screws and K-wires and volumetric modeling
    4. Fluoroscopy
  4. Intraoperative 3D/3D registration
    1. Point cloud to surface registration
  5. Intraoperative 2D/3D (fluoroscopy/CT) registration
    1. Single-view pelvis registration
    2. Multiple-view pelvis/femur/PAO fragment registration

Frequently Asked Questions (FAQ)

Help generate this section by asking some questions via the repository issues page, email, or twitter!

  1. Are there pre-compiled binaries for Windows/Mac/Linux?
    • Not yet! Once these are available they will be posted on the repository page under releases. Stay tuned.
  2. How do I select a specific GPU (or OpenCL device) to use on a system with several GPUs (OpenCL devices) available?
    • This may be accomplished by setting the desired device ID with the --ocl-id flag or through the use of environment variables (e.g. CUDA_VISIBLE_DEVICES). See this page for further information.
  3. Is it possible to run on a system that does not have a GPU or a less-capable GPU (e.g. a server)?
    • Yes! Select the CPU backend by passing --backend cpu or use the OpenCL backend with a compatible CPU device (e.g. something like --backend ocl --ocl-id "Intel(R)Core(TM)[email protected]". Tools that do not provide a backend flag only perform CPU processing. See this page for further information.
  4. My program crashed with some strange OpenCL error message - what happened?
    • This usually occurs when there are insufficient resources, such as memory, on the OpenCL device. The exact reason depends on the processing involved, but typically adjusting the parameters that effect the amount of memory required may resolve the issue. For example, lowering the population sizes for the CMA-ES or Differential Evolution registration strategies will reduce the number of DRRs created during each optimization iteration, and therefore reduce the memory footprint. This may also occur if your code chains together OpenCL ray casters and similarity metrics, but different contexts or command queues are used for each object.
  5. Why did you choose OpenCL for GPU computations instead of CUDA?
    • Although CUDA kernels are generally more computationally efficient than their OpenCL counterparts, using OpenCL avoids a lock-in to NVIDIA GPUs. Since most NVIDIA, AMD, and Intel GPUs provide OpenCL support, nearly any hardware setup, ranging from entry-level laptops to state-of-the-art compute clusters, may leverage GPU support. This should enable any interested user to run this software. Support for CUDA, Metal, and Vulkan processing backends is planned for future work.
  6. How do I incorporate this library into my software?
    • The xReg library is most easily incorporated using standard CMake practices, such as add_subdirectory() and find_package(). See this page for more details.
  7. I would like to add my own similarity metric (or ray caster, etc.) for 2D/3D registration, what is the best way to do this?
    • The typical way to accomplish this is to create a new class that inherits from an appropriate CPU or OpenCL base class. Additional information for extending the library is provided here.

File Formats

TODO. Discuss file formats:

  • volume data (.nii.gz)
  • rigid transform data (.h5 ITK format)
  • landmark annotations (.fcsv Slicer format)
  • projection data (.h5 XREG format)

Code and Programs for Related Publications

The xReg library and supporting executables have been used for research leading to various publications. Some of these publications are listed below, along with links to any available source code.

  1. Automatic Annotation of Hip Anatomy in Fluoroscopy for Robust and Efficient 2D/3D Registration
  2. Pose Estimation of Periacetabular Osteotomy Fragments with Intraoperative X-Ray Navigation
  3. Fast and Automatic Periacetabular Osteotomy Fragment Pose Estimation Using Intraoperatively Implanted Fiducials and Single-View Fluoroscopy
  4. Patch-Based Image Similarity for Intraoperative 2D/3D Pelvis Registration During Periacetabular Osteotomy
  5. Fiducial-Free 2D/3D Registration for Robot-Assisted Femoroplasty
  6. Fiducial-Free 2D/3D Registration of the Proximal Femur for Robot-Assisted Femoroplasty
Clone this wiki locally