Surface

class tissue_forge.models.vertex.solver.Surface

The mesh surface is an area-enclosed object of implicit mesh edges defined by mesh vertices.

The mesh surface consists of at least three mesh vertices.

The mesh surface is always flat.

The mesh surface can have a state vector, which represents a uniform amount of substance attached to the surface.

property id: int
property actors

Object actors

property style

Surface style, if any

property bodies

bodies defined by the surface

property vertices

vertices that define the surface

property neighbor_surfaces

surfaces that share at least one vertex

property density

density of the surface; only used in 2D simulation

property normal

normal of the surface

property unnormalized_normal

unnormalized normal of the surface

property centroid

centroid of the surface

property velocity

velocity of the surface

property area

area of the surface

property perimeter

perimeter of the surface

property normal_stresses

normal stresses bound to the surface

property surface_area_constraints

surface area constraints bound to the surface

property surface_tractions

surface tractions bound to the surface

property edge_tensions

edge tensions bound to the surface

property adhesions

adhesions bound to the surface

property convex_polygon_constraints

convex polygon constraints bound to the surface

property flat_surface_constraints

flat surface constraints bound to the surface

static create(*args)

Overload 1:

Construct a surface from a set of vertices

Parameters:

_vertices (std::vector< TissueForge::models::vertex::VertexHandle,std::allocator< TissueForge::models::vertex::VertexHandle > >) – a set of vertices


Overload 2:

Construct a surface from a face

Parameters:

face (ThreeDFFaceData) – a face


Overload 3:

Construct surfaces from sets of vertices

Parameters:

_vertices (std::vector< std::vector< TissueForge::models::vertex::VertexHandle,std::allocator< TissueForge::models::vertex::VertexHandle > >,std::allocator< std::vector< TissueForge::models::vertex::VertexHandle,std::allocator< TissueForge::models::vertex::VertexHandle > > > >) – sets of vertices


Overload 4:

Construct surfaces from faces

Parameters:

_faces (std::vector< TissueForge::io::ThreeDFFaceData *,std::allocator< TissueForge::io::ThreeDFFaceData * > >) – faces

defines(obj)
definedBy(obj)
static destroy(*args)

Destroy surfaces.

Any resulting vertices without a surface are also destroyed.

Parameters:

target (std::vector< TissueForge::models::vertex::Surface *,std::allocator< TissueForge::models::vertex::Surface * > >) – handles to a surface to destroy

classmethod destroy_c(s)

Destroy a surface.

Any resulting vertices without a surface are also destroyed.

Parameters:

s – surface to destroy or its handle

validate()
position_changed()
toString()

Get a JSON string representation

add(*args)

Overload 1:

Add a vertex

Parameters:

v (Vertex) – vertex to add


Overload 2:

Add a body

Parameters:

b (Body) – body to add

remove(*args)

Overload 1:

Remove a vertex

Parameters:

v (Vertex) – vertex to remove


Overload 2:

Remove a body

Parameters:

b (Body) – body to remove

insert(*args)

Overload 1:

Insert a vertex at a location in the list of vertices

Parameters:

  • v (Vertex) – vertex to insert

  • idx (int) – location


Overload 2:

Insert a vertex before another vertex

Parameters:

  • v (Vertex) – vertex to insert

  • before (Vertex) – vertex to insert before


Overload 3:

Insert a vertex between two vertices

Parameters:

  • toInsert (Vertex) – vertex to insert

  • v1 (Vertex) – first vertex

  • v2 (Vertex) – second vertex

remove(*args)

Overload 1:

Remove a vertex

Parameters:

v (Vertex) – vertex to remove


Overload 2:

Remove a body

Parameters:

b (Body) – body to remove

replace(*args)

Overload 1:

Replace a vertex at a location in the list of vertices

Parameters:

  • toInsert (Vertex) – vertex to insert

  • idx (int) – location of vertex to replace


Overload 2:

Replace a vertex with another vertex

Parameters:

  • toInsert (Vertex) – vertex to insert

  • toRemove (Vertex) – vertex to remove


Overload 3:

Replace a body at a location in the list of bodies

Parameters:

  • toInsert (Body) – body to insert

  • idx (int) – location of body to remve


Overload 4:

Replace a body with another body

Parameters:

  • toInsert (Body) – body to insert

  • toRemove (Body) – body to remove

refresh_bodies()

Refresh internal ordering of defined bodies

