@crossbind/port-gdal-wasi 2.0.0-beta.50

package/dist/prebuilt/wasi-wasm32-st-release/share/man/man1/gdal-raster-pixel-info.1

@@ -0,0 +1,486 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "GDAL-RASTER-PIXEL-INFO" "1" "Aug 18, 2026" "" "GDAL"
+.SH NAME
+gdal-raster-pixel-info \- Return information on a pixel of a raster dataset
+.sp
+Added in version 3.11.
+
+.SH SYNOPSIS
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+Usage: gdal raster pixel\-info [OPTIONS] <INPUT> [<column,line> or <X,Y>]
+
+Return information on a pixel of a raster dataset.
+
+Positional arguments:
+  \-i, \-\-dataset, \-\-input <INPUT>                       Input raster datasets [required]
+  \-p, \-\-pos, \-\-position <column,line> or <X,Y>         Pixel position [may be repeated]
+                                                       Mutually exclusive with \-\-position\-dataset
+
+Common Options:
+  \-h, \-\-help                                           Display help message and exit
+  \-\-json\-usage                                         Display usage as JSON document and exit
+  \-\-config <KEY>=<VALUE>                               Configuration option [may be repeated]
+
+Options:
+  \-f, \-\-of, \-\-format, \-\-output\-format <OUTPUT\-FORMAT>  Output format (default is \(aqGeoJSON\(aq if \(aqposition\-dataset\(aq not specified) [not available in pipelines]
+  \-\-position\-dataset <POSITION\-DATASET>                Vector dataset with coordinates
+                                                       Mutually exclusive with \-\-position
+  \-l, \-\-layer, \-\-input\-layer <INPUT\-LAYER>             Input layer name
+  \-o, \-\-output <OUTPUT>                                Output vector dataset (created by algorithm)
+  \-\-co, \-\-creation\-option <KEY>=<VALUE>                Creation option [may be repeated] [not available in pipelines]
+  \-\-lco, \-\-layer\-creation\-option <KEY>=<VALUE>         Layer creation option [may be repeated] [not available in pipelines]
+  \-\-overwrite                                          Whether overwriting existing output dataset is allowed [not available in pipelines]
+  \-b, \-\-band <BAND>                                    Input band(s) (1\-based index) [may be repeated]
+  \-\-overview <OVERVIEW>                                Which overview level of source file must be used
+  \-\-position\-crs <POSITION\-CRS>                        CRS of position (default is \(aqpixel\(aq if \(aqposition\-dataset\(aq not specified)
+  \-r, \-\-resampling <RESAMPLING>                        Resampling algorithm for interpolation. RESAMPLING=nearest|bilinear|cubic|cubicspline (default: nearest)
+  \-\-promote\-pixel\-value\-to\-z                           Whether to set the pixel value as Z component of GeoJSON geometry
+  \-\-include\-field <INCLUDE\-FIELD>                      Fields from coordinate dataset to include in output (special values: ALL and NONE) (default: ALL) [may be repeated]
+
+Advanced Options:
+  \-\-oo, \-\-open\-option <KEY>=<VALUE>                    Open options [may be repeated] [not available in pipelines]
+  \-\-if, \-\-input\-format <INPUT\-FORMAT>                  Input formats [may be repeated] [not available in pipelines]
+.EE
+.UNINDENT
+.UNINDENT
+.SH DESCRIPTION
+.sp
+\fBgdal raster pixel\-info\fP provide a mechanism to query information about
+a pixel given its location in one of a variety of coordinate systems.
+.sp
+The following items will be reported (when known):
+.INDENT 0.0
+.IP \(bu 2
+Input coordinates
+.IP \(bu 2
+Input coordinates converted to column, line
+.IP \(bu 2
+Pixel value per selected band(s), with unscaled value
+.IP \(bu 2
+For VRT files, which file(s) contribute to the pixel value (only for GeoJSON output)
+.UNINDENT
+.sp
+There are 3 possible ways of providing input location(s):
+.INDENT 0.0
+.IP \(bu 2
+from input stream, with a \(dqX Y\(dq pair per line, potentially followed by other text.
+.IP \(bu 2
+though the \fI\%\-\-position\fP argument.
+.IP \(bu 2
+through a GDAL vector dataset through the \fI\%\-\-position\-dataset\fP argument.
+.UNINDENT
+.sp
+There are 2 possibilities of outputting pixel information:
+.INDENT 0.0
+.IP \(bu 2
+either on the output stream as CSV or GeoJSON (default to GeoJSON)
+.IP \(bu 2
+or as a GDAL vector dataset whose name is specified with the \fI\%\-\-output\fP argument.
+.UNINDENT
+.sp
+Since GDAL 3.13, this algorithm can be part of a \fI\%gdal pipeline\fP\&. In that
+case, only reading coordinates from a GDAL vector dataset and outputting results
+to one is supported.
+.sp
+Added in version 3.13.
+
+.SH GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET)
+.sp
+This program supports serializing the command line as a JSON file using the \fBGDALG\fP output format.
+The resulting file can then be opened as a vector dataset using the
+\fI\%GDALG: GDAL Streamed Algorithm\fP driver, and apply the specified pipeline in a on\-the\-fly /
+streamed way.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+However this algorithm is not natively streaming compatible. Consequently a
+in\-memory temporary dataset will be generated, which may cause significant processing
+time at opening.
+.UNINDENT
+.UNINDENT
+.sp
+The following options are available:
+.SH PROGRAM-SPECIFIC OPTIONS
+.INDENT 0.0
+.TP
+.B \-b <band>
+Selects a band to query. Multiple bands can be listed. By default all
+bands are queried.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-f, \-\-of, \-\-format, \-\-output\-format <FORMAT>
+Which vector output format to use.
+.sp
+When \fI\%\-\-output\fP is not specified, \fBcsv\fP or \fBgeojson\fP are the
+only two supported choices, with \fBgeojson\fP being the default.
+Otherwise, any GDAL\-supported vector format with write capabilities is
+supported.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-position\-dataset <COORDINATE\-DATASET>
+Added in version 3.13.
+
+.sp
+GDAL\-compatible vector dataset from which input coordinates are read.
+If the input feature has a point geometry, its location is used to query
+the raster. For other geometry types, the centroid is used. To read all
+pixel values for non\-point geometries, use \fI\%gdal raster zonal\-stats\fP\&.
+By default, all attribute fields are copied to the output.
+.sp
+If the \fI\%\-\-position\-crs\fP argument is specified, the coordinates of
+the point are interpreted according to the value of that argument.
+.sp
+Otherwise, if the input vector layer has a CRS, coordinates are assumed to
+be expressed in it.
+.sp
+Otherwise, coordinates are assumed to be in the CRS raster dataset if it has
+a CRS.
+.sp
+Otherwise, coordinates are assumed to be expressed in the column,line raster space.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-l, \-\-layer, \-\-input\-layer <INPUT\-LAYER>
+Added in version 3.13.
+
+.sp
+Input layer name of the dataset specified with \fI\%\-\-position\-dataset\fP to use.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-o, \-\-output <OUTPUT>
+Added in version 3.13.
+
+.sp
+Output vector dataset (created by algorithm)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-include\-field <FIELD>
+Added in version 3.13.
+
+.sp
+Name of the field(s) from \fI\%\-\-position\-dataset\fP to include into the output.
+By default, all fields are included (which corresponds to special value \fBALL\fP).
+Special value \fBNONE\fP can be used to mean that no field from the position
+dataset must be included in the output.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-ovr, \-\-overview <index>
+Query the (overview_level)th overview (overview_level=0 is the 1st overview),
+instead of the base band. Note that the x,y location (if the coordinate system is
+pixel/line) must still be given with respect to the base band.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-p, \-\-pos, \-\-position <column,line> or <X,Y>
+Required, if \fI\%\-\-position\-dataset\fP is not specified and no content
+is provided through the input stream.
+.sp
+This can be specified either as an option, a positional value after the
+dataset name, or when called from \fBgdal\fP, as (space separated)
+values provided on the standard input.
+.sp
+By default, when \fI\%\-\-position\-crs\fP is not specified, or set to \fBpixel\fP,
+this is a column, line tuple (possibly with fractional part).
+If \fI\%\-\-position\-crs\fP is set to \fBdataset\fP, this is a georeferenced
+coordinate expressed in the CRS of the dataset.
+If \fI\%\-\-position\-crs\fP is specified to a CRS definition, this is a
+georeferenced coordinate expressed in this CRS.
+.sp
+X means always longitude or easting, Y means always latitude or northing.
+.sp
+Several x,y tuples may be specified.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-position\-crs pixel|dataset|<crs\-def>
+CRS of position, or one of two following special values:
+.INDENT 7.0
+.IP \(bu 2
+\fBpixel\fP means that the position is set as column, line (default)
+.IP \(bu 2
+\fBdataset\fP means that the position is a georeferenced
+coordinate expressed in the CRS of the dataset.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-promote\-pixel\-value\-to\-z
+Added in version 3.13.
+
+.sp
+Whether to set the pixel value as Z component of GeoJSON geometry.
+Only applies if a single band is selected, and for GeoJSON output format.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-r, \-\-resampling nearest|bilinear|cubic|cubicspline
+Select a sampling algorithm. The default is \fBnearest\fP\&.
+.sp
+The available methods are:
+.INDENT 7.0
+.IP \(bu 2
+\fBnearest\fP applies a nearest neighbour.
+.IP \(bu 2
+\fBbilinear\fP applies a bilinear convolution kernel.
+.IP \(bu 2
+\fBcubic\fP applies a cubic convolution kernel.
+.IP \(bu 2
+\fBcubicspline\fP applies a B\-Spline convolution kernel.
+.UNINDENT
+.UNINDENT
+.SH STANDARD OPTIONS
+.INDENT 0.0
+.TP
+.B \-\-oo, \-\-open\-option <NAME>=<VALUE>
+Dataset open option (format specific).
+.sp
+May be repeated.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-if, \-\-input\-format <format>
+Format/driver name to be attempted to open the input file(s). It is generally
+not necessary to specify it, but it can be used to skip automatic driver
+detection, when it fails to select the appropriate driver.
+This option can be repeated several times to specify several candidate drivers.
+Note that it does not force those drivers to open the dataset. In particular,
+some drivers have requirements on file extensions.
+.sp
+May be repeated.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-co, \-\-creation\-option <NAME>=<VALUE>
+Many formats have one or more optional creation options that can be
+used to control particulars about the file created. For instance,
+the GeoTIFF driver supports creation options to control compression,
+and whether the file should be tiled.
+.sp
+May be repeated.
+.sp
+The creation options available vary by format driver, and some
+simple formats have no creation options at all. A list of options
+supported for a format can be listed with the
+\fI\%\-\-formats\fP
+command line option but the documentation for the format is the
+definitive source of information on driver creation options.
+See \fI\%Raster drivers\fP format
+specific documentation for legal creation options for each format.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-lco, \-\-layer\-creation\-option <NAME>=<VALUE>
+Many formats have one or more optional layer creation options that can be
+used to control particulars about the layer created. For instance,
+the GeoPackage driver supports layer creation options to control the
+feature identifier or geometry column name, setting the identifier or
+description, etc.
+.sp
+May be repeated.
+.sp
+The layer creation options available vary by format driver, and some
+simple formats have no layer creation options at all. A list of options
+supported for a format can be listed with the
+\fI\%\-\-formats\fP
+command line option but the documentation for the format is the
+definitive source of information on driver creation options.
+See \fI\%Vector drivers\fP format
+specific documentation for legal creation options for each format.
+.sp
+Note that layer creation options are different from dataset creation options.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-overwrite
+Allow program to overwrite existing target file or dataset.
+Otherwise, by default, \fBgdal\fP errors out if the target file or
+dataset already exists.
+.UNINDENT
+.SH RETURN STATUS CODE
+.sp
+The program returns status code 0 in case of success, and non\-zero in case of
+error (non\-blocking errors emitted as warnings are considered as a successful
+execution).
+.SH EXAMPLES
+.SS Example 1: Reporting on pixel column=5, line=10 on the file byte.tif
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster pixel\-info byte.tif 5 10
+{
+  \(dqtype\(dq:\(dqFeatureCollection\(dq,
+  \(dqcrs\(dq:{
+    \(dqtype\(dq:\(dqname\(dq,
+    \(dqproperties\(dq:{
+      \(dqname\(dq:\(dqurn:ogc:def:crs:EPSG::26711\(dq
+    }
+  },
+  \(dqfeatures\(dq:[
+    {
+      \(dqtype\(dq:\(dqFeature\(dq,
+      \(dqproperties\(dq:{
+        \(dqinput_coordinate\(dq:[
+          5.0,
+          10.0
+        ],
+        \(dqcolumn\(dq:5.0,
+        \(dqline\(dq:10.0,
+        \(dqbands\(dq:[
+          {
+            \(dqband_number\(dq:1,
+            \(dqraw_value\(dq:132,
+            \(dqunscaled_value\(dq:132.0
+          }
+        ]
+      },
+      \(dqgeometry\(dq:{
+        \(dqtype\(dq:\(dqPoint\(dq,
+        \(dqcoordinates\(dq:[
+          441020.0,
+          3750720.0
+        ]
+      }
+    }
+  ]
+}
+.EE
+.UNINDENT
+.UNINDENT
+.SS Example 2: Reporting on point at UTM 11N coordinates easting=441320 and northing=3750720 on the file byte.tif
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster pixel\-info \-\-position\-crs=dataset byte.tif 441320 3750720
+{
+  \(dqtype\(dq:\(dqFeatureCollection\(dq,
+  \(dqcrs\(dq:{
+    \(dqtype\(dq:\(dqname\(dq,
+    \(dqproperties\(dq:{
+      \(dqname\(dq:\(dqurn:ogc:def:crs:EPSG::26711\(dq
+    }
+  },
+  \(dqfeatures\(dq:[
+    {
+      \(dqtype\(dq:\(dqFeature\(dq,
+      \(dqproperties\(dq:{
+        \(dqinput_coordinate\(dq:[
+          441320.0,
+          3750720.0
+        ],
+        \(dqcolumn\(dq:10.0,
+        \(dqline\(dq:10.0,
+        \(dqbands\(dq:[
+          {
+            \(dqband_number\(dq:1,
+            \(dqraw_value\(dq:115,
+            \(dqunscaled_value\(dq:115.0
+          }
+        ]
+      },
+      \(dqgeometry\(dq:{
+        \(dqtype\(dq:\(dqPoint\(dq,
+        \(dqcoordinates\(dq:[
+          441320.0,
+          3750720.0
+        ]
+      }
+    }
+  ]
+}
+.EE
+.UNINDENT
+.UNINDENT
+.SS Example 3: Reporting on point at WGS84 coordinates longitude=\-117.6355 and latitude=33.8970 on the file byte.tif, with CSV output format
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ gdal raster pixel\-info \-\-of=csv \-\-position\-crs=WGS84 byte.tif \-117.6355 33.8970
+geom_x,geom_y,extra_content,column,line,band_1_raw_value,band_1_unscaled_value
+\-117.6355,33.897,,10.020546288988,9.98330473474925,115,115
+.EE
+.UNINDENT
+.UNINDENT
+.SS Example 4: Reporting on point at WGS84 coordinates provided on the standard input with longitude, latitude order.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ echo \-117.6355 33.8970 | gdal raster pixel\-info \-\-of=csv \-\-position\-crs=WGS84 byte.tif
+geom_x,geom_y,extra_content,column,line,band_1_raw_value,band_1_unscaled_value
+\-117.6355,33.897,,10.020546288988,9.98330473474925,115,115
+.EE
+.UNINDENT
+.UNINDENT
+.SS Example 5: Reading coordinates to extract from an input GeoPackage file and writing the output to a GeoPackage file
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+gdal raster pixel\-info \-\-position\-dataset input.gpkg \-\-input byte.tif \-\-output output.gpkg
+.EE
+.UNINDENT
+.UNINDENT
+.SS Example 6: Getting pixel values from a on\-the\-fly resized raster dataset from coordinates in input.gpkg.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+gdal pipeline read byte.tif ! resize \-\-size 50%,50% \-r cubic ! pixel\-info input.gpkg ! write output.gpkg
+.EE
+.UNINDENT
+.UNINDENT
+.SS Example 7: Getting pixel values from coordinates in a piped vector dataset, using the _ placeholder dataset name
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+gdal pipeline read input.gml ! swap\-xy ! pixel\-info \-\-input byte.tif \-\-position\-dataset _ ! write output.gpkg
+.EE
+.UNINDENT
+.UNINDENT
+.SH AUTHOR
+Even Rouault <even.rouault@spatialys.com>
+.SH COPYRIGHT
+1998-2026
+.\" Generated by docutils manpage writer.
+.