'\" -*- coding: us-ascii -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH pkcrop 1 "14 June 2016" "" ""
.SH NAME
pkcrop \- perform raster data operations on image such as crop, extract and stack bands
.SH SYNOPSIS
'nh
.fi
.ad l
\fBpkcrop\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\fB-i\fR \fIinput\fR \fB-o\fR \fIoutput\fR [\fIoptions\fR] [\fIadvanced options\fR]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
\fBpkcrop\fR can subset and stack raster images.
In the spatial domain it can crop a bounding box from a larger image.
The output bounding box is selected by setting the new corner coordinates
using the options \*(T<\fB\-ulx\fR\*(T> \*(T<\fB\-uly\fR\*(T>
\*(T<\fB\-lrx\fR\*(T> \*(T<\fB\-lry\fR\*(T>.
Alternatively you can set the new image center (\*(T<\fB\-x\fR\*(T>
\*(T<\fB\-y\fR\*(T>) and size.
This can be done either in projected coordinates (using the options
\*(T<\fB\-nx\fR\*(T> \*(T<\fB\-ny\fR\*(T>) or in image coordinates
(using the options \*(T<\fB\-ns\fR\*(T> \*(T<\fB\-nl\fR\*(T>).
You can also use a vector file to set the new bounding box (option
\*(T<\fB\-e\fR\*(T>).
In the spectral domain, \fBpkcrop\fR allows you to select
individual bands from one or more input image(s).
Bands are stored in the same order as provided on the command line,
using the option \*(T<\fB\-b\fR\*(T>.
Band numbers start with index 0 (indicating the first band).
The default is to select all input bands.
If more input images are provided, the bands are stacked into a
multi-band image.
If the bounding boxes or spatial resolution are not identical for all
input images, you should explicitly set them via the options.
The \fBpkcrop\fR utility is not suitable to mosaic or
composite images.
Consider the utility
\fBpkcomposite\fR(1)
instead.
.SH OPTIONS
.TP 
\*(T<\fB\-i\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-input\fR\*(T> \fIfilename\fR
Input image file(s).
If input contains multiple images, a multi-band output is created
.TP 
\*(T<\fB\-o\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-output\fR\*(T> \fIfilename\fR
Output image file
.TP 
\*(T<\fB\-of\fR\*(T> \fIout_format\fR, \*(T<\fB\-\-oformat\fR\*(T> \fIout_format\fR
Output image format (see also
\fBgdal_translate\fR(1)).
Empty string: inherit from input image
.TP 
\*(T<\fB\-ot\fR\*(T> \fItype\fR, \*(T<\fB\-\-otype\fR\*(T> \fItype\fR
Data type for output image
({Byte / Int16 / UInt16 / UInt32 / Int32 / Float32 / Float64 / CInt16 / CInt32 / CFloat32 / CFloat64}).
Empty string: inherit type from input image
.TP 
\*(T<\fB\-b\fR\*(T> \fIband\fR, \*(T<\fB\-\-band\fR\*(T> \fIband\fR
Band index to crop (leave empty to retain all bands)
.TP 
\*(T<\fB\-sband\fR\*(T> \fIband\fR, \*(T<\fB\-\-startband\fR\*(T> \fIband\fR
Start band sequence number
.TP 
\*(T<\fB\-eband\fR\*(T> \fIband\fR, \*(T<\fB\-\-endband\fR\*(T> \fIband\fR
End band sequence number
.TP 
\*(T<\fB\-ulx\fR\*(T> \fIULX\fR, \*(T<\fB\-\-ulx\fR\*(T> \fIULX\fR
Upper left x value bounding box
.TP 
\*(T<\fB\-uly\fR\*(T> \fIULY\fR, \*(T<\fB\-\-uly\fR\*(T> \fIULY\fR
Upper left y value bounding box
.TP 
\*(T<\fB\-lrx\fR\*(T> \fILRX\fR, \*(T<\fB\-\-lrx\fR\*(T> \fILRX\fR
Lower right x value bounding box
.TP 
\*(T<\fB\-lry\fR\*(T> \fILRY\fR, \*(T<\fB\-\-lry\fR\*(T> \fILRY\fR
Lower right y value bounding box
.TP 
\*(T<\fB\-dx\fR\*(T> \fIxres\fR, \*(T<\fB\-\-dx\fR\*(T> \fIxres\fR
Output resolution in x (in meter)
(empty: keep original resolution)
.TP 
\*(T<\fB\-dy\fR\*(T> \fIyres\fR, \*(T<\fB\-\-dy\fR\*(T> \fIyres\fR
Output resolution in y (in meter)
(empty: keep original resolution)
.TP 
\*(T<\fB\-r\fR\*(T> \fIresampling_method\fR, \*(T<\fB\-\-resampling\-method\fR\*(T> \fIresampling_method\fR
Resampling method (near: nearest neighbor,
bilinear: bi-linear interpolation).
.TP 
\*(T<\fB\-a_srs\fR\*(T> \fIEPSG:number\fR, \*(T<\fB\-\-a_srs\fR\*(T> \fIEPSG:number\fR
Override the spatial reference for the output file
(leave blank to copy from input file, use epsg:3035
to use European projection and force to European grid)
.TP 
\*(T<\fB\-nodata\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-nodata\fR\*(T> \fIvalue\fR
Nodata value to put in image if out of bounds.
.PP
Advanced options
.TP 
\*(T<\fB\-e\fR\*(T> \fIvector\fR, \*(T<\fB\-\-extent\fR\*(T> \fIvector\fR
get boundary from extent from polygons in vector file
.TP 
\*(T<\fB\-cut\fR\*(T>, \*(T<\fB\-\-crop_to_cutline\fR\*(T>
Crop the extent of the target dataset to the extent of the cutline
.TP 
\*(T<\fB\-eo\fR\*(T> \fIoptions\fR, \*(T<\fB\-\-eo\fR\*(T> \fIoptions\fR
Special extent options controlling rasterization:
\*(T<ATTRIBUTE|CHUNKYSIZE|ALL_TOUCHED|BURN_VALUE_FROM|MERGE_ALG\*(T>,
e.g., \*(T<\fB\-eo\fR\*(T>
\*(T<ATTRIBUTE=\*(T>\fIfieldname\fR
.TP 
\*(T<\fB\-m\fR\*(T> \fIfile\fR, \*(T<\fB\-\-mask\fR\*(T> \fIfile\fR
Use the specified file as a validity mask (0 is nodata)
.TP 
\*(T<\fB\-msknodata\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-msknodata\fR\*(T> \fIvalue\fR
Mask value not to consider for crop
.TP 
\*(T<\fB\-mskband\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-mskband\fR\*(T> \fIvalue\fR
Mask band to read (0 indexed).
.TP 
\*(T<\fB\-co\fR\*(T> \fINAME=VALUE\fR, \*(T<\fB\-\-co\fR\*(T> \fINAME=VALUE\fR
Creation option for output file.
Multiple options can be specified.
.TP 
\*(T<\fB\-x\fR\*(T> \fIcenter_x\fR, \*(T<\fB\-\-x\fR\*(T> \fIcenter_x\fR
x-coordinate of image center to crop (in meter)
.TP 
\*(T<\fB\-y\fR\*(T> \fIcenter_y\fR, \*(T<\fB\-\-y\fR\*(T> \fIcenter_y\fR
y-coordinate of image center to crop (in meter)
.TP 
\*(T<\fB\-nx\fR\*(T> \fIsize_x\fR, \*(T<\fB\-\-nx\fR\*(T> \fIsize_x\fR
image size in x to crop (in meter)
.TP 
\*(T<\fB\-ny\fR\*(T> \fIsize_y\fR, \*(T<\fB\-\-ny\fR\*(T> \fIsize_y\fR
image size in y to crop (in meter)
.TP 
\*(T<\fB\-ns\fR\*(T> \fInsample\fR, \*(T<\fB\-\-ns\fR\*(T> \fInsample\fR
number of samples to crop (in pixels)
.TP 
\*(T<\fB\-nl\fR\*(T> \fInlines\fR, \*(T<\fB\-\-nl\fR\*(T> \fInlines\fR
number of lines to crop (in pixels)
.TP 
\*(T<\fB\-as\fR\*(T> \fImin\fR \*(T<\fB\-as\fR\*(T> \fImax\fR, \*(T<\fB\-\-autoscale\fR\*(T> \fImin\fR \*(T<\fB\-\-autoscaleautoscale\fR\*(T> \fImax\fR
scale output to min and max, e.g.,
\*(T<\fB\-\-autoscale\fR\*(T> \fI0\fR
\*(T<\fB\-\-autoscale\fR\*(T> \fI255\fR
.TP 
\*(T<\fB\-scale\fR\*(T> \fIscale\fR, \*(T<\fB\-\-scale\fR\*(T> \fIscale\fR
output=scale*input+offset
.TP 
\*(T<\fB\-off\fR\*(T> \fIoffset\fR, \*(T<\fB\-\-offset\fR\*(T> \fIoffset\fR
output=scale*input+offset
.TP 
\*(T<\fB\-ct\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-ct\fR\*(T> \fIfilename\fR
colour table in ASCII format having 5 columns: id R G B ALFA
(0: transparent, 255: solid)
.TP 
\*(T<\fB\-align\fR\*(T>, \*(T<\fB\-\-align\fR\*(T>
Align output bounding box to input image
.TP 
\*(T<\fB\-d\fR\*(T> \fIdescription\fR, \*(T<\fB\-\-description\fR\*(T> \fIdescription\fR
Set image description
.TP 
\*(T<\fB\-v\fR\*(T>, \*(T<\fB\-\-verbose\fR\*(T>
verbose
.SH EXAMPLE
Crop the input image to the given bounding box
.PP
.nf
\*(T<
\fBpkcrop\fR \fB\-i\fR \fIinput.tif\fR \fB\-ulx\fR \fI100\fR \fB\-uly\fR \fI1000\fR \fB\-lrx\fR \fI600\fR \fB\-lrx\fR \fI100\fR \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.PP
Crop the input image to the envelop of the given polygon and mask all
pixels outside polygon as 0 (using
\fBgdal_rasterize\fR(1))
.PP
.nf
\*(T<
\fBpkcrop\fR \fB\-i\fR \fIinput.tif\fR \fB\-e\fR \fIextent.shp\fR \fB\-o\fR \fIoutput.tif\fR
gdal_rasterize \-i \-burn 0 \-l extent extent.shp output.tif
\fBgdal_rasterize\fR \fB\-i\fR \fB\-burn\fR \fI0\fR \fB\-l\fR \fIextent\fR \fIextent.shp\fR \fIoutput.tif\fR
      \*(T>
.fi
.PP
Extract bands 3,2,1 (starting from 0) in that order from multi-band
raster image \*(T<\fIinput.tif\fR\*(T>
.PP
.nf
\*(T<
\fBpkcrop\fR \fB\-i\fR \fIinput.tif\fR \fB\-b\fR \fI3\fR \fB\-b\fR \fI2\fR \fB\-b\fR \fI1\fR \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.PP
Scale raster floating point image \*(T<\fIfimage.tif\fR\*(T> with
factor 100 and write as single byte image with the given colourtable
(for auto scaling, see next example)
.PP
.nf
\*(T<
\fBpkcrop\fR \fB\-i\fR \fIfimage.tif\fR \fB\-s\fR \fI100\fR \fB\-ot\fR \fIByte\fR \fB\-o\fR \fIbimage.tif\fR \fB\-ct\fR \fIcolortable.txt\fR
      \*(T>
.fi
.PP
Automatically scale raster floating point image
\*(T<\fIfimage.tif\fR\*(T> to [0:100] and write the output as a
single byte image with the given colourtable
.PP
.nf
\*(T<
\fBpkcrop\fR \fB\-i\fR \fIfimage.tif\fR \fB\-as\fR \fI0\fR \fB\-as\fR \fI100\fR \fB\-ot\fR \fIByte\fR \fB\-o\fR \fIbimage.tif\fR \fB\-ct\fR \fIcolortable.txt\fR
      \*(T>
.fi
.PP
Crop raster image \*(T<\fIlarge.tif\fR\*(T> to the bounding box of
raster image \*(T<\fIsmall.tif\fR\*(T> and use the same pixel size.
.PP
.nf
\*(T<
\fBpkcrop\fR \fB\-i\fR \fIlarge.tif\fR $(\fBpkinfo\fR \fB\-i\fR \fIsmall.tif\fR \fB\-bb\fR \fB\-dx\fR \fB\-dy\fR) \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.SH "SEE ALSO"
\fBpkcomposite\fR(1)