mapscript.layerObj

class mapscript.layerObj(map: mapObj | None = None)

The LAYER object

Overview

The layerObj has the following relationships:

Attributes

bandsitem	char The attribute from the index file used to select the source raster band(s) to be used - normally NULL for default bands processing
bindvals	hashTableObj immutable Relates to RFC59
classgroup	char See CLASSGROUP
classitem	char the attribute used to classify layer data - see CLASSITEM
cluster	clusterObj immutable See CLUSTER
compositer	LayerCompositer immutable See COMPOSITE
connection	char layer connection or data source name - see CONNECTION
connectionoptions	hashTableObj immutable See CONNECTIONOPTIONS
connectiontype	enum MS_CONNECTION_TYPE the layer connection type - see CONNECTIONTYPE
data	char Layer data definition, values depend upon connectiontype - see DATA
debug	int Enable debugging of layer- MS_ON or MS_OFF (default) - see DEBUG
encoding	char For iconving shape attributes, ignored if NULL or "utf-8" - see ENCODING
extent	rectObj immutable optional limiting extent for layer features - see EXTENT
filteritem	char Attribute defining filter - see FILTERITEM
footer	char filename to a template for result's footer - see FOOTER
group	char Name of a group of layers - see GROUP
header	char filename to a template for result's header - see HEADER
index	int immutable Index of layer within parent map's layers array
labelcache	int MS_ON (default) or MS_OFF - see LABELCACHE
labelitem	char attribute defining feature label text - see LABELITEM
labelmaxscaledenom	double See LABELMAXSCALEDENOM
labelminscaledenom	double See LABELMINSCALEDENOM
labelrequires	char Simple logical expression - see LABELREQUIRES
map	mapObj immutable Reference to parent map
mask	char See MASK
maxclasses	int immutable Used to track of the maximum number of classes - see RFC-17
maxfeatures	int Maximum number of layer features that will be drawn - see MAXFEATURES
maxgeowidth	double max map width (in map units) at which the layer should be drawn - see MAXGEOWIDTH
maxscaledenom	double Minimum scale at which layer will be drawn - see MAXSCALEDENOM
metadata	hashTableObj immutable See METADATA
minfeaturesize	int minimum feature size (in pixels) for shape
mingeowidth	double min map width (in map units) at which the layer should be drawn - see MAXGEOWIDTH
minscaledenom	double Maximum scale at which layer will be drawn - see MINSCALEDENOM
name	char See NAME - should be unique
numclasses	int immutable Number of layer classes
numitems	int immutable Number of layer feature attributes (items)
numjoins	int immutable Number of layer joins
numprocessing	int immutable Number of raster processing directives
offsite	colorObj transparent pixel value for raster images - see OFFSITE
plugin_library	char Used to select the library to load by MapServer
plugin_library_original	char this is needed for Mapfile writing
postlabelcache	int MS_ON or MS_OFF (default) - see POSTLABELCACHE
refcount	int immutable reference counting, RFC24
rendermode	enum MS_RENDER_MODE MS_FIRST_MATCHING_CLASS - default and historic MapServer behavior, MS_ALL_MATCHING_CLASSES - SLD behavior
requires	char Context expressions, simple enough to not use expressionObj - see REQUIRES
sizeunits	int applies to all classes - see SIZEUNITS
startindex	int Feature start index - used for paging
status	int See STATUSMS_ON, MS_OFF or MS_DEFAULT
styleitem	char item to be used for style lookup - can also be 'AUTO' - see STYLEITEM
symbolscaledenom	double scale at which symbols are default size - see SYMBOLSCALEDENOM
template	char See TEMPLATE - global template, used across all classes
thisown	The membership flag
tileindex	char layer index file for tiling support - see TILEINDEX
tileitem	char attribute defining tile paths - see TILEITEM
tilesrs	char name of the attribute that contains the SRS of an individual tile - see TILESRS
tolerance	double search buffer for point and line queries (in toleranceunits) - see TOLERANCE
toleranceunits	int See TOLERANCEUNITS
transform	int MS_TRUE (default) or MS_FALSE whether or not layer data is to be transformed to image units - see TRANSFORM
type	enum MS_LAYER_TYPE the layer type - see TYPE
units	int units of the layer - see UNITS
utfdata	expressionObj immutable See UTFDATA
utfitem	char See UTFITEM
utfitemindex	int See CLASSITEM
validation	hashTableObj immutable See VALIDATION

Methods

__init__(map: mapObj | None = None)

A layerObj is associated with mapObj. An instance of layerObj can exist outside of a mapObj

addFeature(shape: shapeObj) → int

Add a new inline feature on a layer. Returns -1 on error. TODO: Is this similar to inline features in a mapfile? Does it work for any kind of layer or connection type?

addProcessing(directive: char const) → void

Adds a new processing directive line to a layer, similar to the PROCESSING directive in a map file. Processing directives supported are specific to the layer type and underlying renderer.

applySLD(sld: char, stylelayer: char) → int

