getting-started.rst 6.67 KB
Newer Older
Philip Trettner's avatar
Philip Trettner committed
1
2
3
Getting Started
===============

Philip Trettner's avatar
Philip Trettner committed
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
Quickstart
----------

::

    // this header includes the most important parts of polymesh
    #include <polymesh/pm.hh>

    // polymesh is often used with a math library, like typed-geometry
    #include <typed-geometry/tg.hh>

    // a Mesh is purely topological, like a graph with vertices, edges, faces
    // polymesh is a half-edge data structure
    pm::Mesh m;

    // attributes are associated with a certain primitive type
    // they behave like a std::vector<T> but automatically resize on topology changes
    auto pos = pm::vertex_attribute<tg::pos3>(m);

    // non-core functionality is implemented as free functions
    // like loading from file
    pm::load("/path/to/mesh.ext", m, pos);

    // topological iteration is supported with a strong functional flavor
    // "handles" are "smart" and can be used to navigate the mesh
    auto smoothed_pos = pm::vertex_attribute<tg::pos3>(m);
    for (auto v : m.vertices())
        smoothed_pos[v] = v.adjacent_vertices().avg(pos);


Philip Trettner's avatar
Philip Trettner committed
34
35
36
37
38
39
40
41
Namespaces
----------

In its implementation, polymesh uses the ``polymesh::`` namespace.
However, long namespace are cumbersome and by default ``pm::`` is provided as an alias.
All examples will use the short version.


Philip Trettner's avatar
Philip Trettner committed
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
CMake Integration
-----------------

Assuming that polymesh was cloned or copied into ``extern/polymesh``, the following CMake snippet will configure and set up the library.

.. code-block:: cmake

    # example math library
    add_subdirectory(extern/typed-geometry)

    # include polymesh CMakeLists.txt
    add_subdirectory(extern/polymesh)

    # make polymesh library available to MyProject
    target_link_libraries(MyProject PUBLIC polymesh)

A math library is optional but recommended (see :doc:`vector-math`).


Philip Trettner's avatar
Philip Trettner committed
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
Philosophy
----------

Polymesh provides a mesh data structure (:class:`polymesh::Mesh`) that contains and manages the mesh topology in a half-edge data structure (see :doc:`mesh-topology`).

A mesh has no positions or normals, no attributes in general.
Instead, attributes are separate value types that behave like a ``std::vector`` but in a type-safe manner with automatic resize on topology change (see :doc:`attributes`).

Algorithms are kept as generic as possible, most are templated on the type of the position.
Polymesh is designed to work with a broad class of math libraries (see :doc:`vector-math` and :doc:`algorithms`).

Except for some core functionality, :doc:`algorithms` and :doc:`properties` are implemented as free functions.
This makes it easy to extend and favors an include-what-you-use approach, reducing compile times in the process.

Working with meshes and attributes involves a lot of iteration.
Often, aggregate statistics like averages, minimums, maximums, and mapped/filtered ranges are needed.
Thus, polymesh provides a clean, composable, and powerful range API (see :doc:`mesh-topology` and :doc:`smart-ranges`).

Philip Trettner's avatar
Philip Trettner committed
79
80
81
Polymesh is performance-oriented but still concerned with usability and safety.
C++ Exceptions are not used but many assertions will trigger in Debug or RelWithDebInfo builds if the API is used wrongly.

Philip Trettner's avatar
Philip Trettner committed
82

Philip Trettner's avatar
Philip Trettner committed
83
84
85
Header Structure
----------------

Philip Trettner's avatar
Philip Trettner committed
86
87
A quick guide for which ``#include <...>`` directives are commonly needed:

Philip Trettner's avatar
Philip Trettner committed
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
``polymesh/fwd.hh``
    Forward declarations of all important types.

``polymesh/pm.hh``
    Most important types and functions, including meshes, attributes, IO, properties.

``polymesh/pm-std.hh``
    Same as ``/pm.hh`` but also includes useful interop with the C++ standard library. Individual interop is located in ``polymesh/std/*``.

``polymesh/Mesh.hh``
    The central data structure, ``pm::Mesh``. Due to dependencies also includes attributes.

``polymesh/formats.hh``
    Basic versions of all input/output formats.
    Individual formats are located in ``polymesh/formats/*``.

``polymesh/objects.hh``
    Helper functions for creating primitives like cubes and spheres.

``polymesh/algorithms.hh``
    Umbrella header for all built-in mesh algorithms. 
    Individual algorithms can be found in ``polymesh/algorithms/*``.

Philip Trettner's avatar
Philip Trettner committed
111
``polymesh/properties.hh``
Philip Trettner's avatar
Philip Trettner committed
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
    Basic topological and geometrical properties like face area, valence, and angle defect.

``polymesh/objects.hh``
    Helper functions for creating primitives like cubes and spheres.
    Individual objects are located in ``polymesh/objects/*``.

``polymesh/ext/attribute-collection.hh``
    Type-erased collection of named attributes. Convenient for generic attribute save/load.

``polymesh/attributes/*``
    Special attribute types like flags and partitionings.


Documentation Structure
-----------------------
Philip Trettner's avatar
Philip Trettner committed
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

:doc:`mesh-topology`
    Describes how mesh topology is stored in the :class:`polymesh::Mesh` class, how primitives are accessed via handles and indices, how topological iteration works, how memory is managed, and how the low-level API can be used to manipulate the internal half-edge data structure.

:doc:`attributes`
    Introduces the "external, smart attributes" design and more advanced topics like flags, partitionings, sparse attributes, and views.

:doc:`vector-math`
    Polymesh does not provide its own math library but assumes an external one is used.
    This section describes which math libraries are recommended and tested and what requirements must be met if a custom math library is to be used.

:doc:`smart-ranges`
    Geometry processing involves a lot of iteration and polymesh supports this with a clean, functional, and powerful "smart range" approach.

:doc:`properties`
    Many topological and geometrical properties like edge lengths, valences, areas, etc. are free functions usable in a composable and generic manner.

:doc:`algorithms`
    Polymesh is mostly "batteries included" and provides many important algorithms and basic operations like edge splits, decimation, smoothing, triangulation, subdivision, and many more.

:doc:`serialization`
    Saving and loading meshes is supported for several popular file formats.
    There are also type-erased ways to store arbitrary attributes.

:doc:`objects`
    Sometimes, meshes are not loaded from file but created from primitives like cubes, spheres, cylinders, etc.
    Many primitive objects are supported out-of-the-box.

:doc:`misc`
    Polymesh provides some miscellaneous support code like custom high-performance assertions or a ``span`` type.

:doc:`cookbook`
    The "Polymesh Cookbook" contains several recipes for common problems/operations in a "how do I do XYZ?"-fashion.

:doc:`faq`
    A collection of common questions or misconceptions.

:doc:`reference`
    Class reference generated mainly by Doxygen that documents noteworthy individual functions and classes.

:doc:`contributing`
    A small guide of code style, philosophy, and tips should anyone want to contribute to polymesh (which we heavily welcome!).