mXrap - XShapes Tutorial

This page describes some of the common types used in mXrap JavaScript.

What is the XShapes library?

The XShapes library is a mXrap JS library that allows the creation and addition of shapes like spheres and cylinders to 3D Views.

To include the XShapes library in your script, add the following snippet to your code:

const XShapes = load('js/standard/xshapes.js');

How are surfaces defined in mXrap?

In mXrap, surfaces are defined using two tables - a Vertices table containing the locations of points, and a Faces table, which define triangles or quad polygons based on the points in the Vertices Table.

The following simple example - for example, defines a rectangle:

Vertices
ID  Location
1   (0, 0, 0)
2   (0, 0, 10)
3   (10, 0, 10)
4   (10, 0, 0)

Faces
ID  V1  V2  V3  V4
1   1   2   3   4

The Faces table's V1...V4 fields reference the ID field in the Vertices table. Vertices defined can be reused across different Faces.

When you add a "Surfaces" series to a 3D View in mXrap, you would be able to specify the Vertices and Faces tables, and their fields.

How does the XShapes library output shapes via the two tables?

The XShapes library uses a GraphicsAdapter object to output shapes to the two tables. The simplest way to create the GraphicsAdapter object is to define the two tables as below (with the requisite javascript names).

Output table "Vertices" 
JS Name "ID"    type "ID"    field name "ID"
JS Name "Location"  type "Point"   field name "Location"
JS Name "FK"   type "ID"     field name "FK" 

Output table "Faces" 
JS Name "ID"    type "ID"    field name "ID"
JS Name "V1"    type "ID"    field name "V1"
JS Name "V2"    type "ID"    field name "V2"
JS Name "V3"    type "ID"    field name "V3"
JS Name "V4"    type "ID"    field name "V4"

and then define the object as:

const GraphicsAdapter = XShapes.Graphics.createPresetAdapter(Vertices, Faces);

If you want to use different field names for your tables, you can instead use this function (substituting the appropriate table functions):

const GraphicsAdapter = XShapes.Graphics.createAdapter(Vertices, Vertices.write_ID, Vertices.write_Location, Vertices.write_FK, Faces, Faces.write_ID, Faces.write_V1, Faces.write_V2, Faces.write_V3, Faces.write_V4);

I have my GraphicsAdapter object. How do I start adding shapes to my tables so I can see them in my 3D View?

The easiest way to add shapes is to use the functions in the "Simple" category. These functions provide a simple interface to add the supported shapes without exposing all the options.

For example, you would be able to create a sphere or cylinder of the appropriate size and orientation, but you wouldn't be able to specify to render only part of the sphere or cylinder - something which the functions in the "Create" category will allow you to do (but with a more complex interface).

Example, to create a sphere of radius 20 at (100, 150,120):

const location = [100, 150, 120];
const radius = 20;
const upDirection = [0, 0, 1];
const key = 0;
const sphereShape = XShapes.Simple.sphere(null, location, radius, upDirection, key);
sphereShape.writeShape(graphicsAdapter);

The first "null" parameter indicates we are creating a new shape, rather than adding the sphere to an existing shape. Working with shape objects is described later in this tutorial in the section "Shape Operations".

The upDirection specification is necessary because of how the sphere is generated - we use UV spheres, which means its generated towards a certain orientation. [0, 0, 1] works for most of your cases.

The key parameter is explained in detail later in this tutorial in the section "Key and Colouring", for now 0 will suffice.

What shapes are supported in the XShapes library?