type()

Get the surface type

become(stype)

Become a different type

Parameters:

stype (SurfaceType) – type to become

find_vertex(dir)

Find a vertex that defines this surface

Parameters:

dir (FVector3) – direction to look with respect to the centroid

find_body(dir)

Find a body that this surface defines

Parameters:

dir (FVector3) – direction to look with respect to the centroid

neighbor_vertices(v)

Connected vertices on the same surface

Parameters:

v (Vertex) – a vertex

connected_surfaces(*args)

Overload 1:

Surfaces that share at least one vertex in a set of vertices

Parameters:

verts (std::vector< TissueForge::models::vertex::Vertex *,std::allocator< TissueForge::models::vertex::Vertex * > >) – vertices


Overload 2:

Surfaces that share at least one vertex

connecting_vertices(other)

Vertices defining this and another surface

Parameters:

other (Surface) – another surface

contiguous_vertex_labels(other)

Get the integer labels of the contiguous vertices that this surface shares with another surface

Parameters:

other (Surface) – another surface

num_shared_contiguous_vertex_sets(other)

Get the number of contiguous vertex sets that this surface shares with another surface

Parameters:

other (Surface) – another surface

shared_contiguous_vertices(other, edgeLabel)

Get the vertices of a contiguous shared vertex set with another surface.

Vertices are labeled in increasing order starting with “1”. A requested set that does not exist returns empty.

A requested edge with label “0” returns all vertices not shared with another surface

Parameters:

  • other (Surface) – another surface

  • edgeLabel (int) – edge label

volume_sense(body)

Get the sign of the volume contribution to a body that this surface contributes

Parameters:

body (Body) – a body

get_volume_contr(body)

Get the volume that this surface contributes to a body

Parameters:

body (Body) – a body

get_outward_normal(body)

Get the outward facing normal w.r.t. a body

Parameters:

body (Body) – a body

get_vertex_area(v)

Get the area that a vertex contributes to this surface

Parameters:

v (Vertex) – a vertex

get_vertex_mass(v)

Get the mass contribution of a vertex to this surface; only used in 2D simulation

Parameters:

v (Vertex) – a vertex

triangle_normal(idx)

Get the normal of a triangle

Parameters:

idx (int) – location of first vertex

normal_distance(pos)

Get the normal distance to a point.

A negative distance means that the point is on the inner side

Parameters:

pos (FVector3) – position

is_outside(pos)

Test whether a point is on the outer side

Parameters:

pos (FVector3) – position

Return type:

boolean

Returns:

true if the point is on the outer side

contains(*args)

Overload 1:

Test whether the surface contains a point

Parameters:

  • pos (FVector3) – position of the point

  • v0 (Vertex) – a vertex of the nearest edge

  • v1 (Vertex) – a vertex of the nearest edge


Overload 2:

Test whether the surface contains a point

Parameters:

pos (FVector3) – position of the point

classmethod sew(s1=None, s2=None, surfs=None, dist_cf: float | None = None)

Sew either two surfaces or a set of surfaces.

All vertices are merged that are a distance apart less than a distance criterion.

The distance criterion is the square root of the average of the two surface areas, multiplied by a coefficient.

Parameters:

  • s1 – the surface or its handle

  • s2 – another surface or its handle

  • surfs – a set of surfaces or their handles

  • dist_cf – distance criterion coefficient

merge(toRemove, lenCfs)

Merge with a surface. The passed surface is destroyed.

Surfaces must have the same number of vertices. Vertices are paired by nearest distance.

Parameters:

  • toRemove (Surface) – surface to remove

  • lenCfs (std::vector< FloatP_t,std::allocator< FloatP_t > >) – distance coefficients in [0, 1] for where to place the merged vertex, from each kept vertex to each removed vertex

extend(vertIdxStart, pos)

Create a surface from two vertices and a position

Parameters:

  • vertIdxStart (int) – index of first vertex

  • pos (FVector3) – position

extrude(vertIdxStart, normLen)

Create a surface from two vertices of a surface in a mesh by extruding along the normal of the surface

todo: add support for extruding at an angle w.r.t. the center of the edge and centroid of the base surface

Parameters:

  • vertIdxStart (int) – index of first vertex

  • normLen (float) – length along surface normal by which to extrude

split(*args)

Overload 1:

Split into two surfaces

Both vertices must already be in the surface and not adjacent

Vertices in the winding from from vertex to second go to newly created surface

