GoTools g2 file format

The GoTools file format (.g2) for geometry entities

For the geometric entities in GoTools with read and write functionality in the GoTools file format, this page describes the form this file format takes. Note that the GoTools file format is a simple format that does not support pointers. Thus, duplication of information may occur.

Each geometric entity is represented by an entity code, as listed below. The file splits into an object header that takes the same form for all geometric entities, and an object body that has a specific form for each geometric entitity. Values are either separated by a blank space or a new line. Both separators are equivalent, but the latter is used to improve readability. It is not possible to write comments in g2-files.

Entity codes and geometric entities

The object header

All geometry entities are preceeded by the object ObjectHeader in a stream, which contains information about the class type of the geometry object to follow and the version number of the file format. The format of the header is as follows:

class type. The entity code given in the list above.
major version. Always 1.
minor version. Always 0.
auxiliary data. 0 if the default colour is chosen, 4 if the rgb-colour code is chosen. In the latter case, the entity is followed by 4 integer digits between 0 and 255 giving the colours red, green, blue, and the alpha (blending) value.

Example of an object header for a circle with default colour

130 1 0 0

The object body

SplineCurve

The object body of SplineCurve takes the following format:

dimension of geometry space, whether or not the curve is rational: 1=rational, 0=non-rational
the number of coefficients, the polynomial order (i.e., degree + 1)
the knot vector; multiple knots are represented by giving the knot value several times
the curve coefficients

The curve coefficients are given continuously, normally divided by a carriage return for each coefficient. The sequence is, in the non-rational case, $(x_i, y_i, z_i)$, with $i=1, \ldots n$, where $n$ is the number of coefficients. In the rational case, the coefficients are given as $(x_i h_i, y_i h_i, z_i h_i, h_i)$, with $i=1, \ldots n $. Here $h_i$ is the weight associated the current coefficient. Note that the coefficients are represented by the weight multiplied with the $x$, $y$ and $z$-value.

Example of a spline curve

Including the header, a linear non-rational spline curve in the parameter interval $[0,1]$ with no inner knots is specified by:

CurveOnSurface

The object body of CurveOnSurface takes the following format:

whether or not the parameter space curve is the master information (1=parameter curve is master, 0=space curve is master), the entity type of the parameter curve (0 if no such curve exists), the entity type of the space curve (0 if no such curve exists)
the description of the parameter curve according to the rules for that curve type
the description of the space curve according to the rules for that curve type

Either the parameter curve, the space curve or both are given. Information regarding constant parameter information for the curve on the surface is not covered by the file format.

Note that CurveOnSurface also contains information about a ParamSurface. Thus, the g2-representation of CurveOnSurface is not stand-alone. It needs to be combined with BoundedSurface; see the example in this section of how CurveOnSurface is used in this context.

Line

The object body of Line takes the following format:

the dimension of the geometry space
a point on the line
the direction of the line
a flag, 0 or 1, for unbounded or bounded
if the line is bounded, the start and end parameters

Circle

The object body of Circle takes the following format:

the dimension of the geometry space
the radius of the circle
the centre of the circle
the normal of the plane in which the circle lies
the vector from the centre of the circle towards the "x-axis" --- the start point of the default parametrization of the circle
the start and end parameters

The circle has a default implicit parametrization from 0 to $2\pi$.

Example of a circle

130 1 0 0
dim
rad
c_x c_y c_z
n_x n_y n_z
v_x v_y v_z

Ellipse

The object body of Ellipse takes the following format:

the dimension of the geometry space
the major radius of the ellipse
the minor radius of the ellipse
the centre of the ellipse
the normal of the plane in which the ellipse lies
the vector from the centre of the ellipse towards the "x-axis" --- the start point of the default parametrization

BoundedCurve

A BoundedCurve is expected to be bounded both parametrically and geometrically. Thus, a flag describing whether or not the restriction in the parameter space or in geometry space is preferred is included in the format.

The object body takes the following format:

Whether the restriction in the parameter space is the master (1 if true)
The start parameter of the bounded curve, the end parameter of the bounded curve
The start point of the bounded curve in geometry space
The end point of the bounded curve in geometry space
The underlying curve described according to its entity type

Example of a bounded curve

We define a bounded line from the point (0,0,0) to (1,0,0), where the position in space is the master regarding the bounding points:

