tdegraphics/doc/kooka/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&kooka;">
  <!ENTITY package "kdegraphics">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"> <!-- change language only here --> 
]>

<book lang="&language;">

<bookinfo>
<title>The &kooka; Manual</title>

<authorgroup>
<author> <firstname>Martin</firstname> 
<surname>Sommer</surname> 
<affiliation><address><email>msommer@suse.de</email></address></affiliation> 
</author>
<othercredit role="developer">
<firstname>Klaas</firstname>
<surname>Freitag</surname>
<affiliation>
<address><email>freitag@suse.de</email></address>
</affiliation>
<contrib>Developer</contrib>
</othercredit>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2002</year>
<holder>Klaas Freitag, Martin Sommer</holder>
</copyright>

<legalnotice
>&FDLNotice;</legalnotice>

<date>2002-02-04</date>
<releaseinfo>0.33.00</releaseinfo>

<abstract><para>&kooka; is a very useful &kde; scanning
application.</para></abstract> 


<keywordset>
<keyword>KDE</keyword>
<keyword>Scanner</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&kooka; is a &kde; application that enables easy scanning using
<acronym>SANE</acronym> libraries. Therefore,<acronym>SANE</acronym>
the package must be installed to use &kooka;. Clear and concise use
was the focus of its development.</para>

<para>Character recognition is also provided by the built-in text
recognition program gocr. Install <application>gocr</application> to
use this functionality. After character recognition is complete, the
recognized material can be opened in the text editor &kate; with just
one click, where you can edit the contents.</para>

</chapter>

<chapter id="how-to-use">
<title>Application Instructions</title>

<para>The web site <ulink
url="http://www.sane-project.org/">http://www.sane-project.org</ulink>
has information about supported scanners. Refer to it before
purchasing a scanner, if possible.</para>

<sect1 id="screen">
<title>The &kooka; Main Window</title>

<screenshot> 
<screeninfo>The &kooka; Main Window </screeninfo> 
<mediaobject> 
<imageobject>
<imagedata fileref="kooka_mainctrl.png" format="PNG"/></imageobject> 
</mediaobject> 

</screenshot>  

<para>Start &kooka; from a console by simply entering
<userinput><command>kooka</command></userinput>.  Create a link on the
&kde; desktop, which uses a scanner icon, if desired.</para>

<para>The main window in &kooka; consists of three frames. At the top,
see both icon and a menu panels.  Use the mouse to enlarge or reduce
the windows as needed.</para>

<itemizedlist> 
<listitem>
<para>The navigation window consists of two tabs, which allow you to
switch between the <guilabel>Preview</guilabel> and the integrated
file browser called the <guilabel>Gallery</guilabel>.  The working
folder is displayed in the lower part of the window along with the
folder where the scan will be saved.</para> 
</listitem>

<listitem>
<para>Make your scanner-dependent settings, which are dependent on the
scanner you have connected, in the lower left window.  Usually, these
are settings for resolution, brightness and contrast, scanning mode
(&eg;, color, gray, or binary), and for gamma values.</para>

<para>Configure your settings here first. Afterwards, initiate the
preview scan with <guimenuitem>Preview</guimenuitem>. If the
<guilabel>Preview</guilabel> tab in the upper window is selected, see
the results there.</para>

<para>Select the various formats in the preview image itself to define
the final dimensions. The <guilabel>User</guilabel> setting is
recommended for this, so you select the area to scan in the preview
display with the mouse.</para>

<para>After this is done, click <guimenu>Scan</guimenu> to scan the
selection made in the preview. After scanning, you will be asked in
which format to save the image whether to make this your standard
format (without being prompted to confirm your selection in the
future).</para>

<note><para>If you checked that you do not want to be asked about the
save format, the memory assistant will no longer appear. To change the
format some time in the future, select <menuchoice>
<guimenu>Settings</guimenu> <guimenuitem>Configure
Kooka...</guimenuitem> <guimenuitem>Save Image</guimenuitem>
<guimenuitem>Always show memory assistant</guimenuitem>
</menuchoice></para></note> 

</listitem> 
<listitem>
<para>The large window shows how the image appears after a final
scan.</para>
</listitem>
</itemizedlist>

