Drawing object

A drawing is the container for a geometric object. The Drawing object stores the vertex data and various settings that determine how the drawing will be displayed.

The following topics are discussed:

Access
Drawing(...)
setVertices(...)
setNormals(...)
setColors(...)
setEdgeColor(...)
setPointColor(...)
addArrayDraw(...)
addIndexDraw(...)
setValues(...)
Members

Access

session.drawings[name]

Drawing(...)

This method creates an empty Drawing object.

Path

session.Drawing

Required arguments

name: A String specifying the repository key.

Optional arguments

None.

Return value

A Drawing object.

Exceptions

ValueError.

If the user attempts to create a new drawing with the name of an existing drawing:: ValueError: There is already a drawing with this name

setVertices(...)

This method accepts the vertex data that defines the Drawing object. It defines in an array of vertices with a length equal to the length of the vertexData sequence divided by vertexDimension.

Required arguments

vertexDimension: An Integer in the range of 2 to 4 specifying how many Float values are needed to compose a single vertex.
vertexData: A sequence of Float values that will be used to compose the vertices. There must be vertexDimension values in the sequence for each vertex.

Optional arguments

None.

Return value

The number of vertices described.

Exceptions

RangeError.

ValueError.

If an invalid vertexDimension is specified:: RangeError: vertexDimension must be in the range 2 <= value <= 4
If vertexData is an empty sequence:: ValueError: vertexData cannot be empty.
If setVertices has already been called and this call is sending fewer vertices:: ValueError: vertexData cannot be reduced

setNormals(...)

This method accepts the normal data for each vertex. It defines in an array of normal vectors with a length equal to the length of the normalData sequence divided by 3.

Required arguments

normalData

A sequence of Float values that will be used to compose the normals. There must be 3 values in the sequence for each normal.

If only one normal is specified, all vertices will use the normal value.

Optional arguments

None.

Return value

The number of normals described.

Exceptions

RangeError.

ValueError.

If normalData is sequence with less than 3 values:: ValueError: normalData must have at least three values.
If setNormals has already been called and this call is sending fewer values:: ValueError: normalData cannot be reduced.

setColors(...)

This method accepts the color data for each vertex. It defines in an array of colors with a length equal to the length of the colorData sequence divided by colorDimension.

Required arguments

colorDimension

An Integer in the range of 3 to 4 specifying how many Float values are needed to compose a single color.

colorData

A sequence of Float values in the range of 0.0 to 1.0 that will be used to compose the colors. There must be colorDimension values in the sequence for each color. The first color will be associated with the fist vertex and so on.

The first Float will be the red value for the first color. The second Float will be the green value and the third will be the blue value. When colorDimension is 4 the 4th Float will be the alpha value for the first color but is ignored.

If only one color is specified, all vertices will use the color value.

Optional arguments

None.

Return value

The number of colors described.

Exceptions

RangeError.

ValueError.

If an invalid colorDimension is specified:: RangeError: colorDimension must be in the range 3 <= value <= 4
If colorData is an empty sequence:: ValueError: colorData cannot be empty.
If setColors has already been called and this call is sending fewer colors:: ValueError: colorData cannot be reduced

setEdgeColor(...)

This method allows a separate, single color to be used when rendering the edges of the drawing. Once called, edges will be rendered using the specified color but facets will continue to use the colors specified in the setColors method. An empty sequence can be specified to resume using the colors arrays for edges.

Required arguments

edgeColor

A sequence of 0 or 3 Float values in the range of 0.0 to 1.0 that will be used to compose the edge color.

If the initial Float value is -1, the viewport background color will be used for the edge color.

Optional arguments

None.

Return value

None.

Exceptions

ValueError.

If edgeColor is not a sequence of 0 or 3 Floats:: ValueError: edgeColor must be a tuple with 3 values

setPointColor(...)

This method allows a separate, single color to be used when rendering the points of the drawing. Once called, points will be rendered using the specified color but facets will continue to use the colors specified in the setColors method. An empty sequence can be specified to resume using the colors arrays for points.

Required arguments

