opale.soya Editor 0.1

Featuring a bean editor and a GUI editor !!!

Hand Book

Last update : 9/7/2000
Document written by : Artiste on the Web (A11W)
I'm not a native english speaker, so please excuse any language mistake ! If you have corrections, just mail me !

1. Running the editor

To run the editor, just run the class opale.soya.editor.Editor :     java [-classpath yourClasspath] opale.soya.editor.Editor
The classes that correspond to the editor app are located in opale.soya.editor for generic classes, and in the same package that the class they edit for the other.

2. Configuration

Just after running it, you will see the editor main window. This is also the configuration window.

In the window, you should see three text fields, they correspond to 3 pathes that soya uses for storing objets files : one for materials (including texture), one for shapes and one for animations. The best thing to do is to create 3 sub-directories in your home directory, called for example materials, shapes and animations, and to enter these pathes in the corresponding text fields.
When saving or loading a world file, soya may uses these pathes to search the corresponding ressources (materials, shapes and animations). Such a ressource is called a "stored in path object" (interface opale.soya.util.StoredInPathObject); and it can be saved either in the world file (avantage : you have only one file with all), or in its path (avantage : you can share the object between many files). If you want to save a "stored in path object" into its path, you have to give it a name (property name from interface opale.soya.util.NamedObject).
My advice is to use those pathes!

That's all for configuration!

3. The editor menus

The editor main window provides 2 usefull menus : new and open.
The new menu allows you to create new soya object : material, shape, world, environment (a world with a few additionnal properties). Animations cannot be created without a world; we will see later how to create a new one.
The open menu allows you to open soya object : material, shape (opened from their pathes), or any file. With the open file menu, you can open any serialized object (soya always uses serialization for saving objects), including materials, shapes, worlds, environments, or even non-soya object! This is possible because we use a bean editor.

4. Editors

Opale.soya editor provides 2 different editors : a bean editor and a GUI editor.
The bean editor is used for all objects. It is called after any edition. The soya bean editor edits all non-hidden properties, including write only properties; when closing the bean editor window, it will ask for saving if the object is saveable (=if it has a save() or save(String) method).
The GUI editor is specially designed to edit specific objects : shapes and worlds (including environment). It is not avalaible for other object.

5. Editing materials...

Materials are edited in the bean editor.

A material describes all the surface properties, including color and texture.
At the top of the window, you can see a 3D view of the material, set over a cube. You can click the view to rotate the cube.
Below, the bean editor lists the properties of the material :
- name the name of the material. Set it to "null" or to "" if you don't want to save this material in the material path; else enter the name of the material. 2 material cannot have the same name!
- diffuse color (red, blue, green and alpha) the diffuse color of the material. This is the "principal" color. Each color component ranges from 0 to 1, but you can set them out of this range.
- specular color (red, blue, green and alpha) the specular color of the material. This is the color of the brightness.
- shininess the shininess of the material. This ranges from 0 (metallic) to 1 (plastic). The fewer it is, the more the specular color takes importance.
- wireframed Set this to true for wireframed drawing.
- overlayed Set this to true if you want objects that have this material to be drawn at the top, even if they are behind other objects. Warning : this can leads to visual artifacts.
- texture The texture object of this material. You can choose "(null)" for no texture, "opale.soya.soya2d.TextureRGB" for an RGB texture (no transparency) "opale.soya.soya2d.TextureRGBM" for an RGB texture with a mask ("all or nothing" transparency), or "opale.soya.soya2d.TextureRGBA" for an RGBA texture with an alpha channel (transparency).

6. Editing shapes in the bean editor...

Shapes are edited first in the bean editor.

A shape describes a geometric shape, build with many fragments, like triangles or quad.
At the top of the window, you can see a 3D view of the shape.
Below, the bean editor lists the properties of the shape :
- name the name of the shape. Set it to "null" or to "" if you don't want to save this shape in the shape path; else enter the name of the shape. 2 shapes cannot have the same name!
- width, height, depth The dimension of the shape.
- x, y and z factors The scale factor of the shape. Scale factors are not supported for shape; set them will rightly scale the shape, but the scale factors remains to 1.
- material Write only. Sets the material for all fragments in the shape. Select the name of the desired material, or choose "(null)" for the default white one, or choose "(other)" to create a new one with no name (in this case it will be saved with the shape).
- smoothLit Write only. Sets the smoothLit for all fragments in the shape. If true, the shape will be lit as if it was smooth (even if it is not) : with 1 normal for each point (instead of one for each face).
- visibility Write only. Sets the visibility for all fragments in the shape. Default is all face visible; you can choose to hide one side of the face (it can speed up the rendering). If you choose "exterior visible", soya will draws only the exterior side of the faces, "interior visible" is just the contrary; these 2 options required your shape to be closed. You can also choose "non-closed"; in this case only 1 side is drawn; it depend of the order of the points of the faces.

