1======
2Shapes
3======
4
5A shape value represents a geometric shape.
6
7For example, ...
8
9Shape Properties
10================
11
122D and 3D Shapes
13----------------
14Every shape is marked as being 2-dimensional, 3-dimensional, or both.
152D shapes are embedded in the XY plane.
16(The only standard shapes that are both are ``everything`` and ``nothing``.)
17
18Infinite and Degenerate Shapes
19------------------------------
20A shape can be infinite. Many shape constructors accept ``inf`` as a dimension argument.
21
22A 2D shape with no area, or a 3D shape with no volume, is called degenerate.
23Examples are geometric points, line segments or curves, and in 3D, surfaces with 0 thickness.
24
25Points and curves are invisible in the preview window, while surfaces are visible.
26Infinite and degenerate shapes are useful as intermediates for constructing
27shapes, even though you can't 3D print them or export them to some file formats.
28
29Colour
30------
31Shapes have volumetric colour.
32A function assigns a colour to each point in the interior and on the boundary
33of every 2D and 3D shape. Primitive shapes are assigned a default yellowish colour,
34which you change using the ``colour`` function.
35Shape operations must specify how the colour of the result shape derives from the
36colour of the argument shapes.
37(Colour assignment and colour transformation operators will be researched elsewhere,
38in `<Colour_Atlas.rst>`_.)
39
40Signed Distance Fields
41----------------------
42Shapes are represented internally as Signed Distance Fields (SDFs), see `<Theory.rst>`_.
43This is not a unique representation: a given shape can be represented by many different SDFs.
44In most cases, the user just wants to let the implementation choose an SDF that is fast
45to compute and fast to render.
46
47However, there are Distance Field Operations (see section 4)
48that construct a shape based on the SDF of an input shape.
49These operations are too useful to leave out.
50For this reason, we document the class of SDF created by each shape operation.
51
52These are the SDF classes:
53
54exact:
55  The distance field contains the exact Euclidean distance to the nearest boundary.
56  The ``offset`` operation will create a rounded offset.
57mitred:
58  Like exact, except vertex and edge information is preserved in all isosurfaces.
59  This can be useful in conjunction with distance field operations.
60  The ``offset`` operation will create a mitred offset.
61approximate:
62  The SDF is implementation dependent, and may change between releases
63  as the library is optimized.
64bad:
65  Worse than approximate: the SDF is Lipschitz continuous with a Lipschitz constant > 1.
66  Sphere tracing won't work unless you correct the SDF using the ``lipschitz`` operator.
67  The correction factor needs to be determined experimentally by the user.
68discontinuous:
69  Worse than bad: the SDF is not Lipschitz continuous, and can't be corrected by the ``lipschitz`` operator.
70  This situation can occur when experimenting with ``make_shape``.
71
72Bounding Box
73------------
74Each shape has an axis aligned bounding box, which may be either exact or approximate.
75An approximate bounding box is larger than necessary to contain the shape.
76
77All of the shape constructors create exact bounding boxes.
78Some of the shape combinators produce exact bounding boxes if their input is exact,
79(as documented), but many create approximate bounding boxes.
80
81You need to worry about whether a bounding box is approximate or exact
82if you use a shape combinator that uses the bounding box of its input
83to determine the shape of its output.
84