Import Lispix Raw formatted image. The Lispix Raw File Format was developed at the National Institute of Standards and Technology (NIST).
- imagedso = lispixrawreadr(filename)
In Solo+MIA, or from an Analysis window, this may be accessed using the menu: "File"->"Import Data"->"X-Block"->"Lispix Raw Formatted Image (RAW)", and selecting the file to import. When using PLS_Toolbox it is necessary to also have MIA_Toolbox installed to access this image-oriented data format.
Read in a Lispix Raw image file. The .raw data file consists of an uncompressed string of numbers all saved in the same format, for example one byte per number. See Lispix for software related to Lispix Raw image files.
.raw and .rpl Files
The data are stored in the .raw file while information about layout of the raw data file contents, etc, are stored in a second .rpl file. Thus, the file format consists of two files: a data file (.raw) and a raw parameter list file (.rpl), where the two files are named similarly with only the extension being different. The filename input to LISPIXRAWREADR can point to either the .raw or the .rpl file.
Note that this file format is different from the Physical Electronics .raw file and also different from the RAW files output by some digital cameras.
The Lispix RAW file format is described at: http://www.nist.gov/lispix/doc/image-file-formats/raw-file-format.htm Please see this for details of the .raw and .rpl file formats. If this link is inaccessible then the raw-file-format.htm file is available by downloading https://www.nist.gov/sites/default/files/documents/2017/03/28/lx249p.exe, in Lx249P\doc\image-file-formats\raw-file-format.htm.
Standard LISPIX Parameters in .rpl File
A typical .rpl file contain 9 lines, where there is one tab (and possibly extra spaces) between the parameter name and parameter value. Parameter names are case-insensitive. The first line is "key <tab> value", and the following 8 lines identify parameters and their values in the form <param-name> <tab> <param-value>. For example:
key value description width 849 # pixels per row integer height 846 # rows integer depth 4096 # images or spec pts integer offset 0 # bytes to skip integer data-length 1 # signed, unsigned, or float data-type unsigned # bytes per pixel 1, 2, 4, or 8 byte-order dont-care # big-endian, little-endian, or dont-care record-by vector # image, vector, or dont-care
This .rpl file indicates the image is 849 pixels wide and 846 pixels high, with 4096 levels in the depth dimension.
When depth is 1, the file has one image, record-by is not relevant and should be dont-care. For spectral images, record-by is vector. For stacks of images, record-by is image.
In addition to these 8 Lispix standard parameter names the LISPIXRAWREADR importer recognizes the following non-standard parameters names which may be specified on extra lines in the .rpl file. These parameters allow reading only a sub-rectangle of the image in height and width and reducing the resolution in the depth dimension. This is useful when reading large images on a system with a small amount of memory (RAM). These additional parameter names are:
- depthbinsize : number of points per bin in the depth dimension. For example, a value of 4 means the depth dimension is reduced by x4.
- width1 : lower width pixel
- width2 : upper width pixel. Read data between width1 and width2, inclusive, in the width dimension.
- height1 : lower height pixel.
- height2 : upper height pixel. Read data between height1 and height2, inclusive, in the height dimension.
- depth1 : lower depth level.
- depth2 : upper depth level. Read data between depth1 and depth2, inclusive, in the depth dimension.
- depthscaleorigin : Origin of axisscale for depth dimension
- depthscaleincrement : Increment for depth axisscale
- depthscaleunits : Units symbol for depth axisscale
The compression in the depth dimension is achieved by averaging bins of "depthbindsize" points. Use a text file editor which does not add special formatting content to the file when making changes to the .rpl file (For example, use Textpad (Windows) but do not use Microsoft Word).
The following lines could be added to the example .rpl file above to read a sub-rectangle of the image and to reduce the depth dimension by a factor of 20:
depthbinsize 2 width1 200 width2 600 height1 200 height2 500 depth1 300 depth2 2999 depthscaleorigin 0 depthscaleincrement 0.02 depthscaleunits keV
For this example LISPIXRAWREADR loads an image dataset object where the image size is 301x401 (301 pixesl high, 401 pixels wide) and 1350 layers deep ((2999-300+1)/2, rounded). An axis scale is specified for the depth dimension which ranges from 0 to 81.92 (=4096*0.02), with units of "keV", but for the sub-range of depth specified it ranges from 4.49 to 58.45 keV.
- filename = file name to read, either the .raw or .rpl file.
- imagedso = an image DataSet object containing the image read from the input file.