Here 120 denotes the entity number for a line and the dimension of the geometry space is 3.

Hyperbola

Parabola

SplineSurface

The object body of a SplineSurface takes the following format:

dimension of the geometry space, whether or not the surface is rational: 1=rational, 0=non-rational
the number of coefficients in the first parameter direction, the polynomial order in this direction (i.e., degree+1)
the knot vector in the first parameter direction, multiple knots are represented by giving the knot value several times
the number of coefficients in the second parameter direction, the polynomial order in this direction (i.e., degree+1)
the knot vector in the second parameter direction
the surface coefficients

The surface coefficients are provided in a sequence, row-wise and from top to bottom in the reflected lexicographic order,

$$(x_{1,1}, y_{1,1}, z_{1,1}), (x_{2,1}, y_{2,1}, z_{2,1}), ..., (x_{n,1}, y_{n,1}, z_{n,1}),$$ $$(x_{1,2}, y_{1,2}, z_{1,2}), (x_{2,2}, y_{2,2}, z_{2,2}), ..., (x_{n,2}, y_{n,2}, z_{n,2}),$$ $$...,$$ $$(x_{1,m}, y_{1,m}, z_{1,m}), (x_{2,m}, y_{2,m}, z_{2,m}), ..., (x_{n,m}, y_{n,m}, z_{n,m}).$$

Here $n$ is the number of coefficients in the first parameter direction, and $m$ is the number of coefficients in the second parameter direction.

As for spline curves, in the rational case the coefficients are multiplied by the weights and an extra entry (from the homogenization) is given for each coefficient.

Example of a spline surface

A simple non-rational, bilinear surface with no inner knots is represented as:

BoundedSurface

A BoundedSurface consists of an underlying rectangular parametric surface and one or more trimming loops. The object body takes the following format:

The entity code of the underlying surface
The number of trimming loops
For each trimming loop
1. The number of curves in the current trimming loop
2. The tolerance within which the loop is found to be continuous
3. The curves in the trimming loop, one by one

The trimming curves are of type ParamCurve, but in most cases they will be represented as a CurveOnSurface.

Example of a bounded surface

The following example illustrates the format of a BoundedSurface. The underlying surface is a Plane, as can be seen from the entity number 250 on line two. The 3 curves in the trimming loop are all of type CurveOnSurface. Note that the entity number of CurveOnSurface does not appear. The space curve corresponding to the CurveOnSurface is the master, and the only curve describing the trimming curve. This is given by the line 0 0 100, which occurs for every curve and should be interpreted as: the space curve is the master, the parameter curve does not exist, the space curve is a spline curve. Following this line is the body of a spline curve in the g2-format.

210 1 0 0
250 
3
0 0 0
0 0 1
1 0 0
1
-3 3
-3 3
0

1
3 0.0001

0 0 100
3 0
2 2
0 0 1 1
-1 0 0
0 -1 0

0 0 100
3 0
2 2
0 0 1 1
0 -1 0
-0.5 2 0

0 0 100
3 0
4 3
0 0 0 0.5 1 1 1
-0.5 2 0
-1 2 0
-2 1 0
-1 0 0

In this case the two first trimming curves are linear spline curves while the last one is of order 3 (degree 2) and has one inner knot. All the curves are non-rational.

SurfaceOnVolume

GoBaryPolSurface

GoHBSplineParamSurface

CompositeSurface

Plane

The object body of a Plane takes the following format:

The dimension of the geometry space
A point in the plane
The normal of the plane
One vector in the set of vectors spanning the plane
A flag, 0 or 1, for unbounded or bounded
If the plane is bounded, the four bounds umin, umax, vmin, vmax describing a bounding box in the parameter domain
A flag, 0 or 1, indicating whether or not the u- and v-parameter directions are swapped.

Example of a plane

The plane used as the underlying surface in the previous example has the format:

Cylinder

The object body of a Cylinder takes the following format:

The dimension of the geometry space
The cylinder radius
A point on the cylinder axis
The cylinder axis
The vector from the cylinder axis towards the cylinder surface giving the start point of the default parametrization
A flag, 0 or 1, for unbounded or bounded in the linear direction
If unbounded, the bounding parameters: umin, umax
If bounded, the bounding parameters: umin, umax, vmin, vmax
A flag, 0 or 1, indicating whether or not the u- and v-parameter directions are swapped

