Using the Part Editor
Tutorial: Experimenting with CcVertexShape
Tutorial: Creating the CoolPool Scene
Tutorial: Creating a Lunar Landscape
Overview
The Part Editor, shown in Figure 3, is used to create and edit instances of CcPart. The editor saves CcPart instances as Dolphin STB files (extension ".stb") in the ST3D Parts folder hierarchy. The part editor can be opened by selecting menu item "Tools->ST3D->Part Editor" or by clicking on the icon in the Dolphin Smalltalk System folder "ST3D".
The Perspective View
The editor’s "perspective view", on the right-hand side of the window, displays the part being edited. The perspective view includes an axis handle (red, blue and green arrows) which is used for manipulating the part(s). To use the axis handle, simply click and hold the left mouse button while the mouse pointer is over one of the handle’s arrows, then move the mouse (with the button still pressed). The resulting effect on the selected part(s) depends on the editor tool that is currently active. The perspective view also includes a light blue grid to give a rough indication of object location.
Figure 3. The ST3D Part Editor
Selecting objects
A shape or component (face, vertex, or edge) can be selected by clicking on the object with the left mouse button. The first shape selected is highlighted with green squares at each of its vertices and green lines along its edges. If multiple shapes are selected, shapes 2–n are highlighted in blue. Selected vertices and the edges of selected faces are shown in red. Selected edges are shown in yellow. The highlighting of a selected component is always visible, even if the component itself is hidden by other faces or shapes. Clicking on a component that is currently selected will deselect the component. Clicking anywhere on the perspective view’s background will clear all selections.
Moving the viewpoint
The perspective view’s viewpoint can be changed using the keyboard. The key mapping is as follows:
Up arrow – Camera forward
Down arrow – Camera back
Left arrow – Camera left
Right arrow – Camera right
CTRL+Up arrow – Rotate camera up
CTRL+Down arrow – Rotate camera down
CTRL+Left arrow – Rotate camera left
CTRL+Right arrow – Rotate camera right
This mapping is only active when the perspective view has focus. Clicking on the view or pressing "Ctrl+1" forces focus onto the view.
The perspective view has an option that allows the camera to track or "watch" the selected part or geometry component. When this option is enabled, the camera rotation commands listed above cause the camera to rotate about the watched object rather than about the camera’s own axis.
The "Scene" Page
A card container (a.k.a. a "notebook") is located on the left-hand side of the Part Editor. It contains pages labeled "Scene", "Parts", "Textures" and "Tool".
The "Scene" page (see Figure 3) displays a hierarchical representation of the nodes and components (faces and vertices) currently being edited. The hierarchical view is known as the "node browser". The node browser provides an alternate means of selecting and deselecting shapes and components via its popup menu. The position of a part within the scene graph hierarchy can be changed by dragging and dropping it on a new parent node.
The "aspect inspector" on the "Scene" page presents the published aspects of the element currently selected in the node browser. The aspects available for editing, by class, are listed below (Note: A class inherits its superclass’s published aspects, e.g., the complete list of published aspects for CcShape are color, shadeMode, lightingMode, faceCullingMode, transparency and shine).
CcScenegraphNode (Values are inherited by children)
- dolphinColor – Color of the node. Inherited by children
CcPart (Values are inherited by children)
- shadeMode – Determines whether part is shaded smooth or flat. Aspect has no effect if lighting mode is set to #unlit. Available values are #smooth and #flat.
- lightingMode – Determines whether part is lit or not. Available values are #lit or #unlit.
- faceCullingMode – Determines the visible side or sides of faces in a part. Available values are #hideBack, #hideFront, #hideBackAndFront, #showBackAndFront. Default is to show front side of face only.
- shine – Determines the shininess of a part (0 – 100).
- translucence – Determines the translucence of a part in terms of a percentage between 0 and 100. 100 is solid. 0 is completely transparent.
CcVertexShape (Values are not inherited by children)
- textureMap – Shape’s texture map (Normally, this will be set using the "Texture" page. Value can be nilled here though.)
- forceFaceNormalUse – Setting to true causes the face normals of the shape’s geometry to always be used in lighting calculations, regardless of the current lighting mode.
CcFace
- dolphinColor – Face’s color. Overrides color and shapeColor or containing shape.
- textureMap – Face’s textureMap. Overrides shape texture map (Normally, this will be set using the "Texture" page.)
CcVertex
- dolphinColor – Vertex’s color. Only effects shape appearance when shape is smoothly shaded. Overrides all other colors.
The "Parts" Page
The "Parts" page, shown in Figure 4, includes a file view presenting subfolders and files located within the ST3D "Parts" and "Geometry" folders. The currently selected part or geometry file is rendered in the "preview view" located directed directly below the file view. An axis handle in the preview view allows the item to be rotated. The selected part or geometry object can be added to the perspective view by double clicking on the file name in the file view.
Figure 4. "Parts" page of Part Editor
The "Textures" Page
The "Textures" page, shown in Figure 5, includes a file view showing the contents of the ST3D "Images" folder. The currently selected image is displayed in the view directly below the file view. The image can be applied to a shape or face by pressing the "Apply texture" or "Apply mipmap" button. Bitmaps must be 32-bit color and the bitmap size must be a power of two in each dimension (e.g., 128 by 256).
Figure 5. "Textures" page of Part Editor
ST3D supports .BMP, .TGA, .JPG and .GIF file formats.
Bitmap files (.BMP extension) can be converted into texture files (.TXR extension) for situations where texture translucence is required (See Figure 6) (The TGA format also supports transparency). In the conversion process, an additional byte of data is added to each pixel in the image to hold an alpha value. The alpha value determines the translucence of the pixel. A value of zero causes the pixel to be completely transparent and a value of 255 makes the pixel opaque.
The conversion process consists of two steps:
- Convert the .BMP file to a .TXR file. Select the .BMP file to be
converted in the file view of the Textures page. Invoke menu item "Convert
BMP->TXT" from the file view’s popup menu. Specify location and file name for
the .TXR file that is to be created. By default, all pixels in the resulting .TXR file
will have an alpha byte of 255 (opaque).
- Modify the alpha value for all pixels of a certain color in the .TXR file. For example, the alpha values for all of the white pixels in the bitmap shown on the left-hand side of Figure 6 were converted from the default value, 255, to 0 so that those pixels would be completely transparent when applied to an object (e.g., the right-hand image in Figure 6 shows such a texture applied to a single polygon positioned directly in front of the camera). The alpha value for a given color in a texture can be changed by selecting the .TXR file in the file view and invoking the "Set alpha component" menu item from the file view’s popup menu. Select the pixel color for which the alpha value is to be set from the resulting color dialog. Then specify the translucence percentage to be applied to the pixels of the chosen color. A value of 0 makes the pixel transparent and a value of 100 makes it opaque.
Figure 6. Bitmap (left) converted to translucent texture (right)
The "Tool" Page
The "Tool" page allows parameters to be specified for the currently active tool (See Figure 7). For example, the "Part Translation" tool allows "free form" control of the translation using the perspective view’s axis handle. However, if more exact positioning is required, coordinates can be entered on the "Tools" page. Figure 7 shows the parameters available for the "Rotate Part" tool. This tool allows an exact orientation to be specified or a rotation, in degrees, about a specific axis.
The tool executes the specified operation when the "Apply" button is pressed.
Figure 7. The "Tool" Page (Rotate Part tool currently active)
Part Editor Tools
The Part Editor provides a number of tools for editing a part. The tools are accessed by invoking the popup menu in the perspective view. Descriptions of Part Editor tools are provided below.
- Drag part - Allows a part to be moved in the xy plane via
drag/drop. It is not necessary for the part to be selected in order to move it. If the
part is selected, however, the tool parameter view allows exact coordinates to be
specified.
- Translate part (world) – Allows selected part(s) to be
moved along the world x, y or z-axis using the axis handle. The tool parameter view allows
exact coordinates to be specified.
- Translate part (local) - Allows selected part(s) to be moved
along the local x, y or z-axis of part’s parent using the axis handle. The tool
parameter view allows exact coordinates to be specified.
- Rotate part (world) - Allows selected part to be rotated about
the world x, y or z-axis using the axis handle. The tool parameter view allows 1) the
exact orientation to be specified or 2) a rotation in degrees about x, y or z-axis to be
specified.
- Rotate part (local) – Same as "Rotate part
(world)" but rotation is performed about part’s local axis.
- Resize shape – Resizes selected shape using axis handle.
The tool parameter view allows the exact size to be specified. Resizing a shape does not
affect the size it’s children.
- Scale part – Uniformly scales selected part(s) using axis
handle tool. Children inherit the parent’s scale.
- Set shape origin - Sets the shape’s origin to the
location of the currently selected shape component (vertex, face, or edge). When a shape
is selected, its origin is indicated by small yellow square. All transformations (e.g.,
size, rotation, translation) are performed with respect to the origin.
- Set group origin - Same as "Set shape origin" but
applies to a part or "group".
- Align components – Aligns first shape selected with
second shape selected. Alignment is done with respect to first selected component in each
shape. Second shape’s position is not changed.
- Separate components… – Similar to "Align
components" but the first component is separated from the second component by a
specified distance (a number) along the second component’s normal vector.
- Group – Add a new CcPart node to the hierarchy with the currently selected nodes as its children. A group cannot be selected by clicking on it within the perspective view. The group must first be selected within the node browser’s tree view and then "Select" must be invoked from the browser’s popup menu. Selected groups are shown using a white wireframe bounding box. (Note: "Ungrouping" can be done within the node browser by dragging the group’s child nodes out from beneath the grouping part and then deleting the grouping part).
"Texture tools" submenu
- Translate face texture – Translates position of
face’s texture. Click on desired face and drag.
- Rotate face texture - Rotates face’s texture. Click on
desired face and drag. "Up" rotates texture clockwise. "Down" rotates
it counter-clockwise.
- Scale face texture (uniform) – Scales face texture
uniformly. Click on desired face and drag. "Up" magnifies texture.
"Down" reduces it.
- Scale face texture (non-uniform) – Scales face texture
non-uniformly. Horizontal and vertical scaling is proportional to mouse movement in
horizontal and vertical directions.
- Translate planar map – Translates texture map when planar
texture map has been applied to shape. Translation is performed in plane defined by axis
of projection (indicated by axis handle).
- Rotate planar map – Rotates texture map when planar
texture map has been applied to shape. Rotation is about axis of projection (indicated by
axis handle).
- Scale planar map (uniform) - Scales planar map using axis
handle.
- Rotate spherical map – Rotates texture when spherical map
has been applied to shape. Uses axis handle.
- Sync textures – Synchronizes a shape’s texture and map with the texture and map of a face. A planar texture map is applied to the "target" shape (first shape selected).
Other options
- Clear selections – Clears all selections.
- Watch selected – Causes camera (viewpoint) track the
selected part or component, regardless of camera’s movement or the watched
object’s movement.
- Stop watching – Disables "watch" mode.
- Inspect selected – Inspect the selected node.
"Edit" submenu
- Undo <operation description> – Undoes previous
operation.
- Redo <operation description> – Redoes previously
undone operation.
- Cut – Cuts currently selected object to ST3D clipboard.
- Copy – Copies currently selected object to ST3D
clipboard.
- Paste – Pastes contents of ST3D clipboard into the
perspective editor.
- Set color – Prompts for the color to apply to the currently selected faces and vertices or the currently selected part (if no components are selected). Colors can also be set component by component and part by part using the aspect inspector on the "Scene" page. "Set color", however, allows the colors of multiple components to be set at the same time.
Menubar Items
File
- New – Create a new part.
- Open… - Open an existing part file (extension .stb)
located in the ST3D Part folder hierarchy.
- Save – Save the part currently being edited.
- Save As… - Save the part currently being edited as a new part file. The part should always be saved within the ST3D Part folder.
Settings->Light
- Camera mounted – Editor’s light source moves with
camera.
- Fix at current camera position – Fixes light source at
its current position/orientation.
- Specify orientation… - Allows the orientation of the light source to be specified.
Settings
- User interface sensitivity… - Determines the sensitivity of keyboard and mouse operations performed in the perspective view. A higher number gives "faster" movement but less precise control. Default is 1.
Misc.
- Set focus on perspective view – Forces focus onto the perspective view. Accelerator for this option is "Ctrl+1". This item makes it possible to give focus to the perspective view without having to click on it.
Tutorial – Experiments with CcVertexShape
This tutorial provides some additional insight into the makeup and behavior of CcPart and CcShape subinstances.
- Open the Part Editor (Menu item "Tools->ST3D->Part
Editor").
- On the "Parts" page, select the folder
"Geometry->CC 3D Shapes". Then double click on file "cube.geo". A
cube should appear in the perspective view. The cube is selected (green outline) and a
small yellow point is shown at its origin. The node browser on the "Scene" page
shows a CcVertexShape (the box) beneath the editor’s root part. The cube’s faces
and vertices can be examined by expanding the CcVertexShape entry in the node browser. The
"Scene" page’s aspect inspector shows the published aspects for the cube.
- Invoke the perspective view’s popup menu (right mouse click) and
select the "Rotate part (local) tool. Select the "Tool" page. Press and
hold the left mouse button on the z-axis (blue arrow) of the axis handle. The cube rotates
about its z-axis. The "Tool" page shows the current orientation of the cube as
it is rotated.
- Select the "Resize shape" tool. Use the axis handle (again,
press, hold and drag on one of the axis) to change the size of the cube in various
directions. The "Tool" page is updated to show the current size of the cube.
- Enter an exact size on the "Tool" page (e.g., 3 @ 3 @ 1)
and press the "Apply" button. The cube dimensions are changed.
- Press the "Undo" button. The shape should revert to its
previous size. Press the "Undo" button repeatedly until the cube is back to it
original orientation and size.
- Press the "Redo" button repeatedly to "replay"
the changes that were just undone.
- Select one of the cube’s vertices by clicking on it. The vertex
should be red when selected. Now select "Set shape origin" from the popup menu.
The yellow dot should move to the selected vertex. Manipulate the cube using the
"rotate (local)" and "resize" tools. Note that changes to the
cube’s size and orientation are performed with respect to the new cube origin.
- Select the "Drag" tool. Press, hold and drag the mouse on
the cube and move it to a new location, away from the origin.
- Add an eight-sided column to the scene by double clicking on file
"column8.geo" on the "Parts" page. The column appears at the origin in
the perspective view and is shown beneath the cube on the "Scene" page.
- Give the cube a symbolic name by clicking on its entry on the
"Scene" page and selecting the "name" aspect in the aspect inspector.
In the aspect inspector’s workspace, enter "#cube" and press CTRL+S to save
the change. Repeat for the column, giving it the name #column.
- On the "Scene" page, drag the entry for column and drop it
onto the cube. The column shape is now a child of the cube shape.
- Deselect both objects by clicking on the background of the
perspective view. Select the box. Select the rotate tool. Rotate the cube using the axis
handle. The cube rotates about its axis and the cube’s child, the column, rotates
about the cube. Try dragging the cube with the drag tool. The column follows the cube.
- Resize the cube. The size of the column is not affected. Choose the
"scale part" tool and scale the cube with the axis handle. Both the cube and
column are affected. Note also that "part scaling" is always uniform whereas a
"shape resizing" can be done independently along each axis.
- With the cube selected on the "Scene" page, double click on
aspect "dolphinColor" and choose a color in the resulting color dialog. The
color is applied to the cube and inherited by its child. Reset the color of the cube by
and selecting "Set to nil" from the aspect inspector’s popup menu (with
aspect "dolphinColor" still selected).
- With the cube selected, select "copy" from the perspective
view’s popup menu (under the "Edit" submenu). The select "paste".
A copy of the cube and the column are added to the scene. Use the drag tool to move the
shapes independently.
- Select both cubes and choose "Cut" from the perspective
view’s popup menu. Now add two new cubes ("cube.geo"). Move the cubes apart
using the drag tool. Select both cubes and invoke the "group" menu item. The
cubes are now children of the same parent node. The parent part is shown with a white
bounding box. Drag the individual cubes to see the bounding box of the parent changes.
- Invoke "File->New". Add an instance of
"Cone15.geo" from "Geometry->CC Geometry". Click on the
"Textures" tab in the card container. Select any texture in the file view and
click the "Apply texture" button. Select "CcPlanarTextureMap z-axis"
in the resulting dialog. The texture is projected onto the cone along its z-axis.
- Select the "Rotate planar map" tool. Click and drag on the blue arrow to rotate the texture map about its projection axis. Experiment with the "Scale planar map" and "Translate planar map" tools as well.
Tutorial – Creating the CoolPool Scene
- Open the part editor. Select subfolder Geometry ->"CC 3D
Shapes" on the "Parts" page. Add "cube_inverted" to the scene by
double clicking on the file.
- Select the bottom face of the inverted box by clicking on it. Set the
box’s origin to be at the center of the selected face by choosing "Set shape
origin" from the perspective view’s popup menu.
- Resize the shape using the resize tool and the "Tools"
page. Set the size to be 25 @ 42 @ 13.
- Pull back from the room by first pressing "Ctrl+1" to
ensure the perspective view has focus and then holding down the "down arrow" key
to move back. Keep moving back until the entire box is visible (Note: You may wish to
change the user interface sensitivity to a higher number like 3 to allow camera movement
to occur more rapidly).
- Change the selected folder on the "Parts" page to
Geometry->CoolPool and add the geometry file "tableAndLegs.geo" to the scene.
- Change the orientation of the table by selecting the rotate local
tool. On the "Tool" page, select "z" in the "rotate about"
dropdown list and enter "90" in the "By degrees" entry field. Press
the "Apply" button.
- Select the "Translate (world)" tool and move the table
"up" along the z-axis (blue arrow) until the legs of the table are visible.
Deselect the table ("Clear selections" on the popup menu) and select the room
and then the floor of the room. Note the z coordinate of the rooms floor as shown in the
tool parameter view (-0.50).
- Deselect the room and select the table again. Now select any vertex
at the bottom of the table’s legs. The location of the selected vertex is shown in
the tool parameter view. Change the z coordinate (only) of the vertex to be –0.5 and
press "Apply". The bottom of the table’s legs is now flush with the floor
of the room.
- Select the "shadeMode" aspect in the aspect inspector on
the "Scene" page (table should be selected in the node browser). Choose #smooth
from the list box. The table now appears smoothly shaded. Do the same with the room
object.
- Select the table and change it’s color aspect to some shade of
brown. Select the face that is the surface of the table. Change the face’s color to a
shade of green or blue.
- Deselect the table, select the room, and then select the floor.
Select the "Textures" page. Select subfolder Images->Pool and file
"parkay.bmp". Press the "Apply mipmap" button to apply the texture to
the floor.
- The contents of the perspective view’s popup menu changes when
the "Textures" page is active. Bring up the popup menu and select "Scale
face texture (uniform). Now click on the floor of the room and drag the mouse down to
cause the texture image to repeat itself across the floor’s surface.
- Deselect the floor by clicking on it and select one of the
room’s walls. Choose the "wall1.bmp" file and press "Apply
mipmap". Choose the "Scale texture (non-uniform)" tool and increase the
textures vertical scale by clicking on the wall and dragging the mouse upward. The texture
can be translated by selecting the "Translate face texture" tool and dragging
the texture with the mouse.
- Repeat the previous step for the room’s other walls with different bitmaps.
Tutorial – Creating a Lunar Landscape
This tutorial shows how to construct a lunar landscape similar to the one used in the "Lander" demo application. The finished landscape will look similar to the screenshot in Figure 8.
- Open the Part Editor.
- Select "User interface sensitivity" from the
"Settings" pulldown menu. Set the sensitivity to 5.
- Select "Specify orientation" from the
"Settings->Light" pulldown menu. Enter "0 @ 0 @ -1 up: 0 @ 1 @ 0"
(without the quotes) in the resulting dialog. This causes the scenes lighting to be
directed straight down rather than being attached to the camera.
- Add "largeDisk.geo", located in the "Geometry->CC
3D Shapes" folder, to the preview view. Set it’s shadeMode to #smooth.
- Move viewpoint away from the disk ("down arrow" key) until
some portion of the disk’s edge is visible.
- Add several instances of range?.geo and mound?.geo (? will be some
number), located in "Geometry->Lander" to the view. Scale each shape to
occupy a reasonable portion of the disk surface (e.g., mound diameter might be 1/8 the
diameter of the large disk). The "resize shape" tool can also be used to distort
the shapes. Set each shape’s shadeMode to #smooth. Distribute the shapes across the
surface of the disk using the "drag part" tool.
- Select the "Textures" page in the editor’s card
container and change the current folder to "Images->Planets->Moon". Click
once on the large disk to select it (green outline is displayed) and click on it a second
time to select its only face (red outline is displayed). Select file
"moonlow2.bmp" in the bitmap chooser and press the "Apply mipmap"
button.
- Select tool "Scale face texture (uniform)". Click and hold
on the large disk and drag the mouse downward to cause the texture to be tiled across the
disk.
- Clear all selections. Select the large disk and then select the large
disk’s face (should show a red outline). Select all of the shapes resting on the
surface of the disk. Now choose "Sync textures" from the popup menu. A texture
and texture map is applied to the selected shapes that is aligned with the texture map of
the underlying disk.
- Enable the display lists for all shapes using the aspect inspector on
the "Scene" page (aspect #isDisplayListEnabled).
- Select one of the mountains and select "Watch selected"
from the popup menu. Clear all selections. The keyboard (up, down, left and right arrows)
can now be used to "fly" around the scene.
Figure 8. Finished lunar landscape