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
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 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
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.
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:
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:
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:
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:
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:
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:
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,
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
Ankit Patel (apatel@cs.cornell.edu)
RENDER LIST
ITEM IDS AND TAGS
COORDINATE SYSTEM
TRANSFORMATIONS
TEXTURE MAPPING
WIDGET COMMAND
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.
Usage Example : .c antiAlias on
Default Value : off
Usage Example : .c clears off
Default Value : on
Usage Example : .c dither on
Default Value : off
Usage Example : .c fill $sphr1 wireframe
Default Value : solid
Usage Example : .c fog on
Default Value : off
Usage Example : .c perspCor on
Default Value : off
Usage Example : .c rotate $cone7 x 1.5
Default Value : None
Usage Example : .c shade flat
Default Value : gouraud
Usage Example : .c scale $box6 2.5 5 2
Default Value : None
Usage Example : .c filter mip_linear
Default Value : nearest
Usage Example : .c transform $box5 $matrix3
Default Value : None
Usage Example : .c translate $cyl4 20.3 0 -5.8
Default Value : None
Usage Example : .c update
Default Value : None
Usage Example : .c wrap $cone1 torus
Default Value : flat
Usage Example : .c zBuffers on
Default Value : off
OVERVIEW OF ITEM TYPES
BOX ITEMS
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.
pathName create box ?option value?
Any transformation to the box is applied through the center of the box.
Usage Example : -center { 2.5 3.0 -5.6 }
Default Value : { 0.0 0.0 0.0 }
Usage Example : -depth 12.5
Default Value : 2.0
Usage Example : -height 12.5
Default Value : 2.0
Usage Example : -surface $surf1
Default Value : None
Usage Example : -tags shapes
Default Value : None
Usage Example : -width 12.5
Default Value : 2.0
CONE ITEMS
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.
pathName create cone ?option value ?
Any transformation to the cone is applied through the center of the cone.
Usage Example : -center { 2.5 3.0 -5.6 }
Default Value : { 0.0 0.0 0.0 }
Usage Example : -height 12.5
Default Value : 2.0
Usage Example : -sections 15
Default Value : 10
Usage Example : -surface $surf1
Default Value : None
Usage Example : -radius 7.5
Default Value : 1.0
Usage Example : -tags shapes
Default Value : None
CYLINDER ITEMS
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.
pathName create cylinder ?option value?
Any transformation to the cylinder is applied through the center of the
cylinder.
Usage Example : -center { 2.5 3.0 -5.6 }
Default Value : { 0.0 0.0 0.0 }
Usage Example : -height 12.5
Default Value : 2.0
Usage Example : -sections 15
Default Value : 10
Usage Example : -surface $surf1
Default Value : None
Usage Example : -radius 7.5
Default Value : 1.0
Usage Example : -tags shapes
Default Value : None
LIGHT ITEMS
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.
attenuation = attenuation0 + (attenuation1 x d) + (attenuation 2 x d x d)
Usage Example : -attenuation0 5.0
Default Value : 1.0
Usage Example : -attenuation1 5.0
Default Value : 1.0
Usage Example : -attenuation2 5.0
Default Value : 1.0
Usage Example : -color { 0.5 1.0 0.0 0.0 }
Default Value : { 1.0 1.0 1.0 1.0 }
Usage Example : -direction { 1.0 0.0 1.0 }
Default Value : { 0.0 0.0 1.0 }
Usage Example : -fallOff 2.5
Default Value : 1.0
Usage Example : -phi 1.5
Default Value : 1.0
Usage Example : -point { 10.0 0.0 -20.0 }
Default Value : { 0.0 0.0 0.0 }
Usage Example : -distance 25.0
Default Value : 20.0
Usage Example : -theta 2.0
Default Value : 1.5
Usage Example : -type parallel
Default Value : directional
MATRIX ITEMS
Items of type matrix are 4x4 matrices of floating-point values.
By default, an identity matrix is created.
pathName create matrix ?option value?
Usage Example : -multiply { matrix2 matrix1 matrix5 }
Default Value : None
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 } }
MESH ITEMS
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.
pathName create mesh ?option value?
Usage Example : -edge
Default Value : None
Usage Example : -expF 20
Default Value : 50
Usage Example : -expV 20
Default Value : 50
Usage Example : -faces { { 0 1 5 } { 3 2 10 } { 14 2 5 } }
Default Value : None
Usage Example : -stats both
Default Value : None
Usage Example : -tags shapes
Default Value : None
Usage Example : -texture { { 1 0.2 0.4 } { 2 0.25 0.35 } }
Default Value : None
Usage Example : -vertices { { 1 2 3.5 } { 4.0 -10.5 6 } }
Default Value : None
POLYGON ITEMS
Items of type polygon appear as a two-dimensional plane item. Polygons are useful to build up environments, three-dimensional meshes, etc.
pathName create polygon ?option value ?
Any transformation to the polygon is applied through the center of the polygon
Usage Example : -center { 2.5 3.0 -5.6 }
Default Value : { 0.0 0.0 0.0 }
Usage Example : -edges 8
Default Value : 5
Usage Example : -surface $surf1
Default Value : None
Usage Example : -radius 12.5
Default Value : 2.0
Usage Example : -tags shapes
Default Value : None
SPHERE ITEMS
Items of type sphere appear as a sphere. By default, the sphere is centered at the origin and has a radius of 1.
pathName create sphere ?option value?
Any transformation to the sphere is applied through the center of the sphere.
Usage Example : -center { 2.5 3.0 -5.6 }
Default Value : { 0.0 0.0 0.0 }
Usage Example : -sections 15
Default Value : 10
Usage Example : -surface $surf1
Default Value : None
Usage Example : -radius 7.5
Default Value : 1.0
Usage Example : -rings 15
Default Value : 10
Usage Example : -tags shapes
Default Value : None
SURFACE ITEMS
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.
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:
Usage Example : -ambient 0.5
Default Value : 1.0
Usage Example : -diffuse { 0.5 0.3 0.4 0.0 }
Default Value : { 1.0 1.0 1.0 1.0 }
Usage Example : -emissive { 0.5 0.3 0.4 0.0 }
Default Value : { 1.0 1.0 1.0 1.0 }
Usage Example : -ramp 1
Default Value : 16
Usage Example : -shine 0.5
Default Value : 1.0
Usage Example : -specular { 0.5 0.75 0.5 1.0 }
Default Value : { 1.0 1.0 1.0 1.0 }
Usage Example : -texture sample.ppm
Default Value : None
Usage Example : -transp 0.5
Default Value : 0.0
VIEWPORT ITEMS
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.
Usage Example : -frustum { 0.75 200.0 25.0 }
Default Value : { 1.0 500.0 5.0 }
Usage Example : -normal { 1.0 0.0 1.0 }
Default Value : { 0.0 0.0 1.0 }
Usage Example : -proj $mat3
Default Value : None
Usage Example : -type orthographic
Default Value : perspective
Usage Example : -up { 1.0 1.0 1.0 }
Default Value : { 0.0 1.0 0.0 }
Usage Example : -view $mat5
Default Value : None
Usage Example : -viewpoint { 45 5 -10.0 }
Default Value : { 0.0 0.0 -10.0 }
Usage Example : -window { 5.0 5.0 1.0 1.0 }
Default Value : { 0.0 0.0 0.0 0.0 }
Usage Example : -world $mat1
Default Value : None