[][src]Module rgmsh::model

Inspection and manipulation of geometry models.

There are two model types:

  1. OccModel, which uses the OpenCASCADE geometry kernel.
  2. GeoModel, which uses the built-in Gmsh geometry kernel.

Either should suffice for most projects.

Creating a model

The only way to get a model is through a Gmsh context object.

let gmsh = Gmsh::initialize()?;

let mut geo: GeoModel = gmsh.create_native_model("geo")?;

let mut occ: OccModel = gmsh.create_occ_model("occ")?;

The model is only valid for the lifetime of Gmsh.

This example deliberately fails to compile
let gmsh = Gmsh::initialize()?;
let mut geom: OccModel = gmsh.create_occ_model("model")?;

// -- do some stuff with geom

// drop the Gmsh context
// try to use the model afterwards
geom.add_point(0., 0., 0.)?; // won't compile

Create, modify and delete shapes

You can define points, lines, 2D surfaces and 3D volumes. After defining a shape, you'll get a geometry tag to identify1 it.

// make a model using the default geometry kernel and call it `model`.
let mut geom = gmsh.create_native_model("model")?;

// make a point
let p1: PointTag = geom.add_point(0., 0., 0.)?;
// and another
let p2: PointTag = geom.add_point(1., 1., 0.)?;

// create a line from the two points
let l1: CurveTag = geom.add_line(p1, p2)?;

There are two ways to make geometries in Gmsh: top-down and bottom-up.

Top-down geometry with the OpenCASCADE kernel

With the OpenCASCADE kernel, you can directly specify the shape you want to make.

let mut geom = gmsh.create_occ_model("model")?;

// make a box starting at (0, 0, 0) with side extents (1, 1, 1)
let b = geom.add_box((0., 0., 0.), (1., 1., 1.))?;

// make a sphere centered at (10, 10, 10) with radius 2.5
let s = geom.add_sphere((10., 10., 10.), 2.5)?;

// make a torus centered at (-1, -2, -3) with major radius 5 and minor radius 2
let t = geom.add_torus((-1., -2., -3.), (5., 2.))?;

Bottom-up geometries with either the OpenCASCADE or built-in kernel

Differences between the CAD engines

OpenCASCADE is a widely-used CAD engine, so it's a good default choice. You can directly define larger shapes without making their smaller components first. You also get access to powerful Boolean geometry operations for making complex shapes.

The Gmsh manual has more information on the differences between the two kernels:

The built-in CAD kernel provides a simple CAD engine based on a bottom-up boundary representation approach: you need to first define points, then curves, then surfaces and finally volumes.

The OpenCASCADE kernel allows one to build models in the same bottom-up manner, or by using a constructive solid geometry approach where solids are defined first. Boolean operations can then be performed to modify them.


Nearly all model functions can fail. Fallible functions will result a GmshResult.

You can use the ? operator for terse error handling.

fn main() -> GmshResult<()> {
    let gmsh = Gmsh::initialize()?;
    let mut geom = gmsh.create_native_model("model")?;

    let p1 = geom.add_point(0., 0., 0.)?;


Geometry tags

Geometry tags are used for:

The different geometry tags are:

Since tags can only be created from successful geometry operations, you can't use raw integers for tags.

This example deliberately fails to compile
// try to make a point from a raw integer
let p1 = PointTag(1); // won't compile
// try to make a line from two raw integers
let l1 = CurveTag(1, 2); // won't compile

This design differs from other Gmsh API implementations. For example, using the C++ API, the following example will compile but cause a runtime error.

#include "gmsh.h"
int main() {
    gmsh::model::geo::addLine(1, 2); // (!)

The Rust API avoids such bugs for a single model by only making tags available through API functions.

Model shadowing

Since two models can have identical tag values, tags from one can be used on the other. It's your responsibility to make sure tags are used with the right model.

If you're lucky, using the wrong tags will cause a runtime error.

let mut geom_a = gmsh.create_occ_model("jimbo")?;
let mut geom_b = gmsh.create_native_model("aircraft-carrier")?;

let p_a = geom_a.add_point(0., 0., 0.)?;

let p_b1 = geom_b.add_point(0., 1., 0.)?;
let p_b2 = geom_b.add_point(1., 1., 0.)?;

// points from different models can have the same value
assert!(p_a == p_b1, "Point tags are different!");

// Bad! Using tags from one model with another.
let line = geom_a.add_line(p_b1, p_b2);

If you're unlucky, the tags will exist in both models, causing a silent logic error in your program. In the API's eyes, you've given it valid tags, and it's going to go ahead and do what you asked for.

let mut geom_a = gmsh.create_occ_model("jimbo")?;
let p_a1 = geom_a.add_point(0., 0., 0.)?;
let p_a2 = geom_a.add_point(1., 0., 0.)?;

let mut geom_b = gmsh.create_native_model("aircraft-carrier")?;
let p_b1 = geom_b.add_point(0., 1., 1.)?;
let p_b2 = geom_b.add_point(0., 1., 1.)?;

// Very bad! A silent logic error. You're on your own debugging this one.
let line = geom_a.add_line(p_b1, p_b2);

Describing shapes using Physical Groups

Physical Groups are Gmsh's way to associate information with geometries. Physical Groups only associate a name with geometry entities and it is up to client software to correctly interpret the Physical Group information.

Some common uses for Physical Groups are:

  1. In most circumstances, tags are a unique identifier. There are some exceptions:

    • If tags are removed from a model, they can be used again for other shapes.
    • One Gmsh context can have many models. It's your responsibility to avoid using tags from one model in another.


pub use crate::interface::geo::*;
pub use crate::interface::occ::*;
pub use shapes::*;



Shape objects.



A curve tag, built from points. The curve type includes straight lines. 1D.


An instance of the built-in geometry kernel.


An instance of the OpenCASCADE geometry kernel.


A point tag. Points are used to build larger shapes. 0D.


A shell tag. Shells are built from surface loops. 2.5D.


A surface tag. Surfaces are built from closed wires. 2D.


A volume tag. Volumes are built from closed shells. 3D.


A wire tag. Wires are built from curves. Wires are a path of multiple curves. 1.5D.