How To Define Geometric Shape¶

Primitive Shapes¶

There is direct support for defining any of the following geometric shapes to add Instrument Definition File.

• Sphere
• Cylinder (finite height)
• Hollow Cylinder (finite height)
• Infinite Cylinder
• Slice of Cylinder Ring
• Cone
• Infinite Cone
• Infinite Plane
• Cuboid
• Hexahedron
• Tapered Guide

Combining Primitive shapes¶

In addition to the shapes listed above, other shapes may be defined by combining already defined shapes into new ones. This is done using an algebra that follows the following notation:

Axes and units of measure¶

All objects are defined with respect to cartesian axes (x,y,z), and the default unit of all supplied values are metres(m). Objects may be defined so that the origin (0,0,0) is at the centre, so that when rotations are applied they do not also apply an unexpected translation.

Within instrument definitions we support the concept of defining a rotation by specifying what point the object is facing. To apply that correctly the side of the object we consider to be the front is the xy plane. Hence, when planning to use facing the shape should be defined such that the positive y-axis is considered to be up, the x-axis the width, and the z-axis the depth of the shape.

Defining a sphere¶

<sphere id="some-sphere">
  <centre x="0.0"  y="0.0" z="0.0" />
  <radius val="0.5" />
</sphere>

<algebra val="some-sphere" />

Any shape must be given an ID name. Here the sphere has been given the name “some-sphere”. The purpose of the ID name is to use it in the description, here this is done with the line . The description is optional. If it is left out the algebraic intersection is taken between any shapes defined.

Defining a ball with a hole through it along the x-axis¶

<cylinder id="stick">
  <centre-of-bottom-base x="-0.5" y="0.0" z="0.0" />
  <axis x="1.0" y="0.0" z="0.0" />
  <radius val="0.05" />
  <height val="1.0" />
</cylinder>

<sphere id="some-sphere">
  <centre x="0.0"  y="0.0" z="0.0" />
  <radius val="0.5" />
</sphere>

<algebra val="some-sphere (# stick)" />

This algebra string reads as follows: take the intersection between a sphere and the shape defined by all points not inside a cylinder of length 1.0 along the x-axis. Note the brackets around # stick in the algebraic string are optional, but here included to emphasis that the “space” between the “some-sphere” and “(# stick)” is the intersection operator.

Sphere¶

<sphere id="A">
  <centre x="4.1"  y="2.1" z="8.1" />
  <radius val="3.2" />
</sphere>

Cylinder¶

<cylinder id="A">
  <centre-of-bottom-base r="0.0" t="0.0" p="0.0" />  <!-- here position specified using spherical coordinates -->
  <axis x="0.0" y="0.2" z="0" />
  <radius val="1" />
  <height val="10.2" />
</cylinder>

Schematic of a cylinder

Hollow Cylinder¶

<hollow-cylinder id="A">
  <centre-of-bottom-base r="0.0" t="0.0" p="0.0" />  <!-- here position specified using spherical coordinates -->
  <axis x="0.0" y="1.0" z="0" />
  <inner-radius val="0.007" />
  <outer-radius val="0.01" />
  <height val="0.05" />
</hollow-cylinder>

Schematic of a hollow cylinder

Infinite Cylinder¶

<infinite-cylinder id="A" >
  <centre x="0.0" y="0.2" z="0" />
  <axis x="0.0" y="0.2" z="0" />
  <radius val="1" />
</infinite-cylinder>

Slice of Cylinder Ring¶

<slice-of-cylinder-ring id="A">
  <inner-radius val="0.0596"/>
  <outer-radius val="0.0646"/>
  <depth val="0.01"/>
  <arc val="45.0"/>
</slice-of-cylinder-ring>

This XML element defines a slice of a cylinder ring. Most importantly the part of this shape facing the sample is flat and looks like this:

XMLsliceCylinderRingDescription.png

Cone¶

<cone id="A" >
  <tip-point x="0.0" y="0.2" z="0" />
  <axis x="0.0" y="0.2" z="0" />
  <angle val="30.1" />
  <height val="10.2" />
</cone>

XMLconeDescription.png

Infinite Cone¶

<infinite-cone id="A" >
  <tip-point x="0.0" y="0.2" z="0" />
  <axis x="0.0" y="0.2" z="0" />
  <angle val="30.1"  />
</infinite-cone>

Infinite Plane¶

Is the 3D shape of all points on the plane and all points on one side of the infinite plane, the side which point away from the infinite plane in the direction of the normal vector.

<infinite-plane id="A">
  <point-in-plane x="0.0" y="0.2" z="0" />
  <normal-to-plane x="0.0" y="0.2" z="0" />
</infinite-plane>

