Using the GeometryBuilder — GSTPy documentation

# Using the GeometryBuilder

## Multipoint

First, call `GeometryBuilder.create_multipoint3()`. Use `GeometryBuilder.add_point()` to add each point of the geometry.

The following example creates a multipoint geometry consisting of three points: (5, 0, 0), (7, 1, 0) and (3, 0, 1).

    from GSTPy import GeometryBuilder, RawPoint3

    gb = GeometryBuilder()
    gb.create_multipoint3()
    # point 0
    gb.add_point(RawPoint3(5, 0, 0))
    # point 1
    gb.add_point(RawPoint3(7, 1, 0))
    # point 2
    gb.add_point(RawPoint3(3, 0, 1))

## Multilinestring

First, call `GeometryBuilder.create_multiline3()`. Use `GeometryBuilder.add_point()` for each point of the linestring. Finish the linestring by calling `GeometryBuilder.new_simplex()`. Repeat this for each individual linestring of the multilinestring.

The following example creates a multilinestring geometry consisting of two linestrings as follows:

linestring1: (5, 0, 0) -> (7, 1, 0) -> (3, 0, 1)
linestring2: (2, 0, 0) -> (3, 0, 0)

    from GSTPy import GeometryBuilder, RawPoint3

    gb = GeometryBuilder()
    gb.create_multiline3()
    # linestring1 (5, 0, 0) -> (7, 1, 0) -> (3, 0, 1)
    gb.add_point(RawPoint3(5, 0, 0))
    gb.add_point(RawPoint3(7, 1, 0))
    gb.add_point(RawPoint3(3, 0, 1))
    gb.new_simplex()
    # linestring2 (2, 0, 0) -> (3, 0, 0)
    gb.add_point(RawPoint3(2, 0, 0))
    gb.add_point(RawPoint3(3, 0, 0))
    gb.new_simplex()

## Tin

To create a geometry of type Tin3 you can use one of two variants. In both examples we are going to create a geometry with the following two triangles:

triangle1: (5, 0, 0) -> (7, 1, 0) -> (3, 0, 1)
triangle2: (3, 0, 1) -> (7, 1, 0) -> (1, 1, 0)

### Variant1

Variant1 is used by calling `GeometryBuilder.create_tin3()`. Use `GeometryBuilder.add_point()` 3 times, once for each point of the triangle. After this call `GeometryBuilder.new_simplex()` to finish the triangle. Repeat this for each individual triangle in the TIN.

Example:

    from GSTPy import GeometryBuilder, RawPoint3

    gb = GeometryBuilder()
    gb.create_tin3()
    # triangle1 (5, 0, 0) -> (7, 1, 0) -> (3, 0, 1)
    gb.add_point(RawPoint3(5, 0, 0))
    gb.add_point(RawPoint3(7, 1, 0))
    gb.add_point(RawPoint3(3, 0, 1))
    gb.new_simplex()
    # triangle2 (3, 0, 1) -> (7, 1, 0) -> (1, 1, 0)
    gb.add_point(RawPoint3(3, 0, 1))
    gb.add_point(RawPoint3(7, 1, 0))
    gb.add_point(RawPoint3(1, 1, 0))
    gb.new_simplex()

### Variant2

Variant2 is used by calling `GeometryBuilder.create_triangle_net3()`. Use `GeometryBuilder.add_point()` to add all the points of your TIN. Afterwards call `GeometryBuilder.add_triangle()` to create the mesh of the TIN, using the ids from the `GeometryBuilder.add_point()` calls before.

Note

`GeometryBuilder.add_point()` returns the id of the added point. This id should be used with `GeometryBuilder.add_triangle()`

    from GSTPy import GeometryBuilder, RawPoint3, IdxTriangle

    gb = GeometryBuilder()
    gb.create_triangle_net3()

    # point 0
    v1 = gb.add_point(RawPoint3(5, 0, 0))
    # point 1
    v2 = gb.add_point(RawPoint3(7, 1, 0))
    # point 2
    v3 = gb.add_point(RawPoint3(3, 0, 1))
    # point 3
    v4 = gb.add_point(RawPoint3(1, 1, 0))
    # triangle1 (5, 0, 0) -> (7, 1, 0) -> (3, 0, 1)
    gb.add_triangle(IdxTriangle(v1, v2, v3))
    # triangle2 (3, 0, 1) -> (7, 1, 0) -> (1, 1, 0)
    gb.add_triangle(IdxTriangle(v3, v2, v4))

This variant has the adavantage that you can share the same point in multiple triangles. Notice how points (7, 1, 0) and (3, 0, 1) were added only once, instead of twice, as in the example of variant1.

Note

You should always prefer using the second variant if possible, because it will result in a much smaller size of the transferred geometry data.

## Tetrahderon Net

To create a geometry of type Multipolygon3 you can use one of two variants. In both examples we are going to create a geometry with the following two tetrahedrons:

tetrahedron1 (5, 0, 0) -> (7, 1, 0) -> (3, 0, 1) -> (4, 4, 0)
tetrahedron2: (3, 0, 1) -> (7, 1, 0) -> (5, 0, 0) -> (1, 1, 0)

### Variant1

