pkcomposite(1)

NAME
pkcomposite - program to mosaic and composite geo-referenced images

SYNOPSIS
\FCpkcomposite\F[]
\FC-i\F[] input [\FC-i\F[] input] \FC-o\F[] output [options] [advanced options]

DESCRIPTION
pkcomposite 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.

Example: Calculate the maximum NDVI composite of two multispectral input images (e.g., red is band 0 and near infrared is band 1)

\FC
pkcomposite -i input1.tif -i input2.tif -o output.tif -cr maxndvi -cb 0 -cb 1
      \F[]

Example: Calculate the minimum nadir composite of two input images, where the forth band (b=3) contains the view zenith angle

\FC
pkcomposite -i input1.tif -i input2.tif -o minzenith.tif -cr minband -cb 3
      \F[]

Example: Calculate the minimum of two input images in all bands

\FC
pkcomposite -i input1.tif -i input2.tif -o minimum.tif -cr minallbands
      \F[]

OPTIONS

\FC-i\F[] filename, \FC--input\F[] filename
    Input image file(s). If input contains multiple images, a multi-band output is created

\FC-o\F[] filename, \FC--output\F[] filename
    Output image file

\FC-b\F[] band, \FC--band\F[] band
    band index(es) to crop (leave empty if all bands must be retained)

\FC-dx\F[] xres, \FC--dx\F[] xres
    Output resolution in x (in meter) (empty: keep original resolution)

\FC-dy\F[] yres, \FC--dy\F[] yres
    Output resolution in y (in meter) (empty: keep original resolution)

\FC-e\F[] vector, \FC--extent\F[] vector
    get boundary from extent from polygons in vector file

\FC-cut\F[], \FC--crop_to_cutline\F[]
    Crop the extent of the target dataset to the extent of the cutline

\FC-eo\F[] options, \FC--eo\F[] options
    Special extent options controlling rasterization: \FCATTRIBUTE|CHUNKYSIZE|ALL_TOUCHED|BURN_VALUE_FROM|MERGE_ALG\F[], e.g., \FC-eo\F[] \FCATTRIBUTE=\F[]fieldname

\FC-m\F[] mask, \FC--mask\F[] mask
    Use the first band of the specified file as a validity mask (0 is nodata)

\FC-msknodata\F[] value, \FC--msknodata\F[] value
    Mask value not to consider for composite

\FC-mskband\F[] value, \FC--mskband\F[] value
    Mask band to read (0 indexed)

\FC-ulx\F[] ULX, \FC--ulx\F[] ULX
    Upper left x value bounding box

\FC-uly\F[] ULY, \FC--uly\F[] ULY
    Upper left y value bounding box

\FC-lrx\F[] LRX, \FC--lrx\F[] LRX
    Lower right x value bounding box

\FC-lry\F[] LRY, \FC--lry\F[] LRY
    Lower right y value bounding box

