geometry

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

The geometry component provides a basic shape for an entity. The primitive property defines the general shape. Geometric primitives, in computer graphics, are irreducible basic shapes. A material component is commonly defined to provide an appearance alongside the shape to create a complete mesh.

Base Properties

Every geometry type will have these properties:

Built-in Geometries

box

The box geometry defines boxes (i.e., any quadrilateral, not just cubes).

<a-entity geometry="primitive: box; width: 1; height: 1; depth: 1"></a-entity>

circle

The circle geometry creates flat two-dimensional circles. These can be complete circles or partial circles (like Pac-Man). Note that because circles are flat, A-Frame will only render a single face of the circle if we don’t specify side: double on the material component.

<a-entity geometry="primitive: circle; radius: 1" material="side: double"></a-entity>

thetaLength and thetaStart Properties

In degrees, thetaStart defines where to start a circle or arc and thetaLength defines where a circle or arc 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 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.

cone

The cone geometry is a cylinder geometry that have different top and bottom radii.

<a-entity geometry="primitive: cone; radiusBottom: 1; radiusTop: 0.1"></a-entity>

cylinder

The cylinder geometry creates cylinders in the traditional sense like a Coca-Cola™ can, but it can also define shapes such as tubes and curved surfaces.

We can create a basic cylinder using height and radius:

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

We can create a tube by making the cylinder open-ended, which removes the top and bottom surfaces of the cylinder such that the inside is visible. Then we need a double-sided material to render properly:

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

We can create a curved surfaces by specifying the arc 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>

We can create prisms by changing 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>

dodecahedron

The dodecahedron geometry creates a polygon with twelve equally-sized faces.

<a-entity geometry="primitive: dodecahedron; radius: 2"></a-entity>

octahedron

The octahedron geometry creates a polygon with eight equilateral triangular faces.

<a-entity geometry="primitive: octahedron"></a-entity>

plane

The plane geometry creates a flat surface. Because planes are flat, A-Frame will render only a single face of the plane unless we specify side: double on the material component.

<a-entity geometry="primitive: plane; height: 10; width: 10" material="side: double"></a-entity>

ring

The ring geometry creates a flat ring, like a CD. Because the ring is flat, A-Frame will only render a single face of the ring unless we specify side: double the material component.

<a-entity geometry="primitive: ring; radiusInner: 0.5; radiusOuter: 1"
          material="side: double"></a-entity>

sphere

The sphere geometry creates spheres (e.g., balls). We can create a basic sphere:

<a-entity geometry="primitive: sphere; radius: 2"></a-entity>

We can create polyhedrons and abstract shapes by specifying the number of horizontal angles and faces:

<a-entity geometry="primitive: sphere; segmentsWidth: 2; segmentsHeight: 8"></a-entity>

tetrahedron

The tetrahedron geometry creates a polygon with four triangular faces.

<a-entity geometry="primitive: tetrahedron; radius: 2"></a-entity>

torus

The torus geometry creates a donut or curved tube shape:

<!-- Half donut -->
<a-entity geometry="primitive: torus; radius: 2; radiusTubular: 0.5; arc: 180"></a-entity>

torusKnot

The torus knot geometry creates a pretzel shape. A pair of coprime integers, p and q, defines the particular shape of the pretzel. 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>

triangle

The triangle geometry creates a flat two-dimensional triangle. Because triangles are flat, A-Frame will render only a single face, which is the one with vertexA, vertexB, and vertexC appear in counterclockwise order on the screen, unless we specify side: double on the material component.

<a-entity geometry="primitive: triangle" material="side: double"></a-entity>

Register a Custom Geometry

We can register our own geometries using AFRAME.registerGeometry and creating an object that is an instance of THREE.Geometry. A-Frame registers all built-in geometries using this API. Here is how A-Frame registers the box geometry:

AFRAME.registerGeometry('box', {
  schema: {
    depth: {default: 1, min: 0},
    height: {default: 1, min: 0},
    width: {default: 1, min: 0},
    segmentsHeight: {default: 1, min: 1, max: 20, type: 'int'},
    segmentsWidth: {default: 1, min: 1, max: 20, type: 'int'},
    segmentsDepth: {default: 1, min: 1, max: 20, type: 'int'}
  },

  init: function (data) {
    this.geometry = new THREE.BoxGeometry(data.width, data.height, data.depth);
  }
});

Like with registering components, we provide a name, a schema that will expose the properties of the geometry, and lifecycle methods. Then we need to create the geometry and set on this.geometry through the init lifecycle method.

When a geometry component sets its primitive property to the custom geometry name, we can set the properties of the custom geometry on the geometry component. Say we registered a custom geometry:

AFRAME.registerGeometry('example', {
  schema: {
    vertices: {
      default: ['-10 10 0', '-10 -10 0', '10 -10 0'],
    }
  },

  init: function (data) {
    var geometry = new THREE.Geometry();
    geometry.vertices = data.vertices.map(function (vertex) {
        var points = vertex.split(' ').map(function(x){return parseInt(x);});
        return new THREE.Vector3(points[0], points[1], points[2]);
    });
    geometry.computeBoundingBox();
    geometry.faces.push(new THREE.Face3(0, 1, 2));
    geometry.mergeVertices();
    geometry.computeFaceNormals();
    geometry.computeVertexNormals();
    this.geometry = geometry;
  }
});

We can then use that custom geometry in HTML:

<a-entity geometry="primitive: example; vertices: 1 1 -3, 3 1 -3, 2 2 -3"></a-entity>