Class: Shapefile

Shapefile(url)

Parses a shapefile and creates shapes representing its contents. Points in the shapefile are represented by Placemarks, lines are represented by Paths or SurfacePolylines, and polygons are represented by Polygons or SurfacePolygons. A parser completion callback may be specified and is called when the shapefile is fully parsed but before shapes are created.

An attribute callback may also be specified to examine each record and configure the shape created for it. This function enables the application to assign independent attributes to each shape. An argument to this function provides any attributes specified in an attribute file (.dbf) accompanying the shapefile. That attribute file is automatically detected, retrieved and parsed along with the shapefile.

Constructor

new Shapefile(url)

Constructs a shapefile object for a specified shapefile URL. Call load to retrieve the shapefile and create shapes for it.
Parameters:
Name Type Description
url String The location of the shapefile.
Source:
Throws:
If the specified URL is null or undefined.
Type
ArgumentError

Members

(readonly) layer :RenderableLayer

The layer containing the shapes representing the records in this shapefile, as specified to this shapefile's constructor or created by the constructor if no layer was specified.
Type:
Source:

(readonly) parserCompletionCallback :function

The completion callback specified to load. This function is called when shapefile parsing is done but before creating shapes for the shapefile. It's single argument is this shapefile.
Type:
  • function
Default Value:
Source:

(readonly) shapeConfigurationCallback :function

The attribute callback specified to load. See that method's description for details.
Type:
  • function
Default Value:
Source:

(readonly) shapeType :String

The shape type of the shapefile. The type can be one of the following:
  • WorldWind.POINT
  • WorldWind.MULTI_POINT
  • WorldWind.POLYLINE
  • WorldWind.POLYGON
This value is defined during shapefile loading.
Type:
  • String
Source:

(readonly) url :String

The shapefile URL as specified to this shapefile's constructor.
Type:
  • String
Source:

Methods

addRenderablesForMultiPoints(layer)

Iterates over this shapefile's records and creates Placemarks for each point in the shapefile's multi-point records. One placemark is created for each point. Applications typically do not call this method directly. It is called by addRenderablesForShapefile.

This method invokes this shapefile's shapeConfigurationCallback once for each record. If that function returns null, the record is skipped. If it returns non-null, the returned value is assumed to be an object with any or all of the following optional properties:

  • attributes: A PlacemarkAttributes object to assign to the placemarks created for the record.
  • highlightAttributes: A PlacemarkAttributes object to assign to the highlight attributes of the placemarks created for the record.
  • altitudeMode: The altitude mode to apply to the created placemarks. If not specified, WorldWind.RELATIVE_TO_GROUND is used.
  • label: A String to assign as the created placemarks' label.
  • altitude: A Number indicating the altitude of the created placemarks. If not specified, the altitude of all created placemarks is 0.
  • name: A String to assign as the created placemarks' label.
  • pickDelegate: An object returned as the userObject when this feature is picked.
  • userProperties: An ad hoc object assigned to the renderable.
Parameters:
Name Type Description
layer RenderableLayer The layer in which to place the newly created shapes.
Source:
Throws:
If the specified layer is null or undefined.
Type
ArgumentError

addRenderablesForPoints(layer)

Iterates over this shapefile's records and creates Placemarks for the shapefile's point records. One placemark is created for each record. Applications typically do not call this method directly. It is called by addRenderablesForShapefile.

This method invokes this shapefile's shapeConfigurationCallback once for each record. If that function returns null, the record is skipped. If it returns non-null, the returned value is assumed to be an object with any or all of the following optional properties:

  • attributes: A PlacemarkAttributes object to assign to the placemark created for the record.
  • highlightAttributes: A PlacemarkAttributes object to assign to the highlight attributes of the placemark created for the record.
  • altitudeMode: The altitude mode to apply to the created placemark. If not specified, WorldWind.RELATIVE_TO_GROUND is used.
  • name: A String to assign as the created placemark's label.
  • altitude: A Number indicating the altitude of the created placemark. If not specified, the altitude of all created placemarks is 0.
  • pickDelegate: An object returned as the userObject when this feature is picked.
  • userProperties: An ad hoc object assigned to the renderable.