7. Editing shapes in the GUI editor...

Shapes have a special GUI editor. You can call it from the bean editor, with a click on the "soya GUI editor..." button.

The GUI editor shows a big 3D view, at the center of it you can see the origin and the 3 axis. You have also a menu bar at the top.
Move the mouse on the 3D view : you should see a green cube that follow the mouse cursor. This is the 3D cursor; you can move it with the mouse (left, right, up, down) and the page up (forward) and page down (backward) key (before typing keys, you may need to click on the 3D view, in order to focus it). In the GUI editor, the green is always the color of the selection.
You can rotate the camera by dragging the mouse, with the right button pressed. The view menu have several usefull predefined views.
If you have created a new shape, there is nothing else.
Open the "face" menu, and then the "class of face submenu". this submenu allows you to choose the type of face you will draw. Basic face are triangles (opale.soya.soya3d.model.Triangle) and quads (opale.soya.soya3d.model.Quad); there are also many shapes elements (different from faces), like Label3D and Sphere3D.
Choose triangles, and then select the menu "new face" in the "face" menu. Then click 3 times on the 3D view, where you want to locate the 3 points of your triangle. You should see something like this :

The 3 points of the triangle are materialized by 3 red cubes; such cubes are called "handles". If you move the cursor on one of them, it will turn green; you can select this handle by left-clicking the mouse. You can move the handle by dragging it (let the left mouse button pressed and move the mouse), and using the page up and page down keys.
To select a handle, you need to move the cursor at its exact position, including in Z; if you think this is too constrainent, you can use the middle mouse button to select all handles above or under (in Z) the cursor.
The shape GUI editor has several modes; you can switch to another with the selection menu. The first and default mode is the point selection mode. Now, switch to the face selection mode!
The red handles disappear, and a blue handle appears at the center of the triangle :

The blue handle is a face handle; you can select it and move it as for the red point handles. When you move it, the triangle moves.
The selection menu allows also to delete the selected face, or to edit the selected face. Edit yout triangle! It will be edited in the bean editor :

