Syntax FACTORY_DEF RasterEvaluationFactory [FACTORY_NAME ] [INPUT A|B FEATURE_TYPE [ ]* []*]* [INTERPRETATION_LIST ] [PRESERVE_INTERPRETATION (yes|no)] [REJECT_INVALID_FEATURES (yes|no)] [EXPRESSION_LIST ] [FORCE_FLOAT_DIVISION (yes|no)] [GROUP_BY []+] [OUTPUT RESULT FEATURE_TYPE [ ]* []*]* Overview This factory is used to evaluate expressions on each cell in a raster, such as algebraic operations or conditional statements. The factory has two input ports: A and B. The cardinality of the input is required to be one of the following cases: One or more As, no Bs One A, one or more Bs When both A and B features are provided, the single A input will be paired with each B input. The GROUP_BY clause can be used to evaluate expressions on multiple pairs of rasters (i.e. multiple As and multiple Bs). Note: This clause is not applicable when only A input is provided; in that case, each raster is considered individually and there are no groupings. The output of the factory will be a single raster feature per input pair. The output rasters will have n bands, where n is the number of interpretation/expression pairs, specified through the INTERPRETATION_LIST and EXPRESSION_LIST keywords. The INTERPRETATION_LIST clause accepts a semicolon-delimited list of the interpretation for each output band. Valid interpretations are INT8, INT16, INT32, INT64, UINT8, UINT16, UINT32, UINT64, REAL32, REAL64, GRAY8, GRAY16, RED8, RED16, GREEN8, GREEN16, BLUE8, BLUE16, ALPHA8, ALPHA16. Additionally, there are two special values that may be used: AUTO and PRESERVE. AUTO indicates that the output interpretation should be automatically determined based on the data types used to perform the calculations. PRESERVE indicates that if all input bands share the same interpretation, the output band should keep that same interpretation. If the input bands do not share the same interpretation, PRESERVE is the same as AUTO. The REJECT_INVALID_FEATURES clause specifies whether the factory will fail upon being supplied invalid features or output them to the port. The EXPRESSION_LIST clause accepts a semicolon-delimited list of expressions describing how to calculate each output band. Please see the Operands section for the syntax of an expression. As an example, if the input for INTERPRETATION_LIST was "REAL64;AUTO;UINT32" and the input for EXPRESSION_LIST was "A[0] + B[0]; A[0] / 2; A[1] * 2", then the output would be a raster with a Real64 band, a band whose type was automatically determined, and a UInt32 band. The cell values in these bands would be calculated using the specified expressions. When pairs of inputs are being operated on (i.e. the expression references both input A and B), the output feature will have all the attributes from both feature A and feature B. If the same attribute exists on both input features, then the attribute value from feature B will be preferred. Similarly, the output raster feature will have the properties of raster B. When only a single input is being operated on (i.e. the expression only references input A), the feature attributes and raster properties will remain unchanged. The following restrictions apply to input features: All input features must have raster geometry. All paired rasters must have the same number of rows and columns. Either all bands used in the same expression must have the same nodata value, or all bands used in the same expression must have no nodata value. No band may have a palette. Operands An expression consists of a combination of operands, operators, and parentheses. White space may be used between the operands, operators, and parentheses as it is ignored by the expression processor. Where possible, operands are interpreted as integer values; otherwise, operands will be treated as floating-point numbers. Floating-point numbers may be specified in any of the ways accepted by an ANSI-compliant C compiler, except that "f", "F", "l", and "L" suffixes are not permitted in most installations. For example, all of the following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. Operands may be any of the following: A band from an input raster, specified using the syntax A[i], where A indicates the input port (i.e. it may be either A or B) and i indicates the band index. Note: Band indices are 0-based. A numeric constant, either integer or floating-point. The value of an attribute, using the syntax A:attributeName. The attribute's value is used as the operand. If the attribute name contains any characters that are not alpanumeric or underscores, the attribute name must be enclosed in quotation marks, e.g. A:"attribute name". If the attribute name contains quotation marks, these must be preceded with the \ character, e.g. A:"my \"special\" attribute" A function whose arguments have any of the above forms for operands, such as sin(A[0]). See the Functions section for a list of defined functions. For example, a simple expression might be A[0] * (B[3] / 255.0). This expression combines the first band of the raster from input A with the fourth band of the raster from input B. Note: Bands, rather than rasters, are used as operands. However, it is possible to apply the same operation to every band in a raster through use of the GROUP_BY clause. Suppose for example that you have two rasters, and you want to add each corresponding band together, i.e. you want to calculate A[i] + B[i] for every band i. A cumbersome way to achieve this would be to explicitly list expressions A[0] + B[0]; A[1] + B[1]; etc. However, this could also be completed through the following steps: Split the bands apart using the RasterSplitterFactory Use the RasterEvaluationFactory with the expression set to A[0] + B[0], grouping by the band index attribute set by the RasterSplitterFactory Recombine the bands using the RasterMergerFactory Operators The valid operators listed below are grouped in decreasing order of precedence: - + ~ ! Unary minus, unary plus, bit-wise NOT, logical NOT. Bit-wise NOT is valid for integer operands only. * / % Multiply, divide, remainder. Remainder is valid for integer operands only. + - Add and subtract. << >> Left and right shift. Valid for integer operands only. < > <= >= Boolean less, greater, less than or equal, and greater than or equal. Each operator produces 1 if the condition is true, 0 otherwise. == != Boolean equal and not equal. Each operator produces 1 if the condition is true, 0 otherwise. & Bit-wise AND. Valid for integer operands only. ^ Bit-wise exclusive OR. Valid for integer operands only. | Bit-wise OR. Valid for integer operands only. && Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. || Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. Functions Several functions are available for usage in expressions. One useful function is if(c, x, y). This function returns: nodata if c is nodata x if c is non-zero y otherwise Another useful function is isnodata(x). This function returns 1 if x is nodata, 0 otherwise. Finally, the following C math functions can be used: abs atan2 exp log10 sqrt acos ceil floor pow tan asin cos fmod sin tanh atan cosh log sinh Each of these functions invokes the C math library function of the same name. Refer to the C Manual entries for the library functions for details on what they do and what arguments are valid. Nodata Any operator or function applied to a nodata value will result in nodata. For example (nodata + 1) = nodata. The exception to this is the isnodata function, described in the Functions section. Nodata may also be produced due to any invalid operands. Examples of these include: Division by zero. Modulus by zero. sqrt of a negative number Additionally, the keyword NODATA may be used in expressions. This keyword will be considered as the nodata value of the bands being evaluated. For example, it could be used in an expression like if(A[0]==0, NODATA, B[0]). Types and Overflows The RasterEvaluationFactory attempts to avoid overflows by changing data types through the course of evaluating an expression. For example, if two UInt8 bands are added together, the internal computations will be performed with a UInt16 type; this ensures that no overflow will occur. In general, performing an arithmetic operation on integer types will produce an integer type. The exception to this is division (see FORCE_FLOAT_DIVISION parameter below). Performing an arithmetic operation on floating-point types will always produce a floating-point type. The FORCE_FLOAT_DIVISION parameter specifies how division should be handled. If no, division of integer arguments will result in integer values, so an expression like "1/2" will produce a result of 0. If yes, division will always result in floating point values, so an expression like "1/2" will produce a result of 0.5. Output Tags The RasterEvaluationFactory supports the following output tag. RESULT The raster created by evaluating the specified expressions. The output feature that is deemed to be invalid input for any of the following reasons: - The feature does not have compatible geometry - The feature has no bands - The feature has palettes - The feature is missing an attribute specified in an expression - The feature is missing a band specified in an expression