Parameters:
Name Type Description
layer RenderableLayer The layer in which to place the newly created shapes.
Source:
Throws:
If the specified layer is null or undefined.
Type
ArgumentError

addRenderablesForPolygons(layer)

Iterates over this shapefile's records and creates Polygons or SurfacePolygons for the shapefile's polygon records, depending on the altitude and height optionally returned by the shapeConfigurationCallback. One shape is created for each record. Applications typically do not call this method directly. It is called by addRenderablesForShapefile.

This method invokes this shapefile's shapeConfigurationCallback once for each record. If that function returns null, the record is skipped. If it returns non-null, the returned value is assumed to be an object with any or all of the following optional properties:

  • attributes: A ShapeAttributes object to assign to the shape created for the record.
  • highlightAttributes: A ShapeAttributes object to assign to the highlight attributes of the shape created for the record.
  • altitudeMode: The altitude mode to apply to the created shape. If not specified, WorldWind.RELATIVE_TO_GROUND is used. If the altitude is 0, this property is ignored.
  • altitude: A Number indicating the altitude of the created shape. If unspecified or 0 and the height property (see next line) is undefined or 0, a SurfacePolygon is created for the record, otherwise a Polygon is created.
  • height: A Number indicating polygon height. If defined and non-zero, a Polygon is created for this record with its position altitudes set to the specified height relative to ground and its extrude property set to true to create an extruded polygon. A height specified here overrides an altitude if both are specified.
  • name: A String to assign as the created shape's displayName property.
  • pickDelegate: An object returned as the userObject when this feature is picked.
  • userProperties: An ad hoc object assigned to the renderable.
Parameters:
Name Type Description
layer RenderableLayer The layer in which to place the newly created shapes.
Source:
Throws:
If the specified layer is null or undefined.
Type
ArgumentError

addRenderablesForPolylines(layer)

Iterates over this shapefile's records and creates Paths or SurfacePolylines for the shapefile's polyline records, depending on the altitude optionally returned by the shapeConfigurationCallback. One shape is created for each record. Applications typically do not call this method directly. It is called by addRenderablesForShapefile.

This method invokes this shapefile's shapeConfigurationCallback once for each record. If that function returns null, the record is skipped. If it returns non-null, the returned value is assumed to be an object with any or all of the following optional properties:

  • attributes: A ShapeAttributes object to assign to the shape created for the record.
  • highlightAttributes: A ShapeAttributes object to assign to the highlight attributes of the shape created for the record.
  • altitudeMode: The altitude mode to apply to the created shape. If not specified, WorldWind.RELATIVE_TO_GROUND is used.
  • altitude: A Number indicating the altitude of the created shape. If unspecified or 0, a SurfacePolyline is created for the record, otherwise a Path is created.
  • name: A String to assign as the created shape's displayName property.
  • pickDelegate: An object returned as the userObject when this feature is picked.
  • userProperties: An ad hoc object assigned to the renderable.
Parameters:
Name Type Description
layer RenderableLayer The layer in which to place the newly created shapes.
Source:
Throws:
If the specified layer is null or undefined.
Type
ArgumentError

addRenderablesForShapefile(layer)

Iterates over this shapefile's records and creates shapes for them. See the following methods for the details of the shapes created and their use of the shapeConfigurationCallback:
Parameters:
Name Type Description
layer RenderableLayer The layer in which to place the newly created shapes.
Source:
Throws:
If the specified layer is null or undefined.
Type
ArgumentError

defaultParserCompletionCallback(shapefile)

The default parser completion callback, called if none was specified to the load method. This default callback merely calls addRenderablesForShapefile to create shapes for this shapefile's records.
Parameters:
Name Type Description
shapefile Shapefile This shapefile.
Source:

defaultShapeConfigurationCallback(attributes, record) → {Object}

The default shapeConfigurationCallback for this shapefile. It is called if none was specified to the load method. This method assigns shared, default attributes to the shapes created for each record. Any changes to these attributes will have an effect in all shapes created by this shapefile.

