sandialabs / SpecUtils

A library for opening, manipulating, and exporting gamma spectral files
GNU Lesser General Public License v2.1
27 stars 9 forks source link
scr-2173 snl-data-analysis

SpecUtils

SpecUtils is a library for opening, manipulating, and exporting spectrum files produced by RadioIsotope Identification Devices (RIIDs), Radiation Portal Monitors (RPMs), radiation search systems, Personal Radiation Detectors (PRDs), and many laboratory detection systems. It opens N42 (2006 and 2012 formats), SPE, SPC, CSV, TXT, PCF, DAT, and many more files; altogether more than a 100 file format variants. The library lets you either programmatically access and/or modify the parsed information, or you can save it to any of 13 different formats.

SpecUtils provides the spectrum file format capabilities for Cambio, InterSpec, and number of other applications and websites. The library is written in cross-platform (tested on Windows, macOS, Linux, iOS, and Android) c++ with Python and Java bindings.

Using SpecUtils

If all you need is to convert spectrum files from your detector to a format you can work with, like CSV or N42, try using the command line version of Cambio - this is actually probably the most common way people and programs use SpecUtils.

But if you want to integrate SpecUtils into your program, you will need a c++11 capable compiler, boost (≥1.42), and cmake (≥3.1.). Linking your program to SpecUtils uses the standard CMake syntax, for example in your CMakeLists.txt file you would add the lines:

add_subdirectory( path/to/SpecUtils )
...
target_link_libraries( MyExe PRIVATE SpecUtils )

A minimal program to print out the channel counts of a spectrum file, and then save as a CSV data file, could then be:

#include  <stdlib.h>
#include  <iostream>
#include  "SpecUtils/SpecFile.h"

int main() {
  SpecUtils::SpecFile specfile;
  if( !specfile.load_file("input.n42", SpecUtils::ParserType::Auto) )
    return EXIT_FAILURE;

  for( int sample : specfile.sample_numbers() ) {
    for( std::string detector : specfile.detector_names() ) {
      std::shared_ptr<const SpecUtils::Measurement> meas = specfile.measurement( sample, detector );
      std::cout << "Sample " << sample << " detector " << detector
                << " has live time " << meas->live_time() << "s and real time "
                << meas->real_time() << "s with counts: ";
      for( size_t i = 0; i < meas->num_gamma_channels(); ++i )
        std::cout << meas->gamma_channel_content(i) << ",";
      std::cout << " with " << meas->neutron_counts_sum() << " neutrons" << std::endl;
    }
  }

  specfile.write_to_file( "outout,csv", SpecUtils::SaveSpectrumAsType::Csv );
  return EXIT_SUCCESS;
}

Relevant CMake Build options

Features

Testing

This library uses a few methods to test the code, but unfortunately still likely contains bugs or issues, especially related to specific file format variants.

The testing methods are:

History

SpecUtils started to extract live-time and channel counts from two very specific detectors, for a specific application. However, over time it was split out into its own library, and new file formats and capabilities have been continually bolted on as needs arose. As such there near continual smaller changes to the interface and when resources become available larger, refactorings (there are a number planned when possible in the future). Currently the library is developed primarily as part of InterSpec, but used by a number of other applications and websites.

Authors

William Johnson is the primary author of the library. Edward Walsh wrote the Java bindings and example program, as well as lead a substantial part of the QC effort. Christian Morte is the primary developer of the D3.js charting capability. Noel Nachtigal provided extensive additional support.

License

This project is licensed under the LGPL v2.1 License - see the LICENSE.md file for details

Copyright

Copyright 2018 National Technology & Engineering Solutions of Sandia, LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software.

Disclaimer

DISCLAIMER OF LIABILITY NOTICE:
The United States Government shall not be liable or responsible for any maintenance,
updating or for correction of any errors in the SOFTWARE or subsequent approved version
releases.

THE INTERSPEC (SOFTWARE) AND ANY OF ITS SUBSEQUENT VERSION
RELEASES, SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF
ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT
NOT LIMITED TO, ANY WARRANTY THAT THE SOFTWARE WILL CONFORM TO
SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY
WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY
THAT THE DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE
SOFTWARE. IN NO EVENT SHALL THE UNITED STATES GOVERNMENT OR ITS
CONTRACTORS OR SUBCONTRACTORS BE LIABLE FOR ANY DAMAGES,
INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL OR
CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANY
WAY CONNECTED WITH THE SOFTWARE OR ANY OTHER PROVIDED
DOCUMENTATION, WHETHER OR NOT BASED UPON WARRANTY, CONTRACT,
TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY
PERSONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS
SUSTAINED FROM, OR AROSE OUT OF THE RESULT OF, OR USE OF, THE
SOFTWARE OR ANY PROVIDED DOCUMENTATION. THE UNITED STATES
GOVERNMENT DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING
THIRD PARTY SOFTWARE, IF PRESENT IN THE SOFTWARE, AND DISTRIBUTES
IT "AS IS."

Acknowledgement

This InterSpec Software was developed with funds from the Science and Technology Directorate of the Department of Homeland Security

InterSpecSCR# 2173.1