Variant1 is used by calling `GeometryBuilder.create_multi_polygon3()`. Use `GeometryBuilder.add_point()` 4 times, once for each point of the tetrahedron. After this call `GeometryBuilder.new_simplex()` to finish the tetrahedron. Repeat this for each individual tetrahedron in the tetrahedron net.

    from GSTPy import GeometryBuilder, RawPoint3

    gb = GeometryBuilder()
    gb.create_multi_polygon3()
    # tetrahedron1 (5, 0, 0) -> (7, 1, 0) -> (3, 0, 1) -> (4, 4, 0)
    gb.add_point(RawPoint3(5, 0, 0))
    gb.add_point(RawPoint3(7, 1, 0))
    gb.add_point(RawPoint3(3, 0, 1))
    gb.add_point(RawPoint3(4, 4, 0))
    gb.new_simplex()
    # tetrahedron2 (3, 0, 1) -> (7, 1, 0) -> (5, 0, 0) -> (1, 1, 0)
    gb.add_point(RawPoint3(3, 0, 1))
    gb.add_point(RawPoint3(7, 1, 0))
    gb.add_point(RawPoint3(5, 0, 0))
    gb.add_point(RawPoint3(1, 1, 0))
    gb.new_simplex()

### Variant2

Variant2 is used by calling `GeometryBuilder.create_tetrahedron_net3()`. Use `GeometryBuilder.add_point()` to add all the points of your tetrahedron net. Afterwards call `GeometryBuilder.add_tetrahedron()` to create the mesh of the tetrahedron net, using the ids from the `GeometryBuilder.add_point()` calls before.

Note

`GeometryBuilder.add_point()` returns the id of the added point. This id should be used with `GeometryBuilder.add_tetrahedron()`

    from GSTPy import GeometryBuilder, RawPoint3, IdxTetrahedron

    gb = GeometryBuilder()
    gb.create_tetrahedron_net3()
    # point 0
    v1 = gb.add_point(RawPoint3(5, 0, 0))
    # point 1
    v2 = gb.add_point(RawPoint3(7, 1, 0))
    # point 2
    v3 = gb.add_point(RawPoint3(3, 0, 1))
    # point 3
    v4 = gb.add_point(RawPoint3(4, 4, 0))
    # point 4
    v5 = gb.add_point(RawPoint3(1, 1, 0))
    # tetrahedron1 (5, 0, 0) -> (7, 1, 0) -> (3, 0, 1) -> (4, 4, 0)
    gb.add_tetrahedron(IdxTetrahedron(v1, v2, v3, v4))
    # tetrahedron2 (3, 0, 1) -> (7, 1, 0) -> (5, 0, 0) -> (1, 1, 0)
    gb.add_tetrahedron(IdxTetrahedron(v3, v2, v1, v5))

This variant has the adavantage that you can share the same point in multiple tetrahedrons. Notice how points (7, 1, 0), (3, 0, 1) and were added only once, instead of twice, as in the example of variant1.

Note

You should always prefer using the second variant if possible, because it will result in a much smaller size of the transferred geometry data.

## Simplex Properties

In the following we present two variants of how to add simplex property values to a geometry. Other call orders are possible, but these are the most generally useful ones.

Both examples create the same geometry:

Point | gold | silver
--- | --- | ---
(5, 0, 0) | 3.0 | 2.0
(7, 1, 0) | 0.5 | NULL
(3, 0, 1) | NULL | 50.0

### Variant1

Here we first add all the points. Afterwards we create the properties and add the property values for each point.

    from GSTPy import GeometryBuilder, RawPoint3, PropertyTypes

    gb = GeometryBuilder()
    gb.create_multipoint3()
    # point 0
    gb.add_point(RawPoint3(5, 0, 0))
    # point 1
    gb.add_point(RawPoint3(7, 1, 0))
    # point 2
    gb.add_point(RawPoint3(3, 0, 1))

    gb.create_vertex_property("gold", PropertyTypes.TypeFloat)
    gb.create_vertex_property("silver", PropertyTypes.TypeFloat)
    # gold for point 0
    gb.add_property_value("3.0")
    # silver for point 0
    gb.add_property_value("2.0")
    # gold for point 1
    gb.add_property_value("0.5")
    # silver for point 1
    gb.add_property_null_value()
    # gold for point 2
    gb.add_property_null_value()
    # silver for point 2
    gb.add_property_value("50.0")

### Variant2

Here we intermix the `add_property_value` with the `add_point` calls.

    from GSTPy import GeometryBuilder, RawPoint3, PropertyTypes

    gb = GeometryBuilder()
    gb.create_multipoint3()
    gb.create_vertex_property("gold", PropertyTypes.TypeFloat)
    gb.create_vertex_property("silver", PropertyTypes.TypeFloat)
    # point 0
    gb.add_point(RawPoint3(5, 0, 0))
    # gold for point 0
    gb.add_property_value("3.0")
    # silver for point 0
    gb.add_property_value("2.0")
    # point 1
    gb.add_point(RawPoint3(7, 1, 0))
    # gold for point 1
    gb.add_property_value("0.5")
    # silver for point 1
    gb.add_property_null_value()
    # point 2
    gb.add_point(RawPoint3(3, 0, 1))
    # gold for point 2
    gb.add_property_null_value()
    # silver for point 2
    gb.add_property_value("50.0")

### Notes

The general order for `add_property_value` is as follows:

With
m the number of properties.
n the number of points.
First call to `add_property_value` is the value for the first property of the first point.
Second call to `add_property_value` is the value for the second property of the first point.
[…]
(m - 1)-th call to `add_property_value` is the value for the last property of the first point.
m-th call to `add_property_value` is the value for the first property of the second point.
(m + 1)-th call to `add_property_value` is the value for the second property of the second point.
[…]
repeat n times.

Or in code:

    for p in points:
        for prop in properties:
            gb.add_property_value("example_value")