Apply the SLD document to the layer object. The matching between the SLD document and the layer will be done using the layer’s name. If a stylelayer argument is passed (argument is optional), the NamedLayer in the SLD that matches it will be used to style the layer. See SLD HOWTO for more information on the SLD support.

applySLDURL(sld: char, stylelayer: char) → int

Apply the SLD document pointed by the URL to the layer object. The matching between the SLD document and the layer will be done using the layer’s name. If a stylelayer argument is passed (argument is optional), the NamedLayer in the SLD that matches it will be used to style the layer. See SLD HOWTO for more information on the SLD support.

clearProcessing() → int

Clears the layer’s raster processing directives. Returns the subsequent number of directives, which will equal MS_SUCCESS if the directives have been cleared.

clone() → layerObj

Return an independent copy of the layer with no parent map.

Not

In the Java & PHP modules this method is named cloneLayer.

close() → void

Close the underlying layer.

convertToString() → char

Output the layerObj object as a Mapfile string. Provides the inverse option for layerObj.updateFromString().

draw(map: mapObj, image: imageObj) → int

Renders this layer into the target image, adding labels to the cache if required. Returns MS_SUCCESS or MS_FAILURE.

drawQuery(map: mapObj, image: imageObj) → int

Draw query map for a single layer into the target image. Returns MS_SUCCESS or MS_FAILURE.

executeWFSGetFeature(layer: layerObj) → char

Executes a GetFeature request on a WFS layer and returns the name of the temporary GML file created. Returns an empty string on error.

generateSLD() → char

