topologicpy.Grid module

Grid.Vertices(grid) returns unique endpoints and intersections of grid Edges, including crossings that have not been split into separate Edges. It accepts the topology returned by Grid.OnFace or a list of Edges. PythonOCC processes curved Edges in a single native batch; straight TopologicCore Edges use analytical 3D intersections with bounding-box pruning. Coincident points are deduplicated using the model-unit tolerance.

Clearance

Grid.OnFace(..., clearance=0.3) clips the original planar grid to the inset region(s) returned by Face.ByOffset. Outer boundaries move inward and holes expand. Distances use the Face plane and model units. Grid positions, divisions, labels and spacing are computed on the original Face; clearance does not recenter or rescale the grid. All surviving regions are retained. An exhausted or failed offset returns None. Positive clearance on intrinsic surface grids is explicitly unsupported, while clearance=0 retains existing surface behavior.

Grid.OnFaces(..., clearance=0.3) measures the margin in horizontal XY, matching its projected grid definition. Continuous adjoining patches are offset together so internal slab seams do not create gaps. Holes are included in the offset. This method retains its linear-boundary requirement. includeBoundary=True includes the clipped region boundaries; the lattice still uses the supplied shared origin and direction.

The default is clearance=0.0. Negative or non-finite values are invalid. Grid.Vertices needs no separate clearance parameter because it derives points from the resulting clipped grid.

Patterned grids

Grid.OnPlane creates a finite grid in a rectangular domain on XY by default. width and length specify its dimensions; origin is its centre and direction is its normal. Grid.OnFace clips the same patterns to a planar Face and its holes. Both accept silent and use model-unit dimensions. Existing OnFace calls retain their original planar and intrinsic-surface behavior.

Use gridType="rectangular" for square or independently spaced U/V grids, "hexagonal" for regular hexagons, "diagrid" for two crossing diagonal families, or "polar" for complete concentric rings and radial lines. Hexagon cellSize is the side length. Diagrid angle is measured from local X; uSpacing and vSpacing measure perpendicular family separation. Polar angularSpacing is in degrees and must divide 360 exactly. Circles are native curves; approximate=True explicitly permits sampled rings when exact circles cannot be constructed by the selected backend.

output="edges" returns a Cluster, output="vertices" a list of unique Vertices (including crossings), and output="faces" a list of partition Faces. The Face output includes partial cells at the clipping boundary. Empty Edge results are None; empty Vertex/Face results are empty lists. Invalid input returns None, with messages suppressed when silent=True.

projection="local" is the OnFace default: dimensions are measured in the face plane. projection="xy" projects a horizontal pattern onto a nonvertical planar Face; XY spacing remains constant on slopes. rotation rotates the pattern in degrees; it does not rotate the clipping Face. origin anchors the lattice, while centre can override the polar centre. Clearance clips to inset regions without shifting the original pattern; OnFace clearance remains a distance in the face plane, including when the pattern is projected from XY. Patterned construction does not accept intrinsic surface mode or legacy U/V divisions, explicit values or labels. Use the existing OnFace interface for those options. All private implementation helpers remain in Grid.py.

Examples:

from topologicpy.Grid import Grid

# Equal spacing on the XY plane.
edges = Grid.OnPlane(width=12, length=8, spacing=1, silent=True)

# Independent X/Y spacing; return the partition Faces.
faces = Grid.OnPlane(width=12, length=8, uSpacing=2, vSpacing=1,
                     output="faces", silent=True)

# Hexagonal cells on an existing planar Face.
faces = Grid.OnFace(face, gridType="hexagonal", cellSize=1,
                    orientation="pointy-top", output="faces", silent=True)

# Diamond diagrid, rotated within the plane.
vertices = Grid.OnPlane(gridType="diagrid", angle=45, rotation=15,
                        output="vertices", silent=True)

# Complete polar pattern, clipped to the Face.
edges = Grid.OnFace(face, gridType="polar", radialSpacing=1,
                    angularSpacing=30, centre=[0, 0, 0], silent=True)

# Horizontal lattice projected onto a sloping Face.
edges = Grid.OnFace(face, gridType="rectangular", projection="xy",
                    spacing=1, origin=[0, 0, 0], silent=True)

class topologicpy.Grid.Grid

Bases: object

Creates grids on planar and non-planar Faces.

Grid.OnFace creates the Edges; Grid.Vertices also finds their intersections.

Methods

`OnFace`(face[, spacing, uSpacing, vSpacing, ...])	Creates a grid on a planar, curved, or NURBS Face.
`OnFaces`(faces[, spacing, origin, direction, ...])	Project one shared XY grid onto planar horizontal/sloping Faces.
`OnPlane`([width, length, spacing, uSpacing, ...])	Creates a finite patterned grid on a plane, defaulting to the XY plane.
`Vertices`(grid[, tolerance, silent])	Return unique grid Edge endpoints and intersections in 3D.

