
%!encoding: iso-8859-1
%!includeconf: txt2tags.rc
= NAME =

pecomato - a portable picture-embedded metadata processor


= SYNOPSIS =

**pecomato** [//OPTION//...] //OP// [//EXPR//] //FILE// [//FILE//...]

**pecomato** [//OPTION//...] //OP// [//EXPR//] //@FILE//

usage of form //OP// //EXPR// only concerns //OP// mode **dump-value**, see below.


use //@file// to read a list of files from that file. the file must contain exactly one
filename to process per line (don't escape anything, filenames are taken as-is).


= DESCRIPTION =

**pecomato** is basically designed to display any kind of information embedded
in picture files, as well as checking, filtering, extracting, removing, adding
and fixing such information. In other words, it's a metadata processor.

It supports the following file formats: //JPEG/JFIF//, //Adobe PSD// and //FFO//, raw //IPTC//.
And it knows about the following metadata formats: //JFIF//, //IPTC//, //Exif//, //Adobe// and
Fotostation. More file and metadata formats might be supported later: //TIFF//,
etc.

One of its main goals is to check the validity of parsed metadata as well as
optionally check the strict compliance to official standards. On another hand,
it aims to provide ways of fixing broken or not compliant chunks as well as
providing general basic functions to manipulate the metadata.

Please visit the program homepage at
//""http://www.mollux.org/projects/pecomato/""//. Thanks for reporting issues at
//""https://www.mollux.org/services/bugzilla/""//.


= OPTIONS =


**general options:**
:  **-v**, **--version**
show version number then exit
:  **-h**, **--help**
show this usage help then exit
:      **--list**
list all supported embedded data structures
:  **-l**, **--log-level** //NUM//
define verbosity (see possible values below)
:  **-c**, **--check-compliance**
perform full checks to test the strict validity and
compliance of structures to official formats


**filtering and extracting options:**
:  **-b**, **--backup**
create backup files of (re)written files if necessary
:  **-d**, **--target-dir** //DIRNAME//
target directory for all written files
:  **-f**, **--fix**
fix metadata inconsistencies when possible


**extracting options:**
:  **-x**, **--extract** //TYPE//
extract and save metadata to a standalone file (see
below for a list of metadata types that can be extracted)
:  **-t**, **--ext** //EXTENSION//
define what filename extension to use when writing
metadata that is extracted (default: //.iptc//)
:  **-a**, **--append-ext**
append extension to original filename when saving
the extracted metadata (default: replace original file
extension)


**filtering options:**
:  **-i**, **--include** //EXPR//
a filter expression describing the datasets to keep
:  **-i**, **--include** //@FILE//
or a file containing a list of datasets to keep,
all other datasets will be filtered out.
if not used, all datasets will be kept
:  **-e**, **--exclude** //EXPR//
a filter expression describing the datasets to filter out
:  **-e**, **--exclude** //@FILE//
a file containing a list of datasets to filter out,
all other datasets will be kept. if not used all
datasets will be kept
:  **--edit** //EXPR//
a filter edit expression describing the datasets to add
:  **--edit** //@FILE//
or a file containing a list of datasets to add.
datasets won't be inserted if that breaks compliance
to the standards
:  **--test**
don't override original file, create *.rewrite file.
this option only affects rewriting of source files


**dump options:**
:  **-w**, **--wrap** //NUM//
max column for wrapping (num must be in range
[8-1024]). default is to dump unwrapped


= POSSIBLE OPS =

:  **check**
just check embedded data structures
:  **dump**
show embedded data (headers only)
:  **dump-full**
show all embedded data (including values)
:  **dump-value**
show requested value (headers only)
:  **filter**
filter embedded data (see **-i**, **-e** and **--edit**)



= DUMP-VALUE EXPRESSIONS =

: IPTC.<record>


same as filter include/exclude expression, see below:


= FILTER INCLUDE/EXCLUDE EXPRESSIONS =

: IPTC.<record>


where <record> can be either:
: all:               *
: hexadecimal unary: 0xhhhh
: hexadecimal range: 0xhhhh-0xhhhh
: decimal unary:     nnn:nnn
: decimal ranges:    nnn:nnn-nnn
:                    nnn:*


**examples:**
: IPTC.0x0219
: IPTC.0x0300-0x0364
: IPTC.3:0-100


= FILTER EDIT EXPRESSIONS =

: IPTC.<record>=<type>:<value>


where <record> can be either:
: hexadecimal unary: 0xhhhh
: decimal unary:     nnn:nnn


where <type> can be either:
: hex
: text


and <value> is:
: hex:  [a-zA-Z0-9] pairs
: text: any char (even widechars) on the line is taken as text, until
:       a newline is found


**examples:**
: IPTC.0x0200=hex:0002
: IPTC.0x0219=text:this is a keyword


= SUPPORTED METADATA FOR EXTRACTION =

:  **iptc**
IPTC datasets


= POSSIBLE LOG LEVELS =

:  **0**
quiet, no output at all
:  **1**
error messages only (default)
:  **2**
warning and error messages
:  **3**
informative, warning and error messages
:  **4**
all messages including debug ones


= SUPPORTED INPUT FILES =

:  **JPEG** files (commonly //.jpeg//, //.jpg//, //.jpe//, //.jfif//, //.jif//)
:  **Adobe Photoshop** files (commonly //.psd//, //.pdd//, //.ffo//)
:  **FotoStation** files (commonly .//fdp//, //.ipt//)
:  standalone **IPTC** metadata (commonly //.iptc//)


= EXIT CODES =

:  **0**
normal exit
:  **1**
usage error
:  **2**
asynchronous signal termination
:  **3**
normal exit, with warning(s)
:  **4**
normal exit, with error(s)
:  **5**
fatal error encountered


= EXAMPLES =

: **Check metadata structures of a JPEG file, only report errors**
``$ pecomato check file.jpg``


= AUTHOR =

Written by Tristan Chabredier //"wwp" <subscript@free.fr>//.


= COPYRIGHT =

Copyright (C) 2005-2007 Tristan Chabredier.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
