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
• Infinite Cylinder
• Cylinder (finite height)
• Slice of cylinder ring
• Infinite Plane
• Cuboid
• Infinite Cone
• Cone

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>

XMLcylinderDescription.png‎

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¶

<cuboid id="shape">
  <left-front-bottom-point x="0.0025" y="-0.1" z="0.0"  />
  <left-front-top-point  x="0.0025" y="-0.1" z="0.02"  />
  <left-back-bottom-point  x="-0.0025" y="-0.1" z="0.0"  />
  <right-front-bottom-point  x="0.0025" y="0.1" z="0.0"  />
</cuboid>
<algebra val="shape" />

This particular example describes a cuboid with the origin at the centre of the front face, which is here facing the negative z-axis and has the dimensions 0.005mm x 0.2mm (in the xy-plane), and the depth of this cuboid is 0.02mm.

XMLcuboidDescription.png

Another example of a cuboid is

<cuboid id="shape">
  <left-front-bottom-point x="0.0" y="-0.1" z="-0.01"  />
  <left-front-top-point  x="0.0" y="0.1" z="-0.01"  />
  <left-back-bottom-point  x="0.001" y="-0.1" z="-0.01"  />
  <right-front-bottom-point  x="0.0" y="-0.1" z="0.01"  />
</cuboid>
<algebra val="shape" />

which describes a cuboid with a front y-z plane (looking down the x-axis). The origin is assumed to be the centre of this front surface, which has dimensions 200mm along y and 20mm along z. The depth of this cuboid is taken to be 1mm (along x).

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.