XRIPL’s Documentation

XRIPL (read as “zripple”) is a library of tools for processing x-ray radiographs and extracting contours of interest within the image using computer vision techniques. Features include spatial calibration, denoising, background and attenuation correction through pseudo-flatfielding, watershed segmentation, contour processing, and visualization. The details of the XRIPL analysis pipeline are published in the Proceedings of the 23rd Topical Conference on High-Temperature Plasma Diagnostics Proceedings [1].

[1] P. M. Kozlowski, Y. Kim, B. M. Haines, H. F. Robey, T. J. Murphy, H. M. Johns, and T. S. Perry. Use of Computer Vision for analysis of image data sets from high temperature plasma experiments. Review of Scientific Instruments 92, 033532 (2021) https://doi.org/10.1063/5.0040285

Installing XRIPL

Requirements

XRIPL requires Python version 3.7 or newer. XRIPL also require the following openly available packages for installation:

• NumPy — 1.15.0 or newer

• matplotlib — 2.2.2 or newer

• scipy — 1.1.0 or newer

• h5py — 2.8.0 or newer

• scikit-image — 0.14.0 or newer

Installation with pip

Official releases of XRIPL are published to pypi.org and can simply be pip installed like so:

pip install xripl

Building and installing from source (for contributors)

Make sure you have python installed, preferably via Anaconda

Here is where you get Anaconda, and make sure to get the Python 3 version. https://www.anaconda.com/distribution/

Setup installation directory

Make a directory called “xripl” in a sensible place on your system. Preferably in a directory where none of the higher level directory names have spaces in them.

Setup a virtual environment

If you have python installed via Anaconda, then create your virtual environment like this

conda create --name xripl

Clone the repository using git

In the xripl directory you created, run the following on the command line

git clone https://github.com/lanl/xripl.git

Activate your virtual environment

Still on the command line, run

source activate xripl

Install requirements

pip install -r requirements.txt

Install xripl

If you are a user then do

pip install .

If you wish to help in developing xripl, then do

pip install -e .

Test if install was successful

Open a python and try doing import xripl. If all went well then you shouldn’t get any error messages.

Examples

General examples

General-purpose and introductory examples from XRIPL

Radiograph segmentation tutorial

Radiograph segmentation tutorial

Importing modules

import numpy as np
import matplotlib.pyplot as plt
from skimage.filters import median, rank

#from xripl.data import shot
from xripl.reader import openRadiograph
from xripl.contrast import equalize
from xripl.clean import cleanArtifacts, flatten
from xripl.segmentation import detectShock
# import xripl.pltDefaults

Plot

xData = np.arange(10)
yData = xData ** 2

plt.plot(xData, yData)
plt.xlabel('X')
plt.ylabel('Y')
plt.show()

How to Contribute

Visit our GitHub repository and look through the list of open issues to see how you can contribute. If you find a bug, or would like to see a feature enhancement, then open up an issue and describe it detail.

Acknowledging and Citing

If you use XRIPL for work/research presented in a publication (whether directly, or as a dependency to another package), we encourage the following acknowledgement:

This research made use of XRIPL, a community-developed Python package for analysis of filtered diode array signals.

and that you cite the following paper(s):

@article{kozlowski2021use,
  title={Use of computer vision for analysis of image datasets from high temperature plasma experiments},
  author={Kozlowski, Pawel Marek and Kim, Y and Haines, Brian Michael and Robey, HF and Murphy, Thomas Joseph and Johns, Heather Marie and Perry, Theodore Sonne},
  journal={Review of Scientific Instruments},
  volume={92},
  number={3},
  pages={033532},
  year={2021},
  publisher={AIP Publishing LLC}
}

XRIPL License (BSD 3-clause)

© 2022. Triad National Security, LLC. All rights reserved. This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.

This program is open source under the BSD-3 License. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2.Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3.Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Clean (xripl.clean)

Created on Thu Aug 1 13:13:52 2019

Functions for cleaning and regularizing images.

@author: Pawel M. Kozlowski

Functions

cleanArtifacts(image[, diskSize, plots, ...])	Applies morphological opening to clean bright streaks and spots from radiographs, and then applies a morphological closing to remove dark artifacts.
flatten(image[, medianDisk, gaussSize, ...])	Produces an approximate image of the background light intensity variations in the image and divides the image by this background to effectively flatten the contrast.
enhanceRadiograph(img[, medianDisk, ...])	Median filter, morphological filter, and pseudo-flatfield the radiographs to prepare it for feature identification.

Contour (xripl.contour)

Created on Mon Oct 22 16:47:46 2018

Tools for identifying contours of equal intensity/contrast.

@author: Pawel M. Kozlowski

Functions

nContours(contours, n)

Get the n longest contours from a list of contours.

Contrast (xripl.contrast)

Created on Mon Oct 22 16:46:08 2018

Functions for adjusting plotting and adjusting the contrast of radiographic images.

@author: Pawel M. Kozlowski

Functions

equalize(image[, plot, savePlot, fileName, ...])

Convenience function for applying contrast equalization to radiographic data.

Films (xripl.films)

Created on Wed Feb 27 15:32:34 2019

Opening and processing microD scanned films.

@author: Pawel M. Kozlowski

Functions

openFilm(fileName)

Opens HDF5 file film scan from microD.

Filters (xripl.filters)

Created on Tue Mar 31 09:50:47 2020