pointColor

A sequence of 0 or 3 Float values in the range of 0.0 to 1.0 that will be used to compose the point color.

If the initial Float value is -1, the viewport background color will be used for the edge color.

Optional arguments

None.

Return value

None.

Exceptions

ValueError.

If pointColor is a not sequence of 0 or 3 Floats:: ValueError: pointColor must be a tuple with 3 values

addArrayDraw(...)

This method adds a rendering command to the drawing and can be called multiple times to add additional rendering commands. When the drawing is referenced by a Viewport, the drawing commands are used the render the Drawing.

The rendering command constructs the specified type of geometric primitive using numVertices array elements starting at element index startIndex.

Required arguments

type: A SymbolicConstant specifying the type of graphics primitive rendered by this command. Possible values are POINTS, LINES, LINE_LOOP, LINE_STRIP, TRIANGLES, TRIANGLE_STRIP, TRIANGLE_FAN, QUADS, and QUAD_STRIP.
startIndex: An Integer specifying the index of the first vertex to render.
numVertices: An Integer specifying the total number of vertices to render.

Optional arguments

polygonMode: A SymbolicConstant specifying how polygonal graphics primitives will be rendered by this command. Possible values are FILL, EDGES, and POINTS. The default value is FILL.

Return value

The total number of rendering commands that have been specified.

Exceptions

ValueError.

If (startIndex + numVertices - 1) is larger than the length of the vertex array:: ValueError: Drawing request extends past array size of vertices.
If (startIndex + numVertices - 1) is larger than the length of the normal array and normals are required for the graphics primitive:: Drawing request extends past array size of normals.
If (startIndex + numVertices - 1) is larger than the length of the color array and vertex colors are required for the graphics primitive:: Drawing request extends past array size of colors.

addIndexDraw(...)

The rendering command constructs the specified type of geometric primitive using numVertices array elements starting at element index startIndex.

Required arguments

type: A SymbolicConstant specifying the type of graphics primitive rendered by this command. Possible values are POINTS, LINES, LINE_LOOP, LINE_STRIP, TRIANGLES, TRIANGLE_STRIP, TRIANGLE_FAN, QUADS, and QUAD_STRIP.
indices: A sequence of Integer values specifying index of each vertex to render.

Optional arguments

polygonMode: A SymbolicConstant specifying how polygonal graphics primitives will be rendered by this command. Possible values are FILL, EDGES, and POINTS. The default value is FILL.

Return value

The total number of rendering commands that have been specified.

Exceptions

ValueError.

If any value in the indices sequence negative:: ValueError: Index values must be positive.
If any value in the indices sequence is larger than the length of the vertex array:: ValueError: Drawing request extends past array size of vertices.
If any value in the indices sequence is larger than the length of the normal array and normals are required for the graphics primitive:: Drawing request extends past array size of normals.
If any value in the indices sequence is larger than the length of the color array and vertex colors are required for the graphics primitive:: Drawing request extends past array size of colors.

setValues(...)

This method modifies the rendering of the Drawing object.

Required arguments

None.

Optional arguments

show

A Boolean specifying whether the drawing object will be rendered when referenced. The default value is OFF.

cullBackfaces

A Boolean specifying whether polygonal graphics primitives facing away from the viewer should be culled (not rendered). The default value is OFF.

The winding order, and not the normal, of the graphics primitive is used to determine its facing.

frontFaceOrder

A SymbolicConstant specifying the winding order for polygonal graphics primitives that face the viewer. Possible values are:

CCW, specifying front face winding order is counter-clockwise.
CW, specifying front face winding order is clockwise.

The default value is CCW.

smoothShade

A Boolean specifying whether the lighting of polygonal graphics primitives is consistent for each facet or calculated for each displayed pixel. The default value is ON.

When False, only the last normal for each facet will be used in the lighting calculation.

edgesInShaded

A Boolean specifying whether edge and point drawing commands will be issued in a FILLED or SHADED display. The default value is ON.

