geometry

Note: This documentation is for the old 0.2.0 version of A-Frame. Check out the documentation for the current 0.5.0 version

The geometry component provides a basic shape for an entity. The general geometry is defined by the primitive property. Geometric primitives, in computer graphics, means an extremely basic shape. With the primitive defined, additional properties are used to further define the geometry. A material component is usually defined alongside to provide a appearance alongside the shape to create a complete mesh.

Properties

We will go through the basic primitives and their respective properties one by one.

PropertyDescriptionDefault Value
primitiveOne of box, circle, cone, cylinder, plane, ring, sphere, torus, torusKnot.None
translateTranslates the geometry relative to its pivot point.0 0 0

Box

The box primitive defines boxes (i.e., any quadilateral, not just cubes).

<a-entity geometry="primitive: box; width: 1; height: 1; depth: 1"></a-entity>
PropertyDescriptionDefault Value
widthWidth (in meters) of the sides on the X axis.1
heightHeight (in meters) of the sides on the Y axis.1
depthDepth (in meters) of the sides on the Z axis.1

Circle

The circle primitive defines two-dimensional circles, which can be complete circles or partial circles (like Pac-Man). Note that because it is flat, only a single side of the circle will be rendered if “side: double” is not specified on the material component.

<a-entity geometry="primitive: circle; radius: 1" material="side: double"></a-entity>
PropertyDescriptionDefault Value
radiusRadius (in meters) of the circle.1
segmentsNumber of triangles to construct the circle, like pizza slices. A higher number of segments means the circle will be more round.32
thetaStartStart angle for first segment. Can be used to define a partial circle.0
thetaLengthThe central angle (in degrees). Defaults to 360, which makes for a complete circle.360

Cone

The cone primitive under the hood is a cylinder primitive with varying top and bottom radiuses.

<a-entity geometry="primitive: cone; radiusBottom: 1; radiusTop: 0.1"></a-entity>
PropertyDescriptionDefault Value
heightHeight of the cone.2
openEndedWhether the ends of the cone are open (true) or capped (false).false
radiusBottomRadius of the bottom end of the cone.1
radiusTopRadius of the top end of the cone.1
segmentsRadialNumber of segmented faces around the circumference of the cone.36
segmentsHeightNumber of rows of faces along the height of the cone.18
thetaStartStarting angle in degrees.0
thetaLengthCentral angle in degrees.360

Cylinder Primitive

The cylinder primitive can define cylinders in the traditional sense like a Coca-Cola™ can, but it can also define shapes such as tubes and curved surfaces. We’ll go over some of these cylinder recipes below.

Basic Cylinder

Traditional cylinders can be defined by using only a height and a radius:

<a-entity geometry="primitive: cylinder; height: 3; radius: 2"></a-entity>

Tube

Tubes can be defined by making the cylinder open-ended, which removes the top and bottom surfaces of the cylinder such that the inside is visible. A double-sided material will be needed to render properly:

<!-- Tube -->
<a-entity geometry="primitive: cylinder; openEnded: true" material="side: double"></a-entity>

Curved Surface

Curved surfaces can be defined by specifying the angle via thetaLength such that the cylinder doesn’t curve all the way around, making the cylinder open-ended, and then making the material double-sided.

<!-- Curved surface -->
<a-entity geometry="primitive: cylinder; openEnded: true; thetaLength: 180"
material="side: double"></a-entity>
PropertyDescriptionDefault Value
radiusRadius of the cylinder.1
heightHeight of the cylinder.2
segmentsRadialNumber of segmented faces around the circumference of the cylinder.36
segmentsHeightNumber of rows of faces along the height of the cylinder.18
openEndedWhether the ends of the cylinder are open (true) or capped (false).false
thetaStartStarting angle in degrees.0
thetaLengthCentral angle in degrees.360

Prisms

Other types of prisms can be defined by varying the number of radial segments (i.e., sides). For example, to make a hexagonal prism:

<!-- Hexagonal prism -->
<a-entity geometry="primitive: cylinder; segmentsRadial: 6"></a-entity>

To play with an example of prism geometry, check out the Hexagon example on Codepen.

Plane

The plane primitive defines a flat surface. Note that because it is flat, only a single side of the plane will be rendered if side: double is not specified on the material component.

<a-entity geometry="primitive: plane; height: 10; width: 10"
material="side: double"></a-entity>
PropertyDescriptionDefault Value
widthWidth along the X axis.1
heightHeight along the Y axis.1

