ScriptOperator Class
An operator that process features with source code specified in a property.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECustomObjects assembly)
Syntax
public class ScriptOperator : FunnelOperatorRemarks
The ScriptOperator makes use of the Carmenta Engine Python API which is available in a separate installation package.
The concept of a ScriptOperator is very similar to the concept of a custom operator. It is not as flexible and powerful as a custom operator, but on the other hand there is no need for a separate dll: all code can be kept in the configuration file. The basic idea is to apply a user-defined Python® script to the passing features.
As a simple example, let us say we have street features with a Name attribute in uppercase, like MAIN STREET, and we want only the first letter of each word to be uppercase, like Main Street. We can then let a script operator use the built-in Python method string.capwords, by setting the code property to:
import string
atts = feature.attributes
atts['Name'] = string.capwords(atts['Name'])
A script operator can operate in different processing modes: Iterative or AllAtOnce.
Iterative processing mode
In this mode, the source code will process each passing feature, one at a time in an iterative manner. The function that is applied to the features has the following signature:
def processFeature(feature, userProperties, viewInfo):
(Note that the function signature should not be written in the script code: it is implicitly defined.)
The feature parameter is the feature that should be processed in some way (the input).
The userProperties parameter is taken from the IUserProperties.UserProperties property of the script operator. In this way it is possible to write more generic code, i.e. we can write a script code that rounds a float attribute to any number of decimals and then reuse it for each problem instance instead of writing a new function each time (RoundToOneDecimal, RoundToTwoDecimals, etc).
The viewInfo parameter is the view settings like the scale and area of interest. For more information, see the documentation for the ViewInfo class.
The function return value (the output) is allowed to be of one of the following types:
None
Nothing will be passed on to the next operator. This is useful if we want to apply some kind of filtering to the input. Note that nothing here means that the current call produces no object. The function is, however, repeatedly called for each feature produced by the previous operators.
Feature
A single feature that will be passed on to the next operator.
FeatureCollection
A set of features that will be passed on to the next operator.
By default, if no return statement is specified in the code, the script operator returns the feature parameter in iterative mode.
All at once processing mode
In some cases we might need to access all objects at once to decide what to return. That is why there is another processing mode, AllAtOnce. The function signature is slightly different in this case. It becomes:
def processFeatures(features, userProperties, viewInfo):
Instead of having a single feature, we retrieve all the features produced from previous operators at once, contained in a FeatureCollection, which is the features parameter. In all other aspects, with one exception, the script operator will work as in the Iterative mode. The exception is that AllAtOnce cannot always support selection, since it is not always possible to figure out the relationship between the input and the output.
By default, if no return statement is specified in the code, the script operator returns the features parameter in all at once mode.
Predefined script operators
Predefined script operators can be found in the templates folder in Carmenta Studio. They can be seen as samples, which can be used directly or modified if needed.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Operator
FunnelOperator
ScriptOperator
Platforms
Windows, Linux, Android
ScriptOperator Members
The ScriptOperator type has the following members.
Constructors
| Name | Description |
|---|---|
| ScriptOperator | Initializes a new instance of the ScriptOperator class |
Properties
| Name | Description |
|---|---|
| Code | Gets or sets the source code used to process the passing features. |
| Description | Gets or sets a short description of the operator. Inherited from Operator |
| DisplayName | Gets or sets a display name for the operator. Inherited from Operator |
| Inputs | Gets the list of inputs connected to this ScriptOperator. Inherited from FunnelOperator |
| IsDisposed | Gets a value that tells whether the current ScriptOperator has been disposed. Inherited from EngineObject |
| IsoMetadataDocument | Gets or sets the path to an ISO 19139 metadata document for the operator. Inherited from Operator |
| Language | Gets or sets the programming language used. |
| Name | Gets or sets the name of the operator. Inherited from Operator |
| NativeHandle | Gets the native Carmenta Engine kernel object the current ScriptOperator represents. Inherited from EngineObject |
| ProcessingMode | Gets or sets the processing mode used. |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| FindChildObject | Overloaded. Finds the child object with the specified name. Inherited from Operator |
| FlushCache | Marks the layer as flushed which will release cached resources during the next update. Inherited from Operator |
| GetChildObjects | Overloaded. Gets the child objects of the current object. Inherited from Operator |
| GetFeatures | Overloaded. Gets features from the operator chain. Inherited from Operator |
| GetLocalizedDescription | Gets a localized version of the operator description in a specific language. Inherited from Operator |
| GetLocalizedDisplayName | Gets a localized version of the operator display name in a specific language. Inherited from Operator |
| GetLocalizedIsoMetadataDocument | Gets the path to an ISO 19139 metadata document for a specific language. Inherited from Operator |
| GetRasterFeature | Overloaded. Gets raster features from the operator chain and merges them into a single raster. Inherited from Operator |
| HasLocalizedDescription | Checks if a localized version of the operator description is available in a specific language. Inherited from Operator |
| HasLocalizedDisplayName | Checks if a localized version of the operator display name is available in a specific language. Inherited from Operator |
| HasLocalizedIsoMetadataDocument | Checks if an ISO 19139 metadata document is available for a specific language. Inherited from Operator |
| SetLocalizedDescription | Sets a operator description in a specific language. Inherited from Operator |
| SetLocalizedDisplayName | Sets a operator display name in a specific language. Inherited from Operator |
| SetLocalizedIsoMetadataDocument | Sets the path to an ISO 19139 metadata document for the operator, for a specific language. Inherited from Operator |