# Shapes and Paths¶

## Shapes vs. Paths¶

Each function in the shapes library creates a list of 2D coordinates in the xy plane, of form

`[ [x0,y0], [x1,y1], [x2,y2], ... ]`

Each function in the paths library creates a list of 3d vectors in the xz plane, of form

`[ vec(x0,y0,z0), vec(x1,y1,z1), ... ]`

The output of shapes.rectangle() and paths.rectangle() is therefore different. However, except for the library name, the syntax of the commands is almost the same. The following descriptions are written for shapes, but can be used to make paths instead simply by changing “shapes” to “paths”. Differences between shapes and paths are noted as needed.

## rectangle¶

rt = shapes.rectangle(width=10, height=6)
Parameters:
• width (scalar) – Width of rectangle. Default 1.

• height (scalar) – Height of rectangle. Default 1.

The function above creates a list of 2D x-y coordinates of the corners of a rectangle of width 10 and height 6. If the height value is omitted the shape is a square with its sides equal to the given width. If you print the value of the list created above you will see this list of 2D coordinates, starting at the lower right and continuing counterclockwise, end at the starting location:

`[[5, -3], [5, 3], [-5, 3], [-5, -3], [5, -3]]`

The rectangle shape can be visualized in VPython by executing the following statement, which extrudes the rectangular shape into the screen, along the line from vec(0,0,0) to vec(0,0,-0.1):

```rectshape = shapes.rectangle(width=10, height=6)
linepath = [ vec(0,0,0), vec(0,0,-0.1) ]
extrusion( shape=rectshape, path=linepath )
```

Other Parameters of Rectangle:

rt = shapes.rectangle(rotate=pi/6, roundness=0.1, invert=True, scale=2, pos=[2,1] )
Parameters:
• rotate (scalar) – Rectangle is rotated by the specified angle (in radians) counterclockwise around the path. Default 0.

• roundness (scalar) – Replaces sharp corners with a circular arc of radius (roundness*min(height,width)).

• invert (boolean) – Setting invert to True plus setting roundness produces chamfered corners.

• scale (scalar) – Multiplies height and width by scale. Default 1.

• xscale (scalar) – Scale factor for width only.

• yscale (scalar) – Scale factor for height only.

• thickness (scalar) – Shape only. Creates a hollow rectangular frame–a rectangle with a rectangular hole in the middle–whose sides have a thickness of (thickness*min(height,width)). Extruding this will make a hollow box. Default 0 (no hole). If thickness>0, the shape will consist of two lists of 2D points: one for the inner contour and one for the outer contour.

• pos (list) – Shape only. 2D position relative to the path. Default: center of rectangle placed at location of path.

Images left to right: rotated rectangle, rounded rectangle, chamfered rectangle, rectangular frame.

## circle¶

Parameters:

• np (scalar) – Number of points used to approximate circle. Default 64. An incomplete circle will not have the full number of points.

• scale (scalar) – Multiplies height and width by scale. Default 1.

• xscale (scalar) – Scale factor for width only.

• yscale (scalar) – Scale factor for height only.

• angle1 (scalar) – Starting angle in radians, ccw from +x axis. By default 0.

• angle2 (scalar) – Ending angle in radians, ccw from +x axis. By default 2*pi.

• thickness (scalar) – Shape only. Creates a circular ring of width (thickness*radius). Extruding this will make a hollow cylinder. Default 0 (no hole).

• pos (list) – Shape only. 2D position relative to the path. Default: center of circle placed at location of path.

Images left to right: thickness, angle1 and angle1, angle1 and angle2 and thickness

## ellipse¶

myellipse = shapes.ellipse(width=5, height=3)
Parameters:
• width (scalar) – Dimension along x-axis. Default 2.

• height (scalar) – Dimension along y-axis. Default 1.

The attributes of ellipse are almost identical to the attributes of circle, with the exception that xscale and yscale are replaced with width and height. The default width of an ellipse is twice that of a circle.

## arc¶

Parameters:

The attributes of arc are very similar to those of circle. An arc can be rotated and scaled. For a shape, if no thickness is specified the arc shape is given a very small thickness so that a closed contour is produced.

Note that np is the number of points in a complete circle, not in the arc itself.

An arc shape extruded along an arc path can give a ribbon:

```hshape = shapes.arc(angle1=0, angle2=pi/3)
hpath = paths.arc(angle1=pi/2, angle2=pi)
demihemi = extrusion( shape=hshape, path=hpath, color=color.yellow)
```

## line¶

Lshape = shapes.line(start=(1,0), end=(1,1), np=20)
Parameters:
• start (list) – For shape, 2D coordinate of line start. Default [0,0]. For path, start is a vector.

• end (list) – For shape, 2D coordinate of line end. Default [0,1]. For path, end is a vector.

• np (scalar) – Number of evenly spaced points in the line.

Creates a straight line from start to end, with a total number of n points, equally spaced over the interval. This can be useful for a path, if you wish to use twist in the extrusion.

Above: a rectangle extruded along a path with 30 points, with a 0.1 radian twist at each step.

## triangle¶

trishape = shapes.triangle(length=5, roundness=0.2)
Parameters:
• length (scalar) – Length of side of an equilateral triangle.

• rotate (scalar) – Rectangle is rotated by the specified angle (in radians) counterclockwise around the path. Default 0.

• roundness (scalar) – Replaces sharp corners with a circular arc of radius roundness*length.

• invert (boolean) – Setting invert to True plus setting roundness produces chamfered corners.

• scale (scalar) – Multiplies height and width by scale. Default 1.

• xscale (scalar) – Scale factor for base only.

• yscale (scalar) – Scale factor for altitude only.

• thickness (scalar) – Shape only. Creates a hollow rectangular frame–a rectangle with a rectangular hole in the middle–whose sides have a thickness of (thickness*length). Extruding this will make a hollow object. Default 0 (no hole). If thickness>0, the shape will consist of two lists of 2D points: one for the inner contour and one for the outer contour.

• pos (list) – Shape only. 2D position relative to the path. Default: center of rectangle placed at location of path.

## pentagon¶

pt = shapes.pentagon(length=3)
Parameters:
• length (scalar) – Length of a side.

• rotate (scalar) – Star is rotated by the specified angle (in radians) counterclockwise around the path. Default 0.

• roundness (scalar) – Replaces sharp corners with a circular arc of radius (roundness*length).

• invert (boolean) – Setting invert to True plus setting roundness produces chamfered corners.

• scale (scalar) – Multiplies height and width by scale. Default 1.

• xscale (scalar) – Scale factor for width only.

• yscale (scalar) – Scale factor for height only.

• thickness (scalar) – Shape only. Creates a pentagonal frame. Extruding this will make a hollow pentagon. Default 0 (no hole). If thickness>0, the shape will consist of two lists of 2D points: one for the inner contour and one for the outer contour.

• pos (list) – Shape only. 2D position relative to the path. Default: center of rectangle placed at location of path.

## hexagon¶

hx = shapes.hexagon(length=5)

The hexagon object has the same attributes as pentagon.

## octagon¶

oc = shapes.octagon(length=5)

The octagon shape has the same attributes as pentagon.

## ngon¶

poly = shapes.ngon(np=7, length=5)
Parameters:
• np (scalar) – The number of sides in the figure.

• radius (scalar) – The n-gon will fit into a circle with this radius. Side length is calculated automatically in this case.

Additional parameters are the same as for pentagon.

## star¶

Parameters:
• n (scalar) – Number of “beams” in the star. Default: 5

• radius (scalar) – Radius of a circle within which the star fits. Changing radius affects only the convex vertices of the star, leaving the inner, concave ones, unchanged.

• rotate (scalar) – Rotation around center.

• roundness (scalar) – Replaces sharp corners with a circular arc.

• invert (boolean) – Setting invert to True plus setting roundness produces chamfered corners.

• scale (scalar) – Multiplies height and width by scale. Default 1.

• xscale (scalar) – Scale factor for width only.

• yscale (scalar) – Scale factor for height only.

• thickness (scalar) – Shape only. Creates a star-shaped frame. Extruding this will make a hollow object. Default 0 (no hole). If thickness>0, the shape will consist of two lists of 2D points: one for the inner contour and one for the outer contour.

• pos (list) – Shape only. 2D position relative to the path. Default: center of rectangle placed at location of path.

## trapezoid¶

tr=shapes.trapezoid(pos=[-2,3], width=5, height=1, top=3)
Parameters:
• width (scalar) – Width of base.

• height (scalar) – Perpendicular distance from base to top.

• top (scalar) – Length of top line. Default is 0.5*width.

For other attributes, refer to pentagon.

## cross¶

st = shapes.cross(width=10, thickness=2)
Parameters:
• width (scalar) – Width of the cross. Default 1.

• thickness (scalar) – Thickness of an arm. Default 0.2. Note that this does not create a hollow frame.

• rotate (scalar) – Star is rotated by the specified angle (in radians) counterclockwise around the path. Default 0.

• scale (scalar) – Multiplies height and width by scale. Default 1.

• xscale (scalar) – Scale factor for width only.

• yscale (scalar) – Scale factor for height only.

• pos (list) – Shape only. 2D position relative to the path. Default: center of rectangle placed at location of path.

paths.cross() produces a path, but the thickness attribute does not give predictable results for thickness >= 1.

## points¶

This function works for shapes only. If you want to specify your own path, just use the list of points as the parameter in the extrusion.

ptshape = shapes.points(pos=[ [1,0], [1,1], [-2,3], [1,0] ], rotate=pi/4)
Parameters:
• pos (list) – A list of points defining the perimeter of a polygon. Last point must be the same as first point.

• scale (scalar) – Multiplies height and width by scale. Default 1.

• rotate (scalar) – Rotation around center.

• roundness (scalar) – Replaces sharp corners with a circular arc.

Note that pos is not an offset to the path, as it is in other shapes.

## gear¶

Gears are used to transmit motion by changing the rotational speed and direction with associated torque. For a detailed description of gears and gear terminology please refer to https://en.wikipedia.org/wiki/Gear. Be sure to click to enlarge the diagram that explains gear nomenclature. It mentions “involute gears” which are discussed at https://en.wikipedia.org/wiki/Involute_gear. The default gear shape is a “spur” gear.

Gear parameters define the way the gear behaves. These parameters must be in a harmony among each other to obtain a well defined gear. Not all parameters are provided in this program to fully control the gear structure. Some of them are calculated by using the others, hence may result in an inconsistent gear structure. Many gear parameters are derived from the radius. The user is responsible to provide a consistent set of parameters.

g = shapes.gear()
Parameters:
• radius (scalar) – Extends from center of gear to a point midway between the base and outer edge of a tooth. Placing the centers of two gears two radii apart usually allows gears to mesh properly. Default 1.

• scale (scalar) – Applies a uniform scale to the gear.

• pos (list) – Shape only. 2D position relative to the path. Default: center of rectangle placed at location of path.

• n (integer) – Defines number of teeth in the gear. Normally, “tooth size” and the number of teeth should define the gear circumference (or the radius), but in this program the “tooth size” is not a control parameter, rather it is calculated from the number of teeth and the radius. Hence the number of teeth, n, can be set arbitrarily and some unrealistic values for the “tooth size” can be obtained in turn. The user should be setting the parameters appropriately to obtain a reasonable tooth structure. The default number of teeth is 20.

• phi (scalar) – Coupled gears exert force on each other on the tooth profile during rotation. Phi is called the Pressure Angle, which is one of the basic parameters defining the tooth profile for a better contact. Also, “tooth size” components like bottom-land (roughly the gap between two teeth at the bottom of the teeth) and top-land (tooth thickness at the very top) are calculated using the pressure angle. Default value for the pressure angle is 20 degrees.

• addendum (scalar) – The “tooth depth” is defined as the sum of addendum and dedendum. Addendum is the part of the tooth above the radius to the tip of the tooth. Default value for addendum is 0.08 times the radius.

• dedendum (scalar) – Dedendum is the part of the tooth below the pitch radius to the depth of the tooth. Default value for dedendum is 0.1 times the radius.

`outer = shapes.circle(radius=1)` # a disk `inner = shapes.gear(radius=0.8)` # a gear-shaped hole in the disk `extrusion(path=[vec(0,0,0), vec(0,0,0.2)], shape=[outer, inner])`