Sphere

The object body of a Sphere takes the following format:

The dimension of the geometry space
The radius of the sphere
The centre of the sphere
The axis on which the degeneracies of a NURBS representation of the sphere will lie, i.e., the sphere axis
The vector from the sphere axis towards the sphere surface giving the start point of the default parametrization
The bounding parameters: umin, umax, vmin, vmax
A flag, 0 or 1, indicating whether or not the u- and v-parameter directions are swapped

Example of a sphere

A sphere with centre (1.5, 0, 0) and radius 1.5 is represented in the g2-format as

270 1 0 0
3
1.5
1.5 0 0
0 0 1
1 0 0
0 6.283185307179586
-1.5707963267948966 1.5707963267948966
0

Cone

The object body of a Cone takes the following format:

The dimension of the geometry space
The cone radius at the position of the point on the cone axis
A point on the cone axis
The cone axis
The vector from the cone axis towards the cone surface giving the start point of the default parametrization
The opening angle of the cone
A flag, 0 or 1, for unbounded or bounded in the linear direction
If unbounded, the bounding parameters: umin, umax
If bounded, the bounding parameters: umin, umax, vmin, vmax
A flag, 0 or 1, indicating whether or not the u- and v-parameter directions are swapped

Torus

The object body of a Torus takes the following format:

The dimension of the geometry space
The major radius of the torus
The minor radius of the torus
The torus centre
The mid axis of the torus
The vector from the torus centre to the torus surface giving the start point of the default parametrization
Select outer (1=yes, 0=no): Defines the parameter domain of the torus in degenerate cases.
A flag, 0 or 1, for unbounded or bounded in the linear direction
If unbounded, the bounding parameters: umin, umax
If bounded, the bounding parameters: umin, umax, vmin, vmax
A flag, 0 or 1, indicating whether or not the u- and v-parameter directions are swapped

SurfaceOfRevolution

The object body of a SurfaceOfRevolution takes the following format:

The dimension of the geometry space
A point on the axis of revolution
The direction of the axis of revolution
The body of the spline curve to rotate around this axis

Example of a surface of revolution

Disc

The object body of a Disc takes the following format:

The dimension of the geometry space
The centre of the disc
The disc radius
The normal to the disc surface
A vector from the disc centre to the disc boundary to give a start point for the parametrization
Whether a NURBS representation should have a degeneracy in the centre (=1) or have degenerate corners (=0)
The angles giving the four degeneracy points at the boundary. Not used if the flag for centre degeneracy is false.

LRSplineSurface

TSplineSurface

Go3dsObject

GoHeTriang

GoSdTriang

GoQuadMesh

GoHybridMesh

ParamTriang

GoVrmlGeometry

PointCloud

The object body of a PointCloud takes the following format:

Number of points
The coordinates of each point.

The points are given one by one, and the dimension of a point in a point cloud is 3 by default.

Example of a point cloud

An example of a point cloud with 3 points is:

LineCloud

The object body of a LineCloud takes the following format:

Number of line segments
The coordinates of the endpoints of each line segments. The lines are given one by one.

The dimension of a line in a line cloud is 3 by default.

Example of a line cloud

The following is an example of a line cloud with 3 lines:

410 1 0 0
3
0 0 0  0 0 1
1 0 0  1 0 1
1 1 0  1 1 1

GoTriangleSets

RectGrid

SplineVolume

The SplineVolume entity is placed in the module trivariate, and its object body takes the following format:

dimension of the geometry space, whether or not the volume is rational: 1=rational, 0=non-rational
the number of coefficients in the first parameter direction, the polynomial order in this direction (i.e., degree+1)
the knot vector in the first parameter direction, multiple knots are represented by repeating the knot values
the number of coefficients in the second parameter direction, the polynomial order in this direction (i.e., degree+1)
the knot vector in the second parameter direction
the number of coefficients in the third parameter direction, the polynomial order in this direction (i.e., degree+1)
the knot vector in the third parameter direction
the volume coefficients