Cuboid¶

Here the dimensions are used to define a 2m x 4m x 0.2m cuboid with its centre at (10,10,10).

<cuboid id="some-cuboid">
  <width val="2.0" />
  <height val="4.0"  />
  <depth  val="0.2" />
  <centre x="10.0" y="10.0" z="10.0"  />
</cuboid>
<algebra val="some-cuboid" />

(Source code, png, hires.png, pdf)

In the next example, four points are used to describe a 2m x 0.8m x 0.4m cuboid with the its centre at the origin.

<cuboid id="shape">
  <left-front-bottom-point x="1" y="-0.4" z="-0.3"  />
  <left-front-top-point  x="1" y="-0.4" z="0.3"  />
  <left-back-bottom-point  x="-1" y="-0.4" z="-0.3"  />
  <right-front-bottom-point  x="1" y="0.4" z="-0.3"  />
</cuboid>
<algebra val="shape" />

(Source code, png, hires.png, pdf)

Hexahedron¶

<hexahedron id="Bertie">
  <left-back-bottom-point  x="0.0" y="0.0" z="0.0"  />
  <left-front-bottom-point x="1.0" y="0.0" z="0.0"  />
  <right-front-bottom-point x="1.0" y="1.0" z="0.0"  />
  <right-back-bottom-point  x="0.0" y="1.0" z="0.0"  />
  <left-back-top-point  x="0.0" y="0.0" z="2.0"  />
  <left-front-top-point  x="0.5" y="0.0" z="2.0"  />
  <right-front-top-point  x="0.5" y="0.5" z="2.0"  />
  <right-back-top-point  x="0.0" y="0.5" z="2.0"  />
</hexahedron>

XMLhexahedronDescription.png

Tapered Guide¶

Available from version 3.0 onwards.

A tapered guide is a special case of hexahedron; a “start” rectangular aperture which in a continued fashion changes into an “end” rectangular aperture.

<tapered-guide id="A Guide">
    <aperture-start height="2.0" width="2.0" />
    <length val="3.0" />
    <aperture-end height="4.0" width="4.0" />
    <centre x="0.0" y="5.0" z="10.0" /> <!-- Optional.  Defaults to (0, 0 ,0) -->
    <axis x="0.5" y="1.0" z="0.0" /> <!-- Optional.  Defaults to (0, 0 ,1) -->
</tapered-guide>

The centre value denotes the centre of the start aperture. The specified axis runs from the start aperture to the end aperture. “Height” is along the y-axis and “width” runs along the x-axis, before the application of the “axis” rotation.

Rotating Shapes¶

Note that some shapes (such as Cylinder (finite height) and Tapered Guide ) can be oriented in a certain direction, using the axis tag, but this representation isn’t general enough to support all possible 3D rotations for all shapes.

Most shapes can be rotated individually or as part of an ensemble, by using the rotate or rotate-all tags respectively. The shapes that can be rotated are: Sphere, Cylinder (finite height), Hollow Cylinder (finite height), Infinite Cylinder, Slice of Cylinder Ring, Infinite Plane, Cuboid, Hexahedron and Tapered Guide.

Use the rotate tag to rotate a shape individually around its centre (or centre-of-bottom-base). The shape is rotated by an angle in degrees around the x,y and z axes in that order. To rotate a cuboid 90° clockwise around x and 45° anti-clockwise around y:

<cuboid id="stick">
  <width val="3.0" />
  <height val="0.5"  />
  <depth  val="0.5" />
  <centre x="0.0" y="0.0" z="0.0"  />
  <rotate x="90" y="-45" z="0" />
</cuboid>

<algebra val="stick" />

Use the rotate-all tag to rotate a combined shape about the origin. To rotate the unison of a sphere on the end of a cylinder (by 90° clockwise around x and 45° anti-clockwise around y):

<cylinder id="stick">
  <centre-of-bottom-base x="-1.0" y="0.0" z="0.0" />
  <axis x="1.0" y="0.0" z="0.0" />
  <radius val="0.2" />
  <height val="2.0" />
</cylinder>

<sphere id="some-sphere">
  <centre x="2.0"  y="0.0" z="0.0" />
  <radius val="0.5" />
</sphere>

<algebra val="some-sphere (: stick)" />
<rotate-all x="90" y="-45" z="0" />

All these rotatable shapes (expect for Infinite Plane and Infinite Cylinder) can be plotted to check your shape definition is correct. For more details see 3D Mesh Plots for Sample Shapes.

Shapes will be automatically rotated, if a rotation is set using SetGoniometer v1. This goniometer rotation is about the origin and can work alongside manual rotation tags. Note the rotations are applied in the order rotate, rotate-all, goniometer.