[−][src]Module rgmsh::model
Inspection and manipulation of Gmsh geometry models.
There are two CAD engines:
- The built-in Gmsh geometry kernel.
- 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
.
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.
// 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
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::*; |
Modules
geo | Autogenerated method implementations for the built-in geometry kernel |
occ | The |
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 |
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. |