Ring

The ring geometry defines a flat ring, like a CD. Note that because it is flat, only a single side of the ring will be rendered if side: double is not specified on the material component.

<a-entity geometry="primitive: ring; radiusInner: 0.5; radiusOuter: 1"
material="side: double"></a-entity>
PropertyDescriptionDefault Value
radiusInnerRadius of the inner hole of the ring.1
radiusOuterRadius of the outer edge of the ring.1
segmentsThetaNumber of segments. A higher number means the ring will be more round.32
segmentsPhiNumber of triangles within each face defined by segmentsTheta.8
thetaStartStarting angle in degrees.0
thetaLengthCentral angle in degrees.360

Sphere

The sphere primitive can define spheres in the traditional sense like a basketball. But it can also define various polyhedrons and abstract shapes given that it can specify the number of horizontal and vertical angles and faces.

Sticking with a basic sphere, the default number of segments is high enough to make the sphere appear round.

<a-entity geometry="primitive: sphere; radius: 2"></a-entity>
PropertyDescriptionDefault Value
radiusRadius of the sphere.1
segmentsWidthNumber of horizontal segments.18
segmentsHeightNumber of vertical segments.36
phiStartHorizontal starting angle.0
phiLengthHorizontal sweep angle size.360
thetaStartVertical starting angle.0
thetaLengthVertical sweep angle size.360

Torus

The torus primitive defines a donut shape.

<!-- Half donut -->
<a-entity geometry="primitive: torus; radius: 2; radiusTubular: 0.5; arc: 180"></a-entity>
PropertyDescriptionDefault Value
radiusRadius of the outer edge of the torus.1
radiusTubularRadius of the tube.0.2
segmentsRadialNumber of segments along the circumference of the tube ends. A higher number means the tube will be more round.36
segmentsTubularNumber of segments along the circumference of the tube face. A higher number means the tube will be more round.32
arcCentral angle.360

Torus Knot

The torus knot primitive defines a pretzel shape, the particular shape of which is defined by a pair of coprime integers, p and q. If p and q are not coprime the result will be a torus link.

<a-entity geometry="primitive: torusKnot; p: 3; q:7"></a-entity>
PropertyDescriptionDefault Value
radiusRadius that contains the torus knot.1
radiusTubularRadius of the tubes of the torus knot.0.2
segmentsRadialNumber of segments along the circumference of the tube ends. A higher number means the tube will be more round.36
segmentsTubularNumber of segments along the circumference of the tube face. A higher number means the tube will be more round.32
pNumber that helps define the pretzel shape.2
qNumber that helps define the pretzel shape.3

thetaLength and thetaStart

In degrees, thetaStart defines where to start a circle and thetaLength defines where a circle ends. If we wanted to make a ( shape, we would start the circle halfway through and define the length as half of a circle. We can do this with thetaStart: 180; thetaLength: 180. Or if we wanted to make a ) shape. We can do do thetaStart: 0; thetaLength: 180.

Useful cases might be to animating thetaStart to create a spinner effect or animating thetaLength on a fuse-based cursor for visual feedback.

translate

The translate property translates the geometry. It is provided as a vec3. This is a useful short-hand for translating the geometry to effectively move its pivot point when running animations.

<!-- Translates the sphere such that its effective pivot point is at its bottom -->
<a-entity geometry="primitive: sphere; radius: 1; translate: 0 1 0"></a-entity>

Defining Your Own Geometry

If there is a geometry that you need that is not provided by the standard geometry component, you can register your own geometry component. Later, we may introduce an API to register geometries:

```js AFRAME.registerComponent(‘my-geometry’, { / Called on component attach and data update. / update: function () { // Grab the mesh. var mesh = this.el.getOrCreateObject3D(‘mesh’, THREE.Mesh);

// Provide your own geometry.
var geometry = mesh.geometry = new THREE.Geometry();
geometry.vertices.push(
  new THREE.Vector3(-10,  10, 0),
  new THREE.Vector3(-10, -10, 0),
  new THREE.Vector3( 10, -10, 0)
);
geometry.faces.push(new THREE.Face3(0, 1, 2));
geometry.computeBoundingSphere();

},

/ Called on component detach. / remove: function () { this.el.getObject3D(‘mesh’).geometry = new THREE.Geometry(); } });