User's Reference - Map

### Map

Category

Transformation

Function

Applies a map to a field or value list.

Syntax

    output = Map(input, map, source, destination);

Inputs

Name | Type | Default | Description
--- | --- | --- | ---
`input` | field, value, or value list | none | field to be mapped
`map` | scalar, vector, or field | identity | map to be used
`source` | string | "positions" | component used as index into map
`destination` | string | "data" | component in which to place the interpolated data.

Outputs

Name | Type | Description
--- | --- | ---
`output` | field, value, or value list | mapped input field

Functional Details

Map is a general purpose module which maps from one field to another.

`input` | is the field or value list to which `map` is applied.
`map` | is the map to be applied to the input object. Unless this parameter specifies a single value, it should contain both a "positions" and a "data" component. Because the module performs interpolation, the map it applies to the input must also contain either (1) a "connections" component or (2) "faces," "loops," and "edges" (see "Faces, Loops, and Edges Components" in IBM Visualization Data Explorer User's Guide). The "data" component may be dependent on "positions," "connections," or "faces." (If the field contains faces, loops, and edges, the data must be dependent on faces.)
`source` | specifies the component of `input` that is to be used for indexing into the "positions" component of `map`. The value of the corresponding "data" in `map` is determined by interpolation between the "positions" in `map`, using the interpolation elements of `map` (either "connections" or "faces", "loops", and "edges"). `source` is ignored if `input` is a value list.
`destination` | specifies the `output` component in which interpolated values should be placed. If `input` is a value list, then the interpolated values simply replace the values in `input`.

The Map module steps through the `source` component of `input`. For each item in that component, the module looks up that value in the "positions" component of `map` and finds the corresponding value in the "data" component of `map`, interpolating if necessary. The resulting value is placed in the `destination` component of `output` (see Figure 3).

Figure 3. Mapping from one field to another. This figure shows an input field and a map field, both with two-dimensional positions and triangle connections. The figure shows how a data value is found for the position (a,b) in the input field by interpolating in the map field when the parameters to the Map module are `input`= Input Field, `map`= Map Field, and `source` and `destination` default to "positions" and "data" respectively.

As with all maps in Data Explorer, the map field must have "positions", "data", and "connections". Since the `source` component is "positions", the "positions" component of `input` is used to index into the "positions" component of `map`. Thus we lookup the position (a,b) in the map field. This leads us to the triangle connecting positions 0, 1, and 2 in the map field. The data values corresponding to positions 0, 1, and 2 are interpolated to yield the result 1.3, which is then placed in the "data" component of the output of Map (since `destination` is "data").

So, for example, if `source` is "positions," `destination` is "data," `input` is an isosurface, and `map` is a 3-D field with temperature values, then Map steps through the "positions" component of the isosurface and finds the temperature value for each position, interpolating if necessary. The resulting temperature value is placed in the "data" component of the output field.

If `map` is a value, the Map module adds to `output` a `destination` component that (1) contains one element for each element of the `source` component and (2) derives its dependency from the `source` component. All elements in this component have the value given them by `map`.

The following table summarizes some of the uses of Map.

Source | Destination | Use
--- | --- | ---
"data" | "colors" | color mapping
"positions" | "data" | data mapping
"data" | "data" | arbitrary tabular function

Notes:

1. The dimensionality of the positions in `input` and in `map` must agree and must also match the dimensionality of the connections in `map`. That is, if `map` has 2-D connections (quads or triangles), the positions must also be 2-D.
2. There are few constraints on Map' functionality. For instance, the Color module is generally preferable for performing mapping, because that module prevents the formation of invalid colors, whereas Map does not.

Components

If `input` is a field, a new component name, specified by `destination`, is created. All other input components are propagated to the output.

If `input` is an array, the output is an array.

If any `source` values cannot be interpolated, an "invalid positions" or "invalid connections" component (depending on the dependency of the `source` parameter) will be created, and values that are not interpolated will be marked invalid.

Example Visual Programs

    AlternateVisualizations.net
    Interop.net

    ManipulateGroups.net

    MappedIso.net
    PlotTwoLines.net
    Thunder_cellcentered.net
    UsingMap.net
    SIMPLE/Map.net

See Also

AutoColor, Color, MapToPlane

[ OpenDX Home at IBM | OpenDX.org ]