READ_BINARY

The READ_BINARY function reads the contents of a binary file using a passed template or basic command line keywords. Data is read from the given filename or from the current file position in the open file pointed to by FileUnit. If no template is provided, keywords can be used to read a single IDL array of data.

Examples

The following reads the data in a binary file, head.data, and passes the data to a volume display:

file = FILEPATH('head.dat', SUBDIR=['examples', 'data'])

vHeadData = READ_BINARY(file, DATA_DIMS=[80,100,57])

v = volume(vHeadData)

Syntax

Result = READ_BINARY ([Filename] | FileUnit [, TEMPLATE=template] [, DATA_START=value] [, DATA_TYPE=typecodes] [, DATA_DIMS=array] [, ENDIAN=string] [, /FLOAT16] )

Return Value

The result is an array or anonymous structure containing all of the entities read from the file.

Arguments

Filename

A scalar string containing the name of the binary file to read. If filename and file unit are not specified, a dialog allows the user to choose a file.

FileUnit

A scalar containing an open IDL file unit number to read from.

Keywords

DATA_DIMS

Set this keyword to a scalar or array of up to eight elements specifying the size of the data to be read and returned. For example, DATA_DIMS=[512,512] specifies that a two-dimensional, 512 by 512 array be read and returned. DATA_DIMS=0 specifies that a single, scalar value be read and returned. Default is -1, which, if a TEMPLATE is not supplied that specifies otherwise, indicates that READ_BINARY will read to end-of-file and store the result in a 1-D array.

DATA_START

Set this keyword to specify where to begin reading in a file. This value is as an offset, in bytes, that will be applied to the initial position in the file. The default is 0.

DATA_TYPE

Set this keyword to an integer giving the IDL typecode of the data to be read. See documentation for the SIZE function for a listing of typecodes. Default is 1 (IDL’s BYTE typecode). Possible values are:

Data_Type	Data Type
0	Undefined
1	Byte
2	Integer
3	Longword integer
4	Floating point
5	Double-precision floating
6	Complex floating
7	String
8	Structure
9	Double-precision complex
10	Pointer
11	Object reference
12	Unsigned Integer
13	Unsigned Longword Integer
14	64-bit Integer
15	Unsigned 64-bit Integer

ENDIAN

Set this keyword to one of three string values: “big”, “little” or “native” which specifies the byte ordering of the file to be read. If the computer running READ_BINARY uses byte ordering that is different than that of the file, READ_BINARY will swap the order of bytes in multi-byte data types read from the file. (Default: “native” = perform no byte swapping.)

FLOAT16

Set this keyword to treat the input data as 16-bit "half-precision" numbers. The data is assumed to be in IEEE 754 binary16/float16 format. If this keyword is set then the DATA_TYPE keyword is ignored. Once the data is read in, it will automatically be converted using the FLOAT16_DECODE function, and an array of 32-bit floating-point numbers will be returned.

TEMPLATE

Set this keyword to a template structure (created using the BINARY_TEMPLATE function) describing the file to be read. The TEMPLATE keyword cannot be used simultaneously with keywords DATA_START, DATA_TYPE, DATA_DIMS, or ENDIAN.

When a template is used with READ_BINARY, the return value is a structure containing fields specified by the template. If a template is not used, the return value is an array.

Additional Examples

Reading in a float16/binary16 data file

First construct a binary file containing every possible binary16/float16 number:

openw, lun, 'myfloat16.dat', /get_lun

writeu, lun, uindgen(65536)

free_lun, lun

Now read in those numbers as 16-bit "half-precision" binary16 numbers, automatically converting them to 32-bit floats:

data = read_binary('myfloat16.dat', /float16)

help, data

print, data[[0, 1, 0x8001, 0x3ff, 0x3c00, 0xbc00, 0x7bff, 0x7c00, 0xfc00, 0x7fff]]

IDL prints:

DATA   FLOAT   =  Array[65536]

0.00000   5.96046e-08   -5.96046e-08   6.09756e-05   1.00000   -1.00000   65504.0   Inf   -Inf   NaN

Tip: If you wanted to save the data back out as float16, you could use the FLOAT16_ENCODE function to convert the 32-bit floats back to 16-bit unsigned integers.

Working with a Binary Data Structure

The following example returns a structure containing the data in the surface.dat file, found in the examples/data subdirectory of the IDL installation directory.

Enter the following statement at the IDL command line to open the Binary Template dialog:

sTemplate = BINARY_TEMPLATE()

Complete the steps described in Using the BINARY_TEMPLATE Interface to define the format of the data.

Use READ_BINARY to access the data using the template, and then display it as a surface:

data = READ_BINARY(FILEPATH('surface.dat', $
   SUBDIRECTORY=['examples', 'data']), TEMPLATE = sTemplate)

s = surface(data.marbells)

Tip: Use the help command to display the sTemplate and data structures.

Displaying Binary Images

Binary images are composed of pixels having one of two values, usually zero or one. With most color tables, pixels having values of zero or one are displayed with almost the same color, such as with a the default grayscale color table. Thus, a binary image is usually scaled to display the zeros as black and the ones as white.

The following example imports a binary image of the world from the continent_mask.dat binary file. In this image, the oceans are zeros (black) and the continents are ones (white). This type of image can be used to mask out data over the oceans. The image contains byte data values and is 360 pixels by 360 pixels. The data is then displayed by scaling the values from 0 (off) to 255 (on).

file = FILEPATH('continent_mask.dat', SUBDIRECTORY = ['examples', 'data'])

data = READ_BINARY(file, DATA_DIMS = [360, 360])

i = image(data * 255)

Displaying a Grayscale Binary Image

Features within grayscale images are created by pixels that have varying intensities. Pixel values range from least intense (black) to the most instance (white). Since a grayscale image is composed of pixels of varying intensities, it is best displayed with a color table that progresses linearly from black to white. The following example imports a grayscale image from the convec.dat binary file. This grayscale image shows the convection of the Earth’s mantle. The image contains byte data values and is 248 pixels by 248 pixels. Since the data type is byte, this image does not need to be scaled before display. If the data was of any type other than byte and the data values were not within the range from 0 to 255, the image would need to be scaled prior to being displayed.

file = FILEPATH('convec.dat', SUBDIRECTORY = ['examples', 'data'])

data = READ_BINARY(file, DATA_DIMS = [248, 248])

i = image(data)

Version History

5.3	Introduced
9.1	Added FLOAT16 keyword