For polygon records, the record's attributes are checked for an attribute named "height", "Height", or "HEIGHT". If found, the returned shape configuration contains a height property holding the value associated with the record attribute. This causes the default shape creation function, addRenderablesForPolygons, to create a Polygon with its extrude property set to true and position altitudes equal to the specified height value.

For all records, the record's attributes are checked for an attribute named "name", "Name" or "NAME". If found, the returned shape configuration contains a name property holding the value associated with the record attribute. This value is specified as the label displayName property for all shapes created. For Placemark shapes it is also specified as the placemark label. It is specified as the displayName for all other shapes.

Parameters:
Name Type Description
attributes Object An object containing the attribute-value pairs found in the database file associated with this shapefile. See load for more information.
record ShapefileRecord The current shapefile record.
Source:
Returns:
An object with properties as described above.
Type
Object

isMeasureType() → {Boolean}

Indicates whether this shapefile contains optional measure values.
Source:
Returns:
True if this shapefile is one that contains measure values.
Type
Boolean

isMultiPointType() → {Boolean}

Indicates whether this shapefile is either Shapefile.MULTI_POINT, Shapefile.MULTI_POINT_M or Shapefile.MULTI_POINT_Z.
Source:
Returns:
True if this shapefile is a multi-point type.
Type
Boolean

isNullType() → {Boolean}

Indicates whether this shapefile is Shapefile.NULL.
Source:
Returns:
True if this shapefile is a null type.
Type
Boolean

isPointType() → {Boolean}

Indicates whether this shapefile is either Shapefile.POINT, Shapefile.POINT_M or Shapefile.POINT_Z.
Source:
Returns:
True if the shapefile is a point type.
Type
Boolean

isPolygonType() → {Boolean}

Indicates whether this shapefile is either Shapefile.POLYGON, Shapefile.POLYGON_M or Shapefile.POLYGON_Z.
Source:
Returns:
True if this shapefile is a polygon type.
Type
Boolean

isPolylineType() → {Boolean}

Indicates whether this shapefile is either Shapefile.POLYLINE, Shapefile.POLYLINE_M or Shapefile.POLYLINE_Z.
Source:
Returns:
True if this shapefile is a polyline type.
Type
Boolean

isZType() → {Boolean}

Indicates whether this shapefile contains Z values.
Source:
Returns:
True if this shapefile contains Z values.
Type
Boolean

load(parserCompletionCallback, shapeConfigurationCallback, layer)

Retrieves the shapefile, parses it and creates shapes representing its contents. The result is a layer containing the created shapes. A function can be specified to be called when parsing is complete. A function can also be specified to be called for each shapefile record so that the attributes and other properties of the shape created for it can be assigned.
Parameters:
Name Type Description
parserCompletionCallback function An optional function called when shapefile loading is complete but shape creation has not begun. If none is specified, defaultParserCompletionCallback is called. That function creates WorldWind shapes for the parsed shapefile records. The single argument to the callback function is this shapefile object. When the callback function is called, the layer containing the shapes is available via this shapefile's layer property.
shapeConfigurationCallback function An optional function called by the addRenderablesFor* methods just prior to creating a shape for the indicated shapefile record. This function can be used to assign attributes to newly created shapes. The callback function's first argument is an object containing the properties read from the corresponding shapefile attributes file, if any. This file, which has a .dbf suffix, is automatically detected, retrieved and parsed if it exists. The second argument to the callback function is the ShapefileRecord currently being operated on. The return value of the callback function must be either an object whose properties define attributes and other information for the shape, or null, in which case no shape is created for that record. See the following methods for descriptions of the configuration properties they recognize:
layer RenderableLayer A RenderableLayer to hold the shapes created for each shapefile record. If null, a new layer is created and assigned to this object's layer property.
Source:

next() → {ShapefileRecord}

Returns the next ShapefileRecord in the shapefile, or null if no more records exist. This method can be used to iterate through the shapefile records. Only one such iteration is possible.
Source:
Returns:
The next shapefile record in the shapefile, or null if no more records exist.
Type
ShapefileRecord