\FC-cr\F[] rule, \FC--crule\F[] rule
    Composite rule (overwrite, maxndvi, maxband, minband, mean, mode (only for byte images), median, sum

\FC-cb\F[] band, \FC--cb\F[] band
    band index used for the composite rule (e.g., for ndvi, use \FC--cband=0\F[] \FC--cband=1\F[] with 0 and 1 indices for red and nir band respectively

\FC-srcnodata\F[] value, \FC--srcnodata\F[] value
    invalid value for input image

\FC-bndnodata\F[] band, \FC--bndnodata\F[] band
    Bands in input image to check if pixel is valid (used for srcnodata, min and max options)

\FC-min\F[] value, \FC--min\F[] value
    flag values smaller or equal to this value as invalid.

\FC-max\F[] value, \FC--max\F[] value
    flag values larger or equal to this value as invalid.

\FC-dstnodata\F[] value, \FC--dstnodata\F[] value
    nodata value to put in output image if not valid or out of bounds.

\FC-r\F[] resampling_method, \FC--resampling-method\F[] resampling_method
    Resampling method (near: nearest neighbor, bilinear: bi-linear interpolation).

\FC-ot\F[] type, \FC--otype\F[] type
    Data type for output image ({Byte / Int16 / UInt16 / UInt32 / Int32 / Float32 / Float64 / CInt16 / CInt32 / CFloat32 / CFloat64}). Empty string: inherit type from input image

\FC-of\F[] GDALformat, \FC--oformat\F[] GDALformat
    Output image format (see also gdal_translate(1)). Empty string: inherit from input image

\FC-co\F[] NAME=VALUE, \FC--co\F[] NAME=VALUE
    Creation option for output file. Multiple options can be specified.

\FC-a_srs\F[] EPSG:number, \FC--a_srs\F[] EPSG:number
    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)

\FC-v\F[], \FC--verbose\F[]
    verbose

Advanced options

\FC-file\F[], \FC--file\F[]
    write number of observations (1) or sequence nr of selected file (2) for each pixels as additional layer in composite. Default: 0

\FC-w\F[] weight, \FC--weight\F[] weight
    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.

\FC-c\F[] name, \FC--class\F[] name
    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.

\FC-ct\F[] filename, \FC--ct\F[] filename
    colour table in ASCII format having 5 columns: id R G B ALFA (0: transparent, 255: solid)

\FC-align\F[], \FC--align\F[]
    Align output bounding box to first input image

\FC-scale\F[] value, \FC--scale\F[] value
    Scale value \FCoutput=scale*input+offset\F[]

\FC-off\F[] value, \FC--offset\F[] value
    Offset value \FCoutput=scale*input+offset\F[]

\FC-d\F[] description, \FC--description\F[] description
    Set image description

EXAMPLE
Create a composit from two input images. If images overlap, keep only last image (default rule)

\FC
pkcomposite -i input1.tif -i input2.tif -o output.tif
      \F[]

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

\FC
pkcomposite -i input1.tif -i input2.tif -srcnodata 255 -bndnodata 1 -dstnodata 0 -o output.tif
      \F[]

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).

\FC
pkcomposite -i input1.tif -i input2.tif -cr maxndvi -rb 0 -rb 1 -srcnodata 255 -bndnodata 0 -dstnodata 0 -o output.tif
      \F[]

Create a composite image using weighted mean: output=(3/4*input1+6/4*input2+3/4*input2)/3.0

\FC
pkcomposite -i input1.tif -i input2.tif -i input3.tif -o output.tif -cr mean -w 0.75 -w 1.5 -w 0.75
      \F[]

Create a median composit of all GTiff images found in current directory that cover (at least part of) the image \FCcoverage.tif\F[]. Values smaller or equal to 0 are set as nodata 0 (default value for \FC-dstnodata\F[])

\FC
pkcomposite -i large.tif $(for IMAGE in *.tif;do pkinfo -i $IMAGE --cover $(pkinfo -i coverage.tif -bb);done) -cr median -min 0 -o output.tif
      \F[]

FAQ
Q1. First question

A1. For individual invalid value(s) in input image, use \FC-srcnodata\F[]

Usage: use unique value for each invalid bands set in \FC--bndnodata\F[] or use a single value that will be applied to all invalid bands

Example:

\FC
pkcomposite -i input1.tif -i input2.tif -o output.tif -srcnodata 0 -srcnodata 255 -bndnodata 0 -bndnodata 1
      \F[]

will consider 0 in band 0 and 255 in band 1 of input images as no value

\FC
pkcomposite -i input1.tif -i input2.tif -o output.tif -srcnodata 0 -bndnodata 0 -bndnodata 1
      \F[]

will consider 0 in both bands 0 and 1 of input images as no value

For range(s) of invalid values in input images: use \FC-min\F[] (\FC--min\F[]) and \FC-max\F[] (\FC--max\F[]) Usage: use unique range set for each invalid bands set in \FC-bndnodata\F[]

Example:

\FC
pkcomposite -i input1.tif -i input2.tif -o output.tif -min 0 -max 200 -min 0 -max 2 -bndnodata 0 -bndnodata 1
      \F[]

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

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?

A2. Yes