Returns an SLD XML string based on all the classes found in the layer (the layer must have STATUS ON`).

getClass()

Fetch the requested class object at i. Returns NULL if the class index is out of the legal range. The numclasses field contains the number of classes available, and the first class is index 0.

getClassIndex(map: mapObj, shape: shapeObj, classgroup: int | None = None, numclasses: int = 0) → int

Get the class index for a shape in the layer.

getExtent() → rectObj

Fetches the extents of the data in the layer. This normally requires a full read pass through the features of the layer and does not work for raster layers.

getFilterString() → char

Returns the current filter expression.

getGeomTransform() → char

Return the geomtransform string for the layer.

getItem(i: int) → char

Returns the requested item. Items are attribute fields, and this method returns the item name (field name). The numitems field contains the number of items available, and the first item is index zero.

getItemDefinitions()

Python MapScript only

Return item (field) names and their types if available. Field types are specified using GML metadata and can be one of the following:

Integer|Long|Real|Character|Date|Boolean

getItemType(i: int) → char

Returns the requested item’s field type. A layer must be open to retrieve the item definition.

Pass in the attribute index to retrieve the type. The layer’s numitems property contains the number of items available, and the first item is index zero.

getNumFeatures() → int

Returns the number of inline features in a layer. TODO: is this really only online features or will it return the number of non-inline features on a regular layer?

getNumResults() → int

Returns the number of entries in the query result cache for this layer.

getOpacity() → int

Returns the opacity value for the layer.

getProcessing(index: int) → char

Return the raster processing directive at index.

getProcessingKey(key: char const) → char

Return the processing directive specified by key.

getProjection() → char

Returns the PROJ definition of the layer’s projection.

getResult(i: int) → resultObj

Fetches the requested query result cache entry, or NULL if the index is outside the range of available results. This method would normally only be used after issuing a query operation.

getResults() → resultCacheObj

Returns a reference to layer’s result cache. Should be NULL prior to any query, or after a failed query or query with no results.

getResultsBounds() → rectObj

Returns the bounds of the features in the result cache.

getShape(record: resultObj) → shapeObj

Get a shape from layer data. Argument is a result cache member from layerObj.getResult()

getWMSFeatureInfoURL(map: mapObj, click_x: int, click_y: int, feature_count: int, info_format: char) → char

Return a WMS GetFeatureInfo URL (works only for WMS layers) clickX, clickY is the location of to query in pixel coordinates with (0,0) at the top left of the image. featureCount is the number of results to return. infoFormat is the format the format in which the result should be requested. Depends on remote server’s capabilities. MapServer WMS servers support only “MIME” (and should support “GML.1” soon). Returns “” and outputs a warning if layer is not a WMS layer or if it is not queryable.

insertClass()

Insert a copy of the class into the layer at the requested index. Default index of -1 means insertion at the end of the array of classes. Returns the index at which the class was inserted.

isVisible() → int

Returns MS_TRUE or MS_FALSE after considering the layer status, minscaledenom, and maxscaledenom within the context of the parent map.

moveClassDown(index: int) → int

The class specified by the class index will be moved up into the array of classes. Returns MS_SUCCESS or MS_FAILURE. For example moveClassDown(1) will have the effect of moving class 1 down to position 2, and the class at position 2 will be moved to position 1.

moveClassUp(index: int) → int

The class specified by the class index will be moved up in the array of classes. Returns MS_SUCCESS or MS_FAILURE. For example moveClassUp(1) will have the effect of moving class 1 up to position 0, and the class at position 0 will be moved to position 1.

nextShape() → shapeObj

Called after layerObj.whichShapes() has been called to actually retrieve shapes within a given area returns a shape object or MS_FALSE Example of usage:

mapObj map = new mapObj("d:/msapps/gmap-ms40/htdocs/gmap75.map");
layerObj layer = map.getLayerByName('road');
int status = layer.open();
status = layer.whichShapes(map.extent);
shapeObj shape;
while ((shape = layer.nextShape()) != null)
{
  ...
}
layer.close();

open() → int

Opens the underlying layer. This is required before operations like layerObj.getResult() will work, but is not required before a draw or query call.

queryByAttributes(map: mapObj, qitem: char, qstring: char, mode: int) → int

Query layer for shapes that intersect current map extents. qitem is the item (attribute) on which the query is performed, and qstring is the expression to match. The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Note that the layer’s FILTER/FILTERITEM are ignored by this function. mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Returns MS_SUCCESS if the query was successfully performed, regardless of whether any shapes were found, or MS_FAILURE if an error occured.

queryByFeatures(map: mapObj, slayer: int) → int

Perform a query set based on a previous set of results from another layer. At present the results MUST be based on a polygon layer. Returns MS_SUCCESS if the query was successfully performed, regardless of whether any shapes were found, or MS_FAILURE if an error occured.

queryByFilter(map: mapObj, string: char) → int

Query by the filter string. For querying, we switch layer status ON and then back to original value before returning.

queryByIndex(map: mapObj, tileindex: int, shapeindex: int, bAddToQuery: int = 0) → int

Pop a query result member into the layer’s result cache. By default clobbers existing cache. Returns MS_SUCCESS or MS_FAILURE

queryByPoint(map: mapObj, point: pointObj, mode: int, buffer: double) → int

Query layer at point location specified in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Note that the layer’s FILTER/FILTERITEM are ignored by this function. mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Returns MS_SUCCESS if the query was successfully performed, regardless of whether any shapes were found, or MS_FAILURE if an error occured.

queryByRect(map: mapObj, rect: rectObj) → int

Query layer using a rectangle specified in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Note that the layer’s FILTER/FILTERITEM are ignored by this function. The MS_MULTIPLE mode is set by default. Returns MS_SUCCESS if the query was successfully performed, regardless of whether any shapes were found, or MS_FAILURE if an error occured.

queryByShape(map: mapObj, shape: shapeObj) → int

Query layer based on a single shape, the shape has to be a polygon at this point. Returns MS_SUCCESS if the query was successfully performed, regardless of whether any shapes were found, or MS_FAILURE if an error occured.

removeClass(index: int) → classObj

Removes the class at index and returns a copy, or NULL in the case of a failure. Note that subsequent classes will be renumbered by this operation. The numclasses field contains the number of classes available.

setConnectionType(connectiontype: int, library_str: char const) → int

Changes the connectiontype of the layer and recreates the vtable according to the new connection type. This method should be used instead of setting the connectiontype parameter directly. In case when the layer.connectiontype = MS_PLUGIN the library_str parameter should also be specified so as to select the library to load by MapServer. For the other connection types this parameter should be set to an empty string “”.

setExtent(minx: double = -1.0, miny: double = -1.0, maxx: double = -1.0, maxy: double = -1.0) → int

Sets the extent of a layer. Returns MS_SUCCESS or MS_FAILURE

setFilter(filter: char) → int

Sets a filter expression similarly to the FILTER expression in a map file. Returns MS_SUCCESS or MS_FAILURE if the expression fails to parse.

setGeomTransform(transform: char) → void

Set the geomtransform string for the layer.

setItems(items: char, numitems: int) → int

Set the items to be retrieved with a particular shape.

setOpacity(opacity: int) → void

Sets an opacity for the layer, where the value is an integer in range [0, 100]. A new COMPOSITE block is generated, containing this OPACITY value.

setProcessingKey(key: char const, value: char const) → void

Adds or replaces a processing directive of the form “key=value”. Unlike the layerObj.addProcessing() function, this will replace an existing processing directive for the given key value. Processing directives supported are specific to the layer type and underlying renderer.

setProjection(proj4: char) → int

Set the layer projection using a PROJ format projection definition (i.e. “+proj=utm +zone=11 +datum=WGS84” or “init=EPSG:26911”). Returns MS_SUCCESS or MS_FAILURE

setWKTProjection(wkt: char) → int

Set the layer projection using OpenGIS Well Known Text format. Returns MS_SUCCESS or MS_FAILURE

updateFromString(snippet: char) → int

Update a layerObj from a string snippet. Returns MS_SUCCESS or MS_FAILURE

whichShapes(rect: rectObj) → int

Performs a spatial, and optionally an attribute based feature search. The function basically prepares things so that candidate features can be accessed by query or drawing functions (e.g using layerObj.nextShape() function). Returns MS_SUCCESS, MS_FAILURE or MS_DONE. MS_DONE is returned if the layer extent does not overlap rect.