Skip to content

Commit 14a5ff7

Browse files
ahuarte47ahuarte47
committed
Add documentation of raster functions
1 parent 03fa25b commit 14a5ff7

19 files changed

+789
-18
lines changed

‎spatial/src/spatial/gdal/functions/aggregate/st_mosaic_agg.cpp

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,39 @@ struct MosaicAggBinaryOperation : RasterAggBinaryOperation {
6363

6464
};
6565

66+
//------------------------------------------------------------------------
67+
// Documentation
68+
//------------------------------------------------------------------------
69+
70+
static constexpr const char *DOC_DESCRIPTION = R"(
71+
Returns a mosaic of a set of raster tiles into a single raster.
72+
73+
Tiles are considered as source rasters of a larger mosaic and the result dataset has as many bands as one of the input files.
74+
75+
`options` is optional, an array of parameters like [GDALBuildVRT](https://gdal.org/programs/gdalbuildvrt.html).
76+
)";
77+
78+
static constexpr const char *DOC_EXAMPLE = R"(
79+
WITH __input AS (
80+
SELECT
81+
1 AS raster_id,
82+
ST_RasterFromFile(file) AS raster
83+
FROM
84+
glob('./test/data/mosaic/*.tiff')
85+
),
86+
SELECT
87+
ST_RasterMosaic_Agg(raster, options => ['-r', 'bilinear']) AS r
88+
FROM
89+
__input
90+
GROUP BY
91+
raster_id
92+
;
93+
)";
94+
95+
static constexpr DocTag DOC_TAGS[] = {
96+
{"ext", "spatial"}, {"category", "aggregation"}
97+
};
98+
6699
//------------------------------------------------------------------------
67100
// Register
68101
//------------------------------------------------------------------------
@@ -86,6 +119,8 @@ void GdalAggregateFunctions::RegisterStRasterMosaicAgg(DatabaseInstance &db) {
86119
st_mosaic_agg.AddFunction(fun02);
87120

88121
ExtensionUtil::RegisterFunction(db, st_mosaic_agg);
122+
123+
DocUtil::AddDocumentation(db, "ST_RasterMosaic_Agg", DOC_DESCRIPTION, DOC_EXAMPLE, DOC_TAGS);
89124
}
90125

91126
} // namespace gdal

‎spatial/src/spatial/gdal/functions/aggregate/st_union_agg.cpp

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,39 @@ struct UnionAggBinaryOperation : RasterAggBinaryOperation {
6767

6868
};
6969

70+
//------------------------------------------------------------------------
71+
// Documentation
72+
//------------------------------------------------------------------------
73+
74+
static constexpr const char *DOC_DESCRIPTION = R"(
75+
Returns the union of a set of raster tiles into a single raster composed of at least one band.
76+
77+
Each tiles goes into a separate band in the result dataset.
78+
79+
`options` is optional, an array of parameters like [GDALBuildVRT](https://gdal.org/programs/gdalbuildvrt.html).
80+
)";
81+
82+
static constexpr const char *DOC_EXAMPLE = R"(
83+
WITH __input AS (
84+
SELECT
85+
1 AS raster_id,
86+
ST_RasterFromFile(file) AS raster
87+
FROM
88+
glob('./test/data/bands/*.tiff')
89+
),
90+
SELECT
91+
ST_RasterUnion_Agg(raster, options => ['-resolution', 'highest']) AS r
92+
FROM
93+
__input
94+
GROUP BY
95+
raster_id
96+
;
97+
)";
98+
99+
static constexpr DocTag DOC_TAGS[] = {
100+
{"ext", "spatial"}, {"category", "aggregation"}
101+
};
102+
70103
//------------------------------------------------------------------------
71104
// Register
72105
//------------------------------------------------------------------------
@@ -90,6 +123,8 @@ void GdalAggregateFunctions::RegisterStRasterUnionAgg(DatabaseInstance &db) {
90123
st_union_agg.AddFunction(fun02);
91124

92125
ExtensionUtil::RegisterFunction(db, st_union_agg);
126+
127+
DocUtil::AddDocumentation(db, "ST_RasterUnion_Agg", DOC_DESCRIPTION, DOC_EXAMPLE, DOC_TAGS);
93128
}
94129

95130
} // namespace gdal

