path: root/doc/chalk/commands-dialogs.docbook

<sect1 id="commands-dialogs">
<title>Dialogs</title>

<para>
This section describes &chalk;'s dialog windows.
</para>

<sect2 id="commands-dialogs-image">
<title>Dialogs for working with images</title>

<sect3 id="commands-dialogs-images-colorrange">
<title>The <guilabel>Color Range</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Color Range</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-colorrange.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Color Range</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Color Range</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
You can create a selection based on the color values of pixels here. In the
dropdown box, choose which color range you want to select. Pixels will be
selected according to their color value on this scale (&eg; a fully yellow
pixel would score maximally on the yellow scale and on the red and green scales).
If you check the <guilabel>Invert</guilabel> box, the selection becomes inverted:
pixels will become selected if they have a lower value in the specified range instead.
You can choose whether the current selection should be
added to or subtracted from the color range selection by clicking the
respective option: <guilabel>Add to current selection</guilabel> or
<guilabel>Subtract from current selection</guilabel>. Choose
<guibutton>Select</guibutton> to actually perform the selection or
<guibutton>Deselect</guibutton> to remove these pixels from the selection.
</para>

</sect3>

<sect3 id="commands-dialogs-image-convertimagetype">
<title>The <guilabel>Convert Image Type</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Convert Image Type</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-convertimagetype.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Convert Image Type</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Convert Image Type</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog allows you to convert your image from one color space to another.
The <guilabel>Target color space</guilabel> and <guilabel>Destination ICM
profile</guilabel> are used to set to which colorspace and profile the image
will be converted. You can influence how this conversion is done with the
<guilabel>Rendering Intent</guilabel> option.
</para>
<para>
With <guilabel>Perceptual</guilabel> conversion, the source color space is
mapped linearly to the destination color space. If the destination color space
<quote>accepts</quote> a lesser color range than the source, shifts may occur
because the range is compressed. <guilabel>Relative colorimetric</guilabel>
conversion converts every color to the closest color in the destination color
space. This may mean that a certain color range is mapped to one color in the
destination color space. <guilabel>Saturation</guilabel> means that fully
saturated colors will remain fully saturated, even if this means that the
actual color is changed. With <guilabel>Absolute colorimetric</guilabel>
conversion, the same approach is used as with <guilabel>Relative
colorimetric</guilabel>, but the white point of the color space (the value
designating the color white) is not changed to match the new color space,
which may result in unwanted changes to near colors.
</para>

</sect3>

<sect3 id="commands-dialogs-image-imageproperties">
<title>The <guilabel>Image Properties</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Image Properties</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-imageproperties.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Image Properties</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Image Properties</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
In this dialog you can change a couple of image properties. First of all, the
<guilabel>Name</guilabel> of the image. If you did not set a name earlier
(that can also be done when creating the image), it will have a default name
like <quote>Image1</quote>. Then, you can set its size (determined by the
<guilabel>Width</guilabel> and <guilabel>Height</guilabel> in pixels and
the <guilabel>Resolution</guilabel> in dots per inch) and the color profile to
be used (<guilabel>Profile</guilabel>). Finally, you can fill in the
<guilabel>Description</guilabel> field with any information you want to add to
the image.
</para>

</sect3>

