diff options
Diffstat (limited to 'doc/kpovmodeler/index.docbook')
| -rw-r--r-- | doc/kpovmodeler/index.docbook | 2100 |
1 files changed, 2100 insertions, 0 deletions
diff --git a/doc/kpovmodeler/index.docbook b/doc/kpovmodeler/index.docbook new file mode 100644 index 00000000..f6551595 --- /dev/null +++ b/doc/kpovmodeler/index.docbook @@ -0,0 +1,2100 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kpovmodeler;"> + <!ENTITY package "kdegraphics"> + <!ENTITY Povray "<application>POV-Ray</application>"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kpovmodeler; Handbook</title> + +<authorgroup> +<author> +<firstname>Lauri</firstname> +<surname>Watts</surname> +<affiliation> +<address><email>[email protected]</email></address> +</affiliation> +</author> + +<author> +<firstname>Andreas</firstname> +<surname>Zehender</surname> +<affiliation> +<address><email>[email protected]</email></address> +</affiliation> +</author> + +<author> +<firstname>Olivier</firstname> +<surname>Saraja</surname> +<affiliation> +<address><email>[email protected]</email></address> +</affiliation> +</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2002-09-07</date> +<releaseinfo>1.00.00</releaseinfo> + +<abstract> +<para> +&kpovmodeler; is a graphical 3D modeler, which can generate scenes for +&Povray; +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KPovModeler</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kpovmodeler; is a 3D modeling application to generate &Povray; +scenes.</para> + +<para>While it is not necessary to fully understand the &Povray; +application in order to make good use of &kpovmodeler;, it is highly +recommended that you read and try to understand the &Povray; +documentation.</para> + +<para>To find out more about &Povray; go to +<ulink url="http://www.povray.org">www.povray.org</ulink>.</para> + +</chapter> + +<chapter id="the-interface"> +<title>The &kpovmodeler; Interface</title> + +<para>When you start &kpovmodeler;, the default layout is as +follows:</para> + +<screenshot> +<screeninfo>The default view layout</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="defaultviewlayout.png" format="PNG"/></imageobject> +<textobject><phrase>The default view layout</phrase></textobject> +</mediaobject> +</screenshot> + +<itemizedlist> +<listitem> +<para><link linkend="menu-reference">Menubars (1)</link></para> +</listitem> +<listitem> +<para>Toolbars (2)</para> +</listitem> +<listitem> +<para><link linkend="the-object-tree">The object tree (3)</link></para> +</listitem> +<listitem> +<para><link linkend="the-properties-view">The object properties +view (4)</link></para> +</listitem> +<listitem> +<para><link linkend="the-wireframe-views">The wireframe and camera views (5)</link></para> +</listitem> +</itemizedlist> + +<sect1 id="the-object-tree"> +<title>The Object Tree</title> + +<para>The object tree displays the objects inside the scene and their hierarchy.</para> +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="objecttree.png" format="PNG"/></imageobject> +<textobject><phrase>The object tree</phrase></textobject> +</mediaobject> +</screenshot> + +<sect2 id="object-tree-selecting-object"> +<title>Selecting Objects</title> +<para>In the object tree you can select objects. Once you select an object, its attributes +are displayed in the +<link linkend="the-properties-view">properties view</link> and rendered yellow in the +<link linkend="the-wireframe-views">wireframe views</link>.</para> + +<para>You can select multiple objects. However, you cannot select a child of an already +selected object, because all children are selected indirectly with the parent.</para> + +<para>If only one object is selected, it is referred to as <quote>the active object</quote> from now on.</para> +</sect2> + +<sect2 id="object-tree-add-objects"> +<title>Adding new Objects</title> + +<para>To add a new object to the object tree, select the object where you want to +insert the new object and either click the icon in the toolbar or choose a menu entry +in the <guimenu>Insert</guimenu> menu.</para> + +<para>There are three possible positions for new objects:</para> +<itemizedlist> +<listitem><para>As the first child of the active object</para></listitem> +<listitem><para>As the last child of the active object</para></listitem> +<listitem><para>As a sibling of the active object</para></listitem> +</itemizedlist> + +<para>If there is more than one position possible, the following popup menu prompts +you to select the correct position:</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="insertaspopup.png" format="PNG"/></imageobject> +<textobject><phrase>The insert position popup</phrase></textobject> +</mediaobject> +</screenshot> + +</sect2> + +<sect2 id="object-tree-remove-objects"> +<title>Removing Objects</title> +<para>To remove objects, select them and select <guimenuitem>Delete</guimenuitem> from +either the <guimenu>Edit</guimenu> menu or the &RMB; context menu.</para> +</sect2> + +<sect2 id="object-tree-move-objects"> +<title>Moving Objects</title> +<para>To move objects, drag and drop the selected objects on to the object tree.</para> +<para>You can cut the object and insert it at the new position as well.</para> +</sect2> + +</sect1> + +<sect1 id="the-properties-view"> +<title>The Properties View</title> + +<para>The properties view displays the attributes of the active object.</para> +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="objectpropertiesview.png" format="PNG"/></imageobject> +<textobject><phrase>The properties view</phrase></textobject> +</mediaobject> +</screenshot> + +<para>If you changed some properties, click the <guibutton>Apply</guibutton> button to +make the changes permanent. If you entered invalid data, a message box will show up with +an error description. You can then adjust the properties and press +<guibutton>Apply</guibutton> again, or revert your changes with the +<guibutton>Cancel</guibutton> button.</para> +<para>If you set the path to your &Povray; user documentation in the +<link linkend="configure-povray-tab">settings dialog</link>, you can open the +&Povray; reference page for the displayed object with the <guibutton>Help</guibutton> +button. +</para> + +<note><para>You need the &Povray; 3.1g or 3.5 HTML user documentation in order to use this feature. +If your distribution does not contain this documentation you can download it +<ulink url="ftp://ftp.povray.org/pub/povray/Old-Versions/Official-3.1g/Docs/povhtml.zip">here</ulink>. +The &Povray; 3.5 package contains the html user documentation.</para> +</note> + +<para>If you edit a texture or a part of a texture, you can preview it inside the properties view.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="texturepreview.png" format="PNG"/></imageobject> +<textobject><phrase>The properties view, texture preview</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Press the <guibutton>Preview</guibutton> button inside the properties view and a +small sample scene with the selected texture will be rendered. By default the whole texture +will be rendered, even if not the top item is selected. If you want to render only a part of +the texture (for example a texture inside a texture map and not the whole texture map), check the +<guilabel>local</guilabel> check box.</para> + +</sect1> + +<sect1 id="the-wireframe-views"> +<title>The Wireframe Views</title> + +<sect2 id="orthographic-views"> +<title>The Orthographic Views</title> + +<para>The orthographic wireframe views show the scene as an orthographic +projection on one of the coordinate planes.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="topview.png" format="PNG"/></imageobject> +<textobject><phrase>The top wireframe view</phrase></textobject> +</mediaobject> +</screenshot> + +<para>There are six types of orthographic wireframes views:</para> +<itemizedlist> +<listitem><para>Top</para></listitem> +<listitem><para>Bottom</para></listitem> +<listitem><para>Left</para></listitem> +<listitem><para>Right</para></listitem> +<listitem><para>Front</para></listitem> +<listitem><para>Back</para></listitem> +</itemizedlist> + +<para>Each type renders the scene from a different perspective.</para> + +<sect3 id="graphical-change"> +<title>Graphical Attribute Changes</title> +<para>In the orthographic views you can change object attribute +properties graphically with the mouse.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="controlpoints.png" format="PNG"/></imageobject> +<textobject><phrase>The control points of the camera object</phrase></textobject> +</mediaobject> +</screenshot> + +<para>The above screenshot shows the control points of the camera. +You can drag the control points around to change the camera's position and direction.</para> + +<para>If a transformation is selected, the control points are removed and a small cross is +displayed in the wireframe view. The cross marks the center for scaling and rotation, +as well as the position for translations. You can change the transformation with the mouse +by dragging inside the whole view.</para> + +<para>Some objects like the bicubic patch support selection and modification of multiple +control points.</para> + +<informaltable> +<tgroup cols="2"><tbody> +<row> + <entry>&LMB;</entry> + <entry>Selects one control point and deselects all others</entry> +</row> +<row> + <entry><keycombo + action="click">&Ctrl;<mousebutton>Left</mousebutton></keycombo> + Mouse Button</entry> + <entry>Selects or deselects one control point</entry> +</row> +<row> + <entry><keycombo + action="click">&Shift;<mousebutton>Left</mousebutton></keycombo> + Mouse Button</entry> + <entry>Drag a rectangle. All control points inside the rectangle are + selected, the others deselected</entry> +</row> +<row> + <entry><keycombo + action="click">&Shift;&Ctrl;<keycap>Left</keycap></keycombo> Mouse Button</entry> + <entry>Drag a rectangle. All control points inside the rectangle are selected</entry> +</row> +</tbody></tgroup> +</informaltable> + +</sect3> + +<sect3 id="display-window-selection"> +<title>Display Window Selection</title> +<para>You can zoom and translate the view to change the display window.</para> +<informaltable> +<tgroup cols="2"><tbody> +<row> + <entry>&MMB;</entry> + <entry>Translates the view</entry> +</row> +<row> + <entry><mousebutton>wheel</mousebutton></entry> + <entry>Zooms the view around the mouse position</entry> +</row> +<row> + <entry><keycap>Left</keycap>, <keycap>Right</keycap>, <keycap>Up</keycap>, <keycap>Down</keycap> </entry> + <entry>Translates the view</entry> +</row> +<row> + <entry><keycombo action="simul"><keycap>Ctrl</keycap><keycap>Left</keycap></keycombo>, + <keycombo action="simul"><keycap>Ctrl</keycap><keycap>Right</keycap></keycombo></entry> + <entry>Zooms the view</entry> +</row> +</tbody></tgroup> +</informaltable> + +</sect3> + +</sect2> + +<sect2 id="camera-view"> +<title>The Camera View</title> + +<para>The camera view displays the scene from the camera's point of view.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="cameraview.png" format="PNG"/></imageobject> +<textobject><phrase>The camera view</phrase></textobject> +</mediaobject> +</screenshot> + +<para>The blue box displays the field of view when the scene is rendered.</para> + +<para>You cannot change control points in the camera view.</para> + +</sect2> + +<sect2 id="visibility-levels"> +<title>Visibility Levels</title> + +<para>By default all objects are displayed in the wireframe views.</para> +<para>Each object with a wire frame has a visibility level. +You can specify a visibility level relative to the parent's visibility level +or an absolute value. Objects are only displayed if they are selected or their visibility +level is smaller or equal the chosen scene visibility level in the +toolbar.</para> + +</sect2> + +</sect1> + + +<sect1 id="view-layouts"> +<title>View Layouts</title> + +<para>&kpovmodeler; comes with a default view layout: The object tree and +the object properties view to the left and four graphical views to the right.</para> + +<para>If you don't like the default layout, or need another layout, you can freely +configure it. You can even save multiple view layouts and switch between them +on the fly.</para> + +<sect2 id="change-the-view-layout"> +<title>Modifying the View Layout</title> + +<para>You can move the existing views by dragging the handle on top of the +views around.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="dockwidget.png" format="PNG"/></imageobject> +<textobject><phrase>The dock widget handle</phrase></textobject> +</mediaobject> +</screenshot> + +<para>To dock a widget above or below an existing view, drag the handle to +the top or bottom of a view. A rectangle will indicate the new position.</para> +<para>To create a new column, drag the handle to the right or left side +of another view. The view will then dock to the left or right side of the +view and span the full height.</para> +<para>If you want multiple views sharing the same space, drag the handle to +the center of another view. You can then switch between the views by +clicking the corresponding tab on top of the views.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="dockwidgettab.png" format="PNG"/></imageobject> +<textobject><phrase>The tabbed view layout</phrase></textobject> +</mediaobject> +</screenshot> + +<para>The last layout possibility are floating views: views that +are not docked into the main view. To undock a view, drag the handle to the +desktop or press the little arrow in the view handle that points to the +top left side.</para> + +<para>To close a view, click the little cross in the handle. To prevent closing, +click the little box between the arrow and the cross.</para> + +<para>You can add additional views to the main window. The <guimenu>View</guimenu> +menu contains entries for each type of view. New views will be created floating, +which you can dock wherever you like.</para> + +</sect2> + +<sect2 id="save-a-view-layout"> +<title>Saving a View Layout</title> + +<para>You can save the current view layout with +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Save View Layout...</guimenuitem> +</menuchoice> A dialog opens that lets you select an existing layout +or create a new one.</para> + +<para>You can then fine-tune your view layout in the +<link linkend="configure-view-layout-tab">settings dialog</link>. + +</para> +</sect2> + +<sect2 id="switching-between-view-layout"> +<title>Switching between View Layouts</title> +<para>You can switch to a saved view layout by selecting the entry in the +<menuchoice><guimenu>View</guimenu><guimenuitem>View Layout</guimenuitem></menuchoice> +menu.</para> + +</sect2> + +</sect1> + +</chapter> + + +<chapter id="povray-interaction"> +<title>&Povray; Interaction</title> + +<sect1 id="rendering-the-scene"> +<title>Rendering the Scene</title> + +<para>Once you have created a scene, you will want to render it. &kpovmodeler; +uses &Povray; 3.1g to render the scene, so you need a correct installation of &Povray;. +At the time of writing &Povray; 3.5 was released. This version is not supported in +the &kpovmodeler; 1.0 version.</para> +<para>Go to <ulink url="http://www.povray.org">www.povray.org</ulink> +to get a version of &Povray; and for installation instructions.</para> + +<para>To render the current scene, press the render icon +<inlinemediaobject> +<imageobject><imagedata fileref="rendericon.png" format="PNG"/></imageobject> +<textobject><phrase>The render icon</phrase></textobject> +</inlinemediaobject> +in the toolbar, or select the +<menuchoice><guimenu>View</guimenu><guimenuitem>Render</guimenuitem></menuchoice> +menu entry.</para> + +<sect2 id="render-modes"> +<title>Render Modes</title> + +<para>A render mode is similar to &Povray;s ini file entries. It specifies the image size +and quality levels for rendering. If you would like to render your scene with different +qualities and sizes, you can add as many render modes as you need, from quick previews +to fullscreen high quality images.</para> + +<sect3 id="render-modes-configuration"> +<title>Render Modes Configuration</title> + +<para>When you press the render settings icon +<inlinemediaobject> +<imageobject><imagedata fileref="rendersettingsicon.png" format="PNG"/></imageobject> +<textobject><phrase>The render settings</phrase></textobject> +</inlinemediaobject> +in the toolbar or select the +<menuchoice><guimenu>View</guimenu><guimenuitem>Render Modes...</guimenuitem></menuchoice> +menu icon, the following dialog opens:</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="rendermodesselection.png" format="PNG"/></imageobject> +<textobject><phrase>The render modes selection dialog</phrase></textobject> +</mediaobject> +</screenshot> + +<para>This dialog shows the list of all available render modes.</para> + +<variablelist> + +<varlistentry><term><guibutton>Add</guibutton></term> +<listitem><para><action>Adds a default render mode to the list</action>.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guibutton>Remove</guibutton></term> +<listitem><para><action>Removes the selected render mode</action>.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guibutton>Edit</guibutton></term> +<listitem><para><action>Opens a dialog to edit the selected render mode</action>.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guibutton>Up</guibutton></term> +<listitem><para><action>Moves the selected render mode one position up</action>.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guibutton>Down</guibutton></term> +<listitem><para><action>Moves the selected render mode one position down</action>.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>The <guibutton>Edit</guibutton> Button opens the following +configuration dialog:</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="rendermodesize.png" format="PNG"/></imageobject> +<textobject><phrase>The render modes size tab</phrase></textobject> +</mediaobject> +</screenshot> + +<para>Each render mode has a description. You can enter any description, but it should reflect +the render mode's properties.</para> + +<para>In the <guilabel>Size</guilabel> tab you can enter the width and height of the rendered image. If +you want to render only a small part of the image, check the +<guilabel>Subselection</guilabel> check box and enter the part of the image +in the fields below.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="rendermodequality.png" format="PNG"/></imageobject> +<textobject><phrase>The render modes quality tab</phrase></textobject> +</mediaobject> +</screenshot> + +<para>In the <guilabel>Quality</guilabel> tab you can select various quality levels +for the rendered image.</para> + +<para>In the <guilabel>Quality</guilabel> combo box you can select the features +&Povray; uses while rendering. The possibilities range from a very simple coloring +and lighting model, to one which has complex diffuse inter-reflection lighting. +See the &Povray; user documentation +for a detailed description of the rendering features.</para> + +<para>If an image is rendered with only one sample per pixel, various errors can occur. +These images often have moiré or stepped effects in curves and lines, and +details can get lost if they are smaller in appearance then one pixel. +This effect is called <quote>aliasing</quote>.</para> + +<para>&Povray; uses a technique called <quote>anti-aliasing</quote> to reduce the impact +of these errors. In general images will look smoother with this feature.</para> + +<para>If you enable anti-aliasing, &Povray; will calculate and combine more then one +sample per pixel. This is called <quote>super-sampling</quote>.</para> + +<para>&Povray; supports two methods of super-sampling. The default +is an adaptive non-recursive method; <quote>adaptive</quote> +because the super-sampling +depends on the local neighborhood of the pixel. Not every +pixel is super-sampled with this method. The second method is an adaptive +recursive one; <quote>recursive</quote> because every pixel is divided and sub-divided +recursively, and <quote>adaptive</quote> because the recursion depth depends on the +computed color values.</para> + +<para>When you select the first method, povray traces one ray per pixel. If the +difference between its color value and that of its neighbor exceeds the given threshold, +both pixels are super-sampled by tracing a fixed number of additional rays. If you set +the depth value to 4, a 4x4 grid of additional points will be calculated, a depth +value of 5 will result in 5x5 (25) samples per pixel.</para> + +<para>The difference between two pixels is computed as follows: r<subscript>1</subscript>, +g<subscript>1</subscript> and b<subscript>1</subscript> are the +red, green and blue values of the first pixel; r<subscript>2</subscript>, +g<subscript>2</subscript> and b<subscript>2</subscript> are the red, +green and blue values of the second pixel. The difference is then: +</para> +<para>diff = abs(r<subscript>1</subscript>-r<subscript>2</subscript>) ++ abs(g<subscript>1</subscript>-g<subscript>2</subscript>) ++ abs(b<subscript>1</subscript>-b<subscript>2</subscript>)</para> + +<para>The recursive method starts with 4 samples per pixel. If the resulting color values +differ more than the given threshold, the pixel is sub-divided into 4 sub pixels that are +separately traced and tested for further subdivision. You can specify the maximum +recursive depth with the depth value.</para> + +<para>An additional method to reduce aliasing effects is to add noise to the +sampling process, called <quote>jittering</quote>. If you enable +jittering, &Povray; jitters the samples a tiny amount to reduce +regular patterns.</para> + +<para>The last quality setting is radiosity. Radiosity is an experimental +&Povray; feature that computes inter-diffuse light reflection. Be patient +when rendering a scene with this feature.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="rendermodeoutput.png" format="PNG"/></imageobject> +<textobject><phrase>The render modes output tab</phrase></textobject> +</mediaobject> +</screenshot> + +<para>In the last tab, you can configure whether or not the +alpha channel should be calculated by povray. +A pixel will then be transparent +if the corresponding ray did not hit a single object.</para> + +</sect3> + +<sect3 id="choosing-a-render-mode"> +<title>Choosing a render mode</title> + +<para>You can select the render mode in the combo box in the rendering toolbar.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="rendermodestoolbar.png" format="PNG"/></imageobject> +<textobject><phrase>The render modes toolbar</phrase></textobject> +</mediaobject> +</screenshot> + +</sect3> + +</sect2> + +<sect2 id="the-render-window"> +<title>The Render Window</title> + +<para>When you started to render a scene, this window will open:</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="renderwindow.png" format="PNG"/></imageobject> +<textobject><phrase>The render window</phrase></textobject> +</mediaobject> +</screenshot> + +<para>It shows the rendered image, the progress and the current rendering +speed.</para> + +<variablelist> + +<varlistentry><term><guibutton>Stop</guibutton></term> +<listitem><para><action>Terminates &Povray;</action>.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guibutton>Suspend</guibutton></term> +<listitem><para><action>Suspends rendering</action>.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guibutton>Resume</guibutton></term> +<listitem><para><action>Resumes rendering</action>.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guibutton>Povray Output...</guibutton></term> +<listitem><para><action>Opens another window that displays the &Povray; +console output</action>. If &Povray; exits abnormally, you can find the reason +in that window.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guibutton>Save...</guibutton></term> +<listitem><para><action>Lets you save the image when it is rendered.</action></para> +</listitem> +</varlistentry> + +<varlistentry><term><guibutton>Close</guibutton></term> +<listitem><para><action>Closes the render window</action>.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="exporting-and-importing-povray"> +<title>Exporting and Importing</title> + +<sect2 id="exporting-and-importing-a-whole-scene"> +<title>Exporting and Importing a Whole Scene</title> + +<para>You can export a scene to &Povray; with the +<menuchoice><guimenu>File</guimenu><guimenuitem>Export Povray...</guimenuitem></menuchoice> +menu entry.</para> +<para>The file save dialog will allow you to choose a name and +location to save the file.</para> +<note><para>&kpovmodeler; will automatically add the +<literal role="extension">.pov</literal> extension.</para></note> + +<para>To import a &Povray; scene select the +<menuchoice><guimenu>File</guimenu><guimenuitem>Import Povray...</guimenuitem></menuchoice> +menu item and choose a file in the file open dialog.</para> + +<note><para>Not the full &Povray; syntax is supported by &kpovmodeler; at the moment. +If there are errors or warnings during importing, a dialog will show up that +lists all messages.</para></note> + +<tip><para>If you want to import unsupported code to &kpovmodeler;, put +the source between the two special comments <quote>//*PMRawBegin</quote> +and <quote>//*PMRawEnd</quote>.</para></tip> + +</sect2> + +<sect2 id="exporting-and-importing-single-objects"> +<title>Exporting and Importing single Objects</title> + +<para>You can drag objects from the object tree to an editor +to export &Povray; code. This will insert the objects code into the current +text file in the editor. To import objects into the scene, simply select +the code in your editor and drag it on to the object tree.</para> +<para>You can use the copy and paste functionality of &kpovmodeler; +and your editor to exchange &Povray; code as well.</para> + +</sect2> + +</sect1> + +</chapter> + + +<chapter id="customizing"> +<title>Configuring &kpovmodeler;</title> + +<sect1 id="configure-povray-tab"> +<title>The <guilabel>Povray</guilabel> Tab</title> + +<sect2 id="configure-povray-command"> +<title><guilabel>Povray Command</guilabel></title> + +<para>The povray command is called when &kpovmodeler; renders a scene. Common commands +are <quote>povray</quote> or <quote>x-povray</quote>.</para> + +</sect2> + +<sect2 id="configure-povray-documentation"> +<title><guilabel>Povray User Documentation</guilabel></title> + +<para>If you press the <guibutton>Help</guibutton> button in the properties view, &kpovmodeler; +opens the &Povray; user documentation for the displayed object. Set here the path to your documentation +and your documentation version. Supported versions are 3.1g and 3.5.</para> + +</sect2> + +<sect2 id="configure-povray-library-paths"> +<title><guilabel>Library Paths</guilabel></title> + +<para>&Povray; searches for external files (height field data as example) in the &Povray; library paths. +If you refer to files not in the scene's folder, you have to add the folder to the list. If a file +exists in multiple library paths, that one in the first path is used.</para> +<para>You can change the order with the <guibutton>Up</guibutton> and +<guibutton>Down</guibutton> buttons.</para> + +</sect2> + +</sect1> + +<sect1 id="configure-graphical-view-tab"> +<title>The <guilabel>Graphical view</guilabel> Tab</title> + +<sect2 id="configure-colors"> +<title><guilabel>Colors</guilabel></title> + +<para>The color tab lets you configure the used colors for the graphical views.</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Background:</guilabel></term> +<listitem><para>The background color.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Wire frame:</guilabel></term> +<listitem><para>The colors for wire frames. The second color is used if the object +is selected.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Control points:</guilabel></term> +<listitem><para>The color for control points. The second color is used if the control point +is selected.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Axes:</guilabel></term> +<listitem><para>The colors for the x-, y- and z-axis.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Field of view:</guilabel></term> +<listitem><para>The color for the field of view rectangle in the camera view +and the view type labels.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="configure-grid"> +<title>The Grid</title> + +<para>This page lets you configure the grid in the wire frame views.</para> + +<sect3 id="configure-displayed-grid"> +<title><guilabel>Displayed Grid</guilabel></title> + +<variablelist> + +<varlistentry> +<term><guilabel>Color:</guilabel></term> +<listitem><para>The grid color.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Distance:</guilabel></term> +<listitem><para>The minimal distance of two grid lines.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="configure-control-point-grid"> +<title><guilabel>Control Point Grid</guilabel></title> + +<para>You can snap control points to the grid with the context menu in +the wireframe views. You can configure the grid for translations, scales and rotations +separately here.</para> + +</sect3> + +</sect2> + +<sect2 id="configure-detail-levels"> +<title><guilabel>Objects</guilabel></title> + +<sect3 id="configure-object-subdivisions"> +<title><guilabel>Subdivisions</guilabel></title> + +<para>You can configure the detail levels for various objects here.</para> + +<para>Higher values lead to a finer wireframe and therefore to a better approximation for +the displayed objects, but slow down rendering. For some objects like the sphere you can +configure the detail level for two directions separately.</para> + +</sect3> + +<sect3 id="configure-object-sizes"> +<title><guilabel>Sizes</guilabel></title> + +<para>Lets you configure the sizes in which infinite objects are displayed in +the wireframe views.</para> + +</sect3> + +<sect3 id="configure-camera-views"> +<title><guilabel>Camera Views</guilabel></title> + +<para>If you check the <guilabel>High detail for enhanced projections</guilabel> check box, +all wire frame lines are subdivided further if the camera uses an enhanced projection. Enhanced +projections are all projections except the perspective and orthographic projections. This feature +greatly improves the approximation of these projections but slows down rendering.</para> + +</sect3> + +</sect2> + +</sect1> + +<sect1 id="configure-dialog-view-tab"> +<title>The <guilabel>Properties view</guilabel> Tab</title> + +<sect2 id="configure-texture-preview"> +<title><guilabel>Texture Preview</guilabel></title> + +<para>This page lets you configure the texture preview in the properties view.</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Size:</guilabel></term> +<listitem><para>The preview image size.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Gamma:</guilabel></term> +<listitem><para>The gamma correction.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Rendered Objects</guilabel></term> +<listitem><para>Defines the small sample scene. At least one +object has to be selected.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Wall</guilabel></term> +<listitem><para>If the <guilabel>Enable wall</guilabel> check box is checked, a +wall will be rendered behind the objects. The wall is textured with a checker pattern with the +two configurable colors.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Floor</guilabel></term> +<listitem><para>If the <guilabel>Enable floor</guilabel> check box is checked, a +floor will be rendered below the objects. The floor is textured with a checker pattern with the +two configurable colors.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Anti-Aliasing</guilabel></term> +<listitem><para>If the <guilabel>Enable antialiasing</guilabel> check box is checked, +the non-recursive antialiasing method will be used for rendering the scene. You can configure the +depth and threshold values. See <link linkend="render-modes-configuration">render modes section</link> +for a detailed description of the parameters.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="configure-view-layout-tab"> +<title>The <guilabel>View Layout</guilabel> Tab</title> + +<para>In this page you can fine-tune existing view layouts or manually +create new ones. See section <link linkend="view-layouts">View Layouts</link> +how to create and save view layouts.</para> + +<sect2 id="configure-default-layout"> +<title>The default View Layout</title> + +<para>The combo box <guilabel>Default view layout:</guilabel> +lists all available view layouts. &kpovmodeler; uses the selected +view layout at program start.</para> + +</sect2> + +<sect2 id="configure-list-of-view-layouts"> +<title>List of View Layouts</title> + +<para>The list <guilabel>Available View Layouts</guilabel> +shows all available view layouts. You can add a new layout with the +<guibutton>Add</guibutton> button and remove the selected layout +with the <guibutton>Remove</guibutton> button.</para> +<para>The selected view layout is displayed in the box +<guilabel>View Layout</guilabel></para> +</sect2> + +<sect2 id="configure-view-layout-details"> +<title>View Layout Details</title> + +<para>Each view layout is identified by its name. The name has to +be unique and must not be empty.</para> + +<para>The list below the name displays all views for the selected +view layout. You can add new views with the +<guibutton>Add</guibutton> button and remove the selected view +with the <guibutton>Remove</guibutton> button.</para> + +<para>The attributes of the views are:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Type:</guilabel></term> +<listitem> +<para>The view type. See <link linkend="the-interface">The &kpovmodeler; Interface</link> +for a description of each view type.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>3D view type:</guilabel></term> +<listitem> +<para>The projection for wire frame views. You can choose one of the six +orthographic projections or the camera mode.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Dock position:</guilabel></term> +<listitem> +<para>The position of the view. <guilabel>New Column</guilabel> will +create a new column to the right side of the previous views, +<guilabel>Below</guilabel> will dock the view below the previous view, +<guilabel>Tabbed</guilabel> will create a tabbed view together with the previous one +and <guilabel>Floating</guilabel> will not dock the view into the main +window but create a separate window.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Column width:</guilabel></term> +<listitem> +<para>The width of the column in percent of the main view width.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>View height:</guilabel></term> +<listitem> +<para>The view height in percent of the main view height.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Width:</guilabel> and <guilabel>Height:</guilabel></term> +<listitem> +<para>The size in pixels for floating views.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Position x:</guilabel> and <guilabel>y:</guilabel></term> +<listitem> +<para>The position on the desktop for floating views.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +</chapter> + +<chapter id="basic-tutorial"> +<title>Basic Tutorial: Creating your first Scene</title> + +<para>OK, that's it. You have just installed &Povray; and &kpovmodeler;, +and now you already want to start without much knowledge of any of the two +softwares. Here we go now: If you follow the steps of this tutorial, +you'll be able to set the ultimate simple scene, very widespread among +the newbies: A sphere over a plane.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="tutorial01-final-render.png" format="PNG"/> +</imageobject> +</mediaobject> +</screenshot> + +<para>At any time you can render your scene using one of the following methods:</para> + +<para>Using the menu: +<menuchoice><guimenu>Display</guimenu><guimenuitem>Render</guimenuitem></menuchoice></para> +<para>Using the toolbar: Click on the +<inlinemediaobject> +<imageobject><imagedata fileref="cr22-action-pmrender.png" format="PNG"/></imageobject> +</inlinemediaobject> icon</para> + +<para>But you should carefully consider the following warnings before complaining +if all you get is a black screen. If this is the very first time you use a 3D software, +you should be aware of these golden rules:</para> + +<itemizedlist> +<listitem><para>If you set no camera, no rules apply to the render engine which can't +render a proper picture, ending in a black picture.</para></listitem> +<listitem><para>If you set no light system, all your scene is in the dark, +ending in a black picture.</para></listitem> +<listitem><para>The objects for which no material has been set won't show on the +rendered picture, ever.</para></listitem> +</itemizedlist> + +<sect1 id="basic-tutorial-step-1"> +<title>Step 1: Start &kpovmodeler;</title> + +<para>If you got everything installed fine, once &kpovmodeler; +is loaded, you discover the following default windows setting:</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="defaultviewlayout.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>Take a few minutes to explore the menus and icons available. +If you have time, please read the documentation in order to get a +fair idea of what you can expect from this piece of software.</para> + +<itemizedlist> +<listitem> +<para><link linkend="menu-reference">Menubars (1)</link></para> +</listitem> +<listitem> +<para>Toolbars (2)</para> +</listitem> +<listitem> +<para><link linkend="the-object-tree">The object tree (3)</link></para> +</listitem> +<listitem> +<para><link linkend="the-properties-view">The object properties +view (4)</link></para> +</listitem> +<listitem> +<para><link linkend="the-wireframe-views">The wireframe and camera views (5)</link></para> +</listitem> +</itemizedlist> + +<para>You will have to use each of them intensively from now on, so always keep them +and their use in mind.</para> + +<para>&kpovmodeler; starts with a simple scene. In order to follow this tutorial +you first have to remove all objects from the object tree. Select the scene +and choose the <menuchoice><guimenu>Edit</guimenu><guimenuitem>Delete</guimenuitem></menuchoice> menu +entry. You should now have an empty scene.</para> + +</sect1> + +<sect1 id="basic-tutorial-step-2"> +<title>Step 2: Setting the Camera</title> + +<para>First of all, we will set a camera. In order to do so, two convenient ways are available:</para> +<para>Using the menu: <menuchoice><guimenu>Insert</guimenu><guimenuitem>Camera</guimenuitem></menuchoice></para> +<para>Using the toolbar: Click on the +<inlinemediaobject> +<imageobject><imagedata fileref="cr22-action-pmcamera.png" format="PNG"/></imageobject> +</inlinemediaobject> icon</para> + +<para>The wireframe view shows how the camera is set regarding the whole scene we are creating. +In particular, we can now see something in the fourth wire frame view (right, bottom): +This is the view of the scene from the camera point of view. +This is what will be seen when you render the scene.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="tutorial01-camera-graphic.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>The object tree now shows a new entry, reading <quote>camera</quote>. If you click on it, +it affects the content of the object properties view, where various parameters +pertaining to the camera can be found. +Referring to the &Povray;'s documentation to learn more about these could be helpful.</para> + +<screenshot> +<mediaobject> +<imageobject><imagedata fileref="tutorial01-camera-dialog.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>We will change nothing to the basic settings of the camera, +this will be the scope of later tutorials, but please note that in the graphic view, +the camera has control points that let you control the point to which the camera points. +You just have to left-click on one handle and move it to an appropriate location.</para> + +</sect1> + +<sect1 id="basic-tutorial-step-3"> +<title>Step 3: Setting a Light</title> + +<para>The same way we have set a camera, we will now set a light system:</para> +<para>Using the menu: +<menuchoice><guimenu>Insert</guimenu><guimenuitem>Light</guimenuitem></menuchoice></para> +<para>Using the toolbar: Click on the +<inlinemediaobject> +<imageobject><imagedata fileref="cr22-action-pmlight.png" format="PNG"/></imageobject> +</inlinemediaobject> icon</para> + +<para>A new entry features now in the object tree. If you click on the light entry, +you see that the properties view changes in order to show the parameters available +to the lighting system. We will change some parameters in order to set the +light higher above the horizon (<guilabel>y</guilabel>=3), slightly on the right +(<guilabel>x</guilabel>=1) and in the foreground (<guilabel>z</guilabel>=1). +We can also rename the light system (<guilabel>Name</guilabel>=<quote>Main Light</quote>). +Change the values in the object properties view as follows:</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-light-dialog.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>Once you press the <guilabel>Apply</guilabel> button (or hit Enter), +the wire frame view and the object tree immediately +change in order to comply to these settings, and here is what now should see the camera.</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-light-graphic.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="basic-tutorial-step-4"> +<title>Step 4: Creating the Ground</title> +<para>There are many ways to create a ground for our scene. +One method could have been to insert a box object +(<menuchoice><guimenu>Insert</guimenu><guisubmenu>Finite Solid Primitives</guisubmenu> +<guimenuitem>Box</guimenuitem></menuchoice>) +and resize x to 100, y to 0 and z to 100, for example, but it's a cumbersome way to do this task.</para> + +<para>In fact, &kpovmodeler; offers you a convenient feature: You can create +a infinite plane that will feature the ground:</para> + +<para>Using the menu: +<menuchoice><guimenu>Insert</guimenu><guisubmenu>Infinite Solid Primitives</guisubmenu> +<guimenuitem>Plane</guimenuitem></menuchoice></para> +<para>Using the toolbar: Click on the +<inlinemediaobject><imageobject><imagedata fileref="cr22-action-pmplane.png" format="PNG"/></imageobject> +</inlinemediaobject> icon.</para> + +<para>Take a good custom: Having the plane selected in the object tree, please change its name +in something that is convenient to you and then press the <guilabel>Apply</guilabel> button (or hit Enter). +The object tree will update the name of the entry.</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-plane-dialog.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>The wire frame view also shows the plane now, even if it looks finite by now. +But don't worry, it will spread up to the horizon line when you'll render the scene!</para> + +<para>If you pay attention to the object tree, you will notice that the ground entry +can be expanded if you click on the <quote>plus</quote> icon standing just before the object. +Once done, you see various settings parented to the object. In this case, +there isn't much yet, apart from the standard options to any newly created object: +Scale, rotate, and translate. Selecting each of these will change the settings +available in the object properties view.</para> + +<screenshot> +<mediaobject> <imageobject><imagedata fileref="tutorial01-plane-tree-expanded.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>In this scene, we will arbitrary translate the ground one unit lower than the horizon line, +just for you to tweak some of these parameters. Select translate, and adjust the parameters as follow:</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-plane-tree-translate.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>Your scene should now look like the following picture.</para> +<screenshot><mediaobject><imageobject><imagedata fileref="tutorial01-plane-graphic.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="basic-tutorial-step-5"> +<title>Step 5: Setting a Material for the Ground</title> + +<para>Please select the ground prior to adding any material properties to it. +Many possibilities await us, but we will stay close to something quite easy for now.</para> + +<para>Using the menu: <menuchoice><guimenu>Insert</guimenu><guisubmenu>Textures</guisubmenu> +<guimenuitem>Pigment</guimenuitem></menuchoice></para> +<para>Using the toolbar: Click on the +<inlinemediaobject> +<imageobject><imagedata fileref="cr22-action-pmpigment.png" format="PNG"/></imageobject> +</inlinemediaobject> icon.</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="insertaspopup.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>In both cases, a popup window will prompt you to choose the way the object should be inserted. +Please choose <guilabel>First Child</guilabel>. The pigment now appears in the object tree. +You can change its name +in the properties view (<guilabel>Name</guilabel>=<quote>Ground Pigment</quote>), and click on the +<guibutton>Preview</guibutton> button +in order to see how the pigment looks like for now.</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-ground-pigment.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>Of course, the preview of the pigment shows nothing but a black matte material, +because we need to refine the pigment settings. Anyway, keep in mind you always +can preview the look and feel of your materials using the <guibutton>Preview</guibutton> button. +We will now define the pigment colors. Again, many possibilities await us, +but we will choose one of the most straightforward for now.</para> + +<para>Using the menu: <menuchoice><guimenu>Insert</guimenu><guisubmenu>Textures</guisubmenu> +<guimenuitem>Color List</guimenuitem></menuchoice></para> +<para>Using the toolbar: Click on the +<inlinemediaobject> +<imageobject><imagedata fileref="cr22-action-pmcolorlist.png" format="PNG"/></imageobject> +</inlinemediaobject> icon</para> + +<para>If no color shows on the box and the sphere of the preview, +click on the <guibutton>Apply</guibutton> button before calling for a preview.</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-ground-color-list.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>The ground material has been successfully set! If you render your picture now, using the +<inlinemediaobject> +<imageobject><imagedata fileref="cr22-action-pmrender.png" format="PNG"/></imageobject> +</inlinemediaobject> render icon, you should get the following result:</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-ground-wrong-colors-render.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>Of course, these colors are not the ones you could have expected. +We still have to see how we can customize them. In the case of the color list, +you have to define two new sets of attributes, called <guilabel>Solid Color</guilabel>. +In the Object Tree, make sure the color list entry is selected. +Then go through this two times (you can't do it more, anyway, +as the checkers color list can only afford the use of two solid colors):</para> + +<para>Using the menu: <menuchoice><guimenu>Insert</guimenu><guisubmenu>Textures</guisubmenu> +<guimenuitem>Solid Color</guimenuitem></menuchoice></para> + +<para>Using the toolbar: Click on the +<inlinemediaobject> +<imageobject><imagedata fileref="cr22-action-pmsolidcolor.png" format="PNG"/></imageobject> +</inlinemediaobject> icon.</para> + +<para>One after another, in the object tree, select the two solid colors +and change their color attributes in the object properties view:</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-ground-solid-color-1.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>...these attributes are for the first solid color (press <guibutton>Apply</guibutton>!),</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-ground-solid-color-2.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>... and these attributes are for the second (press <guibutton>Apply</guibutton> again!).</para> + +<para>Of course, a new rendering of our scene will prove that everything has been +taken into account accordingly:</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-ground-render.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="basic-tutorial-step-6"> +<title>Step 6: Creating the Sphere</title> + +<para>For this step, we should already be at ease, because we begin to understand +&kpovmodeler;'s general behavior. In the object tree, select the scene entry. +Creating the sphere is as easy as creating the ground:</para> + +<para>Using the menu: <menuchoice><guimenu>Insert</guimenu><guisubmenu>Finite Solid Primitives</guisubmenu> +<guimenuitem>Sphere</guimenuitem></menuchoice></para> + +<para>Using the toolbar: Click on the +<inlinemediaobject> +<imageobject><imagedata fileref="cr22-action-pmsphere.png" format="PNG"/></imageobject> +</inlinemediaobject> icon.</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="insertaspopup.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>As before, select <guilabel>First Child</guilabel> when asked for.</para> + +<para>The object properties view offers you immediately to change its settings, +which we'll do right now. By setting the <guilabel>Radius</guilabel> value to 1 +(don't forget to hit Enter or press <guibutton>Apply</guibutton>), +we make sure that the sphere will be in contact +with the ground. Otherwise, since we moved the ground one unit bottom, +the sphere will look like floating above the ground.</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-sphere-dialog.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>Of course, a rendering now will give a strange result: As already seen before, +the sphere appears with a black matte material. We will set a proper material in the following step.</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-sphere-render-nocolor.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="basic-tutorial-step-7"> +<title>Step 7: Setting a Material for the Sphere</title> + +<para>With the sphere selected, you can now set a material for it. As we already did for the ground, +let's give to the sphere a pigment color:</para> + +<para>Using the menu: <menuchoice><guimenu>Insert</guimenu><guisubmenu>Textures</guisubmenu> +<guimenuitem>Pigment</guimenuitem></menuchoice></para> + +<para>Using the toolbar: Click on the +<inlinemediaobject><imageobject><imagedata fileref="cr22-action-pmpigment.png" format="PNG"/></imageobject> +</inlinemediaobject> icon</para> + +<para>Select <guilabel>First Child</guilabel> and rename to <quote>Sphere pigment</quote>, for example. +With the sphere pigment entry selected, insert a solid color and set the parameters as follow:</para> + +<para>Using the menu: <menuchoice><guimenu>Insert</guimenu><guisubmenu>Textures</guisubmenu> +<guimenuitem>Solid Color</guimenuitem></menuchoice></para> + +<para>Using the toolbar: Click on the +<inlinemediaobject><imageobject><imagedata fileref="cr22-action-pmsolidcolor.png" format="PNG"/></imageobject> +</inlinemediaobject> icon</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-sphere-solid-color.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>You already can render the scene and get a first poor result:</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-sphere-render-solidcolor.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>But there are more interesting effects to achieve if we take time to set some finish attributes:</para> + +<para>Using the menu: <menuchoice><guimenu>Insert</guimenu><guisubmenu>Textures</guisubmenu> +<guimenuitem>Finish</guimenuitem></menuchoice></para> +<para>Using the toolbar: Click on the +<inlinemediaobject> +<imageobject><imagedata fileref="cr22-action-pmfinish.png" format="PNG"/></imageobject> +</inlinemediaobject> icon.</para> + +<para>Then change the values according to the following snapshot and press +<guibutton>Apply</guibutton> or hit Enter.</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-sphere-finish-dialog.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +<para>The <guilabel>Specular</guilabel> and <guilabel>Reflection</guilabel> +parameters give particularly good visual effects, +perfect for glass or chrome-like effects, even if <guilabel>Metallic</guilabel> +hasn't been chosen at this step:</para> + +<screenshot> +<mediaobject><imageobject><imagedata fileref="tutorial01-sphere-render-finish.png" format="PNG"/></imageobject> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="basic-tutorial-conclusion"> +<title>Conclusion</title> + +<para>You should now have a fair glimpse of what is possible with kpovmodeler. +Hopefully, you are already skilled enough to do simple but beautiful things.</para> + +</sect1> +</chapter> + +<chapter id="concepts"> +<title>Basic Concepts</title> + +<sect1 id="what-is-raytracing"> +<title>What is Raytracing?</title> + +<para>Raytracing is a method of <link +linkend="gloss-rendering">rendering</link>, that is, creating a 2D +image out of a 3D scene or model.</para> + +<para>When raytracing a scene, the renderer shoots a hypothetical ray +from the perspective of the viewer (that is, from the camera you are +rendering the scene from) through each pixel in the scene. It +calculates how this ray reflects and refracts from objects, the visual +effects of the light sources in the scene and how atmospheric effects such +as fog affect it. The scene is built up, pixel by pixel.</para> + +<para>As you may imagine, without a camera, you cannot see anything - +the camera is your <quote>eye</quote> into the scene. Furthermore, +without any light, you still won't see anything - it would just be +dark. Obviously, any scene intended for raytracing must include +some light, an object of some kind and at least one camera.</para> + +</sect1> + +</chapter> + +<chapter id="objects-reference"> +<title>Objects Reference</title> + +<para>For a complete reference to all objects and attributes +see the &Povray; user documentation.</para> +</chapter> + + +<chapter id="menu-reference"> +<title>Menu Reference</title> + +<sect1 id="file-menu"> +<title>The <guimenu>File</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><menuchoice><shortcut> +<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>New</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Create a new scene.</action></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Import Povray...</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Import a &Povray; scene</action> created outside +&kpovmodeler;.</para> +<para>A normal file dialog will open, allowing you to choose your +file. Povray files usually have the extensions <literal +role="extension">*.pov</literal> or <literal +role="extension">*.inc</literal>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut> +<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Open...</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Open a file.</action> The standard file dialog will +allow you to choose a file you have previously created with +&kpovmodeler;</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guisubmenu>Open Recent</guisubmenu> +</menuchoice></term> +<listitem> +<para><action>Open a file from a list of the files you have been +recently working on.</action></para> +<para>Whenever you open or create a new model, it is added to this +submenu, replacing the oldest entry in the list.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut> +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Save</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Save the currently active scene.</action></para> +<para>If you have already saved this model, it will be saved with the +same name. If it is a new file, you will be asked to name it and +choose a location to save it.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Save As...</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Save the currently active scene with a new +name.</action></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Export Povray...</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Export the scene as a &Povray; file.</action></para> +<para>The file save dialog will allow you to choose a name and +location to save the file.</para> +<note><para>&kpovmodeler; will automatically add the +<literal role="extension">.pov</literal> extension.</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Revert</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Revert the scene to the state it was in the last time +you saved it.</action> Changes you have made since the last save will +be lost.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut> +<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Print...</guimenuitem> +</menuchoice></term> +<listitem> +<para>Printing is not implemented yet.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut> +<keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Close</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Close the current scene</action> without closing +&kpovmodeler;</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><action>Quit</action> &kpovmodeler;. If you have any unsaved +changes, you will be given a chance to save them.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="edit-menu"> +<title>The <guimenu>Edit</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><menuchoice><shortcut> +<keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Undo</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Undo the last action you performed.</action></para> +<para>This menu item is not available unless you have unsaved changes +to the current scene.</para><!-- FIXME: is the number of items in the --> +<!-- undo history configurable? --> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"> +&Ctrl;&Shift;<keycap>Z</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Redo</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Redo the last action you undid.</action> This menu item +is not available unless you have used +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Undo</guimenuitem></menuchoice>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"> +&Ctrl;<keycap>X</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Cut</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Cut</action> the currently selected object(s) from the scene, +and store them on the clipboard.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"> +&Ctrl;<keycap>C</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Copy</action> the currently selected object(s), and +store them on the clipboard.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"> +&Ctrl;<keycap>V</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Paste</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Paste</action> the contents of the clipboard.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Delete</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Delete</action> the currently selected object(s) from +the scene.</para> +<!-- FIXME: Shouldn't this be bound to the delete key? --> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="view-menu"> +<title>The <guimenu>View</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>New Object Tree</guimenuitem> +</term> +<listitem> +<para><action>Create</action> a new <link linkend="the-object-tree">Object Tree</link>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>New Properties View</guimenuitem> +</term> +<listitem> +<para><action>Create</action> a new <link linkend="the-properties-view">Object Properties View</link>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>New Top View</guimenuitem> +</term> +<listitem> +<para><action>Create</action> a new +<link linkend="orthographic-views">Orthographic Wireframe View</link> +from the top perspective.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>New Bottom View</guimenuitem> +</term> +<listitem> +<para><action>Create</action> a new +<link linkend="orthographic-views">Orthographic Wireframe View</link> +from the bottom perspective.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>New Left View</guimenuitem> +</term> +<listitem> +<para><action>Create</action> a new +<link linkend="orthographic-views">Orthographic Wireframe View</link> +from the left perspective.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>New Right View</guimenuitem> +</term> +<listitem> +<para><action>Create</action> a new +<link linkend="orthographic-views">Orthographic Wireframe View</link> +from the right perspective.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>New Front View</guimenuitem> +</term> +<listitem> +<para><action>Create</action> a new +<link linkend="orthographic-views">Orthographic Wireframe View</link> +from the front perspective.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>New Back View</guimenuitem> +</term> +<listitem> +<para><action>Create</action> a new +<link linkend="orthographic-views">Orthographic Wireframe View</link> +from the back perspective.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>New Camera View</guimenuitem> +</term> +<listitem> +<para><action>Create</action> a new +<link linkend="camera-view">Camera View</link>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>View Layouts</guimenuitem> +</term> +<listitem> +<para>Contains a list of all available view layouts. Switch to the +selected layout.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>Save View Layout...</guimenuitem> +</term> +<listitem> +<para>Save the current view layout. A dialog opens to choose a +name for a new layout or to overwrite an existing one.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>Render Modes...</guimenuitem> +</term> +<listitem> +<para>Open the +<link linkend="render-modes-configuration">render modes configuration</link> +dialog.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>Render</guimenuitem> +</term> +<listitem> +<para>Render the scene.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>Render Window</guimenuitem> +</term> +<listitem> +<para>Show the &Povray; render window.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu> +<guimenuitem>Redisplay</guimenuitem> +</term> +<listitem> +<para>Redisplay the wire frame views.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="insert-menu"> +<title>The <guimenu>Insert</guimenu> Menu</title> + +<para>Creation actions for all supported &Povray; objects.</para> + +</sect1> + +<sect1 id="settings-menu"> +<title>The <guimenu>Settings</guimenu> Menu</title> +<para>This menu provides options for configuring &kpovmodeler;, changing its +appearance, shortcuts and standard behavior.</para> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Statusbar</guimenuitem> +</menuchoice></term> +<listitem><para><action>Toggles the statusbar on/off.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Path</guimenuitem> +</menuchoice></term> +<listitem><para><action>Show/hide the path in the caption.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Save settings</guimenuitem> +</menuchoice></term> +<listitem><para><action>Saves the current settings.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Key Bindings...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens a dialog for changing the key bindings.</action> +Using this option you can change the standard key shortcut for &kpovmodeler;'s commands +or create new ones.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens a dialog for configuring the toolbar.</action> You +can add and remove toolbuttons for &kpovmodeler;'s commands with this +option.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure KPovModeler...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens a dialog to configure &kpovmodeler;.</action></para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + + +<sect1 id="help-menu"> +<title>The <guimenu>Help</guimenu> Menu</title> + +&help.menu.documentation; + +</sect1> + +</chapter> + +<chapter id="credits-and-licenses"> +<title>Credits and Licenses</title> + +<para>&kpovmodeler; copyright 2001,2002 the &kpovmodeler; +authors.</para> + +<itemizedlist> +<title>Authors</title> +<listitem> +<para>Andreas Zehender <email>[email protected]</email></para> +</listitem> +<listitem> +<para>Luis Passos Carvalho +<email>[email protected]</email></para> +</listitem> +<listitem> +<para>Phillippe Van Hecke +<email>[email protected]</email></para> +</listitem> +<listitem> +<para>Leonardo Skorianez <email>[email protected]</email></para> +</listitem> +</itemizedlist> + +<para>Documentation copyright 2002 Lauri Watts +<email>[email protected]</email></para> +<para>Documentation copyright 2002 Andreas Zehender +<email>[email protected]</email></para> +<para>Documentation copyright 2002 Olivier Saraja +<email>[email protected]</email></para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; + +</chapter> + +<glossary id="glossary"> +<title>Glossary</title> + +<glossentry id="gloss-bump-map"> +<glossterm>Bump Map</glossterm> +<glossdef> +<para>A bump map is a way to simulate a rough surface, without having +to model every single <quote>bump</quote> on the surface, and without +changing the underlying geometric shape of the object itself.</para> +<para>It is common to use the same file as both a bump map and a <link +linkend="gloss-texture-map">texture map</link>.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-primitives"> +<glossterm>Primitives</glossterm> +<glossdef> +<para>Primitives are the basic geometric shapes that you can use as +<quote>building blocks</quote>. Most complex 3d models are created +from many dozens, or even hundreds, of these primitives, which are +then edited and manipulated to give a more realistic +appearance.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-rendering"> +<glossterm>Rendering</glossterm> +<glossdef> +<para>Not yet written</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-texture-map"> +<glossterm>Texture Map</glossterm> +<glossdef> +<para>A texture map is a way of applying color to the surface of an +object on a pixel by pixel basis, by applying an image file as a color +map.</para> +<para>It is common to use the same image file as a <link +linkend="gloss-bump-map">bump map</link>.</para> +</glossdef> +</glossentry> + + + +</glossary> + +&documentation.index; + +<appendix id="installation"> +<title>Installation</title> + +&install.intro.documentation; +&install.compile.documentation; + +</appendix> + +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +// vim:ts=2:sw=2:tw=78:noet +--> |