With this windows, you can move all the points of the face, or change its properties :
- material Sets the material for this face. Select the name of the desired material, or choose "(null)" for the default white one, or choose "(other)" to create a new one with no name (in this case it will be saved with the shape). Click on the "edit" button to edit the material in the bean editor.
- smoothLit Sets the smoothLit for this face. If true, the face will be lit as if it was smooth (even if it is not) : with 1 normal for each point (instead of one for each face). (You cannot see the difference if your face doesn't share at least a point with another).
- visibility Sets the visibility for this face. Default is all face visible; you can choose to hide one side of your face (it can speed up the rendering). If you choose "exterior visible", soya will draws only the exterior side of the face, "interior visible" is just the contrary; these 2 options required your shape to be closed. You can also choose "non-closed"; in this case only 1 side is drawn; it depend of the order of the points of the face.
You can also select and edit a point :

The bean editor displays its properties :
- x, y, z The position.
- texture coordinate x, y The texture coordinates (usefull only if the face of this point has a textured material).
- useColor This boolean property is true if the point has a valid color.
- red, blue, green, alpha The 4 color component of this point. The color is applied only if useColor is true.

At this time, you should try to draw a more complex shape, like a pyramid or a cube. For that, a few hint :
- When creating a new face, click on a point handle to add this point.
- Press the control key to activate the magnetic grid.
- Press the shift key to select more than one handle at a time.
- You can enter more easily the texture coordinates by selecting the point and choose the menu "point", and then "texture coordinates".
- The edit menu allows to change the magnetic grid step, to light off the cursor, to hide or show the cursor coordinates, and to set the camera in orthometric (ortho) mode.
- Nearly all the menu command have a shortcut; those shortcuts can also be used without holding the control key (type "e" to edit the selected object, "n" for a new face, ...). Type F3 for a new triangle, and F4 for a new quad.
- You can select a face and then enter in the "point in face selection" mode (in the selection menu) to show only the point handles for a face. This can be usefull if you want different texture coordinates for points shared between several faces.
- You can use the "hide handles" mode to make a screen shot!
- You can save the shape with the "file" "save" menu. The "optimize and save" do the same after omptimizing the shape (optimization isn't implemented in opale.soya 0.1).

8. Editing worlds in the bean editor...

Worlds are edited first in the bean editor.

The upper part of the bean editor is a hierarchical view of the world.
Right clicking on an element displays a context menu. You can choose whitch element is edited in the lower part (=the list of properties) by clicking the "edit" menu; it's equivalent to middle-click the element. You can choose "edit in new window" in order to edit in another window.
The "reset position" and "reset orientation" menu moves the element to (0, 0, 0) and resets its orientation to default; they are usefull when used with the GUI editor.
The "choose target" menu edits the element's target, in order to make a "look at".
The "dump" and "dump matrix" menu prints info at the console.
The "remove" menu removes and deletes the selected element. The 2 last menus are avalaible only for world (including its sub-class). The "add" menu contains several sub-menu will the different elements you can add. Choose "other" and type the element full class name in order to add your own element.
The "convert to shape" menu converts the selected world into a fragmented shape, and edit this shape in the bean editor. If you want to save it, give it a name, close the bean editor window and say "yes" when asking for saving. This is a good way to create complex shapes, and the only way to create static-lit shapes. The bean editor lists the properties of the edited element, those properties depends of the element class and there are too numerous to list all of them, but the main are :
- name The name of the element (all element). The name is not used for save.
- x, y and z The position of the element (graphical element only).
- target x, y and z The position of the target of this element (graphical element only). The target is used for "look at" orientation.
- width, height, depth The dimension of the element (volume and world only).
- x, y and z factors The scale factor of the element (volume and world only).
- shape The shape of the element (volume and world only). The list displays all the shapes avalaible in the shape path; you can set it to a new shape by choosing "other". You can edit the shape by clicking on the "edit" button.
- visible The visibility of the element (graphical element only). Set it to false to hide the element.
- ...

9. Editing worlds in the GUI editor...

Worlds have a special GUI editor. You can call it from the bean editor, with a click on the "soya GUI editor..." button.

The world GUI editor is very similar to the shape one. The cursor moves identicaly.
This GUI editor is designed to be used in parallel to the bean editor.
The world GUI editor uses blue handles for position, and yellow handles for orientation. Dimensions cannot be changed through the GUI editor, you must use the bean editor.
To move an element, just move its blue handle. To orientate it, move its yellow handle; the element will look at it. The look at rotates only around X and Y axis; you can rotate an element around its Z axis by pressing the insert and home keys, while one of the element's handles is selected.
When you add an element (in the bean editor), the GUI editor will locate it at the cursor position; click the left mouse button to put it.
When you select an element in the hierarchical view of the bean editor, its handles are selected, and when you select a handle, the corresponding element is selected in the tree. This can be usefull to find an element.

10. Editing animations...

A 3D scene or character rarely uses only one animation, this is why opale.soya defines a collection, called Animations, to store many of them.
Animations cannot be edited directly; you must edit them with a world (=the world to animate).
First edit this world in the bean editor, and in the GUI editor. Then, in the bean editor, set the animations property of the world to the animations collection you want to edit. The bean editor lists the animations avalaible in the animations path; you can choose "(other)" to create a new one.
Now, in the GUI editor, click the animations edit menu. A special bean editor window appear for the animations.

This window allows you to define the properties of the animations collection, in particular its name (this name is used for saving, as for materials or shapes), and a list of all the animation in the collection (empty for new animations). Below, a few buttons allow you to create a new animation, or to edit or delete the selected animation.

Animation are also edited in the bean editor. To create an animation, you need to enter a few "key positions", called states. Opale.Soya is able to interpole between those states.
The bean editor shows a lists of all the state in the animation (empty for new one), a few button and a list of properties.

To add a new state, position each element as you want in the world GUI editor, choose at which time you want to add this state (enter the time value in the correspondant textfield), and click the "add current state" button.
You can remove the selected state in the list with the "delete state" button. Double-click on a state to set it in the world GUI editor.
If you have added more than one state, you can use the scrollbar to define the animation time and see the elements moving smoothly, or click the "play" checkbox to play the animation.
The properties in the bean editor include the following :
- name The name of the animation. Here, the name is not used for saving (animations are saved with the animations collection in whitch they are added), but it can be usefull to find the desired animation.
- cyclic lap This property allows to create cyclic animation. For non-cyclic one, set it to 0. For cyclic animation, it must be the time lap between the last state and the first.

This is all at this time ! Thank you for a so long reading, and good 3D designing !

Artiste on the Web (A11W)