Custom filters for cleaning/blurring images.

@author: Pawel M. Kozlowski

Functions

boxFilter(img[, boxSize])

Applies a symmetric box filter to blur the image.

Instrument (xripl.instrument)

Created on Tue Feb 26 12:58:48 2019

Utilities for convolving 2D radiograph instrument function with synthetically produced radiographs.

@author: Pawel M. Kozlowski

Functions

openSyntheticRadiograph(directory, fileName)	Given the full filename (with path) to an hdf5 file containing synthetic radiograph data, open the file and return the image data as a numpy array.
saveHdf(data, directory, fileName)	Saves radiograph into HDF5 file.

Magnification (xripl.magnification)

Created on Wed Jun 3 14:51:45 2020

@author: Pawel M. Kozlowski

Functions

lineoutMinima(lineoutX, lineoutY[, ...])	Given lineout should be lineout from flattened radiograph image.
tubeCenterPx(minimaIdxs[, lineoutY, plotsFlag])	Given the pixel positions of the tube edges, obtains the tube center in pixels for a tube target.
diameterPx(minimaIdxs)	Obtains the diameter of the tube in pixels when given the tube edges.
magnificationUmPx(innerDiameterPx[, ...])	Get magnification with propagated uncertainty in um/px when given target tube diameter in um, in px, and standard deviation on the diameter in px.
magnificationAnalysis(shot, camera, dataDir, ...)	Get magnification from target radiograph by measuring inner tube wall of known diameter.

Plot Defaults (xripl.pltDefaults)

Created on Fri Oct 27 02:37:12 2017

Default plotting parameters

@author: Pawel M. Kozlowski

Functions

plot_line_shaded(xData, yData, yErrs[, label])	Generate a line plot with shaded region representing y-error bars.
plot_scatter_bars(xData, yData, yErrs[, label])	Generate a scatter plot with y-error bars.

Reader (xripl.reader)

Created on Mon Oct 22 16:42:16 2018

Reads radiographic images and create simple plots

@author: Pawel M. Kozlowski

Functions

openRadiograph(fileName)	Given the full filename (with path) to an hdf5 file containing radiographic data from an XRFC (x-ray framing camera) diagnostic on OMEGA, open the file and return the foreground and background image data as numpy arrays.
omegaDataSearch(dataDir[, camera])	Search given directory and subdirectories for HDF5 files of radiographs from OMEGA LLE XRFC data.
shotRadiograph(shotNum, camera, dataDir[, plots])	Opens a radiograph given a shot number, framing camera and directory containing shot data.

Segmentation (xripl.segmentation)

Created on Thu Jan 10 10:10:36 2019

Image segmentation tools for radiographic images.

@author: Pawel M. Kozlowski

Functions

merge_labels(labels_image, labels_to_merge, ...)	Utility function for merging different labeled regions.
nSegments(labels, n)	Get the n largest area segments from a segmented (labeled) image.
segmentContour(labels, segmentNumber[, plots])	Given a segmented image and a selected segment number, obtains the longest contour of that segment.
detectShock(image[, originalImage, ...])	This is a convenience function for applying watershed segmentation using regions of low gradient as markers, and using another gradient image for processing via watershed.

Tube Transmission (xripl.tubeTransmission)

Created on Tue May 12 10:59:55 2020

Idealized estimate of what a 1D lineout radially through a cylindrical foam + tube would look like. This is to assist in correctly identifying which features in a radiograph correspond to which part of the target for spatial magnification calculation.

@author: Pawel M. Kozlowski

Functions

chord(radius, height)	Calculates the horizontal chord length through a circle at a given height.
tubeThickness(innerDiameter, outerDiameter, ...)	Calculates the chord lengths through the inner region (foam) and outer region (tube wall) for a given target.
transmission(density, opacity, length)	Calculates the transmission through a uniform material of given density, opacity, and length.
tubeTransmission(innerDiameter, ...)	Calculates the transmission through a tube with foam at a given height (radial coordinate) through the tube.
plotTubeTransmission(innerDiameter, ...[, plots])	Generates a plot transmission versus radial coordinate through a tube.
gaussianBlur(heightsArr, transmissions, ...)	heightsArr : numpy.ndarray

Visualizations (xripl.visualizations)

Created on Mon Oct 22 16:44:47 2018

Convenience functions for visualizing radiographic data and processed data from XRIPL.

@author: Pawel M. Kozlowski

Functions

spatialConversion(img, px2Um, pxRef, umRef)	Generates spatial extents of image in micrometers, by using the image shape, pixel to micrometer conversion factor, and a reference position defined in both pixel and micrometer coordinates.
overlayTube(img, extent[, method])	Overlays known coordinates of tube based on shock tube dimensions onto the given image.
cropImgCalibrated(img, px2Um, pxRef, umRef, ...)	Crops the image and provides updated extents for spatial calibration of the image.
rotateImgCalibrated(img, px2Um, pxRef, umRef)	Rotates the image 90 degrees in counter clockwise direction, and provides updated extents for spatial calibration of the image.
lineoutsComparison1(imgRaw, imgDenoised, ...)	Plots normalized lineouts for raw, denoised, and cleaned iamges for comparison.
lineoutsComparison2(imgDenoised, imgFlat, px)	Compares pseudo-flatfielded lineout against denoised lineout.

Indices and tables

• Index

• Module Index

• Search Page