‎spatial/src/spatial/gdal/functions/scalar/st_band_color_interp.cpp

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,74 @@ static void RasterGetColorInterpNameFunction(DataChunk &args, ExpressionState &s
5555
});
5656
}
5757

58+
//------------------------------------------------------------------------
59+
// Documentation
60+
//------------------------------------------------------------------------
61+
62+
static constexpr const char *DOC_DESCRIPTION_1 = R"(
63+
Returns the color interpretation of a band in the raster.
64+
65+
This is a code in the enumeration:
66+
67+
+ Undefined = 0: Undefined
68+
+ GrayIndex = 1: Greyscale
69+
+ PaletteIndex = 2: Paletted (see associated color table)
70+
+ RedBand = 3: Red band of RGBA image
71+
+ GreenBand = 4: Green band of RGBA image
72+
+ BlueBand = 5: Blue band of RGBA image
73+
+ AlphaBand = 6: Alpha (0=transparent, 255=opaque)
74+
+ HueBand = 7: Hue band of HLS image
75+
+ SaturationBand = 8: Saturation band of HLS image
76+
+ LightnessBand = 9: Lightness band of HLS image
77+
+ CyanBand = 10: Cyan band of CMYK image
78+
+ MagentaBand = 11: Magenta band of CMYK image
79+
+ YellowBand = 12: Yellow band of CMYK image
80+
+ BlackBand = 13: Black band of CMYK image
81+
+ YCbCr_YBand = 14: Y Luminance
82+
+ YCbCr_CbBand = 15: Cb Chroma
83+
+ YCbCr_CrBand = 16: Cr Chroma
84+
)";
85+
86+
static constexpr const char *DOC_EXAMPLE_1 = R"(
87+
SELECT ST_GetBandColorInterp(raster, 1) FROM './test/data/mosaic/SCL.tif-land-clip00.tiff';
88+
)";
89+
90+
static constexpr DocTag DOC_TAGS_1[] = {
91+
{"ext", "spatial"}, {"category", "property"}
92+
};
93+
94+
static constexpr const char *DOC_DESCRIPTION_2 = R"(
95+
Returns the color interpretation name of a band in the raster.
96+
97+
This is a string in the enumeration:
98+
99+
+ Undefined: Undefined
100+
+ Greyscale: Greyscale
101+
+ Paletted: Paletted (see associated color table)
102+
+ Red: Red band of RGBA image
103+
+ Green: Green band of RGBA image
104+
+ Blue: Blue band of RGBA image
105+
+ Alpha: Alpha (0=transparent, 255=opaque)
106+
+ Hue: Hue band of HLS image
107+
+ Saturation: Saturation band of HLS image
108+
+ Lightness: Lightness band of HLS image
109+
+ Cyan: Cyan band of CMYK image
110+
+ Magenta: Magenta band of CMYK image
111+
+ Yellow: Yellow band of CMYK image
112+
+ Black: Black band of CMYK image
113+
+ YLuminance: Y Luminance
114+
+ CbChroma: Cb Chroma
115+
+ CrChroma: Cr Chroma
116+
)";
117+
118+
static constexpr const char *DOC_EXAMPLE_2 = R"(
119+
SELECT ST_GetBandColorInterpName(raster, 1) FROM './test/data/mosaic/SCL.tif-land-clip00.tiff';
120+
)";
121+
122+
static constexpr DocTag DOC_TAGS_2[] = {
123+
{"ext", "spatial"}, {"category", "property"}
124+
};
125+
58126
//------------------------------------------------------------------------------
59127
// Register functions
60128
//------------------------------------------------------------------------------
@@ -64,13 +132,17 @@ void GdalScalarFunctions::RegisterStBandColorInterp(DatabaseInstance &db) {
64132
ScalarFunctionSet set("ST_GetBandColorInterp");
65133
set.AddFunction(ScalarFunction({GeoTypes::RASTER(), LogicalType::INTEGER}, LogicalType::INTEGER, RasterGetColorInterpFunction));
66134
ExtensionUtil::RegisterFunction(db, set);
135+
136+
DocUtil::AddDocumentation(db, "ST_GetBandColorInterp", DOC_DESCRIPTION_1, DOC_EXAMPLE_1, DOC_TAGS_1);
67137
}
68138

