'\" -*- coding: UTF-8 -*-
.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 pkcomposite 1 "06 December 2020" "" ""
.SH NAME
pkcomposite \- program to mosaic and composite geo-referenced images
.SH SYNOPSIS
'nh
.fi
.ad l
\fBpkcomposite\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\fB-i\fR \fIinput\fR [\fB-i\fR \fIinput\fR] \fB-o\fR \fIoutput\fR [\fIoptions\fR] [\fIadvanced options\fR]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
\fBpkcomposite\fR can be used to {mosaic} and {composite}
multiple (georeferenced) raster datasets.
A mosaic can merge images with different geographical extents into a
single larger image.
Compositing resolves the overlapping pixels according to some rule
(e.g, the median of all overlapping pixels).
This utility is complementary to GDAL, which currently does not support
a composite step.
Input datasets can have different bounding boxes and spatial resolutions.
.PP
Example: Calculate the maximum NDVI composite of two multispectral
input images (e.g., red is band 0 and near infrared is band 1)
.PP
.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIinput1.tif\fR \fB\-i\fR \fIinput2.tif\fR \fB\-o\fR \fIoutput.tif\fR \fB\-cr\fR \fImaxndvi\fR \fB\-cb\fR \fI0\fR \fB\-cb\fR \fI1\fR
      \*(T>
.fi
.PP
Example: Calculate the minimum nadir composite of two input images,
where the forth band (b=3) contains the view zenith angle
.PP
.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIinput1.tif\fR \fB\-i\fR \fIinput2.tif\fR \fB\-o\fR \fIminzenith.tif\fR \fB\-cr\fR \fIminband\fR \fB\-cb\fR \fI3\fR
      \*(T>
.fi
.PP
Example: Calculate the minimum of two input images in all bands
.PP
.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIinput1.tif\fR \fB\-i\fR \fIinput2.tif\fR \fB\-o\fR \fIminimum.tif\fR \fB\-cr\fR \fIminallbands\fR
      \*(T>
.fi
.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\-b\fR\*(T> \fIband\fR, \*(T<\fB\-\-band\fR\*(T> \fIband\fR
band index(es) to crop (leave empty if all bands must be retained)
.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\-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> \fImask\fR, \*(T<\fB\-\-mask\fR\*(T> \fImask\fR
Use the first band of 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 composite
.TP 
\*(T<\fB\-mskband\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-mskband\fR\*(T> \fIvalue\fR
Mask band to read
(0 indexed)
.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\-cr\fR\*(T> \fIrule\fR, \*(T<\fB\-\-crule\fR\*(T> \fIrule\fR
Composite rule (overwrite, maxndvi, maxband, minband, mean, mode
(only for byte images), median, sum
.TP 
\*(T<\fB\-cb\fR\*(T> \fIband\fR, \*(T<\fB\-\-cb\fR\*(T> \fIband\fR
band index used for the composite rule (e.g., for ndvi, use
\*(T<\fB\-\-cband=0\fR\*(T> \*(T<\fB\-\-cband=1\fR\*(T> with 0 and 1
indices for red and nir band respectively 
.TP 
\*(T<\fB\-srcnodata\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-srcnodata\fR\*(T> \fIvalue\fR
invalid value for input image
.TP 
\*(T<\fB\-bndnodata\fR\*(T> \fIband\fR, \*(T<\fB\-\-bndnodata\fR\*(T> \fIband\fR
Bands in input image to check if pixel is valid
(used for srcnodata, min and max options)
.TP 
\*(T<\fB\-min\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-min\fR\*(T> \fIvalue\fR
flag values smaller or equal to this value as invalid.
.TP 
\*(T<\fB\-max\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-max\fR\*(T> \fIvalue\fR
flag values larger or equal to this value as invalid.
.TP 
\*(T<\fB\-dstnodata\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-dstnodata\fR\*(T> \fIvalue\fR
nodata value to put in output image if not valid or out of bounds. 
.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\-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\-of\fR\*(T> \fIGDALformat\fR, \*(T<\fB\-\-oformat\fR\*(T> \fIGDALformat\fR
Output image format (see also
\fBgdal_translate\fR(1)).
Empty string: inherit from input image 
.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\-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\-v\fR\*(T>, \*(T<\fB\-\-verbose\fR\*(T>
verbose
.PP
Advanced options
.TP 
\*(T<\fB\-file\fR\*(T>, \*(T<\fB\-\-file\fR\*(T>
write number of observations (1) or sequence nr of selected file (2)
for each pixels as additional layer in composite.
Default: 0
.TP 
\*(T<\fB\-w\fR\*(T> \fIweight\fR, \*(T<\fB\-\-weight\fR\*(T> \fIweight\fR
Weights (type: short) for the composite, use one weight for each
input file in same order as input files are provided).
Use value 1 for equal weights.
.TP 
\*(T<\fB\-c\fR\*(T> \fIname\fR, \*(T<\fB\-\-class\fR\*(T> \fIname\fR
classes for multi-band output image: each band represents the
number of observations for one specific class.
Use value 0 for no multi-band output image. 
.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 first input image
.TP 
\*(T<\fB\-scale\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-scale\fR\*(T> \fIvalue\fR
Scale value
\*(T<output=scale*input+offset\*(T>
.TP 
\*(T<\fB\-off\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-offset\fR\*(T> \fIvalue\fR
Offset value
\*(T<output=scale*input+offset\*(T>
.TP 
\*(T<\fB\-d\fR\*(T> \fIdescription\fR, \*(T<\fB\-\-description\fR\*(T> \fIdescription\fR
Set image description
.SH EXAMPLE
Create a composit from two input images. If images overlap, keep only
last image (default rule)
.PP
.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIinput1.tif\fR \fB\-i\fR \fIinput2.tif\fR \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.PP
Create a composit from two input images.
Values of 255 in band 1 (starting from 0) are masked as invalid.
Typically used when second band of input image is a cloud mask
.PP
.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIinput1.tif\fR \fB\-i\fR \fIinput2.tif\fR \fB\-srcnodata\fR \fI255\fR \fB\-bndnodata\fR \fI1\fR \fB\-dstnodata\fR \fI0\fR \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.PP
Create a maximum NDVI (normalized difference vegetation index) composit.
Values of 255 in band 0 are masked as invalid and flagged as 0 if no
other valid coverage.
Typically used for (e.g., MODIS) images where red and near infrared
spectral bands are stored in bands 0 and 1 respectively.
In this particular case, a value of 255 in the first input band
indicates a nodata value (e.g., cloud mask is coded within the data
values).
.PP
.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIinput1.tif\fR \fB\-i\fR \fIinput2.tif\fR \fB\-cr\fR \fImaxndvi\fR \fB\-rb\fR \fI0\fR \fB\-rb\fR \fI1\fR \fB\-srcnodata\fR \fI255\fR \fB\-bndnodata\fR \fI0\fR \fB\-dstnodata\fR \fI0\fR \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.PP
Create a composite image using weighted mean:
output=(3/4*input1+6/4*input2+3/4*input2)/3.0
.PP
.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIinput1.tif\fR \fB\-i\fR \fIinput2.tif\fR \fB\-i\fR \fIinput3.tif\fR \fB\-o\fR \fIoutput.tif\fR \fB\-cr\fR \fImean\fR \fB\-w\fR \fI0.75\fR \fB\-w\fR \fI1.5\fR \fB\-w\fR \fI0.75\fR
      \*(T>
.fi
.PP
Create a median composit of all GTiff images found in current directory
that cover (at least part of) the image
\*(T<\fIcoverage.tif\fR\*(T>.
Values smaller or equal to 0 are set as nodata 0 (default value for
\*(T<\fB\-dstnodata\fR\*(T>)
.PP
.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIlarge.tif\fR $(for IMAGE in *.tif;do \fBpkinfo\fR \fB\-i\fR $IMAGE \fB\-\-cover\fR $(\fBpkinfo\fR \fB\-i\fR \fIcoverage.tif\fR \fB\-bb\fR);done) \fB\-cr\fR \fImedian\fR \fB\-min\fR \fI0\fR \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.SH FAQ
Q1. First question
.PP
A1. For individual invalid value(s) in input image, use
\*(T<\fB\-srcnodata\fR\*(T>
.PP
Usage: use unique value for each invalid bands set in
\*(T<\fB\-\-bndnodata\fR\*(T> or use a single value that
will be applied to all invalid bands
.PP
Example:

.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIinput1.tif\fR \fB\-i\fR \fIinput2.tif\fR \fB\-o\fR \fIoutput.tif\fR \fB\-srcnodata\fR \fI0\fR \fB\-srcnodata\fR \fI255\fR \fB\-bndnodata\fR \fI0\fR \fB\-bndnodata\fR \fI1\fR
      \*(T>
.fi

will consider 0 in band 0 and 255 in band 1 of input images as no value
.PP
.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIinput1.tif\fR \fB\-i\fR \fIinput2.tif\fR \fB\-o\fR \fIoutput.tif\fR \fB\-srcnodata\fR \fI0\fR \fB\-bndnodata\fR \fI0\fR \fB\-bndnodata\fR \fI1\fR
      \*(T>
.fi

will consider 0 in both bands 0 and 1 of input images as no value
.PP
For range(s) of invalid values in input images: use
\*(T<\fB\-min\fR\*(T> (\*(T<\fB\-\-min\fR\*(T>) and
\*(T<\fB\-max\fR\*(T> (\*(T<\fB\-\-max\fR\*(T>)
Usage: use unique range set for each invalid bands set in
\*(T<\fB\-bndnodata\fR\*(T>
.PP
Example:

.nf
\*(T<
\fBpkcomposite\fR \fB\-i\fR \fIinput1.tif\fR \fB\-i\fR \fIinput2.tif\fR \fB\-o\fR \fIoutput.tif\fR \fB\-min\fR \fI0\fR \fB\-max\fR \fI200\fR \fB\-min\fR \fI0\fR \fB\-max\fR \fI2\fR \fB\-bndnodata\fR \fI0\fR \fB\-bndnodata\fR \fI1\fR
      \*(T>
.fi

will consider all negative values in band 0 and 1 of input images as
invalid.
Values larger or equal to 200 in band 0 will be invalid,
as well as values larger or equal to 2 in band 1
.PP
Q2. If I take the mean value as composit rule for multi-band input
images, will the output image contain the mean value of overlapping
images in each band?
.PP
A2. Yes