</sect1>

</chapter>

<chapter id="commands">
<title>Command References</title>

<sect1 id="kooka-toolbar">
<title>The main &kooka; Toolbar</title>


<sect2>
<title>The <guimenu>File</guimenu> Menu</title>

<variablelist> 
<varlistentry> 
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Print</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Prints the displayed image.</para>
</listitem> 
</varlistentry>

<varlistentry> 
<term>
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Create Folder...</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Create a folder to hold your images.</para>
</listitem> 
</varlistentry>

<varlistentry> 
<term>
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save Image</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Save the image selected underneath the 
<guilabel>Kooka Gallery</guilabel>.</para>
<para>See the <link linkend="save"> Save</link> 
section for details.</para>
</listitem> 
</varlistentry>

<varlistentry> 
<term>
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Delete Image</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Delete the image selected underneath the 
<guilabel>Kooka Gallery</guilabel>.</para>
</listitem> 
</varlistentry>

<varlistentry> 
<term>
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Unload Image</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Remove the image displayed in the <guilabel>Image
Viewer</guilabel>.
</para>
</listitem> 
</varlistentry>

<varlistentry> 
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Quit &kooka;.</para>
</listitem> 
</varlistentry>

</variablelist>
</sect2>

<sect2>
<title>The <guimenu>Image</guimenu> Menu</title>

<variablelist> 
<varlistentry> 
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Open image in graphic application</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Enter a graphics application for opening your scanned image
directly. Recommended applications include <application>The
GIMP</application>.</para>
</listitem> 
</varlistentry> 

<varlistentry>
<term>
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>OCR image...</guimenuitem>
</menuchoice></term>
<listitem>
<para>Start the window for optical character recognition
(<acronym>OCR</acronym>). If you have <application>gocr</application>
installed, then the path to it should be in the path line. This
starts the character recognition for the preview image or for the
highlighted area.</para>
</listitem> 
</varlistentry> 

<varlistentry>
<term> 
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>OCR on selection...</guimenuitem>
</menuchoice></term> 
<listitem>
<para>A window will reappear for the character recognition. Here,
however, the character recognition is only for the area highlighted in
the final scan.</para>
</listitem> 
</varlistentry> 


<varlistentry>
<term>
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>I</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Scale to Width</guimenuitem>
</menuchoice></term> 
<listitem >
<para>This proportionally scales the image in the large canvas to the
width of the display.</para>
</listitem> 
</varlistentry>

<varlistentry> 
<term>
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Scale to Height</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Proportionately scales the image to the height of the
display.</para> 
</listitem > 
</varlistentry>

<varlistentry> 
<term >
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Original Size</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Restores the original scan size by reducing or enlarging the
image in  the display.</para> 

<para>There are additional methods of scaling an image:
<mousebutton>right</mousebutton> click the image display. Redefine the
three named options and set the enlargement itself. This can also be
done in the <guilabel>Preview</guilabel> window.</para>
</listitem> 
</varlistentry>

<varlistentry> 
<term>
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Create from selection</guimenuitem>
</menuchoice></term> 
<listitem>
<para>If the scanned image includes more than you want to appear in the final
image, use this tool to crop your image by marking your selection in
the larger image display to the right then selecting this tool. The
image is cropped according to your selection. You may already be
familiar with this function from <application>The GIMP</application>
crop tool.</para>
</listitem> 
</varlistentry> 

<varlistentry> 
<term>
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Mirror image vertically</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Flip image vertically.</para>
</listitem> 
</varlistentry> 

<varlistentry> 
<term><menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>M</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Mirror image horizontally</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para>Flip image horizontally.</para>
</listitem> 
</varlistentry> 

<varlistentry>
<term><menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Mirror both directions</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Flip image both horizontally and vertically.</para>
</listitem>
</varlistentry>

<varlistentry> 
<term>
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Rotate image clockwise</guimenuitem>
</menuchoice></term> 
<listitem>
<para>Rotate the image ninety degrees clockwise.</para>
</listitem>
</varlistentry> 

<varlistentry> 
<term>
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Rotate image counter-clockwise</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para>Rotate the image ninety degrees counterclockwise.</para>
</listitem> 
</varlistentry> 