The volume coefficients are provided in a sequence as in the reflected lexicographic order, i.e., $$(x_{1,1,1}, y_{1,1,1}, z_{1,1,1}), ..., (x_{n,1,1}, y_{n,1,1}, z_{n,1,1}),$$ $$ ...,$$ $$(x_{1,m,1}, y_{1,m,1}, z_{1,m,1}), ..., (x_{n,m,1}, y_{n,m,1}, z_{n,m,1}),$$ $$...,...,$$ $$(x_{1,1,p}, y_{1,1,p}, z_{1,1,p}), ..., (x_{n,1,p}, y_{n,1,p}, z_{n,1,p}),$$ $$ ...,$$ $$(x_{1,m,p}, y_{1,m,p}, z_{1,m,p}), ..., (x_{n,m,p}, y_{n,m,p}, z_{n,m,p}).$$ Here $n$ is the number of coefficients in the first parameter direction, $m$ is the number of coefficients in the second parameter direction, and $p$ is the number of coefficients in the third parameter direction.

As for spline curves and spline surfaces, in the rational case the coefficients are multiplied by the weights and an extra entry (from the homogenization) is given for each coefficient.

Example of a spline volume

A simple non-rational, trilinear volume with no inner knots is represented as:

Parallelepiped

The object body of a Parallelepiped takes the following format:

Dimension of the geometry space
Lower right corner
Unit vector in geometry space representing the first parameter direction
Length of parallelepiped in the first direction
Unit vector in geometry space representing the second parameter direction
Length of parallelepiped in the second direction
Unit vector in geometry space representing the third parameter direction
Length of parallelepiped in the third direction

SphereVolume

The object body of a SphereVolume takes the following format:

Dimension of the geometry space
Sphere radius
Centre of sphere
Axis of sphere, i.e., the vector along which the degeneracies of a NURBS representation of the sphere will lie
Vector from the centre to the outer surface giving input to the sphere parametrization

CylinderVolume

The object body of a CylinderVolume takes the following format:

Dimension of the geometry space
Cylinder centre
Cylinder axis
Vector from the centre to the outer surface giving input to the parametrization of the cylinder
Minimum cylinder radius. If this number is larger than 0, the cylinder will have a hole along the axis
Maximum radius, the radius of the outer cylinder surface
Minimum height, =1: the cylinder is infinite, =0: the cylinder is finite and the distance from the centre to the bottom of the cylinder folllows (positive or negative number)
Maximum height, =1: the cylinder is infinite, =0: the cylinder is finite and the total height of the cylinder follows
Whether a NURBS representation should have a degeneracy in the centre (=1) or have degenerate corners (=0)
The angles giving the four degeneracy points at the boundary. Not used if the flag for centre degeneracy is false.

ConeVolume

The object body of a ConeVolume takes the following format:

Dimension of the geometry space
Radius of the cone at the centre
A point at the cone axis (the centre)
Cone axis
The vector from the cone axis towards the boundary surface of the cone, giving the start point of the cone parametrization
The opening angle of the cone
Minimum height, the distance from the centre to the smallest end disc of the cone (positive or negative number)
Maximum height, =1: the cone is infinite, =0: the cone is finite and the cone height follows
Whether a NURBS representation should have a degeneracy in the centre (=1) or have degenerate corners (=0)
The angles giving the four degeneracy points at the boundary. Not used if the flag for centre degeneracy is false.

TorusVolume

The object body of a TorusVolume takes the following format:

Dimension of the geometry space
The torus centre
The normal to the plane through the large circle of the torus
A vector from the torus centre to the torus surface giving the parametrization
The major radius
The minor radius
Angle of revolution for the small circle
Angle of revolution for the large circle
Whether a NURBS representation should have a degeneracy in the centre (=1) or have degenerate corners (=0)
The angles giving the four degeneracy points at the boundary. Not used if the flag for centre degeneracy is false.

NB: Please install the GitHub with MathJax browser extension for correct visualisation of formulas in this wiki.

Home

Getting started

Miscellaneous

Functionality

Modules
gotools-core
- geometry
- creators
- tesselator
- utils
- examples
compositemodel
- examples
implicitization
igeslib
intersections
isogeometric_model
lrsplines2D
parametrization
qualitymodule
topology
trivariate
- examples
trivariatemodel
- examples
viewlib

Dependencies

SISL
TTL
- API to TTL
- Half-edge data structure
newmat
Boost
Qt
Pugixml
JsonCpp