Lispixrawreadr

From Eigenvector Research Documentation Wiki
Jump to navigation Jump to search

Purpose

Import Lispix Raw formatted image. The Lispix Raw File Format was developed at the National Institute of Standards and Technology (NIST).

Synopsis

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.

Description

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.

Additional Parameters

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.

Inputs

  • filename = file name to read, either the .raw or .rpl file.

Outputs

  • imagedso = an image DataSet object containing the image read from the input file.

See Also

buildimage, rawread