'\" -*- 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 pkdiff 1 "14 June 2016" "" ""
.SH NAME
pkdiff \- program to compare two raster image files
.SH SYNOPSIS
'nh
.fi
.ad l
\fBpkdiff\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\fB-i\fR \fIinput\fR \fB-ref\fR \fIreference\fR [\fIoptions\fR] [\fIadvanced options\fR]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
\fBpkdiff\fR compares two datasets.
The reference can either be a raster or a vector, but the input must be
a raster dataset.
In case the reference is a raster dataset, a pixel by pixel comparison is
performed.
With no further options, the utility reports if the rasters are identical
or different.
If required, an output raster dataset can be written with a qualitative
information per pixel:
0 (input=reference), 1 (input>reference) or 2 (input<reference).
If, however, the reference is a vector dataset, it must consist of point
features.
Polygon features are automatically converted to the centroid points
before analyzing.
.PP
A typical use of the utility is to assess the accuracy of an input raster
land cover map, based on a reference vector dataset.
The reference dataset must contain an attribute (label) for each class.
A confusion matrix is produced if the option
\*(T<\fB\-cm\fR\*(T>|\*(T<\fB\-\-confusion\fR\*(T> is set.
Here too, an output dataset can be written, which will be a vector
dataset in this case.
It contains the reference feature points with the extracted data value of
the raster input dataset as a new attribute.
.SH OPTIONS
.TP 
\*(T<\fB\-i\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-input\fR\*(T> \fIfilename\fR
Input raster dataset.
.TP 
\*(T<\fB\-ref\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-reference\fR\*(T> \fIfilename\fR
Reference (raster or vector) dataset
.TP 
\*(T<\fB\-ln\fR\*(T> \fIlayer\fR, \*(T<\fB\-\-ln\fR\*(T> \fIlayer\fR
Layer name(s) in sample.
Leave empty to select all (for vector reference datasets only)
.TP 
\*(T<\fB\-b\fR\*(T> \fIband\fR, \*(T<\fB\-\-band\fR\*(T> \fIband\fR
Input raster band
.TP 
\*(T<\fB\-cm\fR\*(T>, \*(T<\fB\-\-confusion\fR\*(T>
Create confusion matrix (to stdout)
.TP 
\*(T<\fB\-lr\fR\*(T> \fIattribute\fR, \*(T<\fB\-\-lref\fR\*(T> \fIattribute\fR
Attribute name of the reference label
(for vector reference datasets only)
.TP 
\*(T<\fB\-c\fR\*(T> \fIname\fR, \*(T<\fB\-\-class\fR\*(T> \fIname\fR
List of class names.
.TP 
\*(T<\fB\-r\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-reclass\fR\*(T> \fIvalue\fR
List of class values (use same order as in classname option).
.TP 
\*(T<\fB\-nodata\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-nodata\fR\*(T> \fIvalue\fR
No data value(s) in input or reference dataset are ignored
.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.
Nodata values can be set with the option
\*(T<\fB\-\-msknodata\fR\*(T>.
.TP 
\*(T<\fB\-msknodata\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-msknodata\fR\*(T> \fIvalue\fR
Mask value(s) where image is invalid.
Use negative value for valid data
(example: use \*(T<\fB\-t\fR\*(T> \*(T<\-1\*(T>:
if only \*(T<\-1\*(T> is valid value)
.TP 
\*(T<\fB\-v\fR\*(T> \fIlevel\fR, \*(T<\fB\-\-verbose\fR\*(T> \fIlevel\fR
verbose level
.PP
Advanced options
.TP 
\*(T<\fB\-o\fR\*(T> \fIoutput\fR, \*(T<\fB\-\-output\fR\*(T> \fIoutput\fR
Output dataset (optional)
.TP 
\*(T<\fB\-f\fR\*(T> \fIOGRformat\fR, \*(T<\fB\-\-f\fR\*(T> \fIOGRformat\fR
OGR format for output vector (for vector reference datasets only)
.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\-lc\fR\*(T> \fIattribute\fR, \*(T<\fB\-\-lclass\fR\*(T> \fIattribute\fR
Attribute name of the classified label
(for vector reference datasets only)
.TP 
\*(T<\fB\-\-commission\fR\*(T> \fIvalue\fR
Value for commission errors: input label < reference label
.TP 
\*(T<\fB\-bnd\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-boundary\fR\*(T> \fIvalue\fR
Boundary for selecting the sample
(for vector reference datasets only)
.TP 
\*(T<\fB\-hom\fR\*(T>, \*(T<\fB\-\-homogeneous\fR\*(T>
Only take regions with homogeneous boundary into account
(for reference datasets only)
.TP 
\*(T<\fB\-circ\fR\*(T>, \*(T<\fB\-\-circular\fR\*(T>
Use circular boundary (for vector reference datasets only)
.TP 
\*(T<\fB\-ct\fR\*(T> \fIcolortable\fR, \*(T<\fB\-\-ct\fR\*(T> \fIcolortable\fR
Color table in ASCII format having 5 columns:
id R G B ALFA (0: transparent, 255: solid).
.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.
.SH EXAMPLE
Check if two raster images are different (reports only if images are
different or not)
.PP
.nf
\*(T<
\fBpkdiff\fR \fB\-i\fR \fIinput.tif\fR \fB\-ref\fR \fIreference.tif\fR
      \*(T>
.fi
.PP
Validate a classification map using points from a reference sample and
report confusion matrix
.PP
.nf
\*(T<
\fBpkdiff\fR \fB\-i\fR \fIclassificationMap.tif\fR \fB\-ref\fR \fIreferencePoints.tif\fR \fB\-cm\fR
      \*(T>
.fi