static OnFace(face, spacing: float = 1.0, uSpacing=None, vSpacing=None, uDivisions=None, vDivisions=None, uValues=None, vValues=None, mode: str = 'auto', distribution: str = 'length', xDirection=None, uAlignment: str = 'center', vAlignment: str = 'center', includeBoundary: bool = False, uLabels=None, vLabels=None, approximate: bool = False, samples: int = 128, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False, clearance: float = 0.0, gridType=None, output: str = 'edges', origin=None, rotation: float = 0.0, cellSize=None, orientation: str = 'flat-top', angle: float = 45.0, radialSpacing=None, angularSpacing: float = 30.0, centre=None, projection: str = 'local')

Creates a grid on a planar, curved, or NURBS Face.

mode="auto" uses an intuitive world-oriented planar grid for planar Faces and an intrinsic UV surface grid for non-planar Faces.

In surface mode, U-family lines are constant-U surface isocurves and V-family lines are constant-V isocurves. When the active backend supports exact surface isocurves, they are trimmed by the input Face, so a grid on a curved/NURBS Face contains genuinely curved Edges rather than projected chords.

Each family can be specified independently. Precedence is:

uValues / vValues: explicit normalized parameters in [0, 1].
uDivisions / vDivisions: number of bays.
uSpacing / vSpacing: physical model-unit spacing; if omitted, spacing is used.

For a curved surface, there is no unique globally constant separation between isocurves. Physical U spacing is therefore measured along the central V=0.5 reference curve, and physical V spacing along the central U=0.5 reference curve. distribution="length" uses this same metric for division placement; distribution="parameter" uses equal UV increments.

mode="planar" can be forced for a planar Face and accepts xDirection to control its U direction. mode="surface" can be forced on any Face to use its native parameterization.

Exact non-planar surface isocurves require backend support. By default this method returns None rather than flattening them if exact native curves are unavailable. Set approximate=True explicitly to permit a sampled polyline fallback.

Parameters

facetopologicpy.Face: Input Face.
spacingfloat , optional: Common physical spacing. Default is 1.
uSpacing, vSpacingfloat , optional: Per-family physical spacing overrides.
uDivisions, vDivisionsint , optional: Number of bays in each family.
uValues, vValuesfloat or list , optional: Explicit normalized U/V positions in [0, 1].
modestr , optional: “auto”, “planar”, or “surface”. Default is “auto”.
distributionstr , optional: “length” or “parameter” for surface division placement.
xDirectionlist , optional: Preferred planar U direction. Ignored in surface mode.
uAlignment, vAlignmentstr , optional: “center”, “start”, or “end” for spacing placement.
includeBoundarybool , optional: Include U/V extrema as grid lines. Default is False.
uLabels, vLabelsstr or list , optional: “letters”, “numbers”, a prefix string, or explicit labels.
approximatebool , optional: Permit sampled polylines when native surface isocurves are unavailable. Default is False.
samplesint , optional: Samples used for physical surface metrics and fallback geometry. Does not control exact backend curve geometry. Default is 128.
mantissaint , optional: Decimal precision used in metadata. Default is 6.
tolerancefloat , optional: Geometric tolerance. Default is 0.0001.
silentbool , optional: Suppress errors/warnings. Default is False.
clearancefloat , optional: Nonnegative distance from outer/hole boundaries in the Face plane, measured in model units. Default is 0. Positive clearance supports planar grid mode only and clips the original grid to every region returned by Face.ByOffset. Origin, spacing, divisions, labels and normalized positions are computed from the original Face. Boundary grid lines that no longer intersect the inset region are omitted. Complete erosion or a failed offset returns None without reverting to the original Face. Exact curved planar boundaries are preserved.
gridTypestr , optional: “rectangular” (or “regular”), “hexagonal”, “diagrid”, or “polar”. None preserves the existing planar/surface grid behavior. Explicit patterns require a planar Face. Default is None.
outputstr , optional: “edges” returns a Cluster, “vertices” a list of unique Vertices, and “faces” a list of partition Faces. Default is “edges”.
origintopologic_core.Vertex or list , optional: Pattern origin as a Vertex or three coordinates, projected onto the face plane. Defaults to the face parameter centre. The original origin is retained when applying clearance.
rotationfloat , optional: Counterclockwise pattern rotation in degrees. Default is 0.
cellSizefloat , optional: Hexagon side length. Defaults to spacing.
orientationstr , optional: Hexagon orientation: “flat-top” or “pointy-top”. Default is “flat-top”.
anglefloat , optional: Diagrid family directions, plus/minus this angle from local X. Between 0 and 90 degrees. Family spacing is perpendicular to each line family. Default is 45.
radialSpacingfloat , optional: Spacing between complete polar rings. Defaults to spacing.
angularSpacingfloat , optional: Polar ray spacing in degrees, dividing 360 exactly, at most 180. Default is 30. Circles are exact when supported by the backend; approximate=True permits sampled rings otherwise.
centretopologic_core.Vertex or list , optional: Polar centre, projected onto the face plane. Overrides origin for polar patterns. Default is None.
projectionstr , optional: “local” measures pattern dimensions within the face plane. “xy” projects a world XY pattern onto a nonvertical planar Face. Default is “local”.

Returns

topologic_core.Cluster or list: Cluster of Edges, list of unique Vertices, or list of Faces. Invalid input returns None. Empty grids return None for Edges and an empty list for Vertices/Faces.

Notes

grid_axis="u" denotes a constant-U line (which runs in the surface V direction), and vice versa.

static OnFaces(faces, spacing: float = 1.0, origin=None, direction=None, includeBoundary: bool = False, tolerance: float = 0.0001, clearance: float = 0.0)

Project one shared XY grid onto planar horizontal/sloping Faces.

Unlike independent OnFace calls, all faces share the same grid origin and direction. Spacing is measured in XY, not along a slope. Holes and face boundaries clip the lines. Returns a Cluster of grid Edges or None when no lines intersect. Use OnFace for intrinsic curved-surface grids. clearance is a nonnegative XY distance in model units (default 0). Continuous adjoining patches are inset together using Face.ByOffset; internal slab seams are not treated as physical boundaries. The original XY grid origin/direction/spacing remain fixed. All offset regions survive; complete erosion returns None. Curved boundaries must be tessellated for this projected multi-face method.

static OnPlane(width: float = 10.0, length: float = 10.0, spacing: float = 1.0, uSpacing=None, vSpacing=None, gridType: str = 'rectangular', output: str = 'edges', origin=None, direction=None, rotation: float = 0.0, cellSize=None, orientation: str = 'flat-top', angle: float = 45.0, radialSpacing=None, angularSpacing: float = 30.0, centre=None, includeBoundary: bool = False, clearance: float = 0.0, approximate: bool = False, samples: int = 128, tolerance: float = 0.0001, silent: bool = False)

Creates a finite patterned grid on a plane, defaulting to the XY plane.

Parameters

width, lengthfloat , optional: Positive dimensions of the rectangular clipping Face. Default is 10.
spacingfloat , optional: Common spacing in model units. Default is 1.
uSpacing, vSpacingfloat , optional: Rectangular axis spacing or diagrid perpendicular family spacing. Defaults to spacing.
gridTypestr , optional: “rectangular”, “hexagonal”, “diagrid”, or “polar”. Default is “rectangular”.
outputstr , optional: “vertices”, “edges”, or “faces”. Default is “edges”.
origintopologic_core.Vertex or list , optional: Centre of the clipping rectangle and grid origin, as a Vertex or three coordinates. Default is the world origin.
directionlist , optional: Plane normal. Default is [0, 0, 1].
rotationfloat , optional: Counterclockwise pattern rotation in degrees within the plane. The clipping rectangle is not rotated. Default is 0.
cellSizefloat , optional: Hexagon side length. Defaults to spacing.
orientationstr , optional: “flat-top” or “pointy-top” hexagons. Default is “flat-top”.
anglefloat , optional: Diagrid directions are plus/minus this angle from the local X axis. Must be between 0 and 90 degrees. Default is 45.
radialSpacingfloat , optional: Polar ring spacing. Defaults to spacing.
angularSpacingfloat , optional: Polar ray spacing in degrees, dividing 360 exactly, at most 180. Only complete circular patterns are supported. Default is 30.
centretopologic_core.Vertex or list , optional: Polar centre. Defaults to origin.
includeBoundarybool , optional: Include clipping boundary Edges. Default is False.
clearancefloat , optional: Nonnegative distance from the clipping boundary. Default is 0.
approximatebool , optional: Permit sampled polar rings if exact circles are unavailable. Default is False.
samplesint , optional: Number of samples for boundary bounds or fallback rings. Default is 128.
tolerancefloat , optional: Geometric tolerance. Default is 0.0001.
silentbool , optional: If True, suppress error and warning messages. Default is False.

Returns

topologic_core.Cluster or list: Cluster of Edges, list of unique Vertices, or list of Faces. Invalid input returns None. Empty grids return None for Edges and an empty list for Vertices/Faces.

static Vertices(grid, tolerance: float = 0.0001, silent: bool = False)

Return unique grid Edge endpoints and intersections in 3D.

Parameters

gridtopologic_core.Topology or list: A grid topology (such as the Cluster returned by Grid.OnFace), or a list of Edges. Edges need not have been split at crossings.
tolerancefloat, optional: Model-unit distance used for intersections and deduplication. Default is 0.0001.
silentbool, optional: Suppress error messages. Default is False.

Returns

list: Vertices, with endpoints first, followed by new intersection Vertices. Empty input returns an empty list; invalid input or a failed native intersection operation returns None.

Notes

PythonOCC splits all Edges in one native operation, supporting exact curved Edges as well as straight Edges. TopologicCore uses analytical 3D segment intersections with bounding-box pruning. Spatial hashing deduplicates the output without comparing every pair of Vertices. Overlapping Edges contribute their endpoints; an overlap is not sampled into an infinite set of intersection points. Input geometry is not replaced by the split geometry.