<varlistentry>
<term>
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>
</shortcut>
<guimenu>Image</guimenu>
<guimenuitem>Rotate image 180 degrees</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para>Rotates image 180 degrees.</para>
</listitem> 
</varlistentry> 
</variablelist>
</sect2>

<sect2>
<title>The <guimenu>Settings</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show Toolbar</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para>Removes the top toolbar to give additional viewing area. </para>
</listitem> 
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show Statusbar</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para>Removes the bottom statusbar to give additional viewing area.</para>
</listitem> 
</varlistentry>
 </variablelist>
</sect2>

<sect2>
<title>Configuring Shortcuts</title>

<para>The <menuchoice>
<guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice>
allows you to specify key bindings</para>


<para>Below is an example of how to configure a short cut for deleting
an image.</para>

<screenshot>
<screeninfo>Picture of shortcut dialog</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="shortcut0.png" format="PNG"/>
	  </imageobject>
	</mediaobject>
</screenshot>

<itemizedlist>
<listitem><para>
Click on the custom button.
</para></listitem>

<listitem><para>
Next click on the primary button.
</para></listitem>

<listitem><para>
Do <userinput><keycombo
action="seq"><keycap>CTRL</keycap><keycap>X</keycap></keycombo></userinput>
and the dialog should disappear. The keybinding is now entered. 
</para></listitem>
</itemizedlist>

<screenshot>
<screeninfo>Picture of keybinding  dialog</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="shortcut1.png" format="PNG"/>
	  </imageobject>
	</mediaobject>
</screenshot>

<para>Pressing the keys <userinput><keycombo
action="seq"><keycap>CTRL</keycap><keycap>X</keycap></keycombo></userinput>
now deletes the image selected underneath <guilabel>Kooka Gallery</guilabel>.
</para>
</sect2>

<sect2>
<title>Configuring Toolbars</title>
<para>The <menuchoice>
<guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem></menuchoice>
Is used to add additional buttons to the toolbars.</para>

<screenshot>
<screeninfo>Picture of toolbars dialog</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="toolbar.png" format="PNG"/>
	  </imageobject>
	</mediaobject>
</screenshot>


<itemizedlist>

<listitem>
<para>To add a button to the File toolbar, 
</para>

<screenshot>
<screeninfo>Picture of toolbars dialog</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="toolbar1.png" format="PNG"/>
	  </imageobject>
	</mediaobject>
</screenshot>

<para>  make sure <guilabel>Main Toolbar</guilabel> is displayed in
the top combo box.
</para></listitem>

<listitem><para>
Click on one of the items in the left hand pane. This item will now have a
blue background showing that it has been selected.
</para></listitem>

<listitem><para>
Next click on the <keysym>Right arrow</keysym> button to place it in
the right pane.
</para></listitem>

<listitem><para>
Click on <userinput><guilabel>Apply</guilabel></userinput> and then
click on <userinput><guilabel>OK</guilabel></userinput>
</para></listitem>
</itemizedlist>


<para>The new Item should be in the toolbar. 
<screenshot>
<screeninfo>Picture of toolbars dialog</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="toolbar2.png" format="PNG"/>
	  </imageobject>
	</mediaobject>
</screenshot>
</para>
</sect2>

<sect2>
<title>Configuring Kooka</title>
<para>The <menuchoice>
<guimenu>Settings</guimenu><guimenuitem>Configure Kooka...</guimenuitem>
</menuchoice>
</para>


<variablelist>
<varlistentry>
<term>
<menuchoice>
<guilabel>Kooka Startup Preferences</guilabel> 
</menuchoice>
</term> 
<listitem>
<para>You may want to uncheck <guilabel>Show the scanner selection box
on next startup</guilabel>, if you have only one scanner. If you 
have only one computer you may also want to uncheck
<guilabel>Query network for available scanners</guilabel>. 
</para>
</listitem> 
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guilabel>Thumbnail View</guilabel> 
</menuchoice>
</term> 
<listitem>
<para>Here the size and the shading of the thumbnails can be adjusted;
as well as the background. For example, you might want to reduce the
size of the thumbnails if you are scanning many pages from a book.
</para>
</listitem> 
</varlistentry>