<sect3 id="commands-dialogs-image-imagesize">
<title>The <guilabel>Image Size</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Image Size</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-imagesize.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Image Size</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Image Size</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog lets you resize your image. In the top part, you can choose the
way the image is resized. If you choose <guilabel>Resize</guilabel>, the size
of the image is changed, but its layers (which contain the actual contents)
will not be modified. So, when you double the height and width of the image,
your original image will occupy the top-left quarter part of your new image.
On decreasing the size of your image, the image layers will stretch out over
the image borders, unless you choose <guilabel>Crop layers on image
resize</guilabel>, which will crop all layers to the new image size.
</para><para>
With <guilabel>Scale</guilabel>, the image layers will be resized with the
image. So increasing the image size will actually enlarge the contents, and
similar for decreasing.
</para><para>
Under <guilabel>Pixel dimensions</guilabel>, you can set which new size you
want the image to have. The original size is given as a reference. The new
size can be set both as pixels or as a percentage, with 100% being the
original size. If you select <guilabel>Constrain proportions</guilabel>, the
new width and height will always be set to the same percentage. For example,
if you have an image of 200 x 100 pixels, and set the width to 20 pixels, the
height will automatically be changed to 10. With this checkbox unselected, you
can also resize the image non-proportionally. 
</para><para>
The <guilabel>Filter:</guilabel> dropdown box can be used to select a
different algorithm for determining the colors of the pixels in the newly
resized image that did not correspond to a pixel in the old image (the
calculated corresponding location in the old image was located in between
pixels). <guilabel>BSpline</guilabel> uses a 4 x 4 pixel grid and results into a quite high
blurring. <guilabel>Bell</guilabel> is quite fast while resulting in a reasonably smooth image.
<guilabel>Box</guilabel> is the fastest method, but yields the least appealing result. <guilabel>Hermite</guilabel>
keeps the image quite sharp, while smoothing it as well, and is reasonably
fast. <guilabel>Lanczos3</guilabel> results in sharp images, but is very slow.  <guilabel>Mitchell</guilabel> (the
default) is not very fast, but often yields a good intermediate result.
<guilabel>Triangle/Bilinear</guilabel> uses the 2 x 2 pixel grid around the calculated location
resulting in relatively sharp lines. 
</para>

</sect3>

<sect3 id="commands-dialogs-image-rotateimage">
<title>The <guilabel>Rotate Image</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Rotate Image</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-rotateimage.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Rotate Image</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Rotate Image</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
With this dialog, you can rotate the image. The top part of the dialog shows
the result of the rotation in the form of a change in dimension (if any).
Under <guilabel>Direction</guilabel> you can choose between 
rotating clockwise and counter-clockwise. Under <guilabel>Angle</guilabel>,
you can set the amount of rotation. 90, 180 and 270 degrees can be selected
using the respective option button, other amounts need to be specified with
the <guilabel>Custom</guilabel> spin box.
</para>

</sect3>

<sect3 id="commands-dialogs-image-separateimage">
<title>The <guilabel>Separate Image</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Separate Image</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-separateimage.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Separate Image</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Separate Image</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
With this dialog, you can separate (part of) your image. Every color component
(channel) will be put into a separate layer or image. At the top of the
dialog, the current color model is shown. Below that, a couple of options can
be set.
</para>
<para>
Under <guilabel>Source</guilabel>, you can choose what part of the image to
separate. The two options are <guilabel>Current layer</guilabel>, which
(obviously) only uses the currently selected layer and <guilabel>Flatten all
layers before separation</guilabel>, which uses the entire image.
</para>
<para>
Under <guilabel>Output</guilabel>, you can choose where the result of the
separation should be written to: either to a couple of layers, or to a couple
of images.
</para>
<para>
Under <guilabel>Alpha Options</guilabel>, you can choose what should be done
with the alpha channel of the selected layer(s). It can be copied to each new
channel, be discarded, or separated on its own.
</para>
<para>
The two options at the bottom of the dialog, finally, determine whether the
source should be downscaled to 8 bit colors (if it contains more), and whether
the output should be in color (default is to separate the channels to grayscale
values).
</para>
</sect3>

<sect3 id="commands-dialogs-image-shearimage">
<title>The <guilabel>Shear Image</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Shear Image</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-shearimage.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Shear Image</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Shear Image</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog allows you to shear your image. By shearing, the bounding
rectangle of your image is transformed into a parallellogram. One pixel
row/column is kept in place, the next one is shifted by a certain amount, the
next one by the same amount relative to the previous one, etcetera.
The X and Y shearing angles can be set using the two spin boxes.
</para>