69139
void GdalScalarFunctions::RegisterStBandColorInterpName(DatabaseInstance &db) {
70140

71141
ScalarFunctionSet set("ST_GetBandColorInterpName");
72142
set.AddFunction(ScalarFunction({GeoTypes::RASTER(), LogicalType::INTEGER}, LogicalType::VARCHAR, RasterGetColorInterpNameFunction));
73143
ExtensionUtil::RegisterFunction(db, set);
144+
145+
DocUtil::AddDocumentation(db, "ST_GetBandColorInterpName", DOC_DESCRIPTION_2, DOC_EXAMPLE_2, DOC_TAGS_2);
74146
}
75147

76148
} // namespace gdal

‎spatial/src/spatial/gdal/functions/scalar/st_band_nodata_value.cpp

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,22 @@ static void RasterGetBandNoDataFunction(DataChunk &args, ExpressionState &state,
3434
});
3535
}
3636

37+
//------------------------------------------------------------------------
38+
// Documentation
39+
//------------------------------------------------------------------------
40+
41+
static constexpr const char *DOC_DESCRIPTION = R"(
42+
Returns the NODATA value of a band in the raster.
43+
)";
44+
45+
static constexpr const char *DOC_EXAMPLE = R"(
46+
SELECT ST_GetBandNoDataValue(raster, 1) FROM './test/data/mosaic/SCL.tif-land-clip00.tiff';
47+
)";
48+
49+
static constexpr DocTag DOC_TAGS[] = {
50+
{"ext", "spatial"}, {"category", "property"}
51+
};
52+
3753
//------------------------------------------------------------------------------
3854
// Register functions
3955
//------------------------------------------------------------------------------
@@ -43,6 +59,8 @@ void GdalScalarFunctions::RegisterStBandNoDataValue(DatabaseInstance &db) {
4359
ScalarFunctionSet set("ST_GetBandNoDataValue");
4460
set.AddFunction(ScalarFunction({GeoTypes::RASTER(), LogicalType::INTEGER}, LogicalType::DOUBLE, RasterGetBandNoDataFunction));
4561
ExtensionUtil::RegisterFunction(db, set);
62+
63+
DocUtil::AddDocumentation(db, "ST_GetBandNoDataValue", DOC_DESCRIPTION, DOC_EXAMPLE, DOC_TAGS);
4664
}
4765

4866
} // namespace gdal

‎spatial/src/spatial/gdal/functions/scalar/st_band_pixel_type.cpp

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,70 @@ static void RasterGetPixelTypeNameFunction(DataChunk &args, ExpressionState &sta
5555
});
5656
}
5757