Shape	Code
	Quad Specify the 4 points that make up the quad. const quadShape = XShapes.Simple.quad(null, [0, 0, 0], [0, 0, 10], [0, 10, 10], [0, 10, 0], key); quadShape.writeShape(graphicsAdapter);
	Triangle Specify the 3 points that make up the triangle. const triShape = XShapes.Simple.tri(null, [20, 0, 0], [20, 0, 10], [20, 10, 10], key); triShape.writeShape(graphicsAdapter);
	Circle Specify the center point of the circle, its radius, and then the normal vector of the circle (the direction it faces). const circleShape = XShapes.Simple.circle(null, [40, 5, 5], 5, [0, 1, 0], key); circleShape.writeShape(graphicsAdapter);
	Arrow Specify the "point from" and the "point to" of the arrow. The arrow head is on the "point to" end. const arrowShape = XShapes.Simple.arrow(null, [60, 10, 10], [60, 0, 0], key); arrowShape.writeShape(graphicsAdapter);
	Sphere Specify the center point of the sphere, its radius, and its "up-direction" (axis along which the UV sphere is generated). const sphereShape = XShapes.Simple.sphere(null, [100, 5, 5], 5, [0, 0, 1], key); sphereShape.writeShape(graphicsAdapter);
	Spheroid A spheroid is a sphere with different radii along two axes, so you could generate a stretched "egg". Specify the center point of the sphere, its radius along its widest point, its length, and its "up-direction" (axis along which the UV spheroid is generated). const spheroidShape = XShapes.Simple.spheroid(null, [80, 5, 5], 5, 8, [0, 0, 1], key); spheroidShape.writeShape(graphicsAdapter);
	Regular Cuboid Specify the minimum and maximum points of the cuboid. const cuboidShape = XShapes.Simple.cuboidRegular(null, [120, 0, 0], [130, 10, 10], key); cuboidShape.writeShape(graphicsAdapter);
	Cuboid Specify the 8 points of the cuboid, the first 4 forming a rectangle, and the second 4 forming the other rectangle. const cuboidShape = XShapes.Simple.cuboid(null, [160, 0, 0], [160, 0, 20], [160, 20, 20], [160, 20, 0], [170, 0, 0], [170, 0, 10], [170, 10, 10], [170, 10, 0], key); cuboidShape.writeShape(graphicsAdapter);
	Cone Specify the start . The last parameter indicates whether to render the circle at the base of the cone (true in this example) const coneShape = XShapes.Simple.cone(null, [0, 40, 10], [0, 40, 0], 5, key, true); coneShape.writeShape(graphicsAdapter);
	Cylinder Specify the start and end points of the cylinder, then the radius of the cylinder at the start and end points (they can be different, as in this example). The last parameter indicates whether to render the circles at the ends of the cylinder (true in this example) const cylShape = XShapes.Simple.cylinder(null, [20, 40, 0], [20, 40, 10], 5, 8, key, true); cylShape.writeShape(graphicsAdapter);
	Disc A disc is made up of an outer and an inner cylinder, and is rendered to resemble a hollow cylinder. Specify the start and end points of the cylinder, then the radius of the outer cylinder at the start and end points, then the radius of the inner cylinder at the start and end points. The last parameter indicates whether to render the partial circles at the ends of the disc (true in this example) const discShape = XShapes.Simple.XShapes.Simple.disc(null, [40, 40, 0], [40, 40, 10], 5, 8, 4, 5, key, true); discShape.writeShape(graphicsAdapter);
	Pyramid Specify the top point of the pyramid, then the four points of its base. const pyrShape = XShapes.Simple.pyramid(null, [110, 45, 5], [100, 40, 0], [100, 40, 10], [100, 50, 10], [100, 50, 0], key); pyrShape.writeShape(graphicsAdapter);
	Icosphere The icosphere is a sphere shape created by refining a icosahedron. Specify the point of the sphere, and its radius. The last parameter is optional, it specifies how detailed the icosphere should refine down to - 2 is acceptable for most cases (as image), and 3 for cases when you want it to be more detailed (e.g. for a large icosphere). For each further refine, the sphere will take 4x the number of polygons. const sphereShape = XShapes.Simple.icosphere(null, [80, 45, 5], 5, key, 2); sphereShape.writeShape(graphicsAdapter);
	Frame A frame renders as the "struts" of a regular cuboid. Specify the minimum and maximum point of the cuboid. The last parameter is optional, it specifies as an array the width of the "struts" in the three dimensions. const frameShape = XShapes.Simple.frame(null, [60, 40, 0], [70, 50, 10], key, [0.5, 1, 0.5]); frameShape.writeShape(graphicsAdapter);