Including PyGeometry 101 examples

doc/source/conf.py

@@ -155,12 +155,17 @@
     ".mystnb": ["jupytext.reads", {"fmt": "mystnb"}],
 }
 nbsphinx_thumbnails = {
-    "examples/basic_usage": "_static/thumbnails/basic_usage.png",
-    "examples/dynamic_sketch_plane": "_static/thumbnails/dynamic_sketch_plane.png",
-    "examples/add_design_material": "_static/thumbnails/add_design_material.png",
-    "examples/plate_with_hole": "_static/thumbnails/plate_with_hole.png",
-    "examples/tessellation_usage": "_static/thumbnails/tessellation_usage.png",
-    "examples/design_organization": "_static/thumbnails/design_organization.png",
+    "examples/01_getting_started/01_math": "_static/thumbnails/101_getting_started.png",
+    "examples/01_getting_started/02_units": "_static/thumbnails/101_getting_started.png",
+    "examples/01_getting_started/03_sketching": "_static/thumbnails/101_getting_started.png",
+    "examples/01_getting_started/04_modeling": "_static/thumbnails/101_getting_started.png",
+    "examples/02_sketching/basic_usage": "_static/thumbnails/basic_usage.png",
+    "examples/02_sketching/dynamic_sketch_plane": "_static/thumbnails/dynamic_sketch_plane.png",
+    "examples/02_sketching/advanced_sketching_gears": "_static/thumbnails/advanced_sketching_gears.png",  # noqa: E501
+    "examples/03_modeling/add_design_material": "_static/thumbnails/add_design_material.png",
+    "examples/03_modeling/plate_with_hole": "_static/thumbnails/plate_with_hole.png",
+    "examples/03_modeling/tessellation_usage": "_static/thumbnails/tessellation_usage.png",
+    "examples/03_modeling/design_organization": "_static/thumbnails/design_organization.png",
 }
 nbsphinx_epilog = """
 ----

doc/source/examples.rst

@@ -3,34 +3,36 @@ Examples
 
 These examples demonstrate the behavior and usage of PyGeometry.
 
-Math and sketch examples
-------------------------
-These examples demonstrate math operations on geometric objects
-and basic sketching capabilities.
+PyGeometry 101 demos
+--------------------
+These examples demonstrate basic demos of different operations you
+can perform with PyGeometry.
 
 .. nbgallery::
 
-    examples/basic_usage.mystnb
-
-Service-based examples
-----------------------
+    examples/01_getting_started/01_math.mystnb
+    examples/01_getting_started/02_units.mystnb
+    examples/01_getting_started/03_sketching.mystnb
+    examples/01_getting_started/04_modeling.mystnb
 
-These examples demonstrate service-based operations.
+Sketching examples
+------------------
+These examples demonstrate math operations on geometric objects
+and sketching capabilities - combined with server-based operations.
 
 .. nbgallery::
 
-    examples/add_design_material.mystnb
-    examples/plate_with_hole.mystnb
-    examples/tessellation_usage.mystnb
-    examples/design_organization.mystnb
-
-Advanced sketching features
----------------------------
+    examples/02_sketching/basic_usage.mystnb
+    examples/02_sketching/dynamic_sketch_plane.mystnb
+    examples/02_sketching/advanced_sketching_gears.mystnb
 
-These examples demonstrate advanced sketching features - combined with
-server-based operations.
+Modeling examples
+-----------------
+These examples demonstrate service-based modeling operations.
 
 .. nbgallery::
 
-    examples/dynamic_sketch_plane.mystnb
-    examples/advanced_sketching_gears.mystnb
+    examples/03_modeling/add_design_material.mystnb
+    examples/03_modeling/plate_with_hole.mystnb
+    examples/03_modeling/tessellation_usage.mystnb
+    examples/03_modeling/design_organization.mystnb

doc/source/examples/01_getting_started/01_math.mystnb

@@ -0,0 +1,165 @@
+---
+jupytext:
+  text_representation:
+    extension: .mystnb
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.14.1
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+# PyGeometry 101: math
+
+The ``math`` module is the foundation of PyGeometry. This foundation is built on top of
+[NumPy](https://numpy.org/), one of the most renowned mathematical Python libraries.
+
+In this demo, some of the main PyGeometry math objects are shown
+and it is shown why they are important prior to doing more exciting things in PyGeometry.
+
++++
+
+## Perform required imports
+
+Start by performing the required imports.
+
+```{code-cell} ipython3
+import numpy as np
+
+from ansys.geometry.core.math import Plane, Point2D, Point3D, Vector2D, Vector3D, UnitVector3D
+```
+
+### ``Point`` and ``Vector``
+
+Everything starts with ``Point`` and ``Vector``, which can each be defined in a 2D or 3D form.
+These objects inherit from NumPy's ``ndarray``, providing them with enhanced functionalities.
+It is very important to remember to pass in the arguments as a list (that is, with brackets ``[ ]``)
+when creating these objects.
+
+```
+Point3D([x, y, z])
+Point2D([x, y])
+
+Vector3D([x, y, z])
+Vector2D([x, y])
+```
+
+You can perform standard mathematical operations on these objects like the following.
+
+```{code-cell} ipython3
+vec_1 = Vector3D([1,0,0]) # x-vector
+vec_2 = Vector3D([0,1,0]) # y-vector
+
+print("Sum of vectors [1, 0, 0] + [0, 1, 0]:")
+print(vec_1 + vec_2) # sum
+
+print("\nDot product of vectors [1, 0, 0] * [0, 1, 0]:")
+print(vec_1 * vec_2) # dot
+
+print("\nCross product of vectors [1, 0, 0] % [0, 1, 0]:")
+print(vec_1 % vec_2) # cross
+```
+
+You can also create a ``Vector`` from 2 points.
+
+```{code-cell} ipython3
+p1 = Point3D([12.4, 532.3, 89])
+p2 = Point3D([-5.7, -67.4, 46.6])
+
+vec_3 = Vector3D.from_points(p1, p2)
+vec_3
+```
+
+You can normalize any vector to create a unit vector, also sometimes known as a ``Direction``.
+
+```{code-cell} ipython3
+print("Magnitude of vec_3:")
+print(vec_3.magnitude)
+
+print("\nNormalized vec_3:")
+print(vec_3.normalize())
+
+print("\nNew magnitude:")
+print(vec_3.normalize().magnitude)
+```
+
+There is also a ``UnitVector`` class that will automatically normalize the input.
+
+```{code-cell} ipython3
+uv = UnitVector3D([1,1,1])
+uv
+```
+
+Here are a few more convenient mathematical operations.
+
+```{code-cell} ipython3
+v1 = Vector3D([1, 0, 0])
+v2 = Vector3D([0, 1, 0])
+
+print("Vectors are perpendicular:")
+print(v1.is_perpendicular_to(v2))
+
+print("\nVectors are parallel:")
+print(v1.is_parallel_to(v2))
+
+print("\nVectors are opposite:")
+print(v1.is_opposite(v2))
+
+print("\nAngle between vectors:")
+print(v1.get_angle_between(v2))
+print(f"{np.pi / 2} == pi/2")
+```
+
++++
+
+### ``Plane`` objects
+
+``Plane`` objects also become very important once we get into creating sketches and bodies. It is defined by:
+- An ``origin``, which consists of a ``Point3D``.
+- Two directions which are ``direction_x`` and ``direction_y``, both of them ``UnitVector3D``objects.
+
+If no direction vectors are provided, the ``Plane`` will default to the XY plane.
+
+```{code-cell} ipython3
+plane = Plane(Point3D([0,0,0])) # XY plane
+
+print("(1, 2, 0) is in XY plane:")
+print(plane.is_point_contained(Point3D([1, 2, 0]))) # True
+
+print("\n(0, 0, 5) is in XY plane:")
+print(plane.is_point_contained(Point3D([0, 0, 5]))) # False
+```
+
++++
+
+## Parametric evaluations
+
+Parametric evaluations for some curves and surfaces are also implemented. Here is a brief example for a sphere.
+
+```{code-cell} ipython3
+from ansys.geometry.core.primitives.sphere import Sphere, SphereEvaluation
+from ansys.geometry.core.math import Point3D
+from ansys.geometry.core.misc import Distance
+
+sphere = Sphere(Point3D([0,0,0]), Distance(1)) # radius = 1
+
+eval = sphere.project_point(Point3D([1,1,1]))
+
+print("U Parameter:")
+print(eval.parameter.u)
+
+print("\nV Parameter:")
+print(eval.parameter.v)
+```
+
+```{code-cell} ipython3
+print("Point on the sphere:")
+eval.position()
+```
+
+```{code-cell} ipython3
+print("Normal to the surface of the sphere at the evaluation position:")
+eval.normal()
+```