</sect3>

<sect3 id="commands-dialogs-image-substrate">
<title>The <guilabel>Substrate</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Substrate</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-substrate.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Substrate</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Substrate</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
(This dialog is still to be described.)
</para>

</sect3>

</sect2>

<sect2 id="commands-dialogs-layers">
<title>Dialogs for working with layers</title>

<sect3 id="commands-dialogs-layers-convertlayertype">
<title>The <guilabel>Convert Layer Type</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Convert Layer Type</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-convertlayertype.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Convert Layer Type</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Convert Layer Type</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog is exactly the same as the <link
linkend="commands-dialogs-image-convertimagetype"><guilabel>Convert Image
Type</guilabel> dialog</link>, which converts an entire image instead of a
single layer. See the description there for details.
</para>

</sect3>

<sect3 id="commands-dialogs-layers-dropshadow">
<title>The <guilabel>Drop Shadow</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Drop Shadow</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-dropshadow.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Drop Shadow</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Drop Shadow</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
With this dialog, you can add a drop shadow effect to the current layer.
Select the X and Y offsets (displacements) of the shadow relative to the
original layer with the two topmost spin boxes. The <guilabel>Blur
radius</guilabel> spinbox determines the radius in which the shadow will be
blurred (to achieve a smooth transition at the shadow border). If you want
a special color for the shadow, you can choose one with the
<guilabel>Color</guilabel> field. The <guilabel>Opacity</guilabel> slider and
spinbox can be used to make the shadow more or less transparent. Disable the
<guilabel>Allow resizing</guilabel> checkbox if you don't want the layer to be
resized in order to give it a shadow.
</para>

</sect3>

<sect3 id="commands-dialogs-layers-histogram">
<title>The <guilabel>Histogram</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Histogram</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-histogram.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Histogram</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Histogram</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog shows a histogram for the current layer. With the
<guilabel>Method:</guilabel> settings, you can choose what kind of histogram
to show. You can change the channel(s) to show with the
<guilabel>Channels:</guilabel> listbox, and the scale on which it should be
drawn with the <guilabel>Linear</guilabel> and
<guilabel>Logarithmic</guilabel> radio buttons. Under the preview, there are
buttons available to zoom in to, and move over, the histogram. These are
activated for 16-bit colorspace layers.
</para>

</sect3>

<sect3 id="commands-dialogs-layers-layerproperties">
<title>The <guilabel>Layer Properties</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Layer Properties</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-layerproperties.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Layer Properties</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Layer Properties</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog is in essence the same as the <link
linkend="commands-dialogs-layers-newlayer">New Layer</link> dialog, with the difference that
you cannot change its colorspace or profile anymore. These properties are
shown, though, to keep the information complete.
</para>
</sect3>

<sect3 id="commands-dialogs-layers-layersize">
<title>The <guilabel>Layer Size</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Layer Size</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-layersize.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Layer Size</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Layer Size</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog allows you to resize the current layer.
Under <guilabel>Pixel dimensions</guilabel>, you can set which new size you
want the layer to have. The original size is given as a reference. The new
size can be set both as pixels or as a percentage, with 100% being the
original size. If you select <guilabel>Constrain proportions</guilabel>, the
new width and height will always be set to the same percentage. For example,
if you have a layer of 200 x 100 pixels, and set the width to 20 pixels, the
height will automatically be changed to 10. With this checkbox unselected, you
can also resize the layer non-proportionally. The <guilabel>Filter:</guilabel>
dropdown list can be used to select a different algorithm for resizing the
layer.
</para>

</sect3>

