[−][src]Module rgmsh::model

Inspection and manipulation of Gmsh geometry models.

There are two CAD engines:

  1. The built-in Gmsh geometry kernel.
  2. The OpenCASCADE geometry kernel.

Either kernel should suffice for most projects.

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.

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

let gmsh = Gmsh::initialize()?;
let mut geom = gmsh.create_native_model("model")?;

The model is only valid for the lifetime of Gmsh.

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

// -- do some stuff with geom

// drop the Gmsh context
std::mem::drop(gmsh);
// 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

Geometry tags

Geometry tags are used for:

  • accessing shape information,
  • making more complex shapes (like a line from two points),
  • removing a shape from the model

The different geometry tags are:

  • PointTag
  • CurveTag
  • WireTag
  • SurfaceTag
  • ShellTag
  • VolumeTag

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::initialize();
    gmsh::model::geo::addLine(1, 2); // (!)
    gmsh::finalize();
}

The Rust API avoids such bugs for a single model by only making tags available through API functions. However, the Rust API has a similar issue if there are two or more models. Since two models can have identical point 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);
assert!(line.is_err());

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);
assert!(line.is_ok());

Nearly all geometry 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.)?;

    Ok(())
}

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:

  • Materials

  • Boundary conditions

  • Part names

  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.
     ↩

Re-exports

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

Modules

geo

Autogenerated method implementations for the built-in geometry kernel

occ

The OpenCASCADE geometry kernel

shapes

Shape objects.

Structs

CurveTag

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

GeoModel

An instance of the built-in geometry kernel.

OccModel

An instance of the OpenCASCADE geometry kernel.

PointTag

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

ShellTag

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

SurfaceTag

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

VolumeTag

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

WireTag

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