From 2f5caa0110402a2cf878ce2da004950ceec572f4 Mon Sep 17 00:00:00 2001
From: Guilhem Moulin <guilhem@fripost.org>
Date: Mon, 12 Aug 2013 02:30:50 +0200
Subject: Documentation.

---
 mkindex.pl | 147 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 147 insertions(+)

(limited to 'mkindex.pl')

diff --git a/mkindex.pl b/mkindex.pl
index 6502019..9573394 100755
--- a/mkindex.pl
+++ b/mkindex.pl
@@ -21,6 +21,153 @@ use 5.010_000;
 use warnings;
 use strict;
 
+=head1 NAME
+
+mkindex.pl - Merge a mapset into an index file
+
+=head1 SYNOPSIS
+
+B<mkindex.pl> [B<-q>] [B<-d>] [B<--rename> I<perlexpr>] [B<-s> I<geometry>]
+[B<-r> I<method>] [B<-b> I<border>] [B<-f> I<font>] [B<--s_srs> I<SRS>]
+[B<--t_srs> I<SRS>] I<map> [... I<map>] I<index>
+
+B<mkindex.pl> B<--man>
+
+=head1 DESCRIPTION
+
+Merge all given I<map>s into an index file, and annotate this index with
+tile borders and names.
+
+If required, each map is first expanded into RGBA, to get a decent
+resampling.
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<-q>, B<--quiet>
+
+Be quiet.
+
+=item B<-d>, B<--debug>
+
+Debug mode.
+
+=item B<--rename>=I<perlexpr>
+
+A Perl expression which is expected to modify the $_ string in Perl (set
+to each filename), to what should be displayed on the final index. The
+default is 's/\.[^.]+$//' that is, only the file extension is stripped
+away. See the B<EXAMPLES> section for other examples.
+
+=item B<-s> I<width>xI<height>, B<--size=>I<width>xI<height>
+
+The size of the output index (default: 1024x0). If I<width> or I<height>
+is 0, the other dimension will be guessed from the computed resolution.
+
+=item B<-r> I<resampling_method>, B<--resampling=>I<resampling_method>
+
+The resampling method to use. See gdalwarp(1) for the default and list
+of possible values.
+
+=item B<-b> I<width>[:I<color>], B<--border=>I<width>[:I<color>]
+
+The I<width> and I<color> of the border to draw around each tile
+(default: C<10:red>). I<width> is given in pixels, and I<color> needs to
+comply to ImageMagick's Color Model Specification.
+If one of I<width> or I<color> is left empty, the corresponding default
+is used (but the other can be specified regardless, for instance in
+C<:blue>).
+
+=item B<-f> I<font>[:I<color>[:I<font>]], B<--font=>I<size>[:I<color>[:I<font>]]
+
+The point I<size>, I<color> and I<font> to use when annotating each tile
+with its name (default: C<25::Helvetica>). I<color> and I<font> need to
+be ImageMagick-compatible.
+If I<color> is blank empty, the border's color is used instead.
+If one of I<width> or I<font> is left empty, the corresponding default
+is used (but the other can be specified regardless, for instance in
+C<::DejaVu-Sans-Book>).
+
+=item B<--s_srs=>I<SRS>
+
+The source spatial reference set. If the input maps include a SRS, it is
+ignored. I<SRS> can be passed in any format format understood by
+C<OGRSpatialReference.SetFromUserInput>, see gdalwarp(1) for details.
+
+=item B<--t_srs=>I<SRS>
+
+The target spatial reference set. This is required unless all I<maps>s
+have the same SRS, or if B<--s_srs> is used (in which case that SRS is
+used for the target index).
+I<SRS> can be passed in any format format understood by
+C<OGRSpatialReference.SetFromUserInput>, see gdalwarp(1) for details.
+
+=item B<--help>
+
+Show a brief help.
+
+=item B<--version>
+
+Show the version numbers.
+
+=item B<--man>
+
+Show the manpage.
+
+=back
+
+=head1 EXAMPLES
+
+=over 4
+
+=item mkindex.pl *.tif miff:- | display -
+
+Create an index with all TIFF files in the current directory; Don't save
+the index, but pipe it to display(1).
+
+=item mkindex.pl -b '15:RGBA(255,0,0,.25)' --s_srs=epsg:3067 *.tif index.tif
+
+Assume all map to be projected in EPSG:3067. Draw a 15-pixels wide , 25%
+transparent red around each tile.
+
+=item mkindex.pl -f '75::DejaVu-Sans-Book' --rename='s/U(.*)_RVK_25\.tif/$1/' *.tif index.tif
+
+Use DejaVu Sans with a pointsize of 75 for the captions. Also, display
+only the non-redundant part of the filenames.
+
+=back
+
+=head1 ENVIRONMENT
+
+A temporary working directory is created under the B<TMPDIR> (or C</tmp>
+if unset, at least in Unix:es), see C<File::Spec::tmpdir()>.
+
+=head1 REQUIREMENTS
+
+=over 4
+
+=item *
+
+Requires L<gdalwarp|http://gdal.org/> available on the command line.
+
+=item *
+
+Requires the perl modules
+L<Inline|http://search.cpan.org/~ingy/Inline-0.44/C/C-Cookbook.pod>,
+L<Geo::GDAL|http://geoinformatics.aalto.fi/doc/Geo-GDAL/html/>,
+L<Geo::OSR|http://geoinformatics.aalto.fi/doc/Geo-GDAL/html/> and
+L<Image::Magick|http://www.imagemagick.org/script/perl-magick.php>,
+all available on L<CPAN|http://www.cpan.org/>.
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2013 Guilhem Moulin. mkindex is free software,
+distributed under the GNU Public License, version 3 or later.
+
+=cut
 
 use Getopt::Long qw/:config posix_default no_ignore_case gnu_compat
                             bundling auto_version auto_help/;
-- 
cgit v1.2.3