FAQ | Forum
Adjusting the output:
LIST OF K2PDFOPT COMMAND-LINE OPTIONS
NOTE: A couple command-line options changed from v1.50 to v1.51. See the
k2pdfopt version history (under v1.51)
for full details.
This is the entire list of k2pdfopt command-line options that come directly from
the "usage" output of k2pdfopt. You can get this list by typing ? at the
interactive menu or with the command-line option -?.
To see how to use
these options with k2pdfopt, see the "Customizing K2pdfopt" menu at the left, e.g.
using a shortcut or
using an environment variable. Many of these options
have equivalents in the interactive menu.
k2pdfopt v1.65 (w/MuPDF,DjVuLibre,OCR) (c) 2013, GPLv3, http://willus.com
Compiled Apr 6 2013 with Gnu C (Mingw64) v4.6.3 for Win64 on x64.
usage: k2pdfopt [opts] <input pdf/djvu | folder>
(Or just drag a PDF or DJVU (.djvu) file to this icon.)
Attempts to optimize PDF (or DJVU) files (especially two-column ones) for
display on the Kindle (or other mobile readers/smartphones) by looking for
rectangular regions in the file and re-paginating them without margins and
excess white space. Works on any PDF or DJVU (.djvu) file, but assumes it
has a mostly-white background. Native PDF files (not scanned) work best.
If given a folder, k2pdfopt first looks for bitmaps in the folder and if
any are found, converts those bitmaps to a PDF as if they were pages of a
PDF file. If there are no bitmaps in the folder and if PDF files are in
the folder, then each PDF file will be converted in sequence.
Output files are always .pdf and have _k2opt added to the source name by
default (see -o option to specify alternate output name.)
K2PDFOPT environment variable
You can supply command-line options via the environment variable K2PDFOPT,
set K2PDFOPT=-ui- -x -j 0 -m 0.25
Command line options from the command line take precedence over the ones in
the environment variable K2PDFOPT.
Command Line Options
-?[-] Show [don't show] usage only (no file processing).
Combine with -ui- to get something you can redirect
to a file.
-a[-] Turn on [off] text coloring (use of ANSI color codes) on
the screen output. Default is on.
-as[-] [<maxdeg>] Attempt to automatically straighten tilted source pages.
Will rotate up to +/-<maxdegrees> degrees if a value is
specified, otherwise defaults to 4 degrees max. Use -1 to
turn off. Default is off (-as -1 or -as-).
-bp[-] [<inches>] Break [do not break] output pages at end of each input page.
Default is -bp-. If a numeric value is put after -bp, then
rather than breaking the output page at the end of each
input page, a gap is inserted of that many inches, e.g.
-bp 1 will insert a 1-inch gap between contents of each
-bpc <nn> Set the bits per color plane on the output device to <nn>.
The value of <nn> can be 1, 2, 4, or 8. The default is 4
to match the kindle's display capability.
-c[-] Output in color [grayscale]. Default is grayscale.
-col <maxcol> Set max number of columns. <maxcol> can be 1, 2, or 4.
Default is -col 2. -col 1 disables column searching.
-cg <inches> Minimum column gap width in inches for detecting multiple
columns. Default = 0.1 inches. Setting this too large
will give very poor results for multicolumn files. See also
-cgmax <inches> Max allowed gap between columns in inches. If the gap
between two regions exceeds this value, they will not be
considered as separate columns. Default = 1.5. Use -1 for
no limit (disable). See also -cg.
-cgr <range> Set column-gap range, 0 - 1. This is the horizontal range
over which k2pdfopt will search for a column gap, as a
fraction of the page width. E.g. -cgr 0.5 will search
from 0.25 to 0.75 of the page width for a column gap.
Set this to a small value, e.g. 0.05, to only search for
column breaks in the middle of the page. Default = 0.33.
-ch <inches> Minimum column height in inches for detecting multiple
columns. Default = 1.5 inches.
-cmax <max> Set max contrast increase on source pages. 1.0 keeps
contrast from being adjusted. Use a negative value to
specify a fixed contrast adjustment. Def = 2.0.
-comax <range> Stands for Column Offset Maximum. The <range> given is as a
fraction of the total horizontal 2-column span, as with -cgr,
and it specifies how much the column divider can move around
and still have the columns considered contiguous. Set to -1
to revert back to how columns were treated in k2pdfopt v1.34
and before. Default = 0.2.
-crgh <inches> Set the min height of the blank area that separates regions
with different numbers of columns. Default = 1/72 inch.
-d[-] Turn on [off] dithering for bpc values < 8. See -bpc.
Default is on.
-de <size> Defect size in points. For scanned documents, marks
or defects smaller than this size are ignored when bounding
rectangular regions. The period at the end of a sentence is
typically over 1 point in size. The default is 1.0.
-dev <name> Select device profile (sets width, height, dpi, and corner
marking for selected devices). Currently the selection is
limited. <name> just has to have enough characters to
uniquely pick the device. Use -dev ? to list the devices.
Default is -dev kindle2.
-dpi <dpival> Same as -odpi.
-dr <value> Display resolution multiplier. Default = 1.0. Using a
value greater than 1 should improve the resolution of the
output file (but will make it larger in size). E.g. -dr 2
will double the output DPI, the device width (in pixels),
and the device height (in pixels).
-ds <factor> Override the document size with a scale factor. E.g. if
your PDF reader says the PDF file is 17 x 22 inches and
it should actually be 8.5 x 11 inches, use -ds 0.5. Default
-evl <n> Detects and erases vertical lines in the source document
which may be keeping k2pdfopt from correctly separating
columns or wrapping text, e.g. column dividers. If <n> is
zero, this is turned off (the default). If <n> is 1, only
free-standing vertical lines are removed. If <n> is 2,
vertical lines are erased even if they are the sides of
an enclosed rectangle or figure, for example.
-f2p <val> Fit-to-page option. The quantity <val> controls fitting
tall or small contiguous objects (like figures or
photographs) to the device screen. Normally these are fit
to the width of the device, but if they are too small or
too tall, then if <val>=10, for example, they are allowed
to be 10%% wider (if too small) or narrower (if too tall)
than the screen in order to fit better. Use -1 to fit the
object no matter what. Use -2 as a special case--all
"red-boxed" regions (see -sm option) are placed one per
page. Default is -f2p 0. See also -jf.
Note: -f2p -2 will automatically also set -vb -2 to
exactly preserve the spacing in the red-boxed region. If
you want to compress the vertical spacing in the red-boxed
region, use -ftp -2 -vb -1.
-fc[-] For multiple column documents, fit [don't fit] columns to
the width of the reader screen regardless of -odpi.
Default is to fit the columns to the reader.
-g <gamma> Set gamma value of output bitmaps. A value less than 1.0
makes the page darker and may make the font more readable.
Default is 0.5.
-grid <C>x<R>[x<O>][+] Grid the source page into <C> columns by <R> rows with
with <O> percent overlap. No regard will be made for trying
to break the page between columns or rows of text. If a +
is specified, the destination page order will go across and
then down, otherwise it will go down and then across. To
turn off gridding, specify a zero value for the columns or
for the rows. Default is no gridding. The default overlap
is 2%%. Example: -grid 2x2x5. By default, gridding also
sets the following options, which can be overridden by
following the grid option with other command options:
-n -wrap- -f2p -2 -vb -2 -col 1. For example, if you want
a column search done on each grid piece, you can put this:
-grid 2x2 -col 2.
-gtc <inches> Threshold value for detecting column gaps (expert mode).
Sets how many of the pixels in the column shaft can be
non-white (total height of a line crossing the shaft in
inches). See also -gtr. Default = .005.
-gtr <inches> Threshold for detecting gaps between rows (expert mode).
This sets the maximum total black pixels, in inches, on
average, that can be in each row of pixels before the gap is
no longer considered a gap. A higher value makes it easier
to detect gaps between rows of text. Too high of a value
may inadvertently split figures and other graphics.
Default = 0.006. See also -rsf.
-gtw <inches> Threshold for detecting word gaps (expert mode).
See -gtr. Default = .0015.
-h <height>[in|cm|s|t] Set height of output device in pixels, inches, cm,
source page size (s) or trimmed source region size (t).
The default units are pixels, and the default value is 735
(the height of the Kindle 2 screen in pixels).
Example: -h 6.5in would set the device height to 6.5 in
(using the output dpi to convert to pixels--see -dpi).
Example 2: -h 1.5s would set the device height to 1.5
times the source page height. Also can use -h -1.5.
Example 3: -h 1t would set the device height to whatever
the trimmed region height is (typically used with the
-mode copy and -grid options, for example).
See also -w, -dpi, -dr.
-hy[-] Turn on [off] hyphen detection/elimination when wrapping
text. Default is on.
-gs[-][-] Force use of Ghostscript instead of MuPDF to read PDFs.
K2pdfopt has built-in PDF translation (via the MuPDF
library) but will try to use Ghostscript if Ghostscript
is available and the internal (MuPDF) translation fails
(virtually never happens). You can force Ghostscript to
be used with this -gs option. Use -gs- to use Ghostscript
only if MuPDF fails. Use -gs-- to never use Ghostscript.
Download ghostscript at http://www.ghostscript.com.
-idpi <dpi> Set pixels per inch for input file. Use a negative value
as a multiplier on the output dpi (e.g. -2 will set the
input file dpi to twice the output file dpi (see -odpi).
Default is -2.0.
-j -1|0|1|2[+/-] Set output text justification. 0 = left, 1 = center,
2 = right. Add a + to attempt full justification or a -
to explicitly turn it off. The default is -1, which tells
k2pdfopt to try and maintain the justification of the
document as it is. See also -wrap.
-jf 0|1|2 [<inches>] Set figure (tall region) justification. If a figure
has left or right margins available, this option allows
you to set the justification differently than the text.
E.g. you can center figures with -jf 1. If you want to
specify a minimum height for figures (e.g. minimum region
height where this justification applies), you can tack it
on at the end, e.g. -jf 1 1.5 to center any region taller
than 1.5 inches. Default is 0.75 inches for the minimum
height and to use the same justification on figures as
the rest of the document (-jf -1). See also -f2p to fit
small or tall figures to the page.
-jpg [<quality>] Use JPEG compression in PDF file with quality level
<quality> (def=90). A lower quality value will make your
file smaller. See also -png.
-l <lang> See -ocrlang.
-ls[-] Set output to be in landscape [portrait] mode. The
default is portrait.
-m[b|l|r|t] <in> Ignore <in> inches around the [bottom|left|right|top]
margin[s] of the source file. Default = 0 inches.
[NOTE: Default was 0.25 inches before v1.65.]
E.g. -m 0.5 (set all margins to 0.5 inches)
-mb 0.75 (set bottom margin to 0.75 inches)
You can also give four comma-delimited numbers after -m
to set all margins, e.g. -m 1.0,0.5,1.0,0.5 to set the
left, top, right, and bottom margins to 1, 0.5, 1, and
-mc[-] Mark [don't mark] corners of the output bitmaps with a
small dot to prevent the reading device from re-scaling.
Default = mark.
-mode <mode> Shortcut for setting multiple options at once which
determine the basic way in which k2pdfopt will behave.
Available modes are:
copy Same as -n- -wrap- -col 1 -vb -2 -w -1 -h -1
-dpi 150 -rt 0 -c -t- -f2p -2 -m 0 -om 0 -pl 0
-pr 0 -pt 0 -pb 0 -mc-. Makes k2pdfopt
behave exactly like my pdfr program--source
pages are simply copied to the output file, but
rendered as bitmaps. No trimming or re-sizing
is done. Can also use -mode pdfr.
fw Same as -n -wrap- -col 1 -vb -2 -t -ls. Makes
k2pdfopt behave like sopdf's "fit width"
option. Can also use -mode sopdf.
2col Same as -n -wrap- -col 2 -vb -2 -t.
Optimizes for a 2-column scientific article with
native PDF output.
def Default k2pdfopt mode: -n -wrap -col 2 -vb 1.75
-dev k2 -rt auto -c- -t -f2p 0 -m 0.25 -om 0.02
You can modify modes by overriding their options after
specifying the mode, e.g. -mode fw -vb -1.
-n[-] Use "native" PDF output format, i.e. try to perserve the
native source PDF contents, i.e. do not write the output
PDF file as a set of bitmaps rendered from the source file
but instead use the source PDF's native content along with
additional PDF instructions to translate, scale, and crop
the source content. With native PDF output, if the source
file has selectable text, the text remains selectable in
the output file. The output file can also be zoomed
without loss of fidelity. This may also result in a
smaller output file (but not always). By default, native
PDF output format is turned off.
1. Native PDF output cannot be used with text wrapping
on (see -wrap option). Turning it on will disable
2. Native PDF output is not recommended for source
files which are scanned (there is no benefit unless
the scanned document includes a layer of OCR text).
3. Native PDF output is incompatible with OCR (see -ocr),
though OCR is typically not necessary if the native PDF
contents are kept. Turning it on will disable OCR.
4. Native PDF output can only be used with PDF source
5. Contrast adjust, gamma correction, and sharpening
are disabled with native PDF output.
6. It is recommended that you use -vb -2 with native PDF
output, particularly if you are having difficulty
selecting/searching text in the output PDF file.
7. This option works well with -mode fw or with the
-grid option. It is used by default in those cases.
-neg[-] Inverse [don't inverse] the output images (white letters
on black background, or "night mode").
-o <namefmt> Set the output file name using <namefmt>. %s will be
replaced with the base name of the source file, and %d
will be replaced with the source file count (starting
with 1). The .pdf extension will be appended you don't
specify it. E.g. -o out%04d.pdf will result in output
files out0001.pdf, out0002.pdf, ... for the converted
files. Def = %s_k2opt
-ow[-] [<mb>] Set the minimum file size (in MB) where overwriting the
file will not be done without prompting. Set to -1 (or
just -ow with no value) to overwrite all files with no
prompting. Set to 0 (or just -ow-) to prompt for any
overwritten file. Def = -ow 10 (any existing file
over 10 MB will not be overwritten without prompting).
-om[b|l|r|t] <in> Set [bottom|left|right|top] margin[s] on output device in
inches. Default = 0.02 inches.
E.g. -om 0.25 (set all margins on device to 0.25 inches)
-omb 0.4 (set bottom margin on device to 0.4 inches)
You can also give four comma-delimited numbers after -om
to set all margins, e.g. -om 0.2,0.3,0.4,0.5 to set the
left, top, right, and bottom margins to 0.2, 0.3, 0.4, and
-ocr[-] [g|t] Attempt [don't attempt] to use optical character
recognition (OCR) in order to embed searchable text into
the output PDF document. If followed by t or g, specifies
the ocr engine to use (tesseract or gocr). Default if not
specified is tesseract. See also -ocrvis and -ocrhmax.
NOTE: Turning on OCR will disable native PDF output.
DISCLAIMER: The main intent of OCR isn't to improve the
visual quality of the text at all--at least not the way
k2pdfopt does it. OCR is most useful on scanned PDFs
that don't have selectable text to begin with, but using
OCR with k2pdfopt on such documents doesn't change the
look of the output PDF file at all. The OCR text is
simply placed invisibly over the scanned text so that
you appear to be able to select the scanned text (when,
in fact, you are selecting the invisibly placed OCR
text). So the only time you will even notice the OCR
errors is if you try to search for a word and can't find
that word because the OCR of that word is incorrect, or
if you copy a selection of the OCR text and paste it
into something else so that you can actually see it.
-ocrcol <n> If you are simply processing a PDF to OCR it (e.g. if you
are using the -mode copy optoin) and the source document has
multiple columns of text, set this value to the number of
columns to process (up to 4).
-ocrhmax <in> Set max height for an OCR'd word in inches. Any graphic
exceeding this height will not be processed with the OCR
engine. Default = 1.5. See -ocr.
-ocrlang <lang> Select the Tesseract OCR Engine language. This is the
root name of the training data, e.g. -lang eng for English,
-ocrlang fra for French, -ocrlang chi_sim for simplified
Chinese. You can also use -l. The default language is
whatever is in your Tesseract trained data folder. If you
have more than one .traineddata file in that folder, the
one with the most recent time stamp is used.
NOTE: Using the -ocrvis t option will not show the OCR text
correctly for any character above unicode value 255 since
k2pdfopt does not use any embedded fonts, but the text
will convert to the correct Unicode values when copy /
-ocrvis <s|t|b> Set OCR visibility flags. Put 's' to show the source doc,
't' to show the OCR text, and/or 'b' to put a box around
each word. Default is -ocrvis s. To show both the source
document and the OCR text overlayed on top: -ocrvis st.
See also -ocr. See also -ocrlang (the note about -ocrvis t).
-odpi <dpi> Set pixels per inch of output screen (def=167). See also
-dr, -w, -h, -fc. You can also use -dpi for this.
-p <pagelist> Specify pages to convert. <pagelist> must not have any
spaces. E.g. -p 1-3,5,9,10- would do pages 1 through 3,
page 5, page 9, and pages 10 through the end.
-p[b|l|r|t] <nn> Pad [bottom|left|right|top] side of destination bitmap with
<nn> rows. Defaults = 4 (bottom), 0 (left), 3 (right), and
0 (top). Example: -pb 10. This is typically only used on
certain devices to get the page to come out just right. For
setting margins on the output device, use -om.
-png (Default) Use PNG compression in PDF file. See also -jpeg.
-r[-] Right-to-left [left-to-right] page scans. Default is
left to right.
-rsf <val> Row Split Figure of merit (expert mode). After k2pdfopt has
looked for gaps between rows of text, it will check to see
if there appear to be missed gaps (e.g. if one row is twice
the height of all the others). Increasing this value makes
it harder for k2pdfopt to split a row. Lowering it makes it
easier. Default value = 20.
-rt <deg>|auto|aep Rotate source page counter clockwise by <deg> degrees.
Can be 90, 180, 270. Or use "-rt auto" to examine up to
10 pages of each file to determine the orientation used
on the entire file (this is the default). Or use "-rt aep"
to auto-detect the rotation of every page. If you have
different pages that are rotated differently from each other
within one file, you can use this option to try to auto-
rotate each source page.
-s[-] Sharpen [don't sharpen] images. Default is to sharpen.
-sm[-] Show [don't show] marked source. This is a debugging tool
where k2pdfopt will mark the source file with the regions it
finds on them and the order in which it processes them and
save it as <srcfile>_marked.pdf. Default is not to show
marked source. Red regions are found on the first pass
(use -f2p -2 to put each red region on a separate page).
Green lines mark vertical regions affected by -vb and -vs.
Gray lines mark individual rows of text (top, bottom, and
baseline). Blue boxes show individual words (passed to OCR
if -ocr is specified).
-t[-] Trim [don't trim] the white space from around the edges of
any output region. Default is to trim. Using -t- is not
recommended unless you want to exactly duplicate the source
-ui[-] User input query turned on [off]. Default = on for linux or
if not run from command line in Windows.
-v Verbose output.
-vb <thresh> Set gap-size vertical-break threshold between regions that
cause them to be treated as separate regions. E.g. -vb 2
will break the document into separate regions anywhere
there is a vertical gap that exceeds 2 times the median
gap between lines of text. These separate regions may
then be scaled and aligned independently.
Special values: Use -vb -1 to preserve all horizontal
alignment and scaling across entire regions (vertical
spacing may still be adjusted). Use -vb -2 to exactly
preserve each region (both horizontal alignment and
vertical spacing--this is the value used by -mode fw, for
example). The default is -vb 1.75.
-vls <spacing> Set vertical line spacing as a fraction of the text size.
This can be used to override the line spacing in a document.
If 1, then single spacing is used. 2 = double spacing.
If negative, then the absolute value acts as the limiting
case. E.g., if you set -vls -1.5, then any the line
spacing of the original document is preserved unless it
exceeds 1.5 (times single spacing). Default = -1.2.
See also -vs.
-vs <maxgap> Preserve up to <maxgap> inches of vertical spacing between
regions in the document (marked in green when using -sm
option). This value has no effect if you use a negative
value for -vb. The default value is 0.25.
See also -vls, -vb.
-w <width>[in|cm|s|t] Set width of output device. Default is 560. See -h.
-wrap[-|+] Enable [disable] text wrapping. Default = enabled. If
-wrap+, regions of text with lines shorter than the mobile
device screen are re-flowed to fit the screen width. If
you use -wrap+, you may want to also specify -fc- so that
narrow columns of text are not magnified to fit your device.
Text wrapping disables native PDF output (see -n option).
See also -ws, -j, -pi, -fc, -n.
-ws <spacing> Set minimum word spacing for line breaking as a fraction of
the height of a lowercase 'o'. Use a larger value to make it
harder to break lines. Def = 0.375. See also -wrap.
-wt <whitethresh> Any pixels whiter than <whitethresh> (0-255) are made pure
white. Setting this lower can help k2pdfopt better process
some poorly-quality scanned pages. The default is -1, which
tells k2pdfopt to pick the optimum value. See also -cmax.
-x[-] Exit [don't exit--wait for <Enter>] after completion.