updategeostruct

Convert line or patch display structure to geostruct

Syntax

geostruct = updategeostruct(displaystruct)
geostruct = updategeostruct(displaystruct, str)
[geostruct,symbolspec] = updategeostruct(displaystruct, ...)
[geostruct,symbolspec] = updategeostruct(displaystruct, ..., cmap)

Description

geostruct = updategeostruct(displaystruct) accepts a Mapping Toolbox™ display structure displaystruct. If displaystruct is a vector display structure for which the 'type' field has value 'line' or 'patch', updategeostruct restructures its elements to create a geostruct, geostruct. If displaystruct is an already geographic data structure, it is copied unaltered to geostruct. updategeostruct does not update display structure arrays of type 'text', 'light', 'regular', or 'surface'.

geostruct = updategeostruct(displaystruct, str) selects only elements whose tag field begins with the string scalar or character vector str (and whose type field is either 'line' or 'patch'). The selection is case insensitive.

[geostruct,symbolspec] = updategeostruct(displaystruct, ...) restructures a display structure and determines a symbolspec based on the graphic properties specified in the otherproperty field for each element of displaystruct and, if necessary, the jet colormap.

[geostruct,symbolspec] = updategeostruct(displaystruct, ..., cmap) specifies a colormap, cmap, to define the colors used in symbolspec.

Examples

Update and display a display structure of coastlines.

load coastlines
cmap = [0,0,0];
S = struct('lat',coastlat,'long',coastlon,'tag','coastlines', ...
  'type','line','altitude',[]);
[coastlines,spec] = updategeostruct(S,cmap);

figure
worldmap('world')
geoshow(coastlines,'SymbolSpec',spec)

Map of global coastlines

Tips

There are two Mapping Toolbox encodings for vector features that use MATLAB® structure arrays. In both cases there is one feature per array element, and in both cases a given array's elements all held the same type of feature. Version 1.3.1 and earlier of the Mapping Toolbox software only supported Mapping Toolbox display structures. Version 2.0 introduced a data structure for vector geodata which was less rigidly defined and more open-ended. The new structures are called geostructs (if they contain geographic coordinate data) and mapstructs (if they contain projected coordinate data). Over time, display structures are being phased out of the toolbox; the updategeostruct function is provided to help users migrate from the old display structure format to the current geostruct/mapstruct format.

A Version 1 Mapping Toolbox display structure is a MATLAB structure that can contain line, patch, text, regular data grid, geolocated data grid, and light objects. The displaym function does not accept geostructs produced by Version 2 of the Mapping Toolbox software.

Display structures for lines and patches and Line and Polygon geostructs have the following things in common:

  • A field that specifies the type of feature geometry:

    • A type field a display structure (value: 'line' or 'patch')

    • A Geometry field for a geostruct (value: 'Line' or 'Polygon')

  • A latitude field:

    • lat for a display structure

    • Lat for a geostruct

  • A longitude field:

    • long for a display structure

    • Lon for a geostruct

In terms of their differences,

  • A geostruct has a BoundingBox field; there is no display structure counterpart for this

  • A geostruct typically has one or more “attribute” fields, whose values must be either scalar doubles or character vectors, with arbitrary field names. The presence or absence of a given attribute field—and its value—is dependent on the specific data set that the geostruct represents.

  • A (line or patch) display structure has the following fields:

    • A tag field that names an individual feature or object

    • An altitude coordinate array that extends coordinates to 3-D

    • An otherproperty field in which MATLAB graphics can be specified explicitly, on a per-feature basis

Object properties used in the display are taken from the otherproperty field of the structure. If a line or patch object's otherproperty field is empty, displaym uses default colors. A patch is assigned an index into the current colormap based on the structure's tag field. Lines are assigned colors from the current color order according to their tags.

The newer geostruct representation has significant advantages:

  • It can represent a much wider range of attributes (display structures essentially can represent only a feature name).

  • The geostruct representation (in combination with geoshow and makesymbolspec) keeps graphics display properties separate from the intrinsic properties of the geographic features themselves.

For example, a road-class attribute can be used to display major highways with a distinctive color and greater line width than secondary roads. The same geographic data structure can be displayed in many different ways, without altering any of its contents, and shapefile data imported from external sources need not be altered to control its graphic display.

For information about the display structure format, see Version 1 Display Structures in the reference page for displaym. For a discussion of the characteristics of geographic data structures, see Geographic Data Structures.

Version History

Introduced before R2006a

See Also

| | | |