Satimage Previous | Next
The view3D
Home Documentation SmileLab Scripting Graphic objects Graphic view View3D  
Table of contents
The view3D class is the class for 3D representation. The view3D can contain: SmileLab uses an orthographic parallel viewing (i.e. a viewing with no vanishing point) and a realistic surface rendering.

A common way to draw view3Ds is to use QuickPlotLib:

Making graphs with QuickPlotLib

How view3Ds render space
The view3D displays a piece of the user's 3D space, a parallelepiped parallel to the axes {xmin, xmax, ymin, ymax, zmin, zmax}, the limits property (use current limits if some limit is set to auto).
The view3D maps this domain into a unit cube in the OpenGL space whose coordinates are {-0.5, 0.5, -0.5, 0.5, -0.5, 0.5}.
eye position
The observer is located and oriented according to eye position, a list {x, y, z, ux, uy, uz} where the three first terms are the observer's position\footnote{Note that those coordinates are not relative to the surfaces. They are relative to the OpenGL space.} and the three last terms define what the vertical plane in the figure will be. When you assign a new value to eye position you may provide only the three first terms {x, y, z}. The observer always points towards the center of the unit cube.
Like a camera, the observer views only a sub-domain in the OpenGL space. In his own coordinates system, the observer views a parallelepiped (the projection is parallel) whose coordinates are the projection property. By default projection is set to {-1, 1, -1, 1, 1, 100} where the last pair {1, 100}, the "near" and "far" parameters, are in the direction of the axis of view. The objects in the parallelepiped get projected onto the {-1, 1, -1, 1} square, which in turn gets mapped onto the plot frame of the view 3D.
light position
A source located at light position lightens the scene. light position is a list of four numbers {x, y, z, u}, its coordinates in the projective space\footnote{like eye position, those coordinates are not relative to the surfaces. They are relative to the OpenGL space.}: x, y, z provide the direction of the source, u is the inverse of the distance to the origin of the unit cube (in OpenGL units).
OpenGL defines the x and y directions in the plane of projection and z normal to that plane (towards the observer). SmileLab performs the proper rotation of the objects -- just after mapping them into the unit cube -- so that they look the usual way -- the z direction upwards. The rotation is the rotation property, a list of four numbers { a, vx, vy, vz} where a is the angle of the rotation in degrees and vx, vy, vz is the axis of the rotation. By default rotation is set to {-120.0, 1.0, 1.0, 1.0}. With those values, the definitions of eye position and light position must be considered as {y,z,x} lists relatively to the surface coordinates (because eye position and light position are defined in the OpenGL space coordinates and not in the user's 3D space coordinates).
Using the 3D rendering options
eye position
To change the point of view provide a new value {x, y, z} as the eye position property. Optionally you can provide the orientation: provide the six items {x, y, z, ux, uy, uz}.
The camera sees only objects that are far enough (more than 1.0 unit of length far along the axis of view with the current settings). The center of the unit cube (the absolute OpenGL origin) should be 1.0 unit of length inside the parallelepiped of view. Thus the observer should be (with these settings) at least at 2.0 units of length from the center of the cube. If you set the eye position closer, for instance {1.0, 1.0, 0.0}, the objects may get truncated -- maybe when you rotate the view3D with ⌘-drag: rotating the view3D with the mouse preserves the distance of view.
You may want to change the size of the window of the projection (the four first terms in the list): in some extreme cases the scales or the labels may exit the default parallelepiped, or you may want to draw the objects only, not the axes, and trim margins by focusing the projection window on the objects. For particular purposes, you can even set the projection window to an unsquare shape, provided you rescale the plot frame accordingly.

By changing the window, or the "near" and "far" parameters of projection (the 5th and 6th items in the list), you can achieve special effects such as presenting a cross section of a surface or viewing the interior of a closed surface.

light position
Changing the light position allows for various effects. When the light gets closer (you provide a list with a large value as its 4th item) realistic light source reflection effects can be obtained.
You can set the limits of the user's parallelepiped by supplying a list of 6 items as the limits property. Each item may be either a real number or the string "auto". By default limits is set to {"auto", "auto", "auto", "auto", "auto", "auto"}. You retrieve the current values of the limits with the current limits property.
Graphic options for the view3D
The view3D draws the edges of the cube, the scales and the labels or not according to the boolean value of the drawaxes property (default value: true).
xlabel, ylabel
To display labels for the axes provide strings as the xlabel and/or ylabel properties. Those strings support a set of coded symbols which allow to write mathematical expressions. A table of these symbols (example: \infty is the code for ∞) is given in Drawing texts with the graphic engine.
xlabel offset
To adjust the vertical location of the labels with respect to their axes provide a different value in pixels for the xlabel offset property (40 pixels by default). Both x- and y-labels share the same vertical offset.
The view3D is not a vectorial graphic. Before you save it as a document intended for printing you may want to up its resolution. By default the resolution property (in dots per inch) is set to 72, which is the proper resolution for screen display. If you require a high quality document, up the resolution property e.g. to 300 before saving the window as a pdf.
back pdf, front pdf
back pdf and front pdf are the properties that allow to display (in addition to the plot), either in the background or over the plot, a graphic from a PDF document or a scripted graphic. The instructions are the same as given for the picture views.
convert coordinates
to convert a (x,y,z) triplet given in user's units (the units of the axes) into the coordinates in pixels of the corresponding point use convert coordinates p in v where p is the triplet and v is a reference to the view3D. The coordinates that convert coordinates returns are relative to the view3D's frame's origin.
The Contextual menu
You can pull down the contextual menu of the view3D by ctrl-click in it.
In this menu, you can choose to enable or disable the track mouse (i.e. rotating the view with the mouse with click and drop instead of ⌘-click and drop). You can also choose to display all objects wired when rotating, for speed conveniences. You can also open the Information window from this menu.

The Settings window is a dialog window which lets you edit the main properties of the view3D and the properties of their 3D objects.

Copyright ©2008 Paris, Satimage