<sect3 id="commands-dialogs-layers-newadjustmentlayer">
<title>The <guilabel>New Adjustment Layer</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>New Adjustment Layer</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-newadjustmentlayer.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>New Adjustment Layer</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>New Adjustment Layer</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
In this dialog, you can select the type of adjustment layer to add to the
image. In the left-hand list, you can see the available adjustment layers,
each with a preview. When you select one, the <guilabel>Preview</guilabel>
will change to show a correctly scaled preview of what the result of the
adjustment layer is going to be. 
</para><para>
You can then choose to show either the original image or the preview of the
adjustment layer with the radio buttons below the preview window. The buttons
next to these allow you to zoom in, zoom out, and refresh the preview,
respectively. The <guilabel>Autoupdate</guilabel> checkbox determines if the
preview window should update automatically after you made a change.
</para><para>
The various options available for the filter that is used to create the
adjustment layer, are shown at the bottom of the dialog. See the section on
<link linkend="commands-dialogs-filters">filters</link> of this chapter for
descriptions.
</para>

</sect3>

<sect3 id="commands-dialogs-layers-newlayer">
<title>The <guilabel>New Layer</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>New Layer</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-newlayer.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>New Layer</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>New Layer</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
You can add a new layer to your image with this dialog. If you want a
descriptive name for your layer, you can fill one in at
<guilabel>Name:</guilabel>. You can select the desired colorspace for the new
layer from the <guilabel>Colorspace:</guilabel> list, and the specific
color profile for that colorspace at <guilabel>Profile:</guilabel>.
You can preset the layer's <guilabel>Opacity</guilabel> (you can change it later with the slider in
the <guilabel>Layer</guilabel> box), and choose the mode with which the layer should be composited
onto the final image.
</para>

</sect3>

<sect3 id="commands-dialogs-layers-rotatelayer">
<title>The <guilabel>Rotate Layer</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Rotate Layer</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-rotatelayer.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Rotate Layer</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Rotate Layer</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog, similar to the <link
linkend="commands-dialogs-image-rotateimage"><guilabel>Rotate Image</guilabel>
dialog</link>, allows you to rotate the current layer. You can choose the
direction in which to rotate and the amount to rotate the layer by.
</para>

</sect3>

<sect3 id="commands-dialogs-layers-shearlayer">
<title>The <guilabel>Shear Layer</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Shear Layer</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-shearlayer.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Shear Layer</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Shear Layer</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog works the same as the <link
linkend="commands-dialogs-image-shearimage"><guilabel>Shear Image</guilabel>
dialog</link>, except that it operates on the current layer instead of on the
entire image.
</para>

</sect3>

</sect2>

<sect2 id="commands-dialogs-filters">
<title>Dialogs for working with filters</title>

<para>
All filter dialogs consist of a filter-specific part, at the left, and a
generic part, at the right. The generic part contains a preview window, which
you can configure using the controls below it. Choose
<guilabel>Preview</guilabel> or <guilabel>Original</guilabel> depending on
whether you want the preview window to show the preview of the filter effect
or the original image. The four buttons at the bottom right allow you to zoom
in and zoom out, set the zooming factor to 100% (this shows the image at its
original size), and refresh the preview, respectively. Furthermore, the option
<guilabel>Autoupdate</guilabel> determines if the preview window is updated
automatically. If you uncheck this checkbox, you will have to refresh the
preview yourself.
</para>

<sect3 id="commands-dialogs-filters-blur">
<title>The <guilabel>Blur</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Blur</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-blur.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Blur</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Blur</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog allows you to customize the way your image is blurred. The
<guilabel>Half-width</guilabel> and <guilabel>Half-height</guilabel> spinboxes
determine the size of the areas of your image that are consecutively blurred.
With the <guilabel>Strength</guilabel> spinbox you can set the strength with which the
blurring should be applied, and with the <guilabel>Angle</guilabel> spinbox
you can add a rotation to the area. The <guilabel>Shape</guilabel> setting,
finally, allows you to choose between circular and rectangular areas
</para>

</sect3>