</variablelist>

</sect2>


</sect1>
</chapter>

<chapter id="save">
<title>Save</title>
<subtitle>More on Saving Images</subtitle>

<para>The method for saving an image is somewhat different in &kooka;
than in many other applications. Click the
<guilabel>Gallery</guilabel> tab to open a small file browser. This is
the folder <filename
class="directory">~/.kde/share/apps/ScanImages/</filename> In the
lower portion of the window, your current subfolder in the gallery
is shown. This is where all scanned images are first saved as
files. When starting &kooka; for the first time, you will only see the
<filename class="directory">ScanImages</filename>.  Create
subfolders by <mousebutton>right</mousebutton> clicking this
folder. The selected folder, highlighted in blue, is the first save
location of the scanned images. The scans are labeled in ascending
numerical order as in <filename>kscan_0001</filename> and
<filename>kscan_0002</filename>.</para>

<para>To save an image permanently, <mousebutton>left</mousebutton>
click the name. Next, give a new name and the appropriate ending for
the image format chosen when scanning.  If you enter a different
extension, you will get a message that it does not correspond to the
scanned format. Although you can still save the image under this name,
it will retain its original format. At present,
<quote>On-the-fly</quote> conversion is not offered.</para

><para>If you do not want to use this method of managing your images
in <filename
class="directory">~/.kde/share/apps/ScanImages/</filename>, you can,
of course, save them to another location. To do this,
<mousebutton>right</mousebutton> click the
image name and select <guilabel>Save</guilabel>.  Choose any path
here. In addition, close or permanently delete images here.</para>

<para>To incorporate other images in the gallery, add them in
&konqueror; by dragging and dropping.  Open &konqueror; to the
folder containing the desired images.  Then add them to the &kooka;
gallery by dragging them and dropping them into the gallery.</para>

</chapter>

<chapter id="ocr">
<title>Character Recognition</title>

<para>As already mentioned, the <application>gocr</application> must
be installed. Scan a preview of your document in grayscale or
color. You can only scan in binary mode if you have a pure white sheet
of paper with black print. Next, highlight the text to be recognized
in the preview window. Then, do your final scan in binary mode with
<guibutton>Scan</guibutton>.</para>

<para>Now click the second icon from the left, 
<inlinemediaobject><imageobject>
	    <imagedata fileref="ocr-select.png" format="PNG"/>
	  </imageobject></inlinemediaobject>,   
  in the icon panel,
<guilabel>OCR on Selection...</guilabel>, or select
this item in the <guilabel>Image</guilabel> menu.  For your
first try, do not change the default settings shown in the emerging
<acronym>OCR</acronym> window. These are usually appropriate and meet
most needs.  Now click <guimenuitem>Start character
recognition</guimenuitem>. You will now see a window containing the
<acronym>OCR</acronym> results. The quality depends heavily on that of
the document itself. </para>

<screenshot> <screeninfo>The gocr Window</screeninfo> <mediaobject>
<imageobject><imagedata fileref="kooka_gocr.png"
format="PNG"/></imageobject> </mediaobject> </screenshot>

<para>The text can now be opened by clicking the button with the
&kate; editor. After the final scan, mark a selection in the image
display to the right to load just a part of the text or image to the
<acronym>OCR</acronym>.  Next, in the icon panel, click the third
button from the right or click in the menu on
<guimenuitem>OCR on selection</guimenuitem>. Now
proceed as described in the previous section.</para >

<screenshot> 
<screeninfo>The Results of the <acronym>OCR</acronym></screeninfo> 
<mediaobject> 
<imageobject>
<imagedata fileref="kooka_gocr_result.png"
format="PNG"/></imageobject> 
</mediaobject> 
</screenshot>

</chapter>

<chapter id="credits">
<title>Credits and License</title>
 
<para>&kooka;</para>

<para> Copyright for the application 2001-2002 Klaas Freitag
<email>freitag@suse.de</email></para>

<para>Copyright for the documentation 2002 Martin Sommer
<email>msommer@suse.de</email></para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>  

<appendix id="installation">
<title>Installation</title>

&install.intro.documentation;

&install.compile.documentation;
                
</appendix>

</book>