= GDAL Layer Algebra =

This page describes the GDAL layer algebra in detail and gives examples.

== Common ideas ==

The GDAL layer algebra is implemented as methods in the OGRLayer class. The C API is similar to the methods except that the object itself is the first argument and that the layer pointers are validated. In the Swig bindings these are again methods in Layer class.

Each method works on the object itself (the "input" layer) and a second operand (the "method" layer) and produces a result layer. The result layer needs to exist when calling any of these methods (this may not be the case in bindings languages necessarily).

The schema of the result layer can be user-defined (the layer definition of the result layer has one or more fields) or it can be created by the method. If created, it will be either the schema of the input layer or the combined schema of input and method layers, depending on the method.

Each method may accept additional options.

A progress callback function can be used with each method.

The methods return an error code and set an error context if an error occurs or the execution is interrupted. This may have been converted into an exception in bindings languages.

== Intersection ==

An intersection is a set of features, which represent the common areas of two layers.

[[Image(Intersection.jpg)]]

'''Figure''' An example of the intersection (c) of two layers (a and b) created with Geoinformatica, which uses the GDAL Perl bindings. The schema of layer a is (A int) and that of b is (B int), the layer c is the result layer. The schema of c was empty when the Intersection method was called, thus it gets the schema (A int, B int). The result (c, light green) is as if a (light blue) was clipped to the rectangle in b (shown in light orange). The numbers in the map are the values of attribute A of a and B of b.

== Union ==

A union is a set of features, which represent areas that are in either of the operand layers.

[[Image(Union.jpg)]]

'''Figure''' An example of the union (c) of two layers (a and b). Note that the features have been split for the result layer. The feature with FID 6 of the result layer is selected (its border is drawn in red).

== !SymDifference ==

A symmetric difference is a set of features, which represent areas that are in operand layers but which do not intersect.

[[Image(SymDifference.jpg)]]

'''Figure''' An example of the symmetric difference (c) of two layers (a and b). The feature with FID 3 of the result layer is selected.

== Identity ==

The identity method identifies features in the input layer with features in the method layer possibly splitting features into several features. By default the result layer has attributes from both operand layers.

[[Image(Identity.jpg)]]

'''Figure''' An example of a layer (a) identified with another layer (b).

== Update ==

The update method creates a layer, which add features into the input layer from the method layer possibly cutting features in the input layer. By default the result layer has attributes only from the input layer.

[[Image(Update.jpg)]]

'''Figure''' An example of a layer (a) updated with another layer (b). The result layer is labeled with feature ids.

== Clip ==

The clip method creates a layer, which has features from the input layer clipped to the areas of the features in the method layer. By default the result layer has attributes of the input layer.

[[Image(Clip.jpg)]]

'''Figure''' An example of a layer (a) clipped with another layer (b). The first feature of the result layer is selected.

== Erase ==

The erase method creates a layer, which has features from the input layer whose areas are erased by the features in the method layer. By default the result layer has attributes of the input layer.

[[Image(Erase.jpg)]]

'''Figure''' An example of a layer (a) erased with another layer (b). The result layer is labeled with attribute A.