<sect3 id="commands-dialogs-filters-brightnesscontrast">
<title>The <guilabel>Brightness / Contrast</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Brightness / Contrast</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-brightnesscontrast.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Brightness / Contrast</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Brightness / Contrast</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
With this dialog, you can customize the brightness and contrast of your image.
</para><para>
The curve diagram has a histogram-like background that shows you the abundance
of various brightness levels. The curve itself (initially a diagonal line from
bottom left to top right) determines to which new brightness level (on the
vertical axis) pixels with a certain original level (on the horizontal axis) are
to be mapped. For example, the default diagonal line from bottom left to top
right sets every original pixel to its own brightness value, meaning no
change. A horizontal line means that all pixels will get the same brightness.
This means minimal contrast, the brightness itself is indicated by the height
at which the line is placed.
</para><para>
You can click on a handle (red circle) to select it (a selected handle is
indicated by a filled circle) and drag it around to change the shape of the
curve. The curve will be drawn smoothly through the handles (always
strictly from left to right). If you click on the curve, a handle is added to
it at that position. Clicking somewhere else in the image will also add a
handle at that point. You can press <keycap>Delete</keycap> to delete the
currently selected handle.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-bumpmap">
<title>The <guilabel>Bumpmap</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Bumpmap</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-bumpmap.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Bumpmap</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Bumpmap</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
You can apply a bumpmap effect and customize it using this dialog. One layer
is used as bumpmap layer: it is read as grayscale image and the gray values of
its pixels are used to to distort the other layer for creating the depth
illusion. High grey values, &ie; more white, mean a larger height, small
values, &ie; near black, mean a smaller height &mdash; or a larger depth, the
height can get <quote>below sealevel</quote>. A light source, shining
<quote>from above</quote> on the image that lies <quote>on the ground</quote>,
is simulated to determine the depth and direction of the shadows.
</para><para>
The first option in this dialog offers you the selection of the
<guilabel>Bumpmap layer</guilabel>.
</para><para>
Under <guilabel>Type</guilabel>, you can select what kind of bumpmap to be
applied. There are three types, <guilabel>Linear</guilabel> (a normal
application of the bumpmap), <guilabel>Spherical</guilabel> (focusing on the
extremes, that is, the shadow and highlight values) and
<guilabel>Sinusoidal</guilabel> (focusing on the midtone values).
</para><para>
Then, there are three options to modify the bumpmap apart from its
algorithmical application. With <guilabel>Compensate for darkening</guilabel>,
the image is restored to about its original average lightness if using the
bumpmap filter would make it darker. The <guilabel>Invert bumpmap</guilabel>
option creates an inverted bumpmap (high and low are reversed). With
<guilabel>Tile bumpmap</guilabel>, a bumpmap layer that is smaller than the
layer it is applied to, will be tiled (repeatedly) to cover the entire layer.
</para><para>
Under <guilabel>Settings</guilabel>, you can select the mathematical
parameters for the bumpmap. First of all, <guilabel>Azimuth</guilabel> (the
angle of the light source in the X-Y plane), <guilabel>Elevation</guilabel>
(the height of the simulated light source above the surface in degrees, with 0
degrees being on the ground and 90 degrees being vertically above the image),
and <guilabel>Depth</guilabel> (the maximal vertical distortion of the image).
</para><para>
Then, there are the <guilabel>X offset</guilabel> and <guilabel>Y
offset</guilabel>, with which you can displace the bumpmap layer relative to
the destination layer, <guilabel>Water level</guilabel> (the depth seen as
neutral), and <guilabel>Ambient light</guilabel>, which determines the
relative amount of ambient (environmental) light.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-coloradjustment">
<title>The <guilabel>Color Adjustment</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Color Adjustment</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-coloradjustment.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Color Adjustment</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Color Adjustment</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog allows you to customize the <guilabel>Color Adjustment</guilabel> filter. You can use
the curve (see the section on <link
linkend="commands-dialogs-filters-brightnesscontrast">Brightness /
Contrast</link> for a description on the curve) to determine the mapping
from old to new color levels, for each of the channels separately.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-colortoalpha">
<title>The <guilabel>Color to Alpha</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Color to Alpha</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-colortoalpha.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Color to Alpha</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Color to Alpha</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
With this dialog, you can make parts of the image having a certain color
transparent (officially <quote>alpha-transparent</quote>). You can select the
color you want to remove from the image (replacing it with transparency) with
the <guilabel>Color</guilabel> swatch, and how much a color may differ from
the selected one before it is considered not to match, with the
<guilabel>Threshold</guilabel> spinbox. Setting a threshold of zero (0)
ensures that only pixels with the exact matching color will be made
transparent, higher thresholds will make other colors match as well.
</para>

