'\" -*- 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 rl2sniff 1 "03 August 2020" "" ""
.SH NAME
rl2sniff \- Sniffer tool for RasterLite2
.SH SYNOPSIS
'nh
.fi
.ad l
\fBrl2sniff\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[\fIARGLIST\fR]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
\fBrl2sniff\fR is a sniffer tool for RasterLite2.
Sometimes handling a relevant number of raster images (may be of
different origin and presenting different technical characteristics)
isn't an easy task, most notably when your images are dispersed into
many different folders.
The \fBrl2sniff\fR CLI tool is exactly intended to offer a
significant help in organizing and planning any preliminary activity
required in order to create and populate your RasterLite2's Coverages.
.PP
\fBrl2sniff\fR will examine files containing a raster image,
and will then create a report showing the more relevant characteristics
for each one; the supported arguments are the followings:
.TP 0.2i
\(bu
arguments specifying the intended target:
.RS 
.TP 0.2i
\(bu
\*(T<\fB\-src\fR\*(T> \fIpathname\fR:
will examine just a single input raster image.
.TP 0.2i
\(bu
\*(T<\fB\-dir\fR\*(T> \fIpathname\fR:
will explore a whole directory aka folder.
.TP 0.2i
\(bu
Please note: \*(T<\fB\-src\fR\*(T> and \*(T<\fB\-dir\fR\*(T>
are mutually exclusive options.
.TP 0.2i
\(bu
\*(T<\fB\-ext\fR\*(T> \fIextension\fR:
combined with \*(T<\fB\-dir\fR\*(T> will restrict the search
to a specific raster format.
.TP 0.2i
\(bu
if no target is explicitly selected (e.g. when there are no
arguments at all) then the
\fIcurrent working directory\fR will be
intended by default.
.RE
.TP 0.2i
\(bu
\*(T<\fB\-wf\fR\*(T>: any georeferencing information will be
always retrieved from a companion
.URL http://en.wikipedia.org/wiki/World_file worldfile
\&.

Please note: in this case any georeferencing found in the
\fIworldfile\fR will always override any
other information eventually found e.g. within a GeoTIFF image.
.TP 0.2i
\(bu
\*(T<\fB\-md5\fR\*(T>: the output report will include an
.URL http://en.wikipedia.org/wiki/MD5 "MD5 checksum"
computed for each raster file.

Please note: computing the MD5 checksums could require a
substantial amount of time, most notably when many hundredth
huge-sized files are to be scanned.
.PP
\fBthe output report\fR. 
The report created by \fBrl2sniff\fR simply corresponds
to a TXT/TAB being printed on the stdout file.
The report's columns are as follows:
.TP 0.2i
\(bu
columns always supported for both georeferenced and
non-georeferenced rasters:
.RS 
.TP 0.2i
\(bu
image_format: e.g. GeoTIFF, TIFF+TFW or ASCII Grid.
.TP 0.2i
\(bu
MD5_checksum: may be NULL is the corresponding option
wasn't activated.
.TP 0.2i
\(bu
image_path: the absolute path leading to the raster file.
.TP 0.2i
\(bu
width and height: horizontal and vertical dimensions
(in pixels).
.TP 0.2i
\(bu
sample_type, pixel_type and bands: e.g. UINT8, RGB, 3.
.TP 0.2i
\(bu
no_data: value corresponding to NO-DATA pixels
(currently supported only for ASCII Grids).
.TP 0.2i
\(bu
compression: e.g. DEFLATE or FAX4; NONE if uncompressed.
.RE
.TP 0.2i
\(bu
columns supported only for raster of the georeferenced type:
.RS 
.TP 0.2i
\(bu
srid: the declared SRID value; \*(T<\-1\*(T> if unknown / unspecified.
.TP 0.2i
\(bu
x_resolution and y_resolution: horizontal and vertical
pixel resolution.
.TP 0.2i
\(bu
min_x, min_y, max_x and max_y: extreme points of the
raster's bounding box aka BBOX.
.RE
.SH OPTIONS
.TP 
\*(T<\fB\-h\fR\*(T>, \*(T<\fB\-\-help\fR\*(T>
print usage information
.TP 
\*(T<\fB\-src\fR\*(T> \fIpathname\fR, \*(T<\fB\-\-src\-path\fR\*(T> \fIpathname\fR
single Image/Raster path
.TP 
\*(T<\fB\-dir\fR\*(T> \fIpathname\fR, \*(T<\fB\-\-dir\-path\fR\*(T> \fIpathname\fR
directory path
.TP 
\*(T<\fB\-ext\fR\*(T> \fIextension\fR, \*(T<\fB\-\-file\-ext\fR\*(T> \fIextension\fR
file extension (e.g. .tif)
.TP 
\*(T<\fB\-wf\fR\*(T>, \*(T<\fB\-\-worldfile\fR\*(T>
requires a Worldfile
.TP 
\*(T<\fB\-md5\fR\*(T>, \*(T<\fB\-\-md5\-checksum\fR\*(T>
enabling MD5 checksums