Canvas3D : User Manual
Canvas3D - Create and manipulate Canvas3D widgets
canvas3d pathname ?options?
-height value
Specifies a desired window height that the canvas3d widget should request from its geometry manager. The value may be specified in any of the forms described in the COORDINATE SYSTEM section below.
-width value
Specifies a desired window width that the canvas3d widget should request from its geometry manager. The value may be specified in any of the forms described in the COORDINATE SYSTEM section below.
The canvas3d command creates a new window (given by the pathName argument) and makes it into a Canvas3D widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the canvas3d such as its height. The canvas3d command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.
Canvas3D widgets implement structured three-dimenional graphics. A canvas3d displays any number of items, which may be things like spheres, surfaces, lights, and meshes. Some of the canvas3d items such as the cones are displayable, i.e. they can be seen on the canvas3d widget area. While the rest of the items such as surface, matrix, etc. are non-displayable and they are created to be used as options for the displayable items. Items may be manipulated (e.g. moved or
re-colored) and commands may be associated with items in much the same way that the bind command allows commands to be bound to widgets. For example, a particular command may be ssociated with the event so that the command is invoked whenever button 1 is pressed with the mouse cursor over an item. This means that items in a canvas3d can have behaviors defined by the Tcl scripts bound to them.
Note 1 : The conventions used in this manual are similar to that in the
Tcl7.5/Tk4.1 Manual
Note 2 : A couple of options mentioned in the manual are not yet operational. In most such cases, an appropriate error message would be provided.
The items in a canvas3d are ordered for purposes of rendering, with the first item in the display list being rendered first, followed by the next item in the list, and so on. This is in no way means that the items later in the render list obscure the earlier ones. When a new item is created it is placed at the end of the display list. The current version of Canvas3d does not allow to change the order of the items in the list.
Items in a canvas3d widget may be named in either of two ways: by id or by tag. Each item has a unique identifying number which is assigned to that item when it is created. The id of an item never changes and id numbers are never re-used within the lifetime of a canvas3d widget.
Each item may also have any number of tags associated with it. A tag is just a string of characters, and it may take any form except that of an integer. For example, ``x123'' is OK but ``123'' isn't. The same tag may be associated with many different items. This is commonly done to group items in various interesting ways; for example, all selected items might be given the tag ``selected''.
The tag all is implicitly associated with every item in the canvas3d; it may be used to invoke operations on all the items in the canvas3d.
The tag current is managed automatically by Tk; it applies to the current item, which is the topmost item whose drawn area covers the position of the mouse cursor. If the mouse is not in the canvas3d widget or is not over an item, then no item has the current tag.
When specifying items in canvas3d widget commands, if the specifier is an integer then it is assumed to refer to the single item with that id. If the specifier is not an integer, then it is assumed to refer to all of the items in the canvas3d that have a tag matching the specifier. The symbol tagOrId is used below to indicate that an argument specifies either an id that selects a single item or a tag that selects zero or more items. Some widget commands only operate on a single item at a time; if tagOrId is specified in a way that names multiple items, then the normal behavior is for the command to use the first (lowest) of these items in the display list that is suitable for the command. Exceptions are noted in the widget command descriptions below.
Canvas3D uses a left-handed Cartesian coordinate system for 3D graphics. The positive x-axis points to the right and the positive y-axis to up. Unlike in the right-handed coordinate system, the z-axis points away from the user. This can be remembered by pointing the fingers of your left hand in the positive x direction and curling them into the positive y direction. The direction of your thumb is the positive z-direction of the coordinate system.
All coordinates related to canvas3d and its items are stored as floating-point numbers. Any reference to a coordinate point in canvas3d usually indicates a three-dimensional point that may be specified by a list of three floating-point numbers, such as { 1.5 -17.345 55.3 }. A integer-value is by convention, parsed to its equivalent floating-point value.
Canvas3D supports all the transformation operations such as scale, translate and rotate over the shape items that can be specified through the widget options. These options take a tagOrId as an argument to specify whether the transformation is to be operated upon a single item, or a group of items. It is also possible to apply a transformation matrix to a shape using the -transform option.
Every shape has been provided options to change its structure through specifying the number of sections, rings, etc that it is made up of. Since these computations are currently supported only for shapes created at origin, a shape that is transformed into the coordinate system is recreated at the origin with new specifications. The user is suggested to apply most of the item oriented options when the shape is at the origin, and then transform it into the coordinate system space using widget options.
The texture to be mapped on a three-dimensional shape is specified using two-dimensional (u,v) texture coordinates. The v-vector describes the orientation of the texture and typically lies along the z-axis of a three-dimensional coordinate system. The u-vector is a up vector that lies along the y-axis , with its origin at [0 0 0]. v varies from 0 to 1 over the width of the texture, while u varies from 0 to 1 over the height. Every vertex in the shape carries information regarding the texture coordinate that is to be mapped over it. The rasterizer interprets these coordinates while rendering the shape item. The rasterizer always interpolates the shortest distance between texture coordinates.
In Canvas3D, a texture can be specified in the -texture option of the Surface Item. A texture image can be in a standard image file format, or it may be a name of a video buffer. Video Buffers are maintained in a list, and every buffer has a name field in string format. Canvas3D first checks in the list for the name specified in the -texture option. If no video buffer exists by this name, then it checks for a file. The name can be the entire pathname for the image file. If the file format is not recognized, the option fails. Current version of Canvas3D recognizes only PPM image files. The user may specify different wrap styles for the textures over the shapes.
The canvas3d command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args determine the exact behavior of the command.
Unless specifically mentioned below, the widget commands usually return an empty string, if successful. An error string showing the possible correct syntax is otherwise returned.
The following widget commands are possible for canvas3d widgets. Note that the Usage Examples have the pathname .c, which is created by the Tk command : canvas3d .c
- pathName antiAlias onOrOff
-
This command allows to set the rendering option for antialiasing of the primitive edges for all the shapes in the canvas3d widget. onOrOff may be a string value : on or off.
Usage Example : .c antiAlias on
Default Value : off
- pathName clears onOrOff
-
clears is set to on to allow clearing of viewport before the next time all the items in the render list are rendered. If clears is set to off, the viewport is not cleared before the next render and all the previous items are still visible in canvas3d. onOrOff may be a string value : on or off.
Usage Example : .c clears off
Default Value : on
- pathName create type ?option value?
-
Create a new item in pathName of type type. type may be any of the item types supported by canvas3d. See the subsections on individual item types below for more on the syntax of this command. This command returns the id for the new item. Each item has several options that may be specified during create, or else may be changed later on using itemconfigure. If no options are specified, an item with default values (see individual items below) is created.
- pathName delete tagOrId
-
Delete each of the items given by each tagOrId, and return an empty string.
- pathName dither onOrOff
-
This option allows to enable dithering for all the items of the canvas3d. onOrOff may be a string value : on or off.
Usage Example : .c dither on
Default Value : off
- pathName fill tagOrId fillType
-
This option allows to change the fill mode of an item or a group of items specified by tagOrId. An item can be displayed in a point, wireframe or solid mode. Only the vertices are visible for a shape in the point mode. The wireframe mode makes the edges of the shape visible. A shape with solid mode has its surface fully visible. The color, appearance, etc. for the visible part of the shape is decided by the surface item associated with the shape. fillType may be one of the string values : point, wireframe or solid.
Usage Example : .c fill $sphr1 wireframe
Default Value : solid
- pathName fog onOrOff
-
This option allows to enable fog effects in the canvas3d. onOrOff may be a string value : on or off.
Usage Example : .c fog on
Default Value : off
- pathName perspCor onOrOff
-
This option allows to set the rendering option for perspective correction in the canvas3d. onOrOff may be a string value : on or off.
Usage Example : .c perspCor on
Default Value : off
- pathName rotate tagOrId axis angle
-
An item or a group of items specified by tagOrId can be rotated around the axis by an angle specified in radians. A positive value for the angle gives a clockwise rotation, while a negative value gives an anti-clockwise rotation. The axis can be specified by either of the values : x, y or z. This option is effective only for shapes and light items. The current position and size of the shape is not changed after rotation.
Usage Example : .c rotate $cone7 x 1.5
Default Value : None
- pathName shade shadeType
-
All the items rendered in the canvas3d can be shaded by the specified shadeType. shadeType takes one of the string values : flat, gouraud or phong.
Usage Example : .c shade flat
Default Value : gouraud
- pathName scale tagOrId scaleX scaleY scaleZ
-
Any shape item identified by tagOrId can be scaled by an amount of scaleX, scaleY or scaleZ value in the X, Y or Z directions respectively. The current orientation or position of the shape is not changed. scaleX, scaleY or scaleZ are floating-point values. If either of the three values are zero, no changes are applied to the shape in that direction.
Usage Example : .c scale $box6 2.5 5 2
Default Value : None
- pathName filter filterType
-
This option allows to set the rendering option for the type of texture filtering. filterType takes one of the string values : nearest, linear, mip_nearest, mip_linear, linear_mip_nearest or linear_mip_linear.
Usage Example : .c filter mip_linear
Default Value : nearest
- pathName transform tagOrId matrixId
-
A transformation matrix may be applied to all the vertices of the a shape item to modify its shape. An item may be modified to obtain a shear, twist, taper or any other deformation on it. matrixId is a previously created matrix item. This option applies the transformation to the original shape item, and does not actually create a new item. If the matrix value is changed after this command, it does not effect the shape in any way.
Usage Example : .c transform $box5 $matrix3
Default Value : None
- pathName translate tagOrId posX posY posZ
-
Items specified by tagOrId can be translated through its center by the distances posX, posY and posZ in the X, Y and Z directions of the coordinate space from its current position. The translation is applied to every vertex of the item. This option is effective only for shape and light items. The current orientation and size of the shape is not changed after translation. transX transY transZ are floating-point values. Either of these argument may take a zero value if no translation is to be applied in that direction, such as .c translate $sphr1 5 0 0 will translate a sphere $sphr in only x direction by 5.
Usage Example : .c translate $cyl4 20.3 0 -5.8
Default Value : None
- pathName update
-
This command option renders the current state of the Canvas3D into the window on the screen. The time required for this command is directly proportional to the number of items created as well as the newly updated area for the Canvas3D. Other important factors that effect timing are the hardware (such as processor, video card, etc) / software (such as the Operating System) being used for rendering. The contents of the Canvas3D window depends upon the current position of the camera and the size of the viewing frustum. The execution of this command starts immediately after it is specified, that is, the command does not go into an event queue. update command should be used for taking timing results for an application.
Usage Example : .c update
Default Value : None
- pathName wrap tagOrId wrapStyle
-
A texture may be wrapped on the shape in several ways. See the section TEXTURE MAPPING for more details. wrapStyle may take one of the string values : flat, cyl_u, cyl_v or torus.
Usage Example : .c wrap $cone1 torus
Default Value : flat
- pathName zBuffers onOrOff
-
This option allows to enable z-buffering rendering option. onOrOff may be a string value : on or off.
Usage Example : .c zBuffers on
Default Value : off
The sections below describe the various types of items supported by canvas3d widgets. Each item type is characterized by two things: first, the form of the create command used to create instances of the type; and second, a set of configuration options for items of that type, which may be used in the create and itemconfigure widget commands.
Items of type box appear as a rectangular box aligned with the co-ordinate axes.
By default, the box is centered at (0,0,0) and measures 2 units in each dimension, from -1 to 1.
Textures are applied individually to each face of the box; the entire texture goes on each face. On the front, back, right, and left sides of the box, the texture is applied right side up. On the top, the texture appears right side up when the top of the box is tilted toward the user. On the bottom, the texture appears right side up when the top of the box is tilted towards the -Z axis.
Boxes are created with widget commands of the following form:
pathName create box ?option value?
Any transformation to the box is applied through the center of the box.
After the command there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for boxes:
- -center position
-
The center of the box is specified by a position which is a
list of three floating-point values. The width, height and depth of the
box are equally distributed with respect to the center.
Usage Example : -center { 2.5 3.0 -5.6 }
Default Value : { 0.0 0.0 0.0 }
- -depth value
-
Depth of the box is its extent along the object-space Z-axis specified
in terms of a floating-point value.
Usage Example : -depth 12.5
Default Value : 2.0
- -height value
-
Height of the box is its extent along the object-space Y-axis specified
in terms of a floating-point value.
Usage Example : -height 12.5
Default Value : 2.0
- -surface surfaceId
-
Surface of the box is specified by the surfaceId, which is a
surface item. Any changes in the surface item will change the surface
of the box too.
Usage Example : -surface $surf1
Default Value : None
- -tags tagList
-
Specifies a set of tags to apply to the item. TagList consists of a
list of tag names, which replace any existing tags for the item.
TagList may be an empty list.
Usage Example : -tags shapes
Default Value : None
- -width value
-
Width of the box is its extent along the object-space X-axis specified
in terms of a floating-point value.
Usage Example : -width 12.5
Default Value : 2.0
Items of type cone appear as a simple cone whose central axis is aligned with the Y axis. By default, the
cone is centered at (0,0,0) and has a size of -1 to +1 in all three directions. The cone has a radius of
1 at the bottom and a height of 2, with its apex at 1 and its bottom at -1.
When a texture is applied to a cone, it is applied differently to the sides and bottom. On the sides,
the texture wraps counterclockwise (from above) starting at the back of the cone. The texture has a
vertical seam at the back, intersecting the YZ plane. For the bottom, a circle is cut out of the texture
square and applied to the cone's base circle. The texture appears right side up when the top of the
cone is rotated towards the -Z axis.
Cones are created with widget commands of the following form:
pathName create cone ?option value ?
Any transformation to the cone is applied through the center of the cone.
After the command there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for cones:
- -center position
-
The center of the cone is specified by a position which is a
list of three floating-point values. The height of the
cone is equally distributed with respect to the center.
Usage Example : -center { 2.5 3.0 -5.6 }
Default Value : { 0.0 0.0 0.0 }
- -height value
-
Height of the cone is its extent along the object-space Y-axis specified
in terms of a floating-point value.
Usage Example : -height 12.5
Default Value : 2.0
- -sections number
-
The cone's base is a circular disk made up of number of edges.
The apex of the cone is connected to the edges to form triangular
sections. The number of sections can be set to obtain different
cone shapes, or else, to control the number of vertices in the cone.
Usage Example : -sections 15
Default Value : 10
- -surface surfaceId
-
Surface of the cone is specified by the surfaceId, which is a
surface item. Any changes in the surface item will change the surface
of the cone too.
Usage Example : -surface $surf1
Default Value : None
- -radius value
-
Radius of the cone is the radius of its base circle specified in terms
of a floating-point value.
Usage Example : -radius 7.5
Default Value : 1.0
- -tags tagList
-
Specifies a set of tags to apply to the item. TagList consists of a
list of tag names, which replace any existing tags for the item.
TagList may be an empty list.
Usage Example : -tags shapes
Default Value : None
Items of type cylinder appear as a a simple capped cylinder centered around the Y axis. By default, the cylinder is
centered at (0,0,0) and has a default size of -1 to +1 in all three dimensions. You can use the radius
and height fields to create a cylinder with a different size.
When a texture is applied to a cylinder, it is applied differently to the sides, top, and bottom. On the
sides, the texture wraps counterclockwise (from above) starting at the back of the cylinder. The
texture has a vertical seam at the back, intersecting the YZ plane. For the top and bottom, a circle is
cut out of the texture square and applied to the top or bottom circle. The top texture appears right
side up when the top of the cylinder is tilted toward the +Z axis, and the bottom texture appears
right side up when the top of the cylinder is tilted toward the -Z axis.
Cylinders are created with widget commands of the following form:
pathName create cylinder ?option value?
Any transformation to the cylinder is applied through the center of the
cylinder.
After the command there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for cylinders:
- -center position
-
The center of the cylinder is specified by a position which is a
list of three floating-point values. The height of the
cone is equally distributed with respect to the center.
Usage Example : -center { 2.5 3.0 -5.6 }
Default Value : { 0.0 0.0 0.0 }
- -height value
-
Height of the cylinder is its extent along the object-space Y-axis
specified in terms of a floating-point value.
Usage Example : -height 12.5
Default Value : 2.0
- -sections number
-
The cylinder caps are circular disks made up of number of edges.
The edges of the two disks are connected to form rectangular
sections. The number of sections can be set to obtain different
cylindrical shapes, or else, to control the number of vertices
in the cylinder.
Usage Example : -sections 15
Default Value : 10
- -surface surfaceId
-
Surface of the cylinder is specified by the surfaceId, which is a
surface item. Any changes in the surface item will change the surface
of the cylinder too.
Usage Example : -surface $surf1
Default Value : None
- -radius value
-
Radius of the cylinder is the radius of its circular caps
specified in terms of a floating-point value.
Usage Example : -radius 7.5
Default Value : 1.0
- -tags tagList
-
Specifies a set of tags to apply to the item. TagList consists of a
list of tag names, which replace any existing tags for the item.
TagList may be an empty list.
Usage Example : -tags shapes
Default Value : None
Items of type light defines a light source and illuminates the objects
along the path of its rays depending upon the type of the light.
Different light item options are valid at a time based on the type
of the light. Spotlights are light sources that emits light from a
specific point along a specific direction vector and contrained within
a solid angle. Directional light source illuminates everything within the
coordinate system along rays parallel to a given 3-dimensional vector. Point light source has a fixed 3D location and it illuminates equally in all
directions, i.e, it is omnidirectional.
All the three attenution settings are used to determine the effect of a light
decreasing with distance from the source.The following equations shows how the
attenuation settings are interpreted. If d is the distance between
the vertex being lit and the light source, then,
attenuation = attenuation0 + (attenuation1 x d) + (attenuation 2 x d x d)
Lights are created with widget commands of the following form:
pathName create light
After the command there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for lights:
- -attenuation0 intensity
-
This option specifies the constant light intensity. intensity is
a light level that does not decrease between the light and the cutoff
point given by the -range option. intensity is a floating-point
value.
Usage Example : -attenuation0 5.0
Default Value : 1.0
- -attenuation1 intensity
-
This option specifies the light intensity that decreases linearly.
Light intensity is 50 percent of intensity halfway between the
light and the cutoff point given by the -range option. intensity
is a floating-point value.
Usage Example : -attenuation1 5.0
Default Value : 1.0
- -attenuation2 intensity
-
Light intensity specified by this option decreases according
to a quadratic attenuation factor. intensity is a floating-point
value.
Usage Example : -attenuation2 5.0
Default Value : 1.0
- -color list
-
The list is a value of { r g b a } format used to specify the
color of the light.
Usage Example : -color { 0.5 1.0 0.0 0.0 }
Default Value : { 1.0 1.0 1.0 1.0 }
- -direction vector
-
A vector specifies the direction of the light in the world-space.
A vector can be specified by a list of three floating point values.
Usage Example : -direction { 1.0 0.0 1.0 }
Default Value : { 0.0 0.0 1.0 }
- -fallOff value
-
Falloff is the decrease in illumination between the umbra (specified by
the -theta option) and the outer edge of the penumbra (specified by the
-phi option). value is a floating-point value.
Usage Example : -fallOff 2.5
Default Value : 1.0
- -phi angle
-
An angle, specified in radians, defines the outer edge of the
spotlight's penumbra. Points outside this cone are not lit by the
spotlight.
Usage Example : -phi 1.5
Default Value : 1.0
- -point position
-
This option is used to specify the position of the light in the
world space.
Usage Example : -point { 10.0 0.0 -20.0 }
Default Value : { 0.0 0.0 0.0 }
- -range distance
-
This option specifies the distance beyond which the light has no
effect.
Usage Example : -distance 25.0
Default Value : 20.0
- -theta angle
-
An angle, specified in radians, is the angle of the
spotlight's umbra, i.e. the fully illuminated spotlight cone.
Usage Example : -theta 2.0
Default Value : 1.5
- -type source
-
source is the type of light source. It can have one of the
string values point, spot, directional, parallel or glspot
corresponding to the light to have a point source, a spotlight source,
a directional source, a parallel source or a GL-style spotlight.
Usage Example : -type parallel
Default Value : directional
Items of type matrix are 4x4 matrices of floating-point values.
By default, an identity matrix is created.
Matrices are useful for specifying geometric transformations such as
expressing the location of an object relative to another object,
applying rotation, shear or scale factor to objects, and changing the viewing
positions, directions and perspective.
Matrices are created with widget commands of the following form:
pathName create matrix ?option value?
After the command there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for spheres:
- -multiply listMatrices
-
This option takes in a list of any number of matrix items and multiplies
all of them to the matrix for which the option is applied.
Usage Example : -multiply { matrix2 matrix1 matrix5 }
Default Value : None
- -value matrix
-
A list of 4 sub-lists, each of four floating-point values, is specified as
the matrix to set the value in the matrix item. The four sub-lists
are the four rows of the 4x4 matrix. The values in a sub-list correspond
to the column values of the 4x4 matrix.
Usage Example : -value { { 1.0 2.0 3.0 4.0 } { -1.0 67.0 5.5 -6.3 } { 4.3 -2.34 5 67 } { 6 7 8 -9 } }
Default Value : { { 1.0 0.0 0.0 0.0 } { 0.0 1.0 0.0 0.0 } { 0.0 0.0 1.0 0.0 } { 0.0 0.0 0.0 1.0 } }
Items of type mesh appear as a mesh, which is basically a set of
three-dimensional vertices and triangular faces. Mesh items are useful
to generate irregular shapes and models.
There may be any number of vertices and faces in a mesh. The user may want
to use the -expV and -expF options to do memory management efficiently for
this data. It is suggested not to worry about these options while creating the
mesh interactively. However, when the model is finalized, and the total number
of vertices and faces are known, then these options can be set when the mesh
is created.
Meshes are created with widget commands of the following form:
pathName create mesh ?option value?
Any transformation to the mesh is applied through the center of the
mesh. A mesh is usually created at the origin, that behaves as
the center of the mesh.
After the command there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for meshes:
- -edge edge enableType
-
This option is used to set the edge enable type for a triangular face.
The edge enable types are useful to have control over which edges of
the face should be visible in the wireframe filled mesh.
enableType
Usage Example : -edge
Default Value : None
- -expF value
-
This option sets a value for the expected number of triangular faces in
the mesh item. This value basically decides the step size for the amount
of new memory space required when all that was previously reserved is
exhausted. This option may not be used at all. However, it is suggested to
use this option to set it to a reasonable value for efficient
and reliable memory allocation.
Usage Example : -expF 20
Default Value : 50
- -expV value
-
This option sets a value for the expected number of vertces in
the mesh item. This value basically decides the step size for the amount
of new memory space required when all that was previously reserved is
exhausted. This option may not be used at all. However, it is suggested to
use this option to set it to a reasonable value for efficient
and reliable memory allocation.
Usage Example : -expV 20
Default Value : 50
- -faces list
-
This option is used to add new triangular faces to a list of faces for
the mesh item. Every face is identified by a unique integer value, that
can be checked using `-stats faces' option. list is a list of
any number of sub-lists, each of which has three integer values
representing the three vertices to be connected. A vertex number can be
obtained using the `-stats vertices' option. If any sublist contains an
invalid vertex number, or if the sublist is invalidly specified, then
only all previous faces in the list are added, while all the
other are not added.
Usage Example : -faces { { 0 1 5 } { 3 2 10 } { 14 2 5 } }
Default Value : None
- -stats choice
-
This option displays all the statistics regarding vertices and faces for
the mesh item that have been added at that stage.
choice can be vertices, faces or both. Depending on
the choice value, vertices and/or faces will be displayed along
with their unique number identifiers.
Usage Example : -stats both
Default Value : None
- -tags tagList
-
Specifies a set of tags to apply to the item. TagList consists of a
list of tag names, which replace any existing tags for the item.
TagList may be an empty list.
Usage Example : -tags shapes
Default Value : None
- -texture list
-
Texture coordinates can be specified using this option.
This option specifies a list of sub-lists, each of which takes
three values in it : { verNum tu tv }, where (tu, tv) are texture
coordinates for the vertex number specified by verNum. If a vertex is not
specified any texture coordinate, then the default values of (tu, tv)
for that vertex are (0.0, 0.0). If any sublist is invalidly specified,
only all previous vertices in the list are added, while all the
other are not added. Note that the texture specifications will be
affected by current wrapStyle setting. verNum is an integer,
whereas tu and tv are floating-point values.
Usage Example : -texture { { 1 0.2 0.4 } { 2 0.25 0.35 } }
Default Value : None
- -vertices list
-
This option is used to add new vertex positions to a list of vertices
for the mesh item. Every vertex is identified by a unique integer
value, that can be checked using `-stats vertices' option.
list is a list of any number of sub-lists,
each of which has three floating-point values representing the
three-dimensional coordinate point { x y z }. If any sublist is
invalidly specified, only all previous vertices in the list are
added, while all the other are not added.
Usage Example : -vertices { { 1 2 3.5 } { 4.0 -10.5 6 } }
Default Value : None
Items of type polygon appear as a two-dimensional plane item. Polygons are useful to build up environments, three-dimensional meshes, etc.
A polygon item is basically an implementation of a very generalized way of creating two dimensional shapes with different number of edges. It is a collection of triangles created from a center points, such that the edges of adjacent triangles touche each other while one of the edges is on the outer side of the shape. This basically means that a polygon with three edges is a triangle, four edges is a square, five edges is a pentagon, and so on. A polygon with any number of edges can be created.
The texture mapped over such a polygon gives highly unpredictable results, because of the generality of the item. However, polygons without texture, and only materials show up as a polygon with a uniform material that is visible on one of its side.
Polygonss are created with widget commands of the following form:
pathName create polygon ?option value ?
Any transformation to the polygon is applied through the center of the polygon
After the command there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for polygons:
- -center position
-
The center of the polygon is specified by a position which is a
list of three floating-point values. The edges of the
polygon are equally distributed with respect to the center.
Usage Example : -center { 2.5 3.0 -5.6 }
Default Value : { 0.0 0.0 0.0 }
- -edges number
-
A polygon is defined as a two-dimensional plane shape with number
of edges. A polygon with number equals two is a line, three is a
triangle, four is a square, five is a pentagon, and so on. number
is specified as an integer value. A polygon with a large number
(usually above 15) starts resembling a circle.
Usage Example : -edges 8
Default Value : 5
- -surface surfaceId
-
Surface of the polygon is specified by the surfaceId, which is a
surface item. Any changes in the surface item will change the surface
of the polygon too. Only one side of the polygon plane is visible and
displays the surface. The default polygon makes the surface visible
towards the user.
Usage Example : -surface $surf1
Default Value : None
- -radius value
-
The radius of the polygon is actully the radius of the `virtual' circle
that embeds the polygon. The radius basically controls the size of the
polygon.
Usage Example : -radius 12.5
Default Value : 2.0
- -tags tagList
-
Specifies a set of tags to apply to the item. TagList consists of a
list of tag names, which replace any existing tags for the item.
TagList may be an empty list.
Usage Example : -tags shapes
Default Value : None
Items of type sphere appear as a sphere. By default, the sphere is centered at the origin and has a radius of 1.
Spheres generate their own normals. When a texture is applied to a sphere, the texture covers the entire surface, wrapping counterclockwise from the back of the sphere. The texture has a seam at the back on the YZ plane.
Spheres are created with widget commands of the following form:
pathName create sphere ?option value?
Any transformation to the sphere is applied through the center of the sphere.
After the command there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure widget commands to change the item's configuration.
The following options are supported for spheres:
- -center position
-
The center of the sphere is specified by a position which is a
list of three floating-point values. The surface of the
sphere is equally distributed with respect to the center.
Usage Example : -center { 2.5 3.0 -5.6 }
Default Value : { 0.0 0.0 0.0 }
- -sections number
-
The sphere is vertically made up of number of sections,
where each section touches from the north pole to the south pole.
The number of sections can be set to control the number of vertices
in the sphere. sections and rings can be imagined as the
longitudes and latitudes, respectively on the earth globe.
A number is specified as an integer value.
Usage Example : -sections 15
Default Value : 10
- -surface surfaceId
-
Surface of the cone is specified by the surfaceId, which is a
surface item. Any changes in the surface item will change the surface
of the sphere too.
Usage Example : -surface $surf1
Default Value : None
- -radius value
-
Radius of the sphere is the distance of the surface from the center
specified in terms of a floating-point value.
Usage Example : -radius 7.5
Default Value : 1.0
- -rings number
-
The sphere is horizontally made up of number of rings,
where each ring makes a circles of different radius around the sphere.
The number of rings can be set to control the number of vertices
in the sphere. sections and rings can be imagined as the
longitudes and latitudes, respectively on the earth globe.
A number is specified as an integer value.
Usage Example : -rings 15
Default Value : 10
- -tags tagList
-
Specifies a set of tags to apply to the item. TagList consists of a
list of tag names, which replace any existing tags for the item.
TagList may be an empty list.
Usage Example : -tags shapes
Default Value : None
Items of type surface defines surface properties for associated geometry shapes. A surface is identified by the material and the texture associated with it. Material related options determine the way light reflects off an object to create color effects. A texture can be a standard image file, or a video buffer as explained in TEXTURE MAPPING above.
Every shape item has a surface item associated with it. Any changes in the surface configuration would effect the surface of the related shape too. Surface item is also used as a background for the viewport. A default surface is a material with darkgrey colors. The surface may be wrapped on shapes using different styles that can be configured using the wrap option for canvas3d.
Surfaces are created with widget commands of the following form:
pathName create surface ?option value?
After the command there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for surfaces:
- -ambient value
-
This option specifies how much ambient light from light sources
this surface should reflect. Ambient light is omnidirectional and
depends only on the number of light sources, not their positions with
respect to the surface. Ambient color is calculate as
ambientIntensity * diffuseColor. value is a floating point value
between 0.0 and 1.0 .
Usage Example : -ambient 0.5
Default Value : 1.0
- -diffuse color
-
The diffuseColor reflects all the light sources depending on the
angle of the surface with respect to the light source. The more
directly the surface faces the light, the more diffuse light reflects.
This option takes a color as a list of floating-point
values { red green blue alpha }, where each of the value lies in the
range between 0.0 and 1.0 .
Usage Example : -diffuse { 0.5 0.3 0.4 0.0 }
Default Value : { 1.0 1.0 1.0 1.0 }
- -emissive color
-
Emissive color models "glowing" objects. This can be useful for
displaying radiosity-based models (where the light energy of the room
is computed explicitly), or for displaying scientific data.
This option takes a color as a list of floating-point
values { red green blue alpha }, where each of the value lies in the
range between 0.0 and 1.0 .
Usage Example : -emissive { 0.5 0.3 0.4 0.0 }
Default Value : { 1.0 1.0 1.0 1.0 }
- -ramp value
-
This option specifies the value of the color ramp. For the
monochromatic(ramp) driver, this value must be less than or equal to 1
for materials assigned to the background; otherwise the background is
not displayed. This behavior also occurs when a texture that is assigned
to the background has an associated material whose ramp value
is greater than 1.
Usage Example : -ramp 1
Default Value : 16
- -shine value
-
This option sets the shininess of the material. Lower shininess values
produce soft glows, while higher values result in sharper,
smaller highlights. Shininess is specified a floating-point
value that lies between 0.0 and 1.0 .
Usage Example : -shine 0.5
Default Value : 1.0
- -specular color
-
When the angle from the light to the surface is close to the angle
from the surface to the viewer, the specularColor is added to the
diffuse and ambient color calculations. The color is specified
as a list of four floating-point values { red green blue alpha },
where each value lies in the range of 0.0 to 1.0 .
Usage Example : -specular { 0.5 0.75 0.5 1.0 }
Default Value : { 1.0 1.0 1.0 1.0 }
- -texture image
-
This option associates a texture image with the surface. See
TEXTURE MAPPING for further details. A texture can be specified by
image, which is either a file name of a standard image format
or a video buffer name. Current version of Canvas3D accepts image files
in the PPM format.
Usage Example : -texture sample.ppm
Default Value : None
- -transp value
-
This option specifies transparency of the surface to indicate
how "clear" the object is. A transparency value of 0.0 is
completely opaque, a value of 1.0 is completely transparent.
Usage Example : -transp 0.5
Default Value : 0.0
Items of type viewport define a specific location in a coordinate system from which the user might view the scene. Viewport also decides the orientation and direction in which the user wants to set the camera. The viewing volume is specified as the frustum to limit the boundaries of the camera view. Viewport may be specified to have a perspective view or an orthographic view. Typically there would be only one viewport created for a Canvas3D. However, its options would be changed quite frequently to adjust the view.
Note : Since there are number of open issues regarding this item currently, the user is suggested to see how this item is initially created and used in the test scripts.
Viewports are created with widget commands of the following form:
pathName create viewport
After the command there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for viewport:
- -frustum values
-
The viewing frustum is a 3D volume in a scene positioned relative
to the viewport's camera. Objects within the viewing frustum are visible.
This option takes a list values in the format { angle backPlane
frontPlane } where the angle is calculated on the half-height of the front
clipping plane, with respect to the camera's position. backPlane is
the back clipping plane distance from the viewpoint.
(Note : Currently, angle is specified as half-height itself.)
Usage Example : -frustum { 0.75 200.0 25.0 }
Default Value : { 1.0 500.0 5.0 }
- -normal direction
-
This option specifies the normal direction for the camera. The
direction takes in a vector as its value.
Usage Example : -normal { 1.0 0.0 1.0 }
Default Value : { 0.0 0.0 1.0 }
- -proj matrixId
-
This option sets the projection matrix for Direct3D. This option would
be removed in the future and the -frustum options will then specify the
projection matrix.
Usage Example : -proj $mat3
Default Value : None
- -type viewStr
-
This option is used to set the type of the viewport. viewStr may be
perspective or orthographic. For perspective viewing, the viewing
frustum is a volume of an imaginary pyramid that is between the front
and the back clipping plane. For orthographic viewing, the viewing frustum
is cuboid.
Usage Example : -type orthographic
Default Value : perspective
- -up vector
-
This option specifies the up direction for the camera. The
direction takes in a vector as its value.
Usage Example : -up { 1.0 1.0 1.0 }
Default Value : { 0.0 1.0 0.0 }
- -view matrixId
-
This option sets the view matrix for Direct3D. This option would
be removed in the future. This matrix has been defined in Direct3D as
a combination of projection and window matrix. Further investigation
is needed for this matrix value.
Usage Example : -view $mat5
Default Value : None
- -viewpoint position
-
Viewpoint is the position of the tip of the camera used in perspective
viewing. The position can be specified by a position in the
coordinate system. A position always refers to an absolute value,
and it doesn't change relatively to its previous position.
Usage Example : -viewpoint { 45 5 -10.0 }
Default Value : { 0.0 0.0 -10.0 }
- -window values
-
This option sets the window scaling parameters. Objects with 3D
coordinates are rendered into a 2D window specified by this option.
values is a list of four values : { scaleX scaleY originX originY }
, where scaleX and scaleY are the scaling factors of the window, while
originX and originY specifies the origin of the window.
Usage Example : -window { 5.0 5.0 1.0 1.0 }
Default Value : { 0.0 0.0 0.0 0.0 }
- -world matrixId
-
This option sets the window matrix for Direct3D. This option would
be removed in the future and the -window options will then specify the
world matrix.
Usage Example : -world $mat1
Default Value : None
Ankit Patel (apatel@cs.cornell.edu)