</sect3>
<sect3 id="commands-dialogs-filters-colortransfer">
<title>The <guilabel>Color Transfer</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Color Transfer</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-colortransfer.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Color Transfer</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Color Transfer</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog lets you copy the colors from one image (the <guilabel>Reference
Image</guilabel>) to the current one. The colors in both images are compared
and each color in the one you are working with, will be replaced by the
nearest one in the reference image.
</para>

</sect3>

<!--
<sect3 id="commands-dialogs-filters-cubism">
<title>The <guilabel>Cubism</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Cubism</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-cubism.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Cubism</guilabel> dialog</phrase>
</textobject>
<caption><para>The Cubism dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog has two filter-specific options. The <guilabel>Tile
size:</guilabel> slider and spinbox determine how big the tiles are in which
the image is subdivided, the <guilabel>Tile saturation:</guilabel> setting
sets the color saturation of the tiles.
</para>

</sect3>
-->

<sect3 id="commands-dialogs-filters-customconvolution">
<title>The <guilabel>Custom Convolution</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Custom Convolution</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-customconvolution.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Custom Convolution</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Custom Convolution</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
With this filter, you can apply a customized distortion effect to your image.
The nine spinboxes at the top left determine the distortion. Each pixel is
assigned a new value based on these values: the old color values of the pixel
inself and the eight surrounding pixels are each multiplied by the values in
the respective spinboxes, these results are added, and the final result is the
new color value for the pixel. Before being applied, this final result can be
multiplied with a certain <guilabel>Factor:</guilabel> or a certain
<guilabel>Offset:</guilabel> can be added to it.
</para><para>
In the example screenshot, each pixel is assigned a new value based on its
own (the 1 in the center), to which are added the values of the pixels to its
top right and directly below it (each with a factor of 1, &ie; the actual
value, since multiplying by one has no effect), and from which are subtracted
the values of the pixels to its bottom right and directly above it (added with
a factor of -1, so subtracted by a factor of 1).
</para>

</sect3>

<sect3 id="commands-dialogs-filters-emboss">
<title>The <guilabel>Emboss</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Emboss</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-emboss.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Emboss</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Emboss</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog contains just one option, the <guilabel>Depth:</guilabel> slider
and spinbox which determines the depth of the embossing effect.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-filtersgallery">
<title>The <guilabel>Filters Gallery</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Filters Gallery</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-filtersgallery.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Filters Gallery</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Filters Gallery</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog can be used to get a quick overview of what the various available
filters do. The filters are in turn applied to the current image and the
results are put in the left list box as thumbnails. If you select one, its
options become available in the <guilabel>Configuration</guilabel> section.
See the description of the respective filter for details.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-gaussiannoise">
<title>The <guilabel>Gaussian Noise Reduction</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Gaussian Noise Reduction</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-gaussiannoise.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Gaussian Noise Reduction</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Gaussian Noise Reduction</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog allows you to customize a Gaussian noise reduction. The
<guilabel>Threshold</guilabel> setting is a measure for how much noise should
be removed (&ie; how quickly a <quote>lonely</quote> pixel should be made
equal to its surroundings), while the <guilabel>Window Size</guilabel> setting
determines the radius of the area considered when changing pixels.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-lenscorrection">
<title>The <guilabel>Lens Correction</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Lens Correction</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-lenscorrection.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Lens Correction</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Lens Correction</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
With this dialog, you can fix an image which is distorted due to common lens
anomalies. You can specify a <guilabel>Distortion correction</guilabel>,
indicating how much the image should be corrected if its
concaveness / convexness is not right, for areas near the center and areas
near the edges. If you want an asymmetrical correction, you can specify
different <guilabel>X</guilabel> and <guilabel>Y</guilabel> coordinates for
the center (in percentages of the total width and height, measured from the
top left).
</para><para>
You can also correct a too light or too dark image with the
<guilabel>Brightness correction</guilabel> spinbox.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-imagerestoration">
<title>The <guilabel>Image Restoration</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Image Restoration</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-imagerestoration.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Image Restoration</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Image Restoration</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
Using this dialog, you can specify exactly how the image restoration should
be done. This filter tries to increase the quality of an image, for instance
by removing scratches. Various options are available to customize its
behaviour.
</para><para>
(Unfortunately, these are not described as of yet.)
</para>