If no edge or point drawing commands have been defined, the polygonal drawing commands will be issued in WIREFRAME and HIDDEN_LINE displays with the polygonMode set to EDGES. If only edge and point drawing commands have been defined, the Drawing will not be rendered in FILLED or SHADED displays.

translucency

A Float specifying the opacity for polygonal graphics primitives. Possible values are 0.0 $\leq$ translucency $\leq$ 1.0 with 0.0 being completely transparent (invisible) and 1.0 being opaque. The default value is 1.0.

A value greater than 0.3 will cause the translucent facets to be sorted by depth before being rendered and has the side effect of disabling two-sided lighting for those facets.

lineSize

A Float specifying the width of the line, in millimeters, used to render edges. Possible values are 0.0 $\leq$ lineSize $\leq$ 5.0 with 0.0 being interpreted as the thinnest possible line. The default value is 0.0.

A value of 0.0 will be one pixel on the output device. One pixel on the screen is generally visible but one pixel on a 1200 DPI printer may not be clear.

pointSize

A Float specifying the width of points, in millimeters, used to render points. Possible values are 0.0 $\leq$ lineSize $\leq$ 5.0 with 0.0 being interpreted as the smallest possible point. The default value is 0.0.

A value of 0.0 will be one pixel on the output device. One pixel on the screen is generally visible but one pixel on a 1200 DPI printer may not be clear.

depthTest

A Boolean specifying whether an object's depth will be considered during rendering. The default value is ON.

When OFF, the object will not be hidden by other objects in front of it.

Return value

None.

Exceptions

RangeError.

If an invalid translucency value is specified:: RangeError: translucency must be in the range 0.0 <= value <= 1.0
If an invalid lineSize value is specified:: RangeError: lineSize must be in the range 0.0 <= value <= 5.0
If an invalid pointSize value is specified:: RangeError: pointSize must be in the range 0.0 <= value <= 5.0

Members

The Drawing object has members with the same names and descriptions as the arguments to the Drawing method.

In addition, the Drawing object has the following members:

vertexCount

An Int specifying the number of vertices in the vertex array after a call to the setVertices method. The default value is 0.

normalCount

An Int specifying the number of normal vectors in the normal array after a call to the setNormals method. The default value is 0.

colorCount

An Int specifying the number of colors in the color array after a call to the setColors method. The default value is 0.

show

A Boolean specifying whether the drawing object will be rendered when referenced. The default value is OFF.

cullBackfaces

A Boolean specifying whether polygonal graphics primitives facing away from the viewer should be culled (not rendered). The default value is OFF.

The winding order, and not the normal, of the graphics primitive is used to determine its facing.

frontFaceOrder

A SymbolicConstant specifying the winding order for polygonal graphics primitives that face the viewer. Possible values are:

CCW, specifying front face winding order is counter-clockwise.
CW, specifying front face winding order is clockwise.

The default value is CCW.

translucency

A value greater than 0.3 will cause the translucent facets to be sorted by depth before being rendered and has the side effect of disabling two-sided lighting for those facets.

lineSize

A value of 0.0 will be one pixel on the output device. One pixel on the screen is generally visible but one pixel on a 1200 DPI printer may not be clear.

pointSize

A value of 0.0 will be one pixel on the output device. One pixel on the screen is generally visible but one pixel on a 1200 DPI printer may not be clear.

smoothShade

A Boolean specifying whether the lighting of polygonal graphics primitives is consistent for each facet or calculated for each displayed pixel. The default value is ON.

When False, only the last normal for each facet will be used in the lighting calculation.

edgesInShaded

A Boolean specifying whether edge and point drawing commands will be issued in a FILLED or SHADED display. The default value is ON.

edgeColor

A tuple of three Floats specifying the Red, Green, and Blue component values for the edge color. Possible values for each component are between 0.0 and 1.0.

pointColor

A tuple of three Floats specifying the Red, Green, and Blue component values for the point color. Possible values for each component are between 0.0 and 1.0.

depthTest

A Boolean specifying whether an object's depth will be considered during rendering. The default value is ON.

When OFF, the object will not be hidden by other objects in front of it.