ICoons v. 1.0 1. Introduction ================ ICoons is a spline based object modeller which can be used to generate objects in TTDDD format. TTDDD files can be converted to lots of different object formats by using the T3DLIB shareware package by Glenn Lewis. This document is a poor mans substitute for a real manual, but I don't have time to better one. If you don't like it, you're welcome to write a better one :) ICoons may be distributed under the terms of the GNU General Public License, this license has been included in file COPYING found in this distribution. In the following, I'll refer to the iff pictures included with this documentation. A reference such as 1-1 refers to the first figure in the Man1.iff file. 1.1: About splines: --------------------- ICoons is based on a special type of curves called "Kochanek-Bartels splines", these splines has the following properties: They pass through their control points (called knots), It is possible to control the local behaviour of the spline at each knot, by varying three parameters called TENSION, BIAS and CONTINUITY. It is possible to model nearly any curve by placing knots and modifying these three parameters at each knot. I won't even try to describe how tension, bias and continuity controls the spline, it is much easier (for me at least :-) to tell you to try to create a spline in the editor and modify the parameters. The piece of spline between two knots is called a spline segment. A spline can consist of an unlimited number of knots, but it will always consist of at least 2 knots: The endpoints. (See figure 1-1 & 1-2). It is also possible to form a closed (looping) curve by connecting the endpoints of a spline to each other. Such a spline should contain at least 3 knots (See figure 1-3). In the editor, it is possible to connect knots from different splines to each other. When you do this, the connected knots will always be on the same physical position. They will, however, still keep their other attributes (tension etc.) Figure 1-4 shows two 3-knot splines where the central knots of each spline has been connected to each other. If you would try to move the central knot of one of the splines, the other knot would follow automatically. Figure 1-5 shows another example of two connected splines. 1.2: About surfaces: --------------------- The surfaces created by ICoons, are so called bicubically blended Coons surfaces, such a surface is fully defined by its (up to) 4 boundary curves. The points on the surface is found simply by interpolation between these boundary curves. These surfaces has certain severe drawbacks (which I won't mention :-), but they have some features which makes it easy to create a modeller based on them: The surface is defined fully by the boundary curves, this mean that there's no control points inside the surface. (The more popular Bezier surfaces has internal control points. It can be very difficult for the user to visualize where these controlpoints are). The surface interpolates (ie. passes through) the boundary curves and the control points. Together these two 'features' makes it semi-easy for the user to visualize the surface by looking on the boundary curves. In ICoons, a surface is made up of patches: Each patch (which is a Coons surface) is defined by the 2, 3 or 4 connected spline segments that surround it. These segments must not all be from the same spline. If there's more than 4 segments, then the area defined by the segments don't define a patch, even if the segments comes from different patches. Fig 2-1 to Fig 2-5 shows different examples of this. Furthermore Fig 2- 5 shows how to make a hole in a surface. 1.3: About the display: ------------------------ The display should look familiar to all Imagine users. It consists of 4 views which displays the object from 4 different directions: Lower right view: Along the X axis, Lower left view : Along the Y axis, Upper left view : Along the Z axis, Upper right view: From a user defined direction (perspective view). The views normally only display the splines, but it is possible to get a rendering of the surface in the perspective view. If the user selects one of the big vertical gadgets labelled X, Y, Z and P, the corresponding view will expand and fill the full screen. It is then possible to return to the normal 4-view display by closing this window, or by selecting the 'B' (back) gadget found in the big view. The following color coding is used: Splines: Gray: Unselected spline segments are shown in gray. Red: The up to 2 spline segments near the currently selected knot are shown in red. Violet: When the user is modifying a spline, the spline segments which are affected are shown in violet. Knots: ???? : Some strange color is used for unselected knots. Yellow: The selected knot is shown as a yellow dot. Green: All "grouped" knots are shown in green. Axes: Red: The X axis is red. Yellow: The Y axis is yellow. Green: The Z axis is green. 1.3: About the user interface: ------------------------------- Everything in the modeller can be done with the mouse, either by selecting gadgets, or by using menus. The seasoned user will probably want to use the keyboard shortcuts instead. Where shortcuts exist, they are indicated in the menu. Some shortcuts use the left-amiga + key combination while others are activated by just pressing a key (no left-amiga needed). Most of the shortcuts are modelled after Journeyman:Apprentice, so owners of this fine program will get used to the shortcuts very quickly. 2.0: Reference 'manual': ========================= This section describes all commands and menu entries one by one. 2.1: Mouse commands: --------------------- When no other command has been activated, you are in move-mode. In this mode, you can click on a point to select it. If you keep the left mouse button down, you can drag the point to another position. Release the mouse when you're satisfied with the new position. It is possible to connect two splines while moving a point: Just move the point close to a point on another spline, and press the right mouse button (while keeping the left down). When you do this, the two splines will be connected to each other, try to verify this by moving the point again. It is also possible to form a closed spline by connecting the two endpoints of the spline. If the program is in Group mode, you'll drag all the selected points instead of just one, it isn't possible to connect splines in this mode. 2.2: Project menu: ------------------- This menu contain general commands: About... (Shortcut: None) ----------------------------------------------------------------------- Select this entry to get a short message about the version of the program, and who wrote it. The pop up also contains information about the number of splines, knots and points in the current object. New (Shortcut: None) ----------------------------------------------------------------------- Delete the current object from memory, and start a new one. The user will be requested to confirm/cancel the operation Load - ICoons object (Shortcut: LAmiga-L) ----------------------------------------------------------------------- Load an ICoons object from a disk file. The file can be selected from a file requester. The default file extension for ICoons save files are ".ic". Load - JourneyMan object (Shortcut: None) ----------------------------------------------------------------------- Load a JourneyMan:Apprentice object. ICoons are able to load objects made bye the JourneyMan Sculpture module, these files normally have a ".seg" extension. As JourneyMan and ICoons use different kind of splines, and as the JourneyMan file format hasn't been published by Hash Enterprises, the result may not be as expected. I haven't had problems with any of the objects that I've made in JourneyMan though. The JourneyMan spline parameters (Alpha, Gamma & Magnitude) are ignored, the resulting splines will always have the default spline parameters. Save (Shortcut: LAMiga-S) ----------------------------------------------------------------------- Save the current object in a disk file. The file name may be selected from a file requester. Generate - TTDDD format (Shortcut: LAMiga-S) ----------------------------------------------------------------------- Generate a file containing a TTDDD description of the current object. Each patch will be cut up in a N * N of triangles where N is the "Patch resolution" parameter from the configuration window. A little N creates small and fast objects, while a big N creates objects which follow the corresponding splines much nicer. The file name may be selected from a file requester. The resulting file can be converted to lots of different formats by Glen Lewis' shareware T3DLIB package which can be found on ftp sites around the world (for instance hubcap.clemson.edu). Configuration - Load (Shortcut: None) ----------------------------------------------------------------------- Load ICoons configuration parameters from a disk file. The file "s:ICoons.cfg" is loaded automatically whenever the program starts. Configuration - Save (Shortcut: None) ----------------------------------------------------------------------- Save current ICoons configuration parameters to a disk file. The file "s:ICoons.cfg" is loaded automatically whenever the program starts, so if you want to change the default parameters, then create a configuration file with this name. Configuration - Edit (Shortcut: None) ----------------------------------------------------------------------- Select this menu entry to bring up a window with the parameters which are configurable: Grid size: The size of the grid in world coordinates. Spline resolution: Number of line segments to draw for each spline. If this number is big, then the splines will look very smooth, but will take longer time to draw. If this number is small, then the splines will be 'edgy', but will be drawn fast. The default value is 4. Patch resolution: Number of line segments used in splines when rendering and generating TTDDD objects. The number of triangles in a patch will be the square of this number. A small value for this parameter will give small objects, and fast rendering times. A big value will give smoother objects and use more memory. Note that generated TTDDD objects will have the Phong shading activated. So it is not normally necessary to use a very high number here. The default value is 4, 2 seems to work ok too. Draw delay: The number of seconds to wait before drawing splines when manipulating the current object. When moving, scaling etc. you normally will see a bounding box. If you stop moving the mouse for the time given here, then the object will be drawn. The bounding box will reappear when you start to move the mouse again. For very fast machines, you can set this value low. I use 0.5 on my 68030. Knot: This number defines the max number of mouse moves in the event queue when modifying knot parameters. A high number here will give a smooth change in the display, but will take longer time. If you use 0, the display will only be redrawn when the queue is empty. Rot. Persp: This number defines the max number of mouse moves in the event queue when rotating the perspective view. Rot. group: This number defines the max number of mouse moves in the event queue when rotating a group of points. Scale group: This number defines the max number of mouse moves in the event queue when scaling a group of points. Move group: This number defines the max number of mouse moves in the event queue when moving a group of points. Move: This number defines the max number of mouse moves in the event queue when moving a single point. Ok: Select this gadget to activate the changes you've made. The changes won't be saved to disk automatically, use "Configuration-Save" to do this. Cancel: Select this gadget if you don't want to activate the changes you've made. Configuration - Quit (Shortcut: LAmiga-Q) ----------------------------------------------------------------------- Quit the program. The user must confirm/cancel this operation. Remember to save the object before quitting! 2.3: Display menu: ------------------- This menu contain commands which modifies the display: Zoom in (Shortcut: LAmiga-I) ----------------------------------------------------------------------- Zoom in on the display. Zoom out (Shortcut: LAmiga-O) ----------------------------------------------------------------------- Zoom out on the display. Center (Shortcut: LAmiga-C) ----------------------------------------------------------------------- Place center of view. After selecting this command, you must click in one of the views. That position will be centered in the display. Rotate P. (Shortcut: 'R' gadget) ----------------------------------------------------------------------- Use this command to rotate the perspective view. After selecting Rotate P., you must click in one of the views, and keep the button down. Now the perspective view will rotate when you move the button. Release the button when you are satisfied with the direction. This command can also be activated by pressing the 'R' gadget left of the perspective view. Pan (Shortcut: p) ----------------------------------------------------------------------- Use this command to pan the views. After selecting Pan, you must click in one of the views, and keep the button down. The object will be substituded with a bounding box, and you can now pan the view by moving the mouse. Release the button when you are satisfied with the new position. Grid (Shortcut: None) ----------------------------------------------------------------------- Select this menu entry to toggle visibility of the grid. The size of the grid is defined in the configuration menu. Grid snap (Shortcut: None) ----------------------------------------------------------------------- Select this menu entry to toggle grid snapping. When grid snapping is active, you can only place knots/points on grid points. This can make it much easier to place points correctly. Grid snapping can be active even if the grid is invisible. Resolution - Up (Shortcut: +) ----------------------------------------------------------------------- Increase the spline resolution by 1. See "Configuration - Edit" for more information about this parameter. Resolution - Down (Shortcut: -) ----------------------------------------------------------------------- Decrease the spline resolution by 1. See "Configuration - Edit" for more information about this parameter. Redraw (Shortcut: space bar) ----------------------------------------------------------------------- Redraw all views. 2.4: Windows: ------------------- This menu contain commands which display/remove windows. Knot... (Shortcut: LAmiga-K) ----------------------------------------------------------------------- Select this command to display/remove the Knot information window. This window contains information about the currently selected knot: Point: Id of the knot (-1 if no knot is selected) Pos.: Position of the knot. Tension: Tension of the knot. Bias: Bias of the knot. Continuity: Continuity of the knot. It is also possible to modify the spline parameters from this window: This can be done either by entering the new value into the number field, or by selecting the corresponding gadget (for instance "Tension"). If you select one of the gadgets, you then have to click in one of the views, and keep the left mouse button down. When you then move the mouse, the parameter will change. If you stop moving the mouse for a while, the display will be redrawn to show the splines as they look with the new value. Release the button when you're satisfied with the value. You can remove the window by selecting the "close window" gadget. Scale... (Shortcut: LAmiga-Z) ----------------------------------------------------------------------- Select this command to display/remove the Scale group window. This window should be used when you want to scale the currently selected group of points (see the group commands). The window contains the following gadgets: Scale X: Select this if you want to scale along the X axis. Scale Y: Select this if you want to scale along the Y axis. Scale Z: Select this if you want to scale along the Z axis. Scale Factor: Enter the scale factor here. It is also possible to scale the current group interactively, this is done by selecting the "Scale factor" gadget. Now you have to click in one of the views, and keep the left mouse button down. When you then move the mouse, the scale parameter will change. If you stop moving the mouse for a while, the display will be redrawn to show the splines as they look with the new value. Release the button when you're satisfied with the value. Note that it is possible to enter a negative scale factor. This is useful if you want to mirror the object. You can remove the window by selecting the "close window" gadget. Rotate... (Shortcut: LAmiga-R) ----------------------------------------------------------------------- Select this command to display/remove the Rotate group window. This window should be used when you want to rotate the currently selected group of points (see the group commands) around the origin. The window contains the following gadgets: Rotate around X: Select this if you want to rotate around the X axis. Rotate around Y: Select this if you want to rotate around the Y axis. Rotate around Z: Select this if you want to rotate around the Z axis. Angle : Enter the rotation angle (in degrees) here. It is also possible to rotate the current group interactively, this is done by selecting the "Angle" gadget. Now you have to click in one of the views, and keep the left mouse button down. When you then move the mouse, the angle will change. If you stop moving the mouse for a while, the display will be redrawn to show the splines as they look with the new value. Release the button when you're satisfied with the value. You can remove the window by selecting the "close window" gadget. Move... (Shortcut: LAmiga-M) ----------------------------------------------------------------------- Select this command to display/remove the Move group window. This window can be used when you want to movete the currently selected group of points (see the group commands). The window contains the following gadgets: X: The displacement along the X axis. Y: The displacement along the Y axis. Z: The displacement along the Z axis. Move : Select this to perform an interactive move. It is possible to move the current group interactively, this is done by selecting the "Move" gadget. Now you have to click in one of the views, and keep the left mouse button down. When you then move the mouse, the position will change. If you stop moving the mouse for a while, the display will be redrawn to show the splines as they look with the new value. Release the button when you're satisfied with the value. Note that the default mouse command is move, this mean that you don't have to use the "Move group" window to move points. Just click (and hold down) the left button in the relevant view. When you then move the mouse, you'll move the grouped points. You can remove the window by selecting the "close window" gadget. 2.5: Render: ------------------- This menu contain commands which are used in connection with the rendering of the current object. Mode - Line (Shortcut: None›0~) ----------------------------------------------------------------------- Set rendering mode to line drawing, this is the fastest of all the rendering modes: Only the outlines of the generated triangles will be rendered, and there's no hidden line removal. Mode - Flat (Shortcut: None›0~) ----------------------------------------------------------------------- Set rendering mode to flat, this is the fastest of the solid rendering modes: Only visible surfaces will be rendered and each triangle will be filled with the same color. Mode - Gouraud (Shortcut: None›0~) ----------------------------------------------------------------------- Set rendering mode to Gouraud shading: In this mode, the color of each triangle corner is computed. The color of points in the triangles are computed by interpolation of these values. This mode is faster than the Phong shading mode, but the result isn't as good as the ones you get when using Phong shading. Gouraud shading is the default mode. Mode - Phong (Shortcut: None›0~) ----------------------------------------------------------------------- Set rendering mode to Phong shading: In this mode, the surface normals are interpolated across the triangles. The color of each point is then calculated based on the normal. This mode is the slowest of all the rendering modes, but it gives the best results. Render (Shortcut: r›0~) ----------------------------------------------------------------------- Render the object in the perspective view using current direction. The camera distance will be computed, so that the object nearly fills the view. When you select this command, the following happens: 1: The current object is tesselated, ie. converted to triangles and saved in memory. The number of triangles are based on the "Patch resolution" parameter. 2: The camera position is chosen so that it corresponds to the camera perspective view, and a light source is placed behind the camera. 3: The color table for the ICoons screen are changed into a gray scale. 4: The object is rendered. 5: When the user presses the space bar, the original color table is reinstalled, and the perspective view is redrawn. Re-render (Shortcut: R›0~) ----------------------------------------------------------------------- Re-render the object in the perspective view using current direction. The camera distance will be computed, so that the object nearly fills the view. When you select this command, ICoons will redo phases 2 - 5 as specified under the "Render" command above. That is, it will reuse the tesselated object from the last Render command. Use Re-render if you already has rendered the object, and just want to see the object from another direction, or in the expanded view. In this way, you can skip the time consuming tesselation step. 2.6: Select: ------------------- This menu contain commands which are used to select/deselect points, and to create a group of points. The grouped points are be drawn in green. If you have selected more than one point, you will be in "Group mode". It's possible to modify all the points in the current group in one step by using the "Windows" menu entries. Group box (Shortcut: g›0~) ----------------------------------------------------------------------- After selecting this command, you have to click in one of the views, and keep the left mouse button down. When you then move the mouse, you'll see a "drag box" which follows the mouse. When you release the button all points inside the box will be toggle added to the current group, ie. already grouped points will be removed from the group, and non-grouped points will be added to the group. You'll enter group mode when executing this command. Group spline (Shortcut: ,›0~) ----------------------------------------------------------------------- If you select a knot by clicking on it, it is possible to toggle add all points on that spline by using this command. You'll enter group mode when executing this command. Group all (Shortcut: .›0~) ----------------------------------------------------------------------- If you select this command, you'll toggle add all points to the current group. You'll enter group mode when executing this command. Group point (Shortcut: ;›0~) ----------------------------------------------------------------------- If you select a point by clicking on it, it is possible to add it to the current group by using this command. You'll enter group mode when executing this command. Select next (Shortcut: n›0~) ----------------------------------------------------------------------- If you select a knot by clicking on it, you may not have selected the spline you want. This is possible if splines has been connected to each other at the current point. In this case, it is possible to select the next knot which is at the current position by using the "Select next" command. The knot won't automatically be added to the current group, use the "Group point" command to do this. Deselect all (Shortcut: Return›0~) ----------------------------------------------------------------------- Use this command to deselect all points. 2.7: Commands: ------------------- This menu contain commands which do the real work, such as adding/ deleting splines etc. Add (Shortcut: a›0~) ----------------------------------------------------------------------- This command is used to create a new spline, or to add a new knot to an existing spline: After selecting this command, you should press and hoold the mouse button in one of the views. If the mouse is near a knot, a new knot will be added to the corresponding spline, otherwise a new 2-knot spline will be created. You can now move the knot by moving the mouse. Release the mouse button when you're satisfied with the position of the knot. Combine (Shortcut: C›0~) ----------------------------------------------------------------------- This command is used to combine two splines into one: Place the endpoints of the two splines near each other, and be sure that one of the endpoints are selected (ie. the corresponding segment should be red). When you now select the "Combine" command the two splines will be combined into one. Cut (Shortcut: c›0~) ----------------------------------------------------------------------- This command is used to cut a spline into two splines: Select a knot on the spline you want to cut in two. When you then activate the "Cut" command, the selected knot will be deleted, and the spline will be divided into two seperate splines. This only works for a spline with at least 5 knots. Delete (Shortcut: d›0~) ----------------------------------------------------------------------- This command is used to delete a knot from a spline: Select the knot you want to delete. When you then activate the "Delete" command, the selected knot will be deleted. If the corresponding spline only had two knots before the deletion, the spline will also be deleted. Disconnect (Shortcut: D›0~) ----------------------------------------------------------------------- This command is used to disconnect two or more splines: Select the point where two or more splines has been connected. When you then activate the "Disconnect" command, all the splines which were connected at the point, will be disconnected. Hide (Shortcut: h›0~) ----------------------------------------------------------------------- This command is used to hide all the points which aren't in the current group. If you already have hidden some points, this command will redisplay all points. Move origin (Shortcut: None›0~) ----------------------------------------------------------------------- This command is used move the origin to another position. This can be neccessary to do because the "Rotate group" command rotates about the origin. After selecting this command, you have to click in one of the views to select the new position of the origin. 3. About the source code ========================= The source code is distributed under the GNU General Public License, and you may modify it as you see fit. I probably won't have time to make further changes to the program, so I'll in fact welcome anyone who'll want to enhance it by for instance adding new features to it. The program is reasonably well commented, so it shouldn't be too difficult to make changes to it. You're welcome to contact me if you have any questions about the source code or about usage of the program. My E-Mail address is: her@compel.dk Helge E. Rasmussen