'\" t
.\"     Title: didjvu
.\"    Author: Jakub Wilk <jwilk@jwilk.net>
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 2019-08-07
.\"    Manual: didjvu manual
.\"    Source: didjvu 0.9
.\"  Language: English
.\"
.TH "DIDJVU" "1" "2019\-08\-07" "didjvu 0\&.9" "didjvu manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
didjvu \- DjVu encoder with foreground/background separation
.SH "SYNOPSIS"
.HP \w'\fBdidjvu\ separate\fR\ 'u
\fBdidjvu separate\fR [{\fB\-o\fR\ |\ \fB\-\-output\fR}\ \fIoutput\-mask\fR] [\fIoption\fR...] \fIinput\-image\fR
.HP \w'\fBdidjvu\ separate\fR\ 'u
\fBdidjvu separate\fR \fB\-\-output\-template\fR\ \fIname\-template\fR  [\fIoption\fR...] \fIinput\-image\fR...
.HP \w'\fBdidjvu\ encode\fR\ 'u
\fBdidjvu encode\fR [{\fB\-o\fR\ |\ \fB\-\-output\fR}\ \fIoutput\-djvu\fR] [\fIoption\fR...] \fIinput\-image\fR
.HP \w'\fBdidjvu\ encode\fR\ 'u
\fBdidjvu encode\fR \fB\-\-output\-template\fR\ \fIname\-template\fR  [\fIoption\fR...] \fIinput\-image\fR...
.HP \w'\fBdidjvu\ bundle\fR\ 'u
\fBdidjvu bundle\fR [{\fB\-o\fR\ |\ \fB\-\-output\fR}\ \fIoutput\-djvu\fR] [\fIoption\fR...] \fIinput\-image\fR...
.HP \w'\fBdidjvu\fR\ 'u
\fBdidjvu\fR {\fB\-\-version\fR | \fB\-\-help\fR | \fB\-h\fR}
.SH "DESCRIPTION"
.PP
\fBdidjvu\fR
uses the
\m[blue]\fIGamera\fR\m[]\&\s-2\u[1]\d\s+2
framework to separate foreground/background layers, which can be then encoded into a DjVu file\&.
.PP
\fBdidjvu separate\fR
generates images mask(s) for the supplied input image(s)\&. Masks are saved in the PNG format\&.
.PP
\fBdidjvu encode\fR
converts the supplied input image(s) to single\-page DjVu documents(s)\&.
.PP
\fBdidjvu bundle\fR
converts the supplied input image(s) to a bundled multi\-page DjVu document\&.
.SH "OPTIONS"
.PP
\fBdidjvu\fR
accepts the following options:
.SS "Input, output"
.PP
\fB\-o\fR, \fB\-\-output=\fR\fB\fIoutput\-djvu\fR\fR
.RS 4
Generate a bundled multi\-page document\&. Write the file into
\fIoutput\-djvu\fR
file instead of standard output\&.
.sp
For
\fBseparate\fR
and
\fBencode\fR
commands, this option is allowed only if there is exactly one input file (i\&.e\&. exactly one output file)\&.
.RE
.PP
\fB\-\-output\-template=\fR\fB\fItemplate\fR\fR
.RS 4
Specifies the naming scheme for output files for the
\fBseparate\fR
and
\fBencode\fR
commands\&. Please consult the
\(lqTEMPLATE LANGUAGE\(rq
section for the template language description\&.
.sp
This option is mandatory if there is more than one input file (i\&.e\&. more than one output file)\&.
.RE
.PP
\fB\-\-page\-id\-template=\fR\fB\fItemplate\fR\fR
.RS 4
Specifies the naming scheme for page identifiers for the
\fBbundle\fR
command\&. Please consult the
\(lqTEMPLATE LANGUAGE\(rq
section for the template language description\&. The default template is
\(lq{base\-ext}\&.djvu\(rq\&.
.sp
For portability reasons, page identifiers:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
must consist only of lowercase ASCII letters, digits,
_,
+,
\-
and dot,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
cannot start with a
+,
\-
or a dot,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
cannot contain two consecutive dots,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
must end with the
\&.djvu
extension\&.
.RE
.sp
.RE
.SS "Masks"
.PP
\fB\-\-loss\-level=\fR\fB\fIn\fR\fR
.RS 4
Specifies the aggressiveness of the lossy compression for the
\fBseparate\fR
and
\fBencode\fR
commands\&. The default is 0 (lossless)\&. Valid values are integers between 0 and 200, inclusive\&.
.sp
This option is similar to the
\fB\-losslevel\fR
option of
\fBcjb2\fR; please consult the
\fBcjb2\fR(1)
manual page for details\&.
.RE
.PP
\fB\-\-lossless\fR
.RS 4
Synonym for
\fB\-\-loss\-level=0\fR\&.
.RE
.PP
\fB\-\-clean\fR
.RS 4
Synonym for
\fB\-\-loss\-level=1\fR\&.
.RE
.PP
\fB\-\-lossy\fR
.RS 4
Synonym for
\fB\-\-loss\-level=100\fR\&.
.RE
.PP
\fB\-m\fR, \fB\-\-method=\fR\fB\fImethod\fR\fR
.RS 4
Use the selected method to generate image mask (i\&.e\&. separate foreground from background)\&. The following methods should be available:
.PP
abutaleb
.RS 4
Abutaleb locally\-adaptive thresholding algorithm
.RE
.PP
bernsen
.RS 4
Bernsen thresholding algorithm
.RE
.PP
brink
.RS 4
Brink and Pendock's minimum\-cross entropy method
.sp
This method requires Gamera \(>= 3\&.4\&.0\&.
.RE
.PP
djvu
.RS 4
DjVu thresholding algorithm
.RE
.PP
global
.RS 4
splitting along a global threshold value
.RE
.PP
niblack
.RS 4
Niblack adaptive thresholding algorithm
.RE
.PP
otsu
.RS 4
Otsu thresholding algorithm
.RE
.PP
sauvola
.RS 4
Sauvola adaptive thresholding algorithm
.RE
.PP
shading\-subtraction
.RS 4
thresholds an image after subtracting a possibly shaded background
.RE
.PP
tsai
.RS 4
splitting along a threshold value determined using the Tsai Moment Preserving Threshold algorithm
.RE
.PP
white\-rohrer
.RS 4
White and Rohrer dynamic thresholding algorithm
.RE
.sp
The default is \(oqdjvu\(cq\&.
.sp
Please consult the
\m[blue]\fIGamera documentation\fR\m[]\&\s-2\u[2]\d\s+2
for details\&.
.RE
.PP
\fB\-x\fR, \fB\-\-param=\fR\fB\fIname\fR\fR\fB=\fR\fB\fIvalue\fR\fR
.RS 4
Set parameter for the binarization method\&.
.sp
This option can be used more than once\&.
.sp
Please consult the
\m[blue]\fIGamera documentation\fR\m[]\&\s-2\u[2]\d\s+2
for details\&.
.RE
.PP
\fB\-p\fR, \fB\-\-pages\-per\-dict=\fR\fB\fIn\fR\fR
.RS 4
For
\fBbundle\fR
command: if
\fIn\fR
> 1, compress masks with
\fBminidjvu\fR
using
\fIn\fR
pages in one pass\&. The default is 1\&.
.RE
.PP
\fB\-\-masks\fR, \fB\-\-mask=\fR\fB\fIinput\-mask\fR\fR
.RS 4
Use the pre\-generated image masks for the
\fBencode\fR
and
\fBbundle\fR
commands\&.
.RE
.SS "Foreground/background quality, resolution"
.PP
(These options apply to
\fBencode\fR
and
\fBbundle\fR
commands only\&.)
.PP
\fB\-d\fR, \fB\-\-dpi=\fR\fB\fIresolution\fR\fR
.RS 4
Specifies the desired resolution to
\fIresolution\fR
dots per inch\&. The default is to preserve the input file resolution, or 300 dpi if resolution metadata is missing\&. The allowed range is: 72 \(<=
\fIresolution\fR
\(<= 6000\&.
.RE
.PP
\fB\-\-fg\-slices=\fR\fB\fIn\fR\fR
.RS 4
Specifies the encoding quality of the IW44 foreground layer\&. The default is
100\&.
.sp
This option is similar to the
\fB\-slice\fR
option of
\fBc44\fR; please consult the
\fBc44\fR(1)
manual page for details\&.
.RE
.PP
\fB\-\-fg\-crcb=normal\fR
.RS 4
Select normal chrominance encoding of the foreground layer\&.
.RE
.PP
\fB\-\-fg\-crcb=half\fR
.RS 4
Select half resolution chrominance encoding of the foreground layer\&.
.RE
.PP
\fB\-\-fg\-crcb=full\fR
.RS 4
Select the highest possible quality for encoding the chrominance information of the foreground layer\&. This is the default\&.
.RE
.PP
\fB\-\-fg\-crcb=none\fR
.RS 4
Disable the encoding of the chrominance of the foreground layer\&.
.RE
.PP
\fB\-\-fg\-subsample=\fR\fB\fIn\fR\fR
.RS 4
Specifies the foreground subsampling ratio\&. The default is 6\&. Valid values are integers between 1 and 12, inclusive\&.
.RE
.PP
\fB \-\-bg\-slices=\fR\fB\fIn\fR\fR\fB+\fR\fB\fI\&...\fR\fR\fB+\fR\fB\fIn\fR\fR\fB \fR, \fB \-\-bg\-slices=\fR\fB\fIn\fR\fR\fB,\fR\fB\fI\&...\fR\fR\fB,\fR\fB\fIn\fR\fR\fB \fR
.RS 4
Specifies the encoding quality of the IW44 background layer\&. The default is
74+10+6+7\&.
.sp
This option is similar to the
\fB\-slice\fR
option of
\fBc44\fR; please consult the
\fBc44\fR(1)
manual page for details\&.
.RE
.PP
\fB\-\-bg\-crcb=normal\fR
.RS 4
Select normal chrominance encoding of the background layer\&. This is the default\&.
.RE
.PP
\fB\-\-bg\-crcb=half\fR
.RS 4
Select half resolution chrominance encoding of the background layer\&.
.RE
.PP
\fB\-\-bg\-crcb=full\fR
.RS 4
Select the highest possible quality for encoding the chrominance information of the background layer\&.
.RE
.PP
\fB\-\-bg\-crcb=none\fR
.RS 4
Disable the encoding of the chrominance of the background layer\&.
.RE
.PP
\fB\-\-bg\-subsample=\fR\fB\fIn\fR\fR
.RS 4
Specifies the background subsampling ratio\&. The default is 3\&. Valid values are integers between 1 and 12, inclusive\&.
.RE
.SS "XMP support"
.PP
(These options apply to
\fBencode\fR
and
\fBbundle\fR
commands only\&.)
.PP
\fB\-\-xmp\fR
.RS 4
Create sidecar
\m[blue]\fIXMP\fR\m[]\&\s-2\u[3]\d\s+2
metadata\&.
.sp
This option is experimental!
.RE
.SS "Verbosity, help"
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Display more informational messages while converting the file\&.
.RE
.PP
\fB\-q\fR, \fB\-\-quiet\fR
.RS 4
Don't display informational messages while converting the file\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Output version information and exit\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Display help and exit\&.
.RE
.SH "ENVIRONMENT"
.PP
The following environment variables affects
\fBdidjvu\fR:
.PP
\fITMPDIR\fR
.RS 4
\fBdidjvu\fR
makes heavy use of temporary files\&. It will store them in a directory specified by this variable\&. The default is
/tmp\&.
.RE
.SH "TEMPLATE LANGUAGE"
.SS "Template syntax"
.PP
The template language uses the
\m[blue]\fIPython string formatting syntax\fR\m[]\&\s-2\u[4]\d\s+2\&.
.SS "Available field names"
.PP
\fIname\fR
.RS 4
input file path
.RE
.PP
\fIname\-ext\fR
.RS 4
input file path without file extension
.RE
.PP
\fIbase\fR
.RS 4
input file name without directory components
.RE
.PP
\fIbase\-ext\fR
.RS 4
input file name without directory components and without file extension
.RE
.PP
\fIpage\fR, \fIpage+\fR\fI\fIN\fR\fR, \fIpage\-\fR\fI\fIN\fR\fR
.RS 4
page number, optionally shifted by a number
\fIN\fR
.RE
.SH "SEE ALSO"
.PP
\fBdjvu\fR(1),
\fBdjvumake\fR(1),
\fBc44\fR(1),
\fBcjb2\fR(1),
\fBminidjvu\fR(1),
.SH "NOTES"
.IP " 1." 4
Gamera
.RS 4
\m[blue]\fI\%https://gamera.informatik.hsnr.de/\fR\m[]
.RE
.IP " 2." 4
Gamera documentation
.RS 4
\m[blue]\fI\%https://gamera.informatik.hsnr.de/docs/gamera-docs/binarization.html\fR\m[]
.RE
.IP " 3." 4
XMP
.RS 4
\m[blue]\fI\%https://www.adobe.com/devnet/xmp.html\fR\m[]
.RE
.IP " 4." 4
Python string formatting syntax
.RS 4
\m[blue]\fI\%https://docs.python.org/2/library/string.html#format-string-syntax\fR\m[]
.RE