Meshfree Module

Overview

The Meshfree module provides tools to generate the node (point cloud) distribution required by the Meshless Local Petrov-Galerkin (MLPG) method directly from a GM_CadModel geometry.

Unlike classical FEA, MLPG does not require a mesh. Only a scattered set of nodes with associated normals and boundary flags is needed. This module handles:

• Extracting planar faces from a BRep (OCC) CAD model.
• Placing boundary nodes along face edges at a uniform spacing h.
• Filling the interior with quasi-random nodes via the Bridson Poisson Disk algorithm.
• Saving and loading point clouds in the .gmpcloud format (with embedded display settings).
• Visualising the cloud interactively using the PointCloudEditor (PyVista + PyQt5).
• Generating point clouds for individual CAD entities directly from the editor GUI.
• Defining boundary condition joints on selected CAD sub-entities via the interactive editor.
• Packaging geometry, point cloud, and joints into a unified GM_MfreeModel container.
• Saving and loading the complete analysis model in the .gmmfm format (single portable file).

Quick Start

1 — Load a CAD model

from GM_modules.Cad import GM_CadModel

model = GM_CadModel()
model.load("my_part.step")

2 — Generate the point cloud

from GM_modules.Meshfree.src.generator import PointCloudGenerator

gen = PointCloudGenerator(h=2.0, seed=42)
cloud = gen.generate(model)
print(cloud)
# GM_PointCloud(name='my_part', dim=2, n=312, boundary=48, interior=264)

3 — Save and reload

cloud.save("my_part.gmpcloud")

from GM_modules.Meshfree.src.point_cloud import GM_PointCloud
cloud2 = GM_PointCloud.load("my_part.gmpcloud")

4 — Visualise with the interactive editor

from GM_modules.Meshfree.src.point_cloud_editor import PointCloudEditor

editor = PointCloudEditor(model, cloud)
editor.show(title="My Part — Point Cloud")

5 — Visualise with plain pyvista

import pyvista as pv

plotter = pv.Plotter()
cloud.add_to_pyvista_plotter(plotter, color="red", boundary_color="blue")
plotter.show()

6 — Build a complete meshfree model and apply joints

from GM_modules.Meshfree.src.mfree_model import GM_MfreeModel

# Wrap geometry + cloud into a unified container
mfree = GM_MfreeModel(cad_model=model, point_cloud=cloud, name="my_part")

# Open the editor with the model attached.
# Apply joints via: RMB on viewport → Apply Joint → External…
editor = PointCloudEditor(model, cloud)
editor.mfree_model = mfree
editor.show(title="My Part — Meshfree Editor")

# Save the complete model (geometry + cloud + joints) to a single file.
mfree.save("my_part.gmmfm")

# Reload later (e.g. in a solver node).
mfree2 = GM_MfreeModel.load("my_part.gmmfm")

Dependencies

MLPG Method — Brief Overview

The Meshless Local Petrov-Galerkin method (Atluri & Zhu, 1998) solves PDEs by defining a weak form on a local support domain around each node, without requiring a global mesh. The inputs required by any MLPG solver are:

• Interior nodes: scattered inside the problem domain.
• Boundary nodes: placed on the domain boundary, with associated outward normals for applying Neumann conditions.
• A characteristic length h that controls the support radius of the basis / weight functions (e.g. MLS, Wendland RBF).

This module handles step 1 (node generation). The assembly of the local weak forms and the linear system will be implemented in a subsequent module.

The GM_PointCloud Object

GM_PointCloud is the central data container. Every node is represented by aligned arrays:

Useful methods

Samplers

All samplers derive from BaseSampler and share the same interface:

sampler = SurfaceSampler2D(h=2.0)
cloud   = sampler.sample(entity)   # entity is a CadEntity leaf

SurfaceSampler2D Implemented

Places boundary nodes uniformly along every edge of a planar face at arc-length spacing h. Uses OCC GCPnts_UniformAbscissa for accurate arc-length discretisation.

Outward in-plane normal at each node is computed as: n = T × face_normal, where T is the edge tangent in the CCW wire-traversal direction. This guarantees the correct outward direction for a standard FACE_OUTER_BOUND.

InteriorSampler2D Implemented

Fills the interior using the Fast Poisson Disk algorithm (Bridson 2007). The steps are:

• Generate candidate nodes in the 2-D axis-aligned bounding box of the face with minimum separation h.
• Reject candidates outside the face boundary using matplotlib.path.Path.contains_points().
• Lift surviving 2-D points to 3-D world coordinates.
• Assign all normals equal to the face normal (suitable for MLPG).

SurfaceSampler3D Planned

Will place nodes on the surface of 3-D solid / shell entities. Not yet implemented; calling sample() raises NotImplementedError.

InteriorSampler3D Planned

Will fill the interior of 3-D solids using a 3-D extension of the Bridson algorithm. Not yet implemented.

The .gmpcloud File Format

A .gmpcloud file is a ZIP archive containing five entries:

GM_MfreeModel

