Nets
Nets are one of our data structures. They represent maps from subdomains of
\(\mathbb{R}^m\) or \(\mathbb{Z}^m\)
into another space \(X\), e.g. parameterized curves or surfaces.
In most cases we will consider maps to \(\mathbb{R}^3.\)
There are different types of nets that all inherit from the
Net class, for example
smooth nets as
or their discrete analogs
Further there is the NetCollection class that can handle collections
of multible nets.
Smooth Nets
Creating a Smooth Net
After creating a domain, we can begin constructing a net.
For this we only need to define the desired function and pass both, the function
and the domain, to the class SmoothNet.
>>> import ddg
>>> import numpy as np
>>> domain = ddg.nets.SmoothDomain([[-4, 4]])
>>> def net_fct(t):
... return np.array([t, 2 * t, 0])
...
>>> net = ddg.nets.SmoothNet(net_fct, domain)
>>> net(0)
array([0, 0, 0])
>>> net(2)
array([2, 4, 0])
Note
As opposed to a DiscreteNet, a SmoothNet
does not store values that have been computed once.
The function of a SmoothNet is evaluated anew each time the net is called
with some point from the domain.
A short hand to create a domain on the fly you can use the following convention:
>>> import ddg
>>> import numpy as np
>>> def net_fct(t):
... return np.array([t, 2 * t, 0])
...
>>> net = ddg.nets.SmoothNet(net_fct, [[-4, 4]])
>>> net(0)
array([0, 0, 0])
>>> net(2)
array([2, 4, 0])
Note that similar to SmoothDomain, SmoothNet
expects a list of intervals when the domain is passed in this way. Similar to SmoothInterval
there is the class SmoothCurve which lifts this restriction.
Further Examples
Example: Paraboloid
>>> import ddg
>>> domain = ddg.nets.SmoothDomain([[-4, 4], [-4, 4]])
>>> def paraboloid_fct(x, y):
... return (x, y, x**2 + y**2)
...
>>> paraboloid_net = ddg.nets.SmoothNet(paraboloid_fct, domain)
Example: Helix
>>> import ddg
>>> import numpy as np
>>> def helix_fct(t):
... return (np.cos(t), np.sin(t), t)
...
>>> helix_net = ddg.nets.SmoothNet(helix_fct, [[-2 * np.pi, 2 * np.pi]])
Example: Torus
>>> import ddg
>>> import numpy as np
>>> def torus_fct(u, v):
... a = 0.2
... b = 1
... x1 = (a * np.cos(u) + b) * np.cos(v)
... x2 = (a * np.cos(u) + b) * np.sin(v)
... x3 = a * np.sin(u)
... return (x1, x2, x3)
...
>>> torus_net = ddg.nets.SmoothNet(
... torus_fct, [[0, 2 * np.pi, True], [0, 2 * np.pi, True]]
... )
Discrete Nets
When we want to visualize our net in Blender, we have to make sure that we pass
discrete information to it. For this we use DiscreteNet. All in all, the process
of creating a discrete net is not any different from creating a smooth one
- we could just replace most instances of “Smooth” with “Discrete” - but we have
to make sure that our domain is a subset of \(\mathbb{Z}^n\). Though it is still
possible to evaluate the net at any given “real” point, only the integer points of the domain
will be used further, e.g. for the visualization in Blender.
Creating a Discrete Net
The process of creating a discrete net mirrors the smooth case, but we have to take care
of mapping our discrete domain to not only valid, but also “reasonable” real points to
achieve our desired result. Similar the smooth case the DiscreteDomain
can be created on the fly as in the following where we will create a discrete net of a circle with 10 points in the
domain. (One can also explicitly create discrete domains.)
>>> import ddg
>>> import numpy as np
>>> def discrete_circle_fct(n):
... t = 2 * np.pi / 10 * n
... return np.array([np.cos(t), np.sin(t), 0])
...
>>> discrete_circle = ddg.nets.DiscreteNet(discrete_circle_fct, [[0, 9, True]])
>>> discrete_circle(0)
array([1., 0., 0.])
You might have noticed that we never reach the value \(t=2\pi\) in the function above. This is by design as the net is periodic.
Warning
As opposed to a SmoothNet, a DiscreteNet
saves every value after it has been computed once.
If you call a DiscreteNet with the same point from the domain a second time
the saved value is returned.
Further Examples
The following examples will show you how you could create discrete nets corresponding to the examples given for smooth nets.
Example: Paraboloid
>>> import ddg
>>> def discrete_paraboloid_fct(x, y):
... x /= 2.5
... y /= 2.5
... return (x, y, x**2 + y**2)
...
>>> discrete_paraboloid = ddg.nets.DiscreteNet(
... discrete_paraboloid_fct, [[-10, 10]] * 2
... )
Example: Helix
>>> import ddg
>>> import numpy as np
>>> def discrete_helix_fct(t):
... t = -2 * np.pi + t
... return (np.cos(t), np.sin(t), t)
...
>>> discrete_helix = ddg.nets.DiscreteNet(discrete_helix_fct, [[0, 11]])
Example: Torus
>>> import ddg
>>> import numpy as np
>>> def discrete_torus_fct(u, v):
... a = 0.2
... b = 1
... s = 2 * np.pi / 10
... u = u * s
... v = v * s
... x1 = (a * np.cos(u) + b) * np.cos(v)
... x2 = (a * np.cos(u) + b) * np.sin(v)
... x3 = a * np.sin(u)
... return (x1, x2, x3)
...
>>> discrete_torus = ddg.nets.DiscreteNet(
... discrete_torus_fct, [[0, 9, True], [0, 9, True]]
... )
The process of converting smooth nets to discrete nets in this fashion is rather tedious. We will go over a different way to achieve this conversion later.
Net Collections
Sometimes an object can not be represented by a single net, but we want to consider
multiple nets as one.
as one. For this we have the Netcollection class.
Net collections are exactly what the name describes: a collection of nets.
>>> import ddg
>>> import numpy as np
>>> def line_fct_1(t):
... return np.array([t, t, 0])
...
>>> def line_fct_2(t):
... return np.array([t, -t, 0])
...
>>> line1 = ddg.nets.SmoothNet(line_fct_1, [[-4, 4]])
>>> line2 = ddg.nets.SmoothNet(line_fct_2, [[-4, 4]])
>>> crossing_lines = ddg.nets.NetCollection([line1, line2])
In the nets module of nets we can find the definition of a
applicable_to_netcollection() decorator.
Any function decorated by it will always be able to be applied to both nets and net collections.
Example: Double Helix
>>> import ddg
>>> import numpy as np
>>> def helix_fct_1(t):
... return (np.cos(t), np.sin(t), t)
...
>>> def helix_fct_2(t):
... return (np.cos(t + np.pi), np.sin(t + np.pi), t)
...
>>> helix_net_1 = ddg.nets.SmoothNet(helix_fct_1, [[-2 * np.pi, 2 * np.pi]])
>>> helix_net_2 = ddg.nets.SmoothNet(helix_fct_2, [[-2 * np.pi, 2 * np.pi]])
>>> double_helix = ddg.nets.NetCollection([helix_net_1, helix_net_2])
Example: Two-sheeted Hyperboloid
>>> import ddg
>>> from ddg.nets import compose
>>> import numpy as np
>>> def first_sheet_fct(u, v):
... return (np.sinh(u) * np.cos(v), np.sinh(u) * np.sin(v), np.cosh(u))
...
>>> def second_sheet_fct(u, v):
... return (np.sinh(u) * np.cos(v), np.sinh(u) * np.sin(v), -np.cosh(u))
...
>>> first_sheet = ddg.nets.SmoothNet(
... first_sheet_fct, [[0, np.inf], [0, 2 * np.pi, True]]
... )
>>> second_sheet = ddg.nets.SmoothNet(
... second_sheet_fct, [[0, np.inf], [0, 2 * np.pi, True]]
... )
>>> two_sheeted_hyperboloid = ddg.nets.NetCollection([first_sheet, second_sheet])
>>> two_sheeted_hyperboloid = compose(np.diag([1, 2, 1]), two_sheeted_hyperboloid)
Function Composition for Nets
We can compose nets with callables and numpy arrays using compose().
If f is a callable or a numpy array and n is a net, then compose(f, n) is a net which maps x to f(n(x)) and has the same domain as n.
Passing a numpy array a to compose() is equivalent to passing lambda x: a @ x.
>>> import ddg
>>> import numpy as np
>>> net = ddg.nets.SmoothNet(
... lambda t: np.array([t, t**2, t**3]), [[-np.inf, np.inf]]
... )
>>> net(2)
array([2, 4, 8])
>>> net = compose(np.diag([0.5, 0.5, 0.5]), net)
>>> net(2)
array([1., 2., 4.])
Some common compositions such as embed(), homogenize() and dehomogenize() are included in the ddg.nets module.
>>> import ddg
>>> import numpy as np
>>> circle = ddg.nets.SmoothNet(
... lambda t: np.array([np.cos(t), np.sin(t)]), [[0, np.pi, True]]
... )
>>> circle(0)
array([1., 0.])
>>> embedded_circle = ddg.nets.embed(circle)
>>> embedded_circle(0)
array([1., 0., 0.])
>>> homogenized_circle = ddg.nets.homogenize(circle)
>>> homogenized_circle(0)
array([1., 0., 1.])
>>> dehomogenized_homogenized_circle = ddg.nets.dehomogenize(homogenized_circle)
>>> dehomogenized_homogenized_circle(0)
array([1., 0.])
Note that the second parameter n of compose must be a net.
If it isn’t a net, there is no need to retain a domain and we can write a new function
>>> def f(t):
... return circle(2 * t)
...
>>> np.allclose(circle(np.pi), [-1, 0])
True
>>> np.allclose(f(np.pi), [1, 0])
True
Example: Torus Inverted in a Unit Sphere
>>> import ddg
>>> import numpy as np
>>> def torus_fct(u, v):
... a = 0.2
... b = 1
... x1 = (a * np.cos(u) + b) * np.cos(v)
... x2 = (a * np.cos(u) + b) * np.sin(v)
... x3 = a * np.sin(u)
... return np.array((x1, x2, x3))
...
>>> torus_net = ddg.nets.SmoothNet(
... torus_fct, [[0, 2 * np.pi, True], [0, 2 * np.pi, True]]
... )
>>> translation = lambda x: np.array([x[0] + 0.2, x[1], x[2]])
>>> inversion = lambda x: x / sum([i**2 for i in x])
>>> torus_net = compose(translation, torus_net)
>>> torus_net = compose(inversion, torus_net)
Modifying Nets
Another way of working with nets is the to use our utility functions on them. While domain utility functions will create, when you pass them an actual domain, they will replace the domain of a given net instead.
>>> import ddg
>>> import numpy as np
>>> net = ddg.nets.SmoothNet(lambda t: t, [[-np.inf, np.inf]])
>>> net.domain.intervals
[[-inf, inf]]
>>> new_net = ddg.nets.bound_domain(net, 10)
>>> new_net is net
True
>>> new_net.domain.intervals
[[-5.0, 5.0]]
Example: Surface of Revolution
>>> import ddg
>>> import numpy as np
>>> hyperbola1 = lambda u: np.array([np.sinh(u), np.cosh(u)])
>>> hyperbola2 = lambda u: np.array([np.sinh(u), -np.cosh(u)])
>>> hyperbola1 = ddg.nets.SmoothNet(hyperbola1, [[0, np.inf]])
>>> hyperbola2 = ddg.nets.SmoothNet(hyperbola2, [[0, np.inf]])
>>> hyperbola1 = ddg.nets.surface_of_revolution(hyperbola1)
>>> hyperbola2 = ddg.nets.surface_of_revolution(hyperbola2)
>>> two_sheeted_hyperboloid = ddg.nets.NetCollection([hyperbola1, hyperbola2])
More Utility Functions
The nets module of nets contains a collection of utility functions
which can be applied to nets.
An example is coordinate_lines() , which returns a
NetCollection
of curves describing the coordinate lines of the discrete net.
Sampling
Sampling a smooth set means you choose finitely (or countably) many points to obtain a discrete set. This is important for visualizing smooth nets. Since they have uncountably many points, they must be converted to discrete nets first.
For that, our library provides the function sample_smooth_net. It takes
a SmoothNet and converts it to a DiscreteNet.
Internally, sample_smooth_net uses sample_smooth_domain
to sample the domain of the SmoothNet and then it concatenates the output with the net function of the SmoothNet.
The sampling parameter of sample_smooth_net is handled in the same way as that of
sample_smooth_domain.
See sampling of domains for a detailed description and examples!
Examples
Bounded directions can be sampled with total if we don’t use an achor:
>>> import ddg
>>> import numpy as np
>>> net = ddg.nets.SmoothNet(lambda x, y: np.array([x, y, x * y]), [[-5, 5]] * 2)
>>> discrete_net = ddg.nets.sample_smooth_net(net, [10, "t"])
>>> discrete_net.domain.intervals
[[0, 9], [0, 9]]
>>> discrete_net = ddg.nets.sample_smooth_net(net, [[10, "t"], [5, "t"]])
>>> discrete_net.domain.intervals
[[0, 9], [0, 4]]
>>> discrete_net = ddg.nets.sample_smooth_net(net, [0.5, [5, "t"]])
>>> discrete_net.domain.intervals
[[0, 20], [0, 4]]
Unbounded directions and directions for which we want to set an anchor can only be sampled with stepsize:
>>> import ddg
>>> import numpy as np
>>> net = ddg.nets.SmoothNet(
... lambda x, y: np.array([x, y, x * y]), [[-np.inf, np.inf]] * 2
... )
>>> discrete_net = ddg.nets.sample_smooth_net(net, 0.1)
>>> discrete_net.domain.intervals
[[-inf, inf], [-inf, inf]]
>>> import ddg
>>> import numpy as np
>>> net = ddg.nets.SmoothNet(lambda x, y: np.array([x, y, x * y]), [[-5, 5]] * 2)
>>> discrete_net = ddg.nets.sample_smooth_net(net, [10, "t"])
>>> discrete_net.domain.intervals
[[0, 9], [0, 9]]
Unbounded or Bounded?
In the case of quadrics for example we can not be sure whether the domain of the resulting net is unbounded or not. In this case, it is convenient to use the compound sampling, which can handle both cases.
>>> import ddg
>>> import numpy as np
>>> net = ddg.nets.SmoothNet(
... lambda x, y: np.array([x, y, x * y]), [[-np.inf, np.inf]] * 2
... )
>>> discrete_net = ddg.nets.sample_smooth_net(net, [0.5, 10, "c"])
>>> discrete_net.domain.intervals
[[0, 9], [0, 9]]
Different sampling in both directions
>>> import ddg
>>> import numpy as np
>>> net = ddg.nets.SmoothNet(lambda x, y: np.array([x, y, x * y]), [[-5, 5]] * 2)
>>> discrete_net = ddg.nets.sample_smooth_net(net, 0.5)
>>> discrete_net.domain.intervals
[[0, 20], [0, 20]]
>>> (discrete_net(0, 0) == net(-5, -5)).all()
True
>>> import ddg
>>> import numpy as np
>>> net = ddg.nets.SmoothNet(lambda x, y: np.array([x, y, x * y]), [[-5, 5]] * 2)
>>> discrete_net = ddg.nets.sample_smooth_net(net, [0.5, 0.2])
>>> discrete_net.domain.intervals
[[0, 20], [0, 49]]
>>> discrete_net(10, 49)
array([0. , 4.8, 0. ])
Smooth Net (l), coordinate lines for sampling: 0.5 (m),
coordinate lines for sampling: [0.5, 0.2] (r)
Conversion to Half-edge
Nets of dimension 2 or less with bounded domains can be converted to a The half-edge data structure object using the function
ddg.conversion.halfedge.nets.discrete_net_to_halfedge().
The vertices of the resulting half-edge object will have an attribute "co" containing the value of the net at that
point and the order will be the same as that in the traverser of the domain.
>>> from ddg.conversion.halfedge.nets import discrete_net_to_halfedge
>>> def f(x, y):
... return np.array([x, y, x**2 - y**2])
...
>>> net = ddg.nets.DiscreteNet(f, [[0, 1], [0, 1]])
>>> surface = discrete_net_to_halfedge(net)
>>> for c in net.traverser:
... print(net[c])
...
[0 0 0]
[ 0 1 -1]
[1 0 1]
[1 1 0]
>>> for v in surface.verts:
... print(v.co)
...
[0 0 0]
[ 0 1 -1]
[1 0 1]
[1 1 0]
The name of the coordinate attribute can be changed using the co_attr
argument of the conversion function.
Visualization in Blender
A guide on how to visualize nets in Blender can be found Visualizing with blender.