| 310 | | '''ST_Union(raster|geometry, raster|geometry, 'raster'|'geometry') -> raster/geometry'''[[BR]] |
| | 310 | '''ST_Union(set of raster[, p_expression, p_nodata1expr, p_nodata2expr, p_nodatanodataexpr, t_expression, t_nodata1expr, t_nodata2expr, t_nodatanodataexpr, f_expression, f_nodata1expr, f_nodata2expr, f_nodatanodataexpr]) -> raster'''[[BR]] |
| | 311 | |
| | 312 | * ST_Union is an aggregate function which merges, one by one, all the selected rasters into a unique raster. |
| | 313 | |
| | 314 | * It can be used to simply merge disjoint tiles into a bigger raster but also to blend overlapping areas together using different rules. |
| | 315 | |
| | 316 | * As an aggregate function it is using a STATE and a FINAL function materialized by a state expression (p_expression) and a final expression (f_expression) and their respective nodata value alternatives (p_nodata1expr, p_nodata2expr, p_nodatanodataexpr, f_nodata1expr and f_nodata2expr, f_nodatanodataexpr). All expressions are SQL expressions that are evaluated by the internal two raster version of ST_MapAlgebra(). |
| | 317 | |
| | 318 | * An optional temporary expression (t_expression) and its nodata value alternatives (t_nodata1expr, t_nodata2expr, t_nodatanodataexpr) can be provided of used internally depending on which variant or which predefined expression is passed to ST_Union(). When it is used, MapAlgebra is called two times: one time to fill this temporary band using the t_expression and a second time to fill the first band using the p_expression. This temporary band is useful to implement some expressions needing two variables like the predefined ‘MEAN’ and ‘RANGE’ expressions. |
| | 319 | |
| | 320 | * The different expressions resume like this: |
| | 321 | |
| | 322 | * p_expression, p_nodata1expr, p_nodata2expr and p_nodatanodataexpr is the main set of state expressions accumulating the final values if no final expression are used. |
| | 323 | |
| | 324 | * t_expression, t_nodata1expr, t_nodata2expr and t_nodatanodataexpr is the optional set of temporary expressions accumulating values in a temporary raster. t_expressions are evaluated before p_expressions. |
| | 325 | |
| | 326 | * f_expression, f_nodata1expr, f_nodata2expr and p_nodatanodataexpr is the optional set of final expressions. Final expressions may refer to the raster resulting from the p_expression (rast1) and the t_expression (rast2) to determine the final pixel values. |
| | 327 | |
| | 328 | * As explained in the ST_MapAlgebra() specifications, alternate expressions like p_nodata1expr and f_nodata2expr are used to simplify complex decision expression trying to deal with the presence of nodata value pixels. Having three short expressions like this: |
| | 329 | |
| | 330 | 'rast2', 'rast2', 'rast1', NULL |
| | 331 | |
| | 332 | is simpler than a single complex expression dealing with nodata like this: |
| | 333 | |
| | 334 | 'CASE WHEN rast1 IS NULL AND rast2 IS NULL THEN NULL WHEN rast2 IS NULL THEN rast1 ELSE rast2 END' |
| | 335 | |
| | 336 | This is a simple case. In more complex cases, expressions can quickly get incomprehensible and alternate expressions greatly simplify the task of writing expressions, even if having so many parameters may seams cumbersome. One must also consider the fact that in many simple cases, the t_ set and the f_ set of expressions is optional as well as the alternate expressions of the p_ set. In these very simple cases only one p_ expression has to be passed to or used by ST_Union. Another factor reducing the apparent complexity is that in many cases, users will be happy with the predefined expressions, reducing a call to ST_Union to something like ST_Union(rast, 'SUM'). |
| | 337 | |
| | 338 | |
| | 339 | * Here are some commonly used predefined expressions and how they materialize as the four (4) "p_", "t_" and "f_" expressions passed to ST_Mapalgebra(rast1, rast2): |
| | 340 | |
| | 341 | - LAST: 'rast2', 'rast2', 'rast1', NULL |
| | 342 | |
| | 343 | - FIRST: 'rast1', 'rast2', 'rast1', NULL |
| | 344 | |
| | 345 | - MIN: 'LEAST(rast1, rast2)', 'rast2', 'rast1', NULL |
| | 346 | |
| | 347 | - MAX: 'GREATEST(rast1, rast2)', 'rast2', 'rast1', NULL |
| | 348 | |
| | 349 | - COUNT: 'rast1 + 1', '1', 'rast1', '0' |
| | 350 | |
| | 351 | - SUM: 'rast1 + rast2', 'rast2', 'rast1', NULL |
| | 352 | |
| | 353 | - RANGE: |
| | 354 | - p_expressions = 'LEAST(rast1, rast2)', 'rast2', 'rast1', NULL |
| | 355 | - t_expressions = 'GREATEST(rast1, rast2)', 'rast2', 'rast1', NULL |
| | 356 | - f_expressions = 'rast1 - rast2', NULL, NULL, NULL |
| | 357 | |
| | 358 | - MEAN: |
| | 359 | - p_expressions = 'rast1 + rast2', 'rast2', 'rast1', NULL //sum |
| | 360 | - t_expressions = 'rast1 + 1', '1', 'rast1', '0' //count |
| | 361 | - f_expressions = 'CASE WHEN rast2 > 0 THEN rast1 / rast2::float8 ELSE NULL END', NULL, NULL, NULL //sum/count |
| | 362 | |
| | 363 | - STANDARD_DEVIATION: NOT POSSIBLE, nead two passes. See how ST_SummaryStats() does it... |
| | 364 | |
| | 365 | - MAX_LENGTH, MAX_AREA or MAX_ANYTHING (require MapAlgebra being able to reference other bans than 1): |
| | 366 | - p_expressions = 'CASE WHEN rast1[2] > rast2[t] THEN rast1[1] ELSE rast2[1] END', 'rast2[1]', 'rast1[1]', NULL |
| | 367 | - t_expressions = 'CASE WHEN rast1[2] > rast2[2] THEN rast1[2] ELSE rast2[2] END', 'rast2[2]', 'rast1[2]', NULL |
| | 368 | - f_expressions = 'rast1', NULL, NULL, NULL |
| | 369 | |
| | 370 | |
| | 371 | * A PL/pgSQL prototype of ST_Union exist in script/plpgsql/st_union.sql. |
| | 372 | |
| | 373 | |
