Synopsis
Reads in a field file and outputs fields. See Field File Format. For information on using time-dependant fields see Reading In All Data and Writing Out Time-Dependent Fields.
Input Ports
Parameters
Output Ports
Description
The Read_Field module reads in a field file (identified by the extension .fld) and converts its contents into the appropriate Fld structure. This module can read in files containing either standard (single-step) data or time-dependent (multistep) data.
When you open Read_Field initially, its user interface contains only a set of objects for the parameters from Portable (XDR) through Field Filename. If you input a field file containing standard data, the module processes the data one step at a time, writing it to the field port as the appropriate Fld structure. It also outputs a renderable version of the data to the out_obj port.
If you input a field file containing time-dependent data, the module adds to its user interface a set of objects for the parameters from Store All Steps through Bounce. You use the Store All Steps parameter as the primary tool for controlling how the module reads in and processes the step data.
If you turn off Store All Steps (the default), Read_Field processes the step data one step at a time as specified by the Step Forward through Bounce parameters, then outputs it to the field port as the appropriate Fld structure.
If you turn on Store All Steps, Read_Field reads in the step data for all of the steps simultaneously and stores it in memory, rather than accessing the file for each step. It then outputs the step data, in a fast and continuous manner, to the time_field port as a time-dependent Fld structure.
Note that while processing time-dependent data in store-all-steps mode saves time, it uses more memory. This may be a problem when you process field files that contain large quantities of time-dependent data and/or many steps. To determine whether you should use store-all-steps mode, proceed as described in the following process:
1. Input to Read_Field the field file that contains time-dependent data. The module adds to its user interface the objects from Store All Steps through Bounce, with the Store All Steps button turned off. Read_Field now reads in the data corresponding to the first step and outputs it to the field port as the appropriate Fld structure.
2. Check the number of steps (displayed in the Total Steps object in the user interface) and determine whether there is enough memory to store all of them. If there is, turn on Store All Steps, otherwise leave it turned off.
If you turn on Store All Steps, all of the data (including the first step) is read in and stored in memory, then written to the time_field port as a time-dependent Fld structure, otherwise it is processed one step at a time and written to the field port as the appropriate Fld structure.
If the amount of memory used to store the data read in with Store All Steps is so large that it affects other operations, turn it off.
If you turn off Store All Steps:
Read_Field frees the memory used to store all of the step data and deletes the time-dependent data from the time_field output port.
The data corresponding to the first step is output to the field port.
Note: If you turn off the Store All Steps button, the button becomes invisible. You cannot turn it on again except by specifying the file to the Read_Field module again.
Additional considerations in the use of this module are as follows.
Each step in a field file can store time and comments. When step data is output to the time_field port, the time values are output in its time subobject.
If the time values are input as numbers, they are set as is in the time subobject.
If the time values are not input as numbers, they are specified in the time subobject as consecutive integers starting with 0.
In field data of the rectilinear type, the coordinates change from step to step. You cannot process data of this type in store-all-steps mode.
Renderable object data is output to the out_obj and title_obj ports only in the following cases:
You input a field file containing standard data (out_obj port only).
You input a field file containing time-dependent data but do not process it in store-all-steps mode (out_obj and title_obj ports).
Renderable object data is not output to these ports if you input a field file containing time-dependent data and process it in store-all-steps mode.
The Current Step through Bounce objects are added to the user interface only when you input a field file that contains time-dependent data and are relevant only when you do not process that data in store-all-steps mode. These parameters control how the step data is written to the field, out_obj, and title_obj ports (see their parameter descriptions later in this reference page).
Input Ports
ui_parent
Connects the module to a user interface object that contains the module's user interface objects. By default, this input port is connected to the default user interface object in the application in which the module is instanced.
Parameters
Portable(XDR)
A UItoggle object that specifies whether the data is in the machine-dependent XCR format.
If you enable this parameter when binary data is being read in, the machine assumes that the data is in XDR format. In this case, it ignores any other format specified in the ASCII file header.
If you disable this parameter, the machine assumes that the data is not in XDR format.
Swap Bytes
A UItoggle object that specifies whether the byte order is swapped when binary data is read in.
Enable this parameter to swap the byte order.
Disable this parameter to not swap the byte order.
This UItoggle object appears only if the Portable(XDR) UItoggle object is disabled.
Flip Image
A UItoggle object that specifies whether image data is inverted before it is output. Typically, image data is described with the upper-left corner as the starting point. As a result, when it is read in as field data, the image appears flipped vertically.
Enable this parameter to invert the data before outputting it.
Disable this parameter to not invert the data before outputting it.
Field Filename
Specifies the name of the file to be read in. You can either type it into the type-in area (UItext) or click on the Browse button (UIbutton) and select it using the file browser that opens.
Store All Steps
A UItoggle object that specifies how step data is read in and processed.
Enable this parameter to read in all of the steps simultaneously and store them in memory, then output them to the time_field port as a time-dependent field.
Disable this parameter to read in the steps one at a time and output them to the field port as a standard field.
This object appears only if the file specified with the Field Filename parameter contains time-dependent data.
Total Steps
A UIfield object containing UItext that specifies the total number of steps of time-dependent data. This object appears only if the file specified with the Field Filename parameter contains time-dependent data.
Current Steps
A UIfield object containing UItext that specifies the number of the step whose data is currently being output. To output the data corresponding to a particular step, enter a step number in the text box.
This object appears only if the file specified with the Field Filename parameter contains time-dependent data.
Step Forward
A UIbutton object that, when pressed, outputs the data for the next step. This object appears only if the file specified with the Field Filename parameter contains time-dependent data.
Step Backward
A UIbutton object that, when pressed, outputs the data for the previous step. This object appears only if the file specified with the Field Filename parameter contains time-dependent data.
One-time
A UItoggle object that specifies whether data is output continuously through the last step in the current set of steps.
Enable this parameter to output the data continuously.
Disable this parameter to not output the data continuously.
This object appears only if the file specified with the Field Filename parameter contains time-dependent data.
Continuous
A UItoggle object that specifies whether the data is output continuously from the first to last step of data and repeatedly for all sets of steps.
Enable this parameter to output the data continuously and repeatedly.
Disable this parameter to not output the data continuously and repeatedly.
This object appears only if the file specified with the Field Filename parameter contains time-dependent data.
Bounce
A UIbutton object that, when pressed, outputs the data continuously and repeatedly in bounce mode . In bounce mode, for n steps, the data is output from step 1 through step n and then down through step 1, repeatedly. For example, if there are three steps, the data is output in this order:
step 1
step 2
step 3
step 2
step 1
step 2
...
This object appears only if the file specified with the Field Filename parameter contains time-dependent data.
Output Ports
field
Output data in an appropriate Fld structure. The type depends on the value of the field attribute in the ASCII file header, as follows:
|
Field Value |
Output Field Type |
|
uniform |
Field_Unif |
|
rectilinear |
Field_Rect |
|
irregular |
Field_Struct |
Data is output to this port only if:
The file specified with the Field Filename parameter contains standard (single-step) data.
The file specified with the Field Filename parameter contains time-dependent (multistep) data but you do not process it in store-all-steps mode.
time_field
Output data in a time-dependent Fld structure. Data is output to this port only if the file specified with the Field Filename parameter contains time-dependent data and you process it in store-all-steps mode.
out_obj
A renderable version of the output field. Data is output to this port only if:
The file specified with the Field Filename parameter contains standard (single-step) data.
The file specified with the Field Filename parameter contains time-dependent (multistep) data but you do not process it in store-all-steps mode.
title_obj
A renderable text object containing the comment text for each step. If this output port is connected to a viewer module, this text object is displayed as a title. Data is output to this port only if the file specified with the Field Filename parameter contains time-dependent data but you do not process it in store-all-steps mode.
See Also