</sect3>

<sect3 id="commands-dialogs-filters-oilpaint">
<title>The <guilabel>Oilpaint</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Oilpaint</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-oilpaint.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Oilpaint</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Oilpaint</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog can configure two parameters for the associated filter. The
<guilabel>Brush size:</guilabel> setting determines the size of the brush that
is used to simulate the oilpaint effect, the <guilabel>Smooth:</guilabel>
setting specifies if the difference in colors between adjacent
<quote>swatches</quote> may be large (low smoothness) or should be small (high
smoothness).
</para>

</sect3>

<sect3 id="commands-dialogs-filters-pixelize">
<title>The <guilabel>Pixelize</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Pixelize</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-pixelize.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Pixelize</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Pixelize</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
On this dialog, you can adjust two settings. <guilabel>Pixel width:</guilabel>
and <guilabel>Pixel height:</guilabel> indicate the width and height of the
area that should be taken together and averaged to form one new, large
<quote>pixel</quote>.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-raindrops">
<title>The <guilabel>Raindrops</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Raindrops</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-raindrops.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Raindrops</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Raindrops</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This filter can be configured using the settings <guilabel>Drop
size:</guilabel> (the average diameter of the raindrops),
<guilabel>Number:</guilabel> (the number of raindrop effects that should be
added to the image), and <guilabel>Fish eyes:</guilabel> (the percentage of
raindrops that should be rendered as fisheye lens effects instead of plain
raindrop effects).
</para>
</sect3>

<sect3 id="commands-dialogs-filters-randomnoise">
<title>The <guilabel>Random Noise</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Random Noise</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-randomnoise.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Random Noise</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Random Noise</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This filter adds random noise (speckles, or something similar) to your image.
There are two customizable settings: the amount of noise
(<guilabel>Level</guilabel>, as a percentage) and the
<guilabel>Opacity</guilabel> of the noise (should the original color still be
a bit visible or not).
</para>

</sect3>
<sect3 id="commands-dialogs-filters-randompick">
<title>The <guilabel>Random Pick</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Random Pick</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-randompick.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Random Pick</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Random Pick</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
In this dialog, you can specify parameters for the <guilabel>Random Pick</guilabel>
filter. The <guilabel>Level</guilabel> setting determines how much pixels will
be affected (measured as a percentage), the area which is looked in to take a
new color for a pixel is set with the <guilabel>Size of the window</guilabel>
setting, and the <guilabel>Opacity</guilabel> of the modifications can be set as
well.
</para>

</sect3>


