.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "FINDIMAGEDUPES 1p"
.TH FINDIMAGEDUPES 1p 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
findimagedupes \- Finds visually similar or duplicate images
.SH SYNOPSIS
.IX Header "SYNOPSIS"
findimagedupes [option ...] [\-\-] [ \- | [file ...] ]
.PP
.Vb 9
\&   Options:
\&      \-f, \-\-fingerprints=FILE    \-c, \-\-collection=FILE
\&      \-M, \-\-merge=FILE           \-p, \-\-program=PROGRAM
\&      \-P, \-\-prune                \-s, \-\-script=FILE
\&      \-a, \-\-add                  \-i, \-\-include=TEXT
\&      \-r, \-\-rescan               \-I, \-\-include\-file=FILE
\&      \-n, \-\-no\-compare
\&                                 \-q, \-\-quiet
\&      \-t, \-\-threshold=AMOUNT     \-v, \-\-verbosity=LIST
\&
\&      \-0, \-\-null                 \-h, \-\-help
\&      \-R, \-\-recurse                  \-\-man
\&                                     \-\-version
.Ve
.PP
With no options, compares the specified files and does not use nor
update any fingerprint database.
.PP
Directories of images may be specified instead of individual files;
Sub-directories of these are not searched unless \-\-recurse is used.
.SH OPTIONS
.IX Header "OPTIONS"
.IP "\fB\-0\fR, \fB\-\-null\fR" 8
.IX Item "-0, --null"
If a file \f(CW\*(C`\-\*(C'\fR is given, a list of files is read from stdin.
.Sp
Without \fB\-0\fR, the list is specified one file per line, such as
produced by \fBfind\fR\|(1) with its \f(CW\*(C`\-print\*(C'\fR option.
.Sp
With \fB\-0\fR, the list is expected to be null-delimited, such as
produced by \fBfind\fR\|(1) with its \f(CW\*(C`\-print0\*(C'\fR option.
.IP "\fB\-a\fR, \fB\-\-add\fR" 8
.IX Item "-a, --add"
Only look for duplicates of files specified on the commandline.
.Sp
Matches are also sought in any fingerprint databases specified.
.IP "\fB\-c\fR, \fB\-\-collection\fR=\fIFILE\fR" 8
.IX Item "-c, --collection=FILE"
Create GQView collection \fIFILE\fR.gqv of duplicates.
.Sp
The program attempts to produce well-formed collections.
In particular, it will print a warning and exclude any file
whose name contains newline or doublequote. (In this situation,
\&\fBgqview\fR\|(1) seems to create a .gqv collection file that it
silently fails to read back in properly.)
.IP "\fB\-d\fR, \fB\-\-debug\fR=\fIOPTS\fR" 8
.IX Item "-d, --debug=OPTS"
Enable debugging output. Options \fIOPTS\fR are subject to change.
See the program source for details.
.IP "\fB\-f\fR, \fB\-\-fingerprints\fR=\fIFILE\fR" 8
.IX Item "-f, --fingerprints=FILE"
Use \fIFILE\fR as fingerprint database.
.Sp
May be abbreviated as \fB\-\-fp\fR or \fB\-\-db\fR.
.Sp
This option may be given multiple times when \fB\-\-merge\fR is used.
(Note: \fIFILE\fR could contain commas, so multiple databases may
not be specified as a single comma-delimited list.)
.IP "\fB\-h\fR, \fB\-\-help\fR" 8
.IX Item "-h, --help"
Print usage and option sections of this manual, then exit.
.IP "\fB\-i\fR, \fB\-\-include\fR=\fITEXT\fR" 8
.IX Item "-i, --include=TEXT"
\&\fITEXT\fR is Bourne-shell code to customise \fB\-\-script\fR.
.Sp
It is executed after any code included using \fB\-\-include\-file\fR.
.Sp
May be given multiple times. Code will be concatenated.
.IP "\fB\-I\fR, \fB\-\-include\-file\fR=\fIFILE\fR" 8
.IX Item "-I, --include-file=FILE"
\&\fIFILE\fR is a file containing Bourne-shell code to customise 
\&\fB\-\-script\fR.
.Sp
It is executed before any code included using \fB\-\-include\fR.
.IP \fB\-\-man\fR 8
.IX Item "--man"
Display the full documentation, using default pager, then exit.
.IP "\fB\-M\fR, \fB\-\-merge\fR=\fIFILE\fR" 8
.IX Item "-M, --merge=FILE"
Takes any databases specified with \fB\-\-fingerprints\fR
and merges them into a new database called \fIFILE\fR.
Conflicting fingerprints for an image will cause one of two actions to occur:
.RS 8
.IP 1. 4
If the image does not exist, then the entry is elided.
.IP 2. 4
If the image does exist, then the old information is ignored
and a new fingerprint is generated from scratch.
.RE
.RS 8
.Sp
By default, image existence is not checked unless there is a conflict.
To force removal of defunct data, use \fB\-\-prune\fR as well.
.Sp
A list of image files is not required if this option is used.
However, if a list is provided, fingerprint data for the files
will be copied or (re)generated as appropriate.
.Sp
When \fB\-\-merge\fR is used, the original fingerprint databases are not modified,
even if \fB\-\-prune\fR is used.
.Sp
If multiple fingerprint databases are to be used but the merge output is
not required, specify: \fB\-\-merge\fR=\fI/dev/null\fR
.Sp
See also: \fB\-\-rescan\fR
.RE
.IP "\fB\-n\fR, \fB\-\-no\-compare\fR" 8
.IX Item "-n, --no-compare"
Don't look for duplicates.
.IP "\fB\-p\fR, \fB\-\-program\fR=\fIPROGRAM\fR" 8
.IX Item "-p, --program=PROGRAM"
Launch \fIPROGRAM\fR (in foreground) to view each set of dupes.
.Sp
\&\fIPROGRAM\fR must be the full path to an existing executable file.
For more flexibility, see the \fB\-\-include\fR and \fB\-\-include\-file\fR
options.
.Sp
See also: \fB\-\-script\fR
.IP "\fB\-P\fR, \fB\-\-prune\fR" 8
.IX Item "-P, --prune"
Remove fingerprint data for images that do not exist any more.
Has no effect unless \fB\-\-fingerprints\fR or \fB\-\-merge\fR is also used.
.Sp
Databases specified by \fB\-\-fingerprints\fR are only modified if
\&\fB\-\-merge\fR is not used.
.IP "\fB\-q\fR, \fB\-\-quiet\fR" 8
.IX Item "-q, --quiet"
This option may be given multiple times.
.Sp
Usually, progress, warning and error messages are printed on stderr.
If this option is given, warnings are not displayed.
If it is given twice or more, errors are not displayed either.
.Sp
Information requested with \fB\-\-verbosity\fR is still displayed.
.IP "\fB\-R\fR, \fB\-\-recurse\fR" 8
.IX Item "-R, --recurse"
Use \fB\-\-recurse\fR to search recursively for images inside
subdirectories. For historical reasons, the default is to not do so.
To avoid looping, symbolic links to directories are never followed.
.IP "\fB\-r\fR, \fB\-\-rescan\fR" 8
.IX Item "-r, --rescan"
(Re)generate all fingerprints, not just any that are unknown.
.Sp
If used with \fB\-\-add\fR, only the fingerprints of files specified
on the commandline are (re)generated.
.Sp
Implies \fB\-\-prune\fR.
.IP "\fB\-s\fR, \fB\-\-script\fR=\fIFILE\fR" 8
.IX Item "-s, --script=FILE"
When used with \fB\-\-program\fR, \fIPROGRAM\fR is not launched immediately.
Instead \fBsh\fR\|(1)\-style commands are saved to \fIFILE\fR.
This script may be edited (if desired) and then executed manually.
.Sp
When used without \fB\-\-program\fR, two skeletal shell functions
are generated: \f(CW\*(C`VIEW\*(C'\fR simply \fBecho\fR\|(1)s its arguments; 
the empty function \f(CW\*(C`END\*(C'\fR runs after files-processing is finished.
.Sp
To display to terminal (or feed into a pipe), use \f(CW\*(C`\-\*(C'\fR as \fIFILE\fR.
.Sp
If \fB\-\-script\fR is not given, the script is still created in memory and
is executed immediately. So, with the default VIEW and END functions,
lines containing sets of duplicates are displayed. See: \fBEXAMPLES\fR
.Sp
See also: \fB\-\-include\fR, \fB\-\-include\-file\fR
.IP "\fB\-t\fR, \fB\-\-threshold\fR=\fIAMOUNT\fR" 8
.IX Item "-t, --threshold=AMOUNT"
Use \fIAMOUNT\fR as threshold of similarity.
Append \f(CW\*(C`%\*(C'\fR to give a percentage or \f(CW\*(C`b\*(C'\fR for bits.
For backwards compatibility, a number with no unit is treated as
a percentage. Percentage is the minimum required for a match;
bits is the maximum that may differ: bits=floor(2.56(100\-percent))
.Sp
A fractional part may be given but it is only accurate to 100/256
(0.390625) for percentage and it is meaningless for \f(CW\*(C`bits\*(C'\fR.
Default is \f(CW\*(C`90%\*(C'\fR (\f(CW\*(C`25b\*(C'\fR) if not specified.
.IP "\fB\-v\fR, \fB\-\-verbosity\fR=\fILIST\fR" 8
.IX Item "-v, --verbosity=LIST"
Enable display of informational messages to stdout,
where \fILIST\fR is a comma-delimited list of:
.RS 8
.IP \fBmd5\fR 8
.IX Item "md5"
Display the checksum for each file, as per \fBmd5sum\fR\|(1).
.IP "\fBfingerprint\fR | \fBfp\fR" 8
.IX Item "fingerprint | fp"
Display the base64\-encoded fingerprint of each file.
.RE
.RS 8
.Sp
Alternatively, \fB\-\-verbosity\fR may be given multiple times, and accumulates.
Note that this may not be sensible. For example, to be useful,
\&\fBmd5\fR output probably should not be merged with \fBfingerprint\fR data.
.RE
.IP \fBversion\fR 8
.IX Item "version"
Display the program version, then exit.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBfindimagedupes\fR compares a list of files for visual similarity.
.IP "To calculate an image fingerprint:" 1
.IX Item "To calculate an image fingerprint:"
.Vb 9
\& 1) Read image.
\& 2) Resample to 160x160 to standardize size.
\& 3) Grayscale by reducing saturation.
\& 4) Blur a lot to get rid of noise.
\& 5) Normalize to spread out intensity as much as possible.
\& 6) Equalize to make image as contrasty as possible.
\& 7) Resample again down to 16x16.
\& 8) Reduce to 1bpp.
\& 9) The fingerprint is this raw image data.
.Ve
.IP "To compare two images for similarity:" 1
.IX Item "To compare two images for similarity:"
.Vb 3
\& 1) Take fingerprint pairs and xor them.
\& 2) Compute the percentage of 1 bits in the result.
\& 3) If percentage exceeds threshold, declare files to be similar.
.Ve
.SH "RETURN VALUE"
.IX Header "RETURN VALUE"
.IP \fB0\fR 4
.IX Item "0"
Success.
.IP \fB1\fR 4
.IX Item "1"
Usage information was requested (\fB\-\-help\fR or \fB\-\-man\fR), or there
were warnings.
.IP \fB2\fR 4
.IX Item "2"
Invalid options or arguments were provided.
.IP \fB3\fR 4
.IX Item "3"
Runtime error.
.PP
Any other return values indicate an internal error of some sort.
.SH DIAGNOSTICS
.IX Header "DIAGNOSTICS"
To be written.
.SH EXAMPLES
.IX Header "EXAMPLES"
.ie n .IP """findimagedupes \-R \-\- .""" 4
.el .IP "\f(CWfindimagedupes \-R \-\- .\fR" 4
.IX Item "findimagedupes -R -- ."
Look for and compare images in all subdirectories of the current directory.
.ie n .IP """find . \-type f \-print0 | findimagedupes \-0 \-\- \-""" 4
.el .IP "\f(CWfind . \-type f \-print0 | findimagedupes \-0 \-\- \-\fR" 4
.IX Item "find . -type f -print0 | findimagedupes -0 -- -"
Same as above.
.ie n .IP """findimagedupes \-i \*(Aqecho ""# sort: manual""\*(Aq \-i \*(AqVIEW(){ for f in ""$@"";do echo \e""file://$f\e"";done }\*(Aq \-\- *.jpg > dupes.gqv""" 4
.el .IP "\f(CWfindimagedupes \-i \*(Aqecho ""# sort: manual""\*(Aq \-i \*(AqVIEW(){ for f in ""$@"";do echo \e""file://$f\e"";done }\*(Aq \-\- *.jpg > dupes.gqv\fR" 4
.IX Item "findimagedupes -i echo ""# sort: manual"" -i VIEW(){ for f in ""$@"";do echo ""file://$f"";done } -- *.jpg > dupes.gqv"
Use script hooks to produce collection-style output
suitable for use with \fBgthumb\fR\|(1).
.SH FILES
.IX Header "FILES"
To be written.
.SH BUGS
.IX Header "BUGS"
There is a memory leak somewhere.
.PP
Killing the program may corrupt the fingerprint database(s).
.PP
The program does not lock the fingerprint database although concurrent
write access to it is unsafe.
.PP
GraphicsMagick does not expose its auto-orient functionality to Perl.
.PP
Changing version of GraphicsMagick invalidates fingerprint databases.
.SH NOTES
.IX Header "NOTES"
Directory recursion is deliberately not implemented:
Composing a file-list and using it with \f(CW\*(C`\-\*(C'\fR is a more flexible approach.
.PP
Repetitions are culled before comparisons take place, so a commandline
like \f(CW\*(C`findimagedupes a.jpg a.jpg\*(C'\fR will not produce a match.
.PP
The program needs a lot of memory. Probably not an issue, unless your
machine has less than 128MB of free RAM and you try to compare more than
a hundred-thousand files at once (and the program will run quite slowly
with that many files anyway\-\-\-about eight hours initially to generate
fingerprints and another ten minutes to do the actual comparing).
.PP
Fingerprinting images is a bottleneck but unfortunately the program was
not written with parallel processing in mind. For a workaround, see:
https://github.com/jhnc/findimagedupes/issues/9
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBfind\fR\|(1), \fBmd5sum\fR\|(1)
.PP
\&\fBgqview\fR \- GTK based multiformat image viewer
.PP
\&\fBgthumb\fR \- an image viewer and browser for GNOME
.SH AUTHOR
.IX Header "AUTHOR"
Jonathan H N Chin <code@jhnc.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
.Vb 1
\& Copyright © 2006\-2022 by Jonathan H N Chin <code@jhnc.org>.
\&
\& This program is free software; you may 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, write to the Free Software
\& Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111\-1307  USA
.Ve
.SH HISTORY
.IX Header "HISTORY"
This code has been written from scratch. However it owes its existence
to \fBfindimagedupes\fR by Rob Kudla and uses the same duplicate-detection
algorithm.