File Exchange

image thumbnail

maxsich/loadSPE

version 2.7.0.0 (34.2 KB) by Maksym Sich
Load data from .SPE files (full support v2.x & v3.0) created by PI software (LightField, WinSpec).

1 Download

Updated 28 Mar 2018

GitHub view license on GitHub

Load data from .SPE files created by Princeton Instruments software (LightField, WinSpec). Full support for v2.x & v3.0 multi-frame, multi-ROI files and header information.
[data, wavelengths, params] = loadSPE( filename )
*data*
If the file has only one ROI and one frame then data is a simple (2D) array. If the file has one ROI but several frames then data is a 3D array of dimensions ( height, width, number of frames).
If the file has several ROIs then the data variable will look different for v2.x and v3.x spe files due to the difference in how the data is stored.
For v3.x if the file has one frame and several ROIs data is a struct data.ROI{numOfROIs}( height, width). If the file has several frames and several ROIs in each frame then data is an array of structs data (numOfFrames).ROI{numOfROIs}( height, width).
For v2.x the data will be either a 2D or 3D array, depending on the number of frames. Then params.ROI will contain a struct with info on sizes of ROIs and location on the full frame, which then can be individually extracted. This may be added in the future releases
*params*
params.version contains version info of the file. For SPE v3.x the whole XML footer is parsed as a struct in params.SpeFormat.
SPE v3.0 file and XML specification is at ftp://ftp.princetoninstruments.com/public/Manuals/Princeton%20Instruments/SPE%203.0%20File%20Format%20Specification.pdf.
For the SPE v2.x all parameters were stored in file header some of the key parameters are stored directly in the 'root' of the params struct:
params.ROI
params.xdim
params.ydim
params.xlabel
params.ylabel
params.dlabel
params.SpecGrooves
params.ExperimentTimeLocal
params.date
params.exp_sec
Full set of parameters are stored in params.full except for x and y calibrations which are stored separately as params.xcalib and params.ycalib. Full specification of the SPE v2.x header is available at
ftp://ftp.piacton.com/Public/Manuals/Princeton%20Instruments/WinSpec%202.6%20Spectroscopy%20Software%20User%20Manual.pdf.
*wavelengths*
For SPE v2.x is a single 1D array defined by either x-axis or y-axis calibration, whichever is present in the file using the polynomial
method.
For SPE v3.x wavelengths is a 1D array if there is a single ROI or a cell array of 1D arrays corresponding to the different ROIs

Examples:
- 1 frame and 1 ROI per frame
[ d, w, ~] = loadSPE( 'example.spe' );
plot( w, d );

- 1 frame and several ROIs per frame. Some ROIs are 1D spectra, some are
2D images of CCD
[ d, w, ~] = loadSPE( 'example2.spe' );
for i = 1 : length( w )
[ x, y ] = d.ROI{i}';
if y == 1 %1D spectra
plot( w{i}, d.ROI{i} );
else %2D image
imagesc( w{i}, 1:y, d.ROI{i}' );
% or could simply plot pixels imagesc( d.ROI{i}');
end
end

Copyright
XML parsing is implemented using functions based on https://mathworks.com/matlabcentral/fileexchange/28518-xml2struct, written by W. Falkena, modified by A. Wanner, I. Smirnov, X. Mo. xml2struct (C) 2012, W. Falkena

(C) 2018, M. Sich, The University of Sheffield
v2.7 27-03-2018

Cite As

Maksym Sich (2019). maxsich/loadSPE (https://www.github.com/maxsich/loadSPE), GitHub. Retrieved .

Comments and Ratings (4)

Maksym Sich

@Yau Chuen Yiu, I've updated the code to enable checking for invalid XML characters in the footer. However, I should mention that the error you got comes from the native MATLAB xmlread function when it encounters those invalid (by specification) characters. So it is likely that the file you are trying to read might be corrupted or LightField is not properly configured since the error pops up in the description of the camera model, which is set to 'null', and would be typically one of the PI's cameras (e.g. 'PIXIS: 256E' which is stored in 'SpeFormat.DataHistories.DataHistory.Origin.Experiment.System.Cameras.Camera.Attributes.model'). Hope this helps.

Thank you for developing the code.

I got the below error message when I try to load a SPE v3.0 file in matlab R 2016b

[Fatal Error] tp66be79ec_9825_4c61_97cc_51fd91539811.xml:1:32288: An invalid XML character (Unicode: 0x0) was found in the value of attribute "model" and element is "Camera".

Error using xmlread (line 106)
Java exception occurred:
org.xml.sax.SAXParseException; systemId:
file:/C:/Users/AppData/Local/Temp/tp66be79ec_9825_4c61_97cc_51fd91539811.xml;
lineNumber: 1; columnNumber: 32288; An invalid XML character (Unicode: 0x0) was found in the
value of attribute "model" and element is "Camera".

at org.apache.xerces.parsers.DOMParser.parse(Unknown Source)

at org.apache.xerces.jaxp.DocumentBuilderImpl.parse(Unknown Source)

at javax.xml.parsers.DocumentBuilder.parse(Unknown Source)

Error in loadSPE (line 118)
xmlTreeObject = xmlread(filename);

Maksym Sich

@Tullio Barbui, I think I pinned down the error. So, should work in v2.5

I get the following error when I try to load a SPE v3.0 file (MATLAB R2016b)

[Fatal Error] tp7630f94f_9bbe_44dd_a416_0ada2e5c288d.xml:1:1: Content is not allowed in prolog.
Error using xmlread (line 106)
Java exception occurred:
org.xml.sax.SAXParseException; systemId: file:/tmp/tp7630f94f_9bbe_44dd_a416_0ada2e5c288d.xml; lineNumber: 1; columnNumber: 1; Content is not allowed
in prolog.
at org.apache.xerces.parsers.DOMParser.parse(Unknown Source)
at org.apache.xerces.jaxp.DocumentBuilderImpl.parse(Unknown Source)
at javax.xml.parsers.DocumentBuilder.parse(Unknown Source)

Error in loadSPE (line 118)
xmlTreeObject = xmlread(filename);

Updates

2.7.0.0

Added checking for invalid characters in XML footer. Check for known invalid XML characters, such as 0x0 (null), and replace them with spaces (0x32).

2.6.0.0

Fixed an error where in v3.0 files 2D data was not correctly exported.

2.5.0.0

Fixed an error when in some cases XML failed to parse properly

2.4.0.0

Corrected check for 'WavelengthMapping' in v3.0 SPE XML

2.3.0.0

Corrected bug function would crash with v3.0 files without calibration

2.2.0.0

Optimised code

2.1.0.0

Corrected error where sensor's start x=0 resulted in a crush. With no ROI or binning sensor starting, x is set to 0, while in MATLAB has to be 1. Added checking this value. and shifting by 1. Applies to SPE v3.0 files

2.0.0.0

Updated description

2.0.0.0

Added complete support for v2.x headers and multiple ROIs and some basic logic extracting wavelengths calibrations (for v2.x).

MATLAB Release Compatibility
Created with R2012b
Compatible with any release
Platform Compatibility
Windows macOS Linux
Acknowledgements

Inspired by: xml2struct, xml2struct