58+
//------------------------------------------------------------------------
59+
// Documentation
60+
//------------------------------------------------------------------------
61+
62+
static constexpr const char *DOC_DESCRIPTION_1 = R"(
63+
Returns the pixel type of a band in the raster.
64+
65+
This is a code in the enumeration:
66+
67+
+ Unknown = 0: Unknown or unspecified type
68+
+ Byte = 1: Eight bit unsigned integer
69+
+ Int8 = 14: 8-bit signed integer
70+
+ UInt16 = 2: Sixteen bit unsigned integer
71+
+ Int16 = 3: Sixteen bit signed integer
72+
+ UInt32 = 4: Thirty two bit unsigned integer
73+
+ Int32 = 5: Thirty two bit signed integer
74+
+ UInt64 = 12: 64 bit unsigned integer
75+
+ Int64 = 13: 64 bit signed integer
76+
+ Float32 = 6: Thirty two bit floating point
77+
+ Float64 = 7: Sixty four bit floating point
78+
+ CInt16 = 8: Complex Int16
79+
+ CInt32 = 9: Complex Int32
80+
+ CFloat32 = 10: Complex Float32
81+
+ CFloat64 = 11: Complex Float64
82+
)";
83+
84+
static constexpr const char *DOC_EXAMPLE_1 = R"(
85+
SELECT ST_GetBandPixelType(raster, 1) FROM './test/data/mosaic/SCL.tif-land-clip00.tiff';
86+
)";
87+
88+
static constexpr DocTag DOC_TAGS_1[] = {
89+
{"ext", "spatial"}, {"category", "property"}
90+
};
91+
92+
static constexpr const char *DOC_DESCRIPTION_2 = R"(
93+
Returns the pixel type name of a band in the raster.
94+
95+
This is a string in the enumeration:
96+
97+
+ Unknown: Unknown or unspecified type
98+
+ Byte: Eight bit unsigned integer
99+
+ Int8: 8-bit signed integer
100+
+ UInt16: Sixteen bit unsigned integer
101+
+ Int16: Sixteen bit signed integer
102+
+ UInt32: Thirty two bit unsigned integer
103+
+ Int32: Thirty two bit signed integer
104+
+ UInt64: 64 bit unsigned integer
105+
+ Int64: 64 bit signed integer
106+
+ Float32: Thirty two bit floating point
107+
+ Float64: Sixty four bit floating point
108+
+ CInt16: Complex Int16
109+
+ CInt32: Complex Int32
110+
+ CFloat32: Complex Float32
111+
+ CFloat64: Complex Float64
112+
)";
113+
114+
static constexpr const char *DOC_EXAMPLE_2 = R"(
115+
SELECT ST_GetBandPixelTypeName(raster, 1) FROM './test/data/mosaic/SCL.tif-land-clip00.tiff';
116+
)";
117+
118+
static constexpr DocTag DOC_TAGS_2[] = {
119+
{"ext", "spatial"}, {"category", "property"}
120+
};
121+
58122
//------------------------------------------------------------------------------
59123
// Register functions
60124
//------------------------------------------------------------------------------
@@ -64,13 +128,17 @@ void GdalScalarFunctions::RegisterStBandPixelType(DatabaseInstance &db) {
64128
ScalarFunctionSet set("ST_GetBandPixelType");
65129
set.AddFunction(ScalarFunction({GeoTypes::RASTER(), LogicalType::INTEGER}, LogicalType::INTEGER, RasterGetPixelTypeFunction));
66130
ExtensionUtil::RegisterFunction(db, set);
131+
132+
DocUtil::AddDocumentation(db, "ST_GetBandPixelType", DOC_DESCRIPTION_1, DOC_EXAMPLE_1, DOC_TAGS_1);
67133
}
68134

69135
void GdalScalarFunctions::RegisterStBandPixelTypeName(DatabaseInstance &db) {
70136

71137
ScalarFunctionSet set("ST_GetBandPixelTypeName");
72138
set.AddFunction(ScalarFunction({GeoTypes::RASTER(), LogicalType::INTEGER}, LogicalType::VARCHAR, RasterGetPixelTypeNameFunction));
73139
ExtensionUtil::RegisterFunction(db, set);
140+
141+
DocUtil::AddDocumentation(db, "ST_GetBandPixelTypeName", DOC_DESCRIPTION_2, DOC_EXAMPLE_2, DOC_TAGS_2);
74142
}
75143

76144
} // namespace gdal

‎spatial/src/spatial/gdal/functions/scalar/st_has_no_band.cpp

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,23 @@ static void RasterHasNoBandFunction(DataChunk &args, ExpressionState &state, Vec
2525
});
2626
}
2727

28+
//------------------------------------------------------------------------
29+
// Documentation
30+
//------------------------------------------------------------------------
31+
32+
static constexpr const char *DOC_DESCRIPTION = R"(
33+
Returns true if there is no band with given band number.
34+
Band numbers start at 1 and band is assumed to be 1 if not specified.
35+
)";
36+
37+
static constexpr const char *DOC_EXAMPLE = R"(
38+
SELECT ST_HasNoBand(raster, 1) FROM './test/data/mosaic/SCL.tif-land-clip00.tiff';
39+
)";
40+
41+
static constexpr DocTag DOC_TAGS[] = {
42+
{"ext", "spatial"}, {"category", "property"}
43+
};
44+
2845
//------------------------------------------------------------------------------
2946
// Register functions
3047
//------------------------------------------------------------------------------
@@ -34,6 +51,8 @@ void GdalScalarFunctions::RegisterStGetHasNoBand(DatabaseInstance &db) {
3451
ScalarFunctionSet set("ST_HasNoBand");
3552
set.AddFunction(ScalarFunction({GeoTypes::RASTER(), LogicalType::INTEGER}, LogicalType::BOOLEAN, RasterHasNoBandFunction));
3653
ExtensionUtil::RegisterFunction(db, set);
54+
55+
DocUtil::AddDocumentation(db, "ST_HasNoBand", DOC_DESCRIPTION, DOC_EXAMPLE, DOC_TAGS);
3756
}
3857

3958
} // namespace gdal

0 commit comments

Comments
 (0)