<sect3 id="commands-dialogs-filters-roundcorners">
<title>The <guilabel>Round Corners</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Round Corners</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-roundcorners.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Round Corners</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Round Corners</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog has one setting: the radius of the rounded corners.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-smalltiles">
<title>The <guilabel>Small Tiles</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Small Tiles</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-smalltiles.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Small Tiles</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Small Tiles</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
In this dialog, you can set the amount of subdivisions with the
<guilabel>Number of tiles</guilabel> settings.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-sobel">
<title>The <guilabel>Sobel</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Sobel</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-sobel.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Sobel</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Sobel</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
Here, you can set the parameters for the <guilabel>Sobel</guilabel> edge
detection filter. First of all you can determine which directions to sobel in:
horizontally, vertically, or both. The <guilabel>Keep sign of
result</guilabel> setting does not affect regular images.
<guilabel>Make image opaque</guilabel> determines whether the resulting image
is opaque or transparent.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-unsharpmask">
<title>The <guilabel>Unsharp Mask</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Unsharp Mask</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-unsharpmask.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Unsharp Mask</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Unsharp Mask</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog offers three options for the sharpening filter
<guilabel>Unsharp Mask</guilabel>: the radius (<guilabel>Half-size</guilabel>)
of the mask, the <guilabel>Amount</guilabel> of sharpening that should be
done, and the <guilabel>Threshold</guilabel> level.
</para>

</sect3>

<sect3 id="commands-dialogs-filters-wave">
<title>The <guilabel>Wave</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Wave</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-wave.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Wave</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Wave</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
For both the horizontal and the vertical components of the wave distortion
(note: a vertical wave means that the vertical position is dependent on the
horizontal one, and hence looks like a <quote>W</quote>),
you can determine four settings here. The <guilabel>Wavelength</guilabel> (a
shorter wavelength means a more erratical wave), the
<guilabel>Shift</guilabel> (which point of the wave should be started at), the
<guilabel>Amplitude</guilabel> (the amount of distortion), and the
<guilabel>Shape</guilabel> (<guilabel>Sinusoidal</guilabel> or rounded,
versus <guilabel>Triangle</guilabel> or pointy).
</para>

</sect3>

<sect3 id="commands-dialogs-filters-waveletnoise">
<title>The <guilabel>Wavelet Noise Reduction</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Wavelet Noise Reduction</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-waveletnoise.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Wavelet Noise Reduction</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Wavelet Noise Reduction</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
The only setting here, <guilabel>Threshold</guilabel>, indicates how easily pixels
are seen as noise that should be removed and made equal to the surrounding area.
</para>

</sect3>

</sect2>

<sect2 id="commands-dialogs-misc">
<title>Miscellaneous dialogs</title>

<sect3 id="commands-dialogs-misc-addpalette">
<title>The <guilabel>Add Palette</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Add Palette</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-addpalette.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Add Palette</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Add Palette</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
With this dialog, you can add a custom color palette to &chalk;. Fill in the
name for your palette in the text field at the top. Then make the palette: use
the button <guibutton>Add New Color...</guibutton> to add a color to the palette
and <guibutton>Remove Selected Color</guibutton> to remove the currently
selected color. Click the button <guibutton>Add to Predefined
Palettes</guibutton> to add your newly created palette to the palette list, or
just choose <guibutton>OK</guibutton> when you're done.
</para>

</sect3>

<sect3 id="commands-dialogs-misc-documentinformation">
<title>The <guilabel>Document Information</guilabel> dialog</title>

<para>
<screenshot>
<screeninfo>The <guilabel>Document Information</guilabel> dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dialogs-documentinformation.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The <guilabel>Document Information</guilabel> dialog</phrase>
</textobject>
<caption><para>The <guilabel>Document Information</guilabel> dialog</para></caption>
</mediaobject>
</screenshot>
</para>

<para>
This dialog is the same as in other &koffice; programs. You can enter various
information about your document here, which will be saved with the document so
that you can retrieve it later to review or edit.
</para>

<para>
On the <guilabel>General</guilabel> tab, you can enter the title, subject and
keywords, as well as an abstract. On the bottom of this tab, some statistical
information is displayed. On the <guilabel>Author</guilabel> tab, you can
store information about yourself. The third tab, <guilabel>User-defined
Metadata</guilabel>, allows you to store any other information.
</para>
</sect3>

</sect2>


</sect1>