Requires updated surface members (e.g., centroid)

Parameters:

  • v1 (Vertex) – fist vertex defining the split

  • v2 (Vertex) – second vertex defining the split

Return type:

Surface

Returns:

Surface*


Overload 2:

Split into two surfaces

Requires updated surface members (e.g., centroid)

Parameters:

  • cp_pos (FVector3) – point on the cut plane

  • cp_norm (FVector3) – normal of the cut plane

__str__() → str

Return str(self).

__lt__(rhs) → bool

Return self<value.

__gt__(rhs) → bool

Return self>value.

__le__(rhs) → bool

Return self<=value.

__ge__(rhs) → bool

Return self>=value.

__eq__(rhs) → bool

Return self==value.

__ne__(rhs) → bool

Return self!=value.

class tissue_forge.models.vertex.solver.SurfaceHandle(_id=-1)

A handle to a Surface.

The engine allocates Surface memory in blocks, and Surface values get moved around all the time, so their addresses change.

This is a safe way to work with a Surface.

property id
property surface

underlying Surface instance, if any

property bodies

bodies defined by the surface

property vertices

vertices that define the surface

property neighbor_surfaces

surfaces that share at least one vertex

property density

density of the surface; only used in 2D simulation

property normal

normal of the surface

property unnormalized_normal

unnormalized normal of the surface

property centroid

centroid of the surface

property velocity

velocity of the surface

property area

area of the surface

property perimeter

perimeter of the surface

property style

style of the surface, if any

property normal_stresses

normal stresses bound to the surface

property perimeter_constraints

perimeter constraints bound to the surface

property surface_area_constraints

surface area constraints bound to the surface

property surface_tractions

surface tractions bound to the surface

property edge_tensions

edge tensions bound to the surface

property adhesions

adhesions bound to the surface

property convex_polygon_constraints

convex polygon constraints bound to the surface

property flat_surface_constraints

flat surface constraints bound to the surface

defines(b)

Test whether defines a body

Parameters:

b (BodyHandle) – a body

Return type:

boolean

Returns:

true if defines a body

definedBy(v)

Test whether defined by a vertex

Parameters:

v (VertexHandle) – a vertex

Return type:

boolean

Returns:

true if defined by a vertex

destroy()

Destroy the surface

validate()

Validate the surface

Return type:

boolean

Returns:

true if valid

position_changed()

Update internal data due to a change in position

toString()

Get a JSON string representation

static fromString(s)

Create an instance from a JSON string representation

Parameters:

s (string) – JSON string

add(*args)

Overload 1:

Add a vertex

Parameters:

v (VertexHandle) – vertex to add


Overload 2:

Add a body

Parameters:

b (BodyHandle) – body to add

remove(*args)

Overload 1:

Remove a vertex

Parameters:

v (VertexHandle) – vertex to remove


Overload 2:

Remove a body

Parameters:

b (BodyHandle) – body to remove

insert(*args)

Overload 1:

Insert a vertex at a location in the list of vertices

Parameters:

  • v (VertexHandle) – vertex to insert

  • idx (int) – location of insertion


Overload 2:

Insert a vertex before another vertex

Parameters:

Overload 3:

Insert a vertex between two vertices

Parameters:
replace(*args)

Overload 1:

Replace a vertex at a location in the list of vertices

Parameters:

  • toInsert (VertexHandle) – vertex to insert

  • idx (int) – location of vertex to remove


Overload 2:

Replace a vertex with another vertex

Parameters:

Overload 3:

Replace a body at a location in the list of bodies

Parameters:

  • toInsert (BodyHandle) – body to insert

  • idx (int) – location of body to remove


Overload 4:

Replace a body with another body

Parameters:
refresh_bodies()

Refresh internal ordering of defined bodies

type()

Get the surface type

become(stype)

Become a different type

Parameters:

stype (SurfaceType) – type to become

find_vertex(dir)

Find a vertex that defines this surface

Parameters:

dir (FVector3) – direction to look with respect to the centroid

find_body(dir)

Find a body that this surface defines

Parameters:

dir (FVector3) – direction to look with respect to the centroid

neighbor_vertices(v)

Connected vertices on the same surface

Parameters:

v (VertexHandle) – a vertex

connected_surfaces(*args)

Overload 1:

Surfaces that share at least one vertex in a set of vertices

Parameters:

verts (std::vector< TissueForge::models::vertex::VertexHandle,std::allocator< TissueForge::models::vertex::VertexHandle > >) – a set of vertices


Overload 2:

Surfaces that share at least one vertex

connecting_vertices(other)

Vertices defining this and another surface

Parameters:

other (SurfaceHandle) – another surface

contiguous_vertex_labels(other)

Get the integer labels of the contiguous edges that this surface shares with another surface

Parameters:

other (SurfaceHandle) – another surface

num_shared_contiguous_vertex_sets(other)

Get the number of contiguous edges that this surface shares with another surface

Parameters:

other (SurfaceHandle) – another surface

shared_contiguous_vertices(other, edgeLabel)

Get the vertices of a contiguous shared edge with another surface.

Edges are labeled in increasing order starting with “1”. A requested edge that does not exist returns empty.

A requested edge with label “0” returns all vertices not shared with another surface

Parameters:

  • other (SurfaceHandle) – another surface

  • edgeLabel (int) – edge label

volume_sense(body)

Get the sign of the volume contribution to a body that this surface contributes

Parameters:

body (BodyHandle) – a body

get_volume_contr(body)

Get the volume that this surface contributes to a body

Parameters:

body (BodyHandle) – a body

get_outward_normal(body)

Get the outward facing normal w.r.t. a body

Parameters:

body (BodyHandle) – a body

get_vertex_area(v)

Get the area that a vertex contributes to this surface

Parameters:

v (VertexHandle) – a vertex

get_vertex_mass(v)

Get the mass contribution of a vertex to this surface; only used in 2D simulation

Parameters:

v (VertexHandle) – a vertex

triangle_normal(idx)

Get the normal of a triangle

Parameters:

idx (int) – index of first triangle vertex

normal_distance(pos)

Get the normal distance to a point.

A negative distance means that the point is on the inner side

Parameters:

pos (FVector3) – position

is_outside(pos)

Test whether a point is on the outer side

Parameters:

pos (FVector3) – position

Return type:

boolean

Returns:

true if on the outer side

contains(*args)

Overload 1:

Test whether the surface contains a point

Parameters:

  • pos (FVector3) – position of the point

  • v0 (VertexHandle) – a vertex of the nearest edge

  • v1 (VertexHandle) – a vertex of the nearest edge


Overload 2:

Test whether the surface contains a point

Parameters:

pos (FVector3) – position of the point

merge(toRemove, lenCfs)

Merge with a surface. The passed surface is destroyed.

Surfaces must have the same number of vertices. Vertices are paired by nearest distance.

Parameters:

  • toRemove (SurfaceHandle) – surface to remove

  • lenCfs (std::vector< FloatP_t,std::allocator< FloatP_t > >) – distance coefficients in [0, 1] for where to place the merged vertex, from each kept vertex to each removed vertex

extrude(vertIdxStart, normLen)

Create a surface from two vertices of a surface in a mesh by extruding along the normal of the surface

todo: add support for extruding at an angle w.r.t. the center of the edge and centroid of the base surface

Parameters:

  • vertIdxStart (int) – index of first vertex

  • normLen (float) – length along surface normal by which to extrude

split(*args)

Overload 1:

Split into two surfaces

Both vertices must already be in the surface and not adjacent

Vertices in the winding from from vertex to second go to newly created surface

Requires updated surface members (e.g., centroid)

Parameters:

Overload 2:

Split into two surfaces

Requires updated surface members (e.g., centroid)

Parameters:

  • cp_pos (FVector3) – point on the cut plane

  • cp_norm (FVector3) – normal of the cut plane

__str__() → str

Return str(self).

__lt__(rhs) → bool

Return self<value.

__gt__(rhs) → bool

Return self>value.

__le__(rhs) → bool

Return self<=value.

__ge__(rhs) → bool

Return self>=value.

__eq__(rhs) → bool

Return self==value.

__ne__(rhs) → bool

Return self!=value.

class tissue_forge.models.vertex.solver.SurfaceTypeSpec

Interface for class-centric design of SurfaceType

density: float | None = None

Mass density; only used in 2D simulation

edge_tension_lam: float | None = None

Edge tension Lagrange multiplier

edge_tension_order: int | None = None

Edge tension order

normal_stress_mag: float | None = None

Normal stress magnitude

perimeter_lam: float | None = None

Perimeter constraing Lagrange multiplier

perimeter_val: float | None = None

Perimeter constraint target value

surface_area_lam: float | None = None

Surface area constraint Lagrange multiplier

surface_area_val: float | None = None

Surface area constraint target value

surface_traction_comps: fVector3 | List[float] | None = None

Surface traction components

adhesion: Dict[str, float] | None = None

Adhesion by name and parameter

classmethod get() → _vertex_solver_SurfaceType

Get the engine type that corresponds to this class.

The type is automatically registered as necessary.

Returns:

registered type instance

classmethod edge_tension() → _vertex_solver_EdgeTension | None

edge tension actor generator according to specs, if any

classmethod normal_stress() → _vertex_solver_NormalStress | None

normal stress actor generator according to specs, if any

classmethod perimeter_constaint() → _vertex_solver_PerimeterConstraint | None

perimeter constaint actor generator according to specs, if any

classmethod surface_area_constaint() → _vertex_solver_SurfaceAreaConstraint | None

surface area constaint actor generator according to specs, if any

classmethod surface_traction() → _vertex_solver_SurfaceTraction | None

surface traction actor generator according to specs, if any

static bind_adhesion(specs: List[Type]) → Dict[str, Dict[str, _vertex_solver_Adhesion]]

Bind adhesion to all registered types according to all passed specifications

class tissue_forge.models.vertex.solver.SurfaceType(MeshObjType)

Mesh surface type.

Can be used as a factory to create mesh surface instances with processes and properties that correspond to the type.

Overload 1:

Construct a new surface type

Parameters:

  • flatLam (float) – parameter for flat surface constraint

  • convexLam (float) – parameter for convex surface constraint


Overload 2:

Construct a new surface type

property name

Name of this surface type

property registered: bool

Tests whether this type is registered

property style

The style of the surface type

property density

Mass density; only used in 2D simulation

property normal_stresses

normal stresses bound to the type

property surface_area_constraints

surface area constraints bound to the type

property surface_tractions

surface tractions bound to the type

property edge_tensions

edge tensions bound to the type

property adhesions

adhesions bound to the type

property convex_polygon_constraints

convex polygon constraints bound to the type

property flat_surface_constraints

flat surface constraints bound to the type

toString()

Get a JSON string representation

static fromString(str)

Create from a JSON string representation.

The returned type is automatically registered with the solver.

Parameters:

str (string) – a string, as returned by toString

static find_from_name(_name)

Get a registered type by name

Parameters:

_name (string) – type name

register_type()

Registers a type with the engine.

Note that this occurs automatically, unless noReg==true in constructor.

get()

Get the type engine instance

add(*args)

Overload 1:

Add an instance

Parameters:

i (SurfaceHandle) – instance to add


Overload 2:

Add instances

Parameters:

i (std::vector< TissueForge::models::vertex::SurfaceHandle,std::allocator< TissueForge::models::vertex::SurfaceHandle > >) – instances to add

remove(*args)

Overload 1:

Remove an instance

Parameters:

i (SurfaceHandle) – instance to remove


Overload 2:

Remove instances

Parameters:

i (std::vector< TissueForge::models::vertex::SurfaceHandle,std::allocator< TissueForge::models::vertex::SurfaceHandle > >) – instances to remove

n_polygon(n: int, center, radius: float, ax1, ax2)

Construct a N-sided polygonal surface of this type

Parameters:

  • n – number of vertices

  • center – center of polygon

  • radius – radius of circle for placing vertices

  • ax1 – first axis defining the plane of the polygon

  • ax2 – second axis defining the plane of the polygon

replace(to_replace, len_cfs)

Replace a vertex with a surface. Vertices are created for the surface along every destroyed edge.

Parameters:

  • to_replace – vertex to replace

  • len_cfs – coefficient in (0, 1) along each connected edge defining how far to construct a new vertex

__call__(vertices=None, positions=None, face_data=None, safe_face_data: bool = True)

Construct a surface of this type

Parameters:

  • vertices – a list of vertices

  • positions – a list of positions

  • face_data – 3DF face data

__str__() → str

Return str(self).

__lt__(rhs) → bool

Return self<value.

__gt__(rhs) → bool

Return self>value.

__le__(rhs) → bool

Return self<=value.

__ge__(rhs) → bool

Return self>=value.

__eq__(rhs) → bool

Return self==value.

__ne__(rhs) → bool

Return self!=value.

__len__() → int
__getitem__(index: int)
__contains__(item)