GM_MfreeModel is the unified container that wraps all data needed for a meshfree analysis: CAD geometry, the point cloud, and boundary condition joints. It is the central object exchanged between nodes in the GearMaster Visual workflow:

CAD_Editor → Meshfree_Editor → [GM_MfreeModel] → Mfree_Solver

Persistence via the .gmmfm format (see below):

model.save("analysis.gmmfm")
model2 = GM_MfreeModel.load("analysis.gmmfm")

Boundary Conditions — Joints

Boundary conditions in GearMaster Meshfree are defined as Joints. A joint ties a scoping region (one or more CAD faces, edges, or vertices) to a reference point and prescribes which degrees of freedom are constrained on all cloud nodes found within that region.

Joint types

Defining a joint in the PointCloudEditor

1. Select one or more faces / edges / vertices on the CAD geometry in the 3-D viewport.
2. Right-click in the viewport → Apply Joint → External…
3. Fill in the dialog: name, type, behaviour, DOFs, and optionally adjust the reference point coordinates.
4. Click OK. The joint appears in the Boundary Conditions panel and its actors (a violet sphere + connector lines) remain visible in the viewport.

Data stored per joint

The .gmmfm File Format

A .gmmfm (GearMaster Meshfree Model) file is a ZIP archive that bundles the complete analysis model — geometry, point cloud, and joints — into a single portable file.

API — GM_PointCloud

from GM_modules.Meshfree.src.point_cloud import GM_PointCloud

GM_PointCloud is a Python dataclass. All constructor arguments are validated in __post_init__.

Constructor

GM_PointCloud(
    points           : np.ndarray,           # (N, 3) float64
    normals          : np.ndarray,           # (N, 3) float64
    is_boundary      : np.ndarray,           # (N,)   bool
    entity_ids       : np.ndarray,           # (N,)   str
    dimension        : int = 2,              # 2 or 3
    name             : str = "point_cloud",
    display_settings : PointDisplaySettings = PointDisplaySettings(),
)

Read-only properties

cloud.n_points          # int – total node count
cloud.n_boundary        # int – boundary node count
cloud.n_interior        # int – interior node count
cloud.unique_entity_ids # list[str] – sorted unique entity identifiers

API — PointDisplaySettings

from GM_modules.Meshfree.src.point_display_settings import PointDisplaySettings

Lightweight dataclass that controls how a GM_PointCloud is rendered inside the PointCloudEditor. Persisted in manifest.json of every .gmpcloud file (format version "1.1").

Fields

Serialisation

d        = settings.to_dict()                    # dict – JSON-serialisable
settings = PointDisplaySettings.from_dict(d)     # restore from dict (tolerant of missing keys)

API — SurfaceSampler2D

from GM_modules.Meshfree.src.samplers.surface_sampler_2d import SurfaceSampler2D

sampler = SurfaceSampler2D(
    h     : float,             # arc-length spacing along edges
    n_max : int | None = None, # hard node limit per entity
)
cloud = sampler.sample(entity)  # entity: CadEntity leaf with planar face(s)

API — InteriorSampler2D

from GM_modules.Meshfree.src.samplers.interior_sampler_2d import InteriorSampler2D

sampler = InteriorSampler2D(
    h     : float,             # minimum inter-node distance
    n_max : int | None = None, # hard node limit per entity
    k     : int        = 30,   # Bridson candidate count per active sample
    seed  : int | None = None, # random seed (None = non-deterministic)
)
cloud = sampler.sample(entity)

API — PointCloudGenerator

from GM_modules.Meshfree.src.generator import PointCloudGenerator

gen = PointCloudGenerator(
    h                  : float,
    n_max_per_entity   : int | None = None,
    k                  : int        = 30,
    seed               : int | None = None,
    n_jobs             : int        = 1,
    verbose            : bool       = False,
)
cloud = gen.generate(model)         # model: GM_CadModel (loaded)
cloud = gen.generate_entity(entity) # single entity convenience

API — I/O Functions

from GM_modules.Meshfree.src.io.gmpcloud_io import save_gmpcloud, load_gmpcloud

# Save
path = save_gmpcloud(cloud, "output.gmpcloud", extra_metadata={"h": 2.0})

# Load
cloud = load_gmpcloud("output.gmpcloud")

# Convenience wrappers on GM_PointCloud:
cloud.save("output.gmpcloud")
cloud2 = GM_PointCloud.load("output.gmpcloud")

The .gmpcloud extension is appended automatically when absent. extra_metadata is an optional dictionary stored in manifest.json under the key "extra"; it is not read back by load_gmpcloud.

API — PointCloudEditor

from GM_modules.Meshfree.src.point_cloud_editor import PointCloudEditor

editor = PointCloudEditor(
    model              : GM_CadModel,
    cloud              : GM_PointCloud | None = None,
    linear_deflection  : float = 0.1,
    angular_deflection : float = 0.5,
    background_color   : str   = "white",
    mode               : str   = "view",   # "view" or "edit"
)
editor.show(
    title              : str             = "",
    window_size        : tuple[int, int] = (1280, 800),
    blocking           : bool            = True,
)

PointCloudEditor extends CadEditor with a Point Cloud panel in the left sidebar. CAD geometry and point cloud share the same PyVista 3-D viewport.

Left panel — Point Cloud tree

Each loaded entity appears as a collapsible tree node with Interior and Boundary child items. Checkboxes toggle actor visibility in the viewport directly.

Meshfree menu

Per-entity generation — CAD tree right-click

Right-click any leaf entity in the CAD feature tree and choose Generate Point Cloud.

• A dialog asks for the node spacing h (model units).
• If a cloud already exists for that entity, a confirmation dialog offers OK (overwrite) or Cancel.
• The new entity sub-cloud is merged into the global GM_PointCloud and the viewport updates immediately.
• Colour assignment cycles through a fixed palette and remains stable across overwrite operations.

Point Display dialog

Accessed via Meshfree → Point Display….

The dialog has three buttons:

• Apply — applies settings immediately; dialog stays open for further adjustments.
• OK — applies settings and closes the dialog.
• Cancel — reverts to the settings that were active when the dialog was opened, then closes.

Left panel — Boundary Conditions tree

Below the Point Cloud panel a second tree widget lists all joints under a collapsible “Joints” root node. Each joint entry shows:

• Scoping — summary of selected sub-entities (e.g. 2 faces).
• Type — Fixed or Custom.
• Behaviour — Rigid.
• Ref. point — coordinates of the reference point.
• Ref. point ID / Constrained DOFs / Connected points — read-only computed values (rendered in grey).

Joint context menu (RMB in BC tree)

Apply Joint dialog

Opened via RMB on the viewport → Apply Joint → External… (requires a selection).

API — GM_MfreeModel

from GM_modules.Meshfree.src.mfree_model import GM_MfreeModel

Constructor

GM_MfreeModel(
    cad_model   : GM_CadModel,
    point_cloud : GM_PointCloud | None = None,
    name        : str                  = "",
)

Joint management

model.add_joint(joint)            # add a GM_Joint (raises ValueError on duplicate id)
model.remove_joint(joint_id)      # remove by id (raises KeyError if not found)
joint = model.get_joint(joint_id) # retrieve by id (raises KeyError if not found)
model.joints                      # list[GM_Joint] – copy of the internal list
model.has_joints                  # bool

Persistence

path  = model.save("analysis.gmmfm")   # returns resolved Path
model = GM_MfreeModel.load("analysis.gmmfm")

API — GM_Joint

from GM_modules.Meshfree.src.joints import GM_Joint, ScopingItem

Constructor

GM_Joint(
    name       : str,
    scoping    : list[ScopingItem],
    joint_type : str         = "Fixed",      # "Fixed" | "Custom"
    behaviour  : str         = "Rigid",
    joint_id   : str | None  = None,         # auto-generated 8-char hex if None
)

Key attributes

Serialisation

d     = joint.to_dict()        # JSON-serialisable dict
joint = GM_Joint.from_dict(d)  # reconstruct (tolerant of missing keys)

ScopingItem

ScopingItem(
    entity_id        : str,   # CAD entity identifier
    sub_entity_type  : str,   # "face" | "edge" | "vertex"
    sub_entity_index : int,
)

Module File Structure

GM_modules/Meshfree/
├── __init__.py
├── src/
│   ├── __init__.py                # exports GM_PointCloud, PointCloudGenerator, GM_MfreeModel
│   ├── mfree_model.py             # GM_MfreeModel container
│   ├── point_cloud.py             # GM_PointCloud dataclass
│   ├── point_display_settings.py  # PointDisplaySettings dataclass
│   ├── generator.py               # PointCloudGenerator orchestrator
│   ├── joints.py                  # GM_Joint, ScopingItem, JOINT_TYPES, BEHAVIOURS
│   ├── joint_dialog.py            # Qt dialog for boundary condition joints
│   ├── point_cloud_editor.py      # PointCloudEditor + _PointCloudEditorWindow
│   ├── samplers/
│   │   ├── __init__.py
│   │   ├── base_sampler.py        # BaseSampler ABC + OCC helpers
│   │   ├── surface_sampler_2d.py  # boundary nodes on planar edges
│   │   ├── interior_sampler_2d.py # interior nodes (Bridson + rejection)
│   │   ├── surface_sampler_3d.py  # PLACEHOLDER
│   │   └── interior_sampler_3d.py # PLACEHOLDER
│   └── io/
│       ├── __init__.py
│       ├── gmpcloud_io.py         # save / load .gmpcloud
│       └── gmmfm_io.py            # save / load .gmmfm
├── tests/
│   ├── test_point_cloud_io.py     # 37 tests
│   ├── test_samplers_2d.py        # 49 tests
│   └── test_generator.py          # 30 tests
├── examples/
│   └── example_generate_point_cloud.py
└── docs/
    └── manual.html   ← this file

Roadmap