The Advanced Photon Source
a U.S. Department of Energy Office of Science User Facility


rsMap3D allows examining a volume of data so that users can select portions of the data, apply transformations needed to map from diffractometer geometry into reciprocal space, mapping detector pixels onto a reciprocal space grid. Data are collected using spec macros to drive diffractometer axes through a predefined volume of reciprocal space.The acquisition process yields a spec data file, which contains information about the scan, including details of the diffractometer angles scanned, and a series of TIFF image files stored in a well-defined directory structure.However, the information stored in the spec and TIFF image files lacks information on instrument and detector geometry, so specifications that provide this information are stored in auxiliary XML files (one each for instrument and detector geometries).

rsMap3D provides a user interface for users to specify the spec data file and the instrument geometry.On reading the information stored in these files, the user is presented with a 3D representation of the data volume, allowing the user to select which parts of the collected data should be processed into the 3D reciprocal space map.rsMap3D uses external python packages pyspec, for reading the spec data file, and xrayutilities, for providing the transformation of diffractometer angles into reciprocal space coordinates.Once the user selects which data will be processed, the user can map pixel data from the detector into a 3D reciprocal space grid.This grid is saved as a VTK data file.

Once data is processed, it can be viewed and manipulated by any application that can read the VTK data format, such as ParaView. ParaView allows the user to easily read VTK data files and allows the user to manipulate and view the data using a number of included filters or using user supplied filters.Filters included with ParaView allow the user to easily produce 3D contour plots, make slices through the data using plane cuts or cuts on the surface of a defined sphere (for constant |Q| cuts).
Distribution & Impact

rsMap3D is used on data collected at the 33-BM-C, 33-ID-D, and 13-BM-C beamlines at APS.

The home page for rsMap3D is here. It is distributed as a Python pip package (see Linux, Windows and Mac OS X installation instructions). The source code for rsMap3D is available from Github.



Funding Source

This project has been produced using operational funding from the APS, contract DE-AC02-06CH11357.


Future Work
  • Provide processing of Energy scan data from 34-ID-E (stationary geometry).
  • Process scanned data in HDF files (scan data, image data and geometry in a single file).



The application rsMap3D has been developed as a collaboration between the Software Services Group in the APS Engineering Services Division and the Surface Scattering and Microdiffraction Group in the X-Ray Science Division. In particular, John Hammonds (SSG-AES) and Christian Schlepütz (SSM-XSD) have been the main contributors. 

rsMap3D also makes use of two external Python libraries from the x-ray scattering community: xrayutilities and pyspec. 

The package xrayutilities has been developed by Dominik Kriegner (Johannes Kepler University Linz) and Eugen Wintersberger (DESY) and is used to provide conversion between diffractometer geometry and reciprocal space.It also provides a means to merge and re-grid data from collected images into a 3D block of reciprocal space.

The package pyspec has been developed by Stuart Wilkins (BNL) and is used to read Spec files produced during the scan process.Spec is a standard experiment control package from Certified Scientific Software and is currently used to control scans at many APS beamlines.

A number of other standard Python packages are being used in this project:

  • numpy – for array manipulations
  • PyQt – to build the main GUI of rsMap3D
  • Vtk- for 3D visualization of 3D volume over which data was collected

This project also relies on an external package called ParaView from Kitware Inc. to view 3D maps of reciprocal space.ParaView allows easy reading/slicing of VTK data files.