Command: shape

Usage:
shape  shape  options

The shape command creates a surface model of the specified shape. For geometric objects that can be used in distance and angle measurements, see define instead. See also: topography, volume mask, marker fromMesh, cartoon, surface operations, Marker Placement, 3D object formats

The shape can be:

• sphere
• ellipsoid
• cylinder
• cone
• icosahedron
• triangle
• rectangle
• ribbon – a ribbon of rectangular cross-section connecting a series of atoms or markers
• tube – a tube connecting a series of atoms or markers
• boxPath – zigzag “beams” connecting a series of atoms or markers

The default radius r is 1.0 in units of physical distance (typically Å). To instead add a marker (a pseudoatom that can be used in measurements) at a specified point, see the marker command.

The default radius r is 1.0 along each axis. If a single value is specified, the result is a sphere. Specifying three values (rx,ry,rz) sets ellipsoid radii along the X, Y, and Z axes, respectively. See also: measure inertia

The default radius r and height h are both 1.0. The default orientation is with the axis of symmetry (height dimension) along the Z axis. The caps option indicates whether to cap the cylinder or leave it open-ended. Some options are mutually exclusive:

• the orientation can be given with the axis option instead of rotation values (in general options)
• the endpoints can be specified directly with fromPoint and toPoint instead of with height, center, and rotation values

See also: define axis

The default radius rbase and height h are both 1.0. The default orientation is with the axis of symmetry (height dimension) along the Z axis and top towards +Z. The topRadius rtop defaults to 0.0, giving a pointed cone, but values > 0 can be used to produce a truncated cone. The caps option indicates whether to cap the end(s) of the cone or leave them open. Some options are mutually exclusive:

• the orientation can be given with the axis option instead of rotation values (in general options)
• the endpoints can be specified directly with fromPoint (base) and toPoint (tip) instead of with height, center, and rotation values

The radius r is the distance from the center to a 5-fold vertex (default 1.0). The orientation type can be:

• 222 (default) – with two-fold symmetry axes along the X, Y, and Z axes
• 2n5 – with two-fold symmetry along X and 5-fold along Z
• n25 – with two-fold symmetry along Y and 5-fold along Z
• 2n3 – with two-fold symmetry along X and 3-fold along Z
• 222r – same as 222 except rotated 90° about Z
• 2n5r – same as 2n5 except rotated 180° about Y
• n25r – same as n25 except rotated 180° about X
• 2n3r – same as 2n3 except rotated 180° about Y

The sphereFactor option allows generating a shape that is an interpolation between an icosahedron and a sphere of equal radius. The factor f is the weight of the sphere component in the interpolation and can range from 0.0 (default, icosahedron) to 1.0 (sphere). The interpolation only affects vertex positions and will not generate curved mesh lines or curved surface triangles. The lattice option allows showing the icosahedron surface with hexagons and pentagons instead of triangles. A shape with icosahedral symmetry (like many virus capsids) can be idealized as a sheet of hexagons in which curvature is introduced by replacing certain hexagons with pentagons, as in a geodesic dome. The pentagons occupy the points of the icosahedron, while the indices h and k refer to the number and arrangement of hexagons in each face (details...). Hexagons are bent where they cross from one triangular face to another. The indices h and k can each be zero (but not both zero) or a positive integer. Surface generation can be slow if large values are used. See also: hkcage, Cage Builder

The vertices of the triangle can be supplied as a specification of three atoms or with three separate uses of the point option. If neither of those are used, an equilateral triangle of side length 1 will be created.

^*The general options center, rotation, qrotation, and coordinateSystem do not apply if the atoms option is used.

The width w and height h are the X and Y dimensions of the rectangle (both default to 1.0). The number of surface points in the rectangle along the X dimension will equal 1 + dw and along the Y dimension will equal 1 + dh. Both the widthDivisions dw and heightDivisions dh default to 10, and these settings override the divisions general option.

A ribbon is a smooth path with rectangular cross-section connecting a series of atoms or markers. The default width w and height h of the cross-section are 1.0 and 0.1, respectively. The yaxis and twist options control ribbon orientation and how it varies along the path. If neither is specified, the ribbon normal varies along the path so that there is no local twist. The yaxis vector (default none) is specified as three numbers separated by commas only, and is interpreted in the coordinate system of the model containing the first atom in the path. If the vector is specified, the ribbon normal is aligned with it as closely as possible within the constraints of the path. A constant twist angle t (default 0°) is applied at each point along the path.

The segmentSubdivisions setting controls how many straight segments are used to form the curve between a consecutive pair of atoms; higher values give smoother curves. The number of straight segments forming the curve between a pair of atoms will equal divisions + 1 (default 10 + 1 = 11). The bandLength option specifies what length of ribbon centered on an atom should be colored to match that atom (default 0.0). The followBonds option indicates whether the ribbon should follow the directions of the bonds connecting the atoms; the option should be set to false for atoms that are not bonded.

^*The general options center, rotation, qrotation, coordinateSystem, and slab do not apply to ribbon shapes.

A tube is a smooth path with circular cross-section connecting a series of atoms or markers. The default radius r is 1.0. The segmentSubdivisions setting controls how many straight segments are used to form the curve between a consecutive pair of atoms; higher values give smoother curves. The number of straight segments forming the curve between a pair of atoms will equal divisions + 1 (default 10 + 1 = 11). The bandLength option specifies what length of tube centered on an atom should be colored to match that atom (default 0.0). The followBonds option indicates whether the tube should follow the directions of the bonds connecting the atoms; the option should be set to false for atoms that are not bonded.

^*The general options center, rotation, qrotation, coordinateSystem, and slab do not apply to tube shapes.

A boxPath is a 3D zigzag of “beam” segments connecting a series of atoms or markers. The beam has a square cross-section of width w (default 1.0), and the twist t (default 0.0°) sets the rotational orientation of the segments about their long axes. To make a physical replica of the boxpath (see the sculpture at DePauw), the segments could be generated by angled cuts along a single straight beam. Setting reportCuts to true gives the locations of such cuts along the four edges of a hypothetical beam; the cutScale s (default 1.0) is a factor for converting these distances from Å to the appropriate physical units.

^*The general options center, rotation, qrotation, coordinateSystem, divisions, and slab do not apply to boxPath shapes.

center  point-spec
The center location of the shape (default 0,0,0).

rotation  ax,ay,az,angle
Rotate the shape angle degrees around the specified axis (ax,ay,az). The default is no rotation.

qrotation  qx,qy,qz,qw
Apply the rotation specified as a quaternion. The default is no rotation.

coordinateSystem  model-number
Specify a coordinate system for the shape surface model (default is its own coordinate system, but a different reference model can be specified). A model's coordinate system defines the X, Y, and Z directions and the position of the origin, and is generally aligned with the scene coordinates unless the model has been moved separately.

color  color-spec
Specify the color of the surface (default #bebebe ).

name  model-name
Specify a name for the surface model. If no name is specified, a generic shape name will be used (for example, “sphere”).

modelId  model-number
Specify an ID number for the surface model. The default is the lowest unused number. If the number is already in use for a surface model from the shape command, that surface will be replaced.

divisions  d
Set the fineness of surface triangulation; d is the number of square mesh cells around the circumference (default 72). The number of triangles around the circumference is roughly 2-4 times higher, depending on the shape and on the value of d. This setting does not apply to an icosahedron with lattice specified, as it will be shown with the indicated numbers of hexagons and pentagons rather than with triangles.

mesh  true | false
Whether to display the surface as a mesh or as a solid surface. The default is false except for an icosahedron with lattice specified.

slab  width | d1,d2
The slab option indicates that a shell or slab of finite thickness should be created instead of a single layer of surface. If a single value (width) is supplied, the inner and outer layers of the slab will be offset from the nominal radius r by ±½(width). Alternatively, two values separated by a comma but no spaces can be used to specify the offsets of the two layers independently. Offsets can be positive (outward) or negative (inward).