GBLoadWave

GBLoadWave [flags] fileNameStr

The GBLoadWave operation loads data from a binary file into waves.

For more complex applications such as loading structured data into Igor structures see the FBinRead operation.

Parameters

If fileNameStr is omitted or is "", or if the /I flag is used, GBLoadWave presents an Open File dialog from which you can choose the file to load.

If you use a full or partial path for fileNameStr, see Path Separators for details on forming the path.

Flags

/A	Automatically assigns arbitrary wave names using "wave" as the base name. Skips names already in use.
/A=baseName	Same as /A but it automatically assigns wave names of the form baseName0, baseName1.
/B=b	Tells GBLoadWave the byte order used for multi-byte data (shorts, longs, floats and doubles).
	b=0: Bytes in data in high-byte-first (Motorola) format. This is the default (used if /B is omitted). b=1: Bytes in data in low-byte-first (Intel) format.
	Just /B is equivalent to /B=1. Do not use /B for VAX floating point.
/D=d	New programming should use the /T flag instead of the /D, /L and /F flags.
	d=0: Creates single-precision waves. d=1: Creates double-precision waves.
	/D by itself is equivalent to /D=1.
/F=f	New programming should use the /T flag instead of the /D, /L and /F flags.
	f specifies the data format of the data in the file:
	f=1: Signed integer (8, 16, 32 bits allowed) f=2: Unsigned integer (8, 16, 32 bits allowed) f=3: Floating point (default, 32, 64 bits allowed)
/FILT=fileFilterStr	Provides control over the file filter menu in the Open File dialog. This flag was added in Igor Pro 7.00.
	The construction of fileFilterStr is the same as for the /F=fileFilterStr flag of the Open operation. See Open File Dialog File Filters for details.
/I[={macFilterStr , winFilterStr }]
	Specifies interactive mode which displays the Open File dialog.
	In Igor 7 and later, the macFilterStr and winFilterStr are ignored. Use the /FILT flag instead.
/J=j	Specifies how input floating point data is interpreted.
	j=1: IEEE floating point (default) j=2: VAX floating point
/L=length	New programming should use the /T flag instead of the /D, /L and /F flags.
	length specifies the data length of the data in the file in bits (default = 32). Allowable data lengths are 8, 16, 32, 64.
/N	Same as /A except that, instead of choosing names that are not in use, it overwrites existing waves.
/N=baseName	Same as /N except that Igor automatically assigns wave names of the form baseName0, baseName1.
/O=o	Controls overwriting of waves in case of a name conflict.
	o=0: Use unique wave names. o=1: Overwrite existing waves.
	/O by itself is equivalent to /O=1.
/P=pathName	Specifies the folder to look in for fileNameStr. pathName is the name of an existing symbolic path.
/Q=q	Controls messages written to the history area of the command window.
	q=0: Write messages. q=1: Suppress messages.
	/Q by itself is equivalent to /Q=1.
/S=s	s is the number of bytes at the start of the file to skip. It defaults to 0.
/T={fType , wType }	Specifies the data type of the file (fType ) and the data type of the wave or waves to be created (wType ). The allowed codes for both fType and wType are:
	2: Single-precision floating point 4: Double-precision floating point 8: 8-bit signed integer 16: 16-bit signed integer 32: 32-bit signed integer 128: 64 bit signed integer (Igor 7 or later) 72: 8-bit unsigned integer (8+64) 80: 16-bit unsigned integer (16+64) 96: 32-bit unsigned integer (32+64) 192: 64 bit unsigned integer (128+64) (Igor 7 or later)
/U=u	Specifies the number of points of data per array in the file.
	The default is 0 which means "auto". In this case GBLoadWave calculates the number of data points per array based on the number of bytes in the file, the number of bytes to be skipped at the start (/S flag), and the number of arrays in the file (/W flag).
/V=v	Specifies interleaving of data in the file.
	v=0: Data in file is not interleaved (default) v=1: Data in file is interleaved
	/V by itself is equivalent to /V=1.
/W=w	Specifies the number of arrays in the file. The default is 1.
	If you omit /W but specify the number of points per data array in the file via /U then GBLoadWave calculates the number of waves to be loaded based on the number of bytes in the file, the number of bytes to be skipped at the start (/S flag), and the specified number of points per data array in the file (/U flag). Therefore, if you specify /U and want to load just one wave you must also specify /W=1.
/Y={offset , mult }	Data loaded into waves is scaled using offset and mult :
	output data = (input data + offset) * multiplier
	This is useful to convert integer data into scaled, real numbers.

Details

The /N flag instructs Igor to automatically name new waves "wave" (or baseName if /N=baseName is used) plus a number. The number starts from zero and increments by one for each wave loaded from the file. If the resulting name conflicts with an existing wave, the existing wave is overwritten.

The /A flag is like /N except that Igor skips names already in use.

The /T flag allows you to specify a data type for both the input (data in the file) and the output (data in the waves). You should use the /T flag instead of the /D, /L and /F flags. These flags are obsolete but are still supported.

GBLoadWave Open File Dialog

If you include the /I flag, or if the /P=pathName flag and the fileNameStr parameter do not fully specify the file to be loaded, GBLoadWave displays the Open File dialog.

The /FILT=fileFilterStr provides control over the file filter menu in the Open File dialog. This flag was added in Igor Pro 7.00. The construction of fileFilterStr is the same as for the /F=fileFilterStr flag of the Open operation. See Open File Dialog File Filters for details.

In Igor 7 and later, the macFilterStr and winFilterStr parameters of the /I flag are ignored. Use the /FILT flag instead.

Output Variables

GBLoadWave sets the following variables:

V_flag	Number of waves loaded.
S_fileName	Name of the file being loaded.
S_path	File system path to the folder containing the file.
S_waveNames	Semicolon-separated list of the names of loaded waves.

S_path uses Macintosh path syntax (e.g., "hd:FolderA:FolderB:"), even on Windows. It includes a trailing colon.

When GBLoadWave presents an Open File dialog and the user cancels, V_flag is set to 0 and S_fileName is set to "".

Examples

// Load 128 point single precision version 2 Igor binary wave file
GBLoadWave/S=126/U=128 "fileName"

// Load 8 256 point arrays of 16 bit signed integers into single-precision waves
// after skipping 128 byte header
GBLoadWave/S=128/T={16,2}/W=8/U=256 "fileName"

// Load n 100 point arrays of double-precision floating point numbers
// into double-precision Igor waves with names like temp0, temp1, etc,
// overwriting existing waves. n is determined by the number of bytes
// in the file.
GBLoadWave/O/N=temp/T={4,4}/U=100 "fileName"

// Load a file containing a 1024 byte header followed by a 512 row
// by 384 column array of unsigned bytes into an unsigned byte matrix
// wave and display it as an image
GBLoadWave/S=1024/T={8+64,8+64}/N=temp "fileName"
Rename temp0, image
Redimension/N=(512,384) image
if (<file uses row-major order>)
	MatrixTranspose image
endif
Display; AppendImage image

"Row-major order" relates to how a 2D array is stored in memory. In row-major order, all data for a given row is stored contiguously in memory. In column-major order, all data for a given column is stored contiguously in memory. Igor uses column-major order but row-major is more common.

See Also

Loading General Binary Files

See the FBinRead operation for more complex applications such as loading structured data into Igor structures.