InsightCAD - hkroeger/insightcae GitHub Wiki

InsightCAD is a script-based tool for creating three-dimensional geometry models. All geometric operations are based on the OpenCASCADE geometry kernel. It uses the boundary representation approach (BREP) for treating the geometry. Thus it is possible to import and export the common exchange formats IGES and STEP.

Although the primary intention of InsightCAD is creation of fully parameterized CAD models for systematic numerical simulations, it can also be used for mechanical design purposes. It therefore provides the possibility to export projections and sections of the created models in DXF format for use in drawings. Additionally, there is support for a library of parametric standard parts.

The basic entity in InsightCAD is a "model". A model is described by a script and stored in an ASCII script file (extension ".iscad"). Inside a model script, symbols are defined, which can represent the following data types:

• Scalars

• Vectors

• Datum objects (axes, planes)

• 3D geometry objects (features)

• Selections of vertices, edges, faces or solids of 3D geometry objects

There is no explicit type declaration: the data type of each symbol is deduced from the defining expression.

Beyond their geometry representation, geometry feature objects are containers for scalar, vector, datum and feature objects. These symbols can be accessed in the model script but are read-only.

It is possible to load another model into the current one by the "loadmodel" command (see section "Features"). In this case, the loaded model represents a subassembly, i.e. a compound of features. Since not all defined geometry objects in the submodel may represent assembly components, marking of components is supported by the feature definition syntax and needs to be utilized properly in the definition script of the submodel. Also, when loading models (subassemblies), parameters can be passed to the submodel. These can be scalars, vectors, datums or features.

In a model script, after the definition of the aforementioned symbols, an optional section with postprocessing actions can follow. These can be e.g. file export, drawing export or others.

The general model script layout begins with a mandatory symbol defining section, followed by an optional postprocessing section, started by "@post":

<identifier> [ = | ?= | : ] <expression>;
...

@post

<postprocessing action>;
...

Comments are lines starting with "#" or text regions enclosed by "/*" and "*/" (C-style).

Example:

D ?= 123.5;
L = 2.*D;

The "?=" operator assigns a default value. This needs to be used for symbols which are intended to be used as parameters in the "loadmodel" feature command. Symbols defined by the equal sign operator ("=") cannot be overridden during the loadmodel command.

Supported operations are listed in the following table.

There are scalars predefined in each model. They are listed in the following table.

Example:

v ?= 5*EX + 3*EY + [0,0,1];
ev = v/mag(v);

The "?=" operator assigns a default value. This needs to be used for symbols which are intended to be used as parameters in the "loadmodel" feature command. Symbols defined by the equal sign operator ("=") cannot be overridden during the loadmodel command.

Supported operations are listed in the table below.

There are vectors predefined in each model. They are listed in the table below.

Some simple examples are given below.

myaxis   ?= RefAxis(O, EX+EY); # diagonal axis
myplane  = Plane(5*EX, EY);  # offset plane
myplane2 = XZ << 5*EX; # same offset plane
axis2    = xsec_plpl(XY, myplane); # axis at intersection of XY-Plane and offset plane

The "?=" operator assigns a default value. This needs to be used for symbols which are intended to be used as parameters in the "loadmodel" feature command. Symbols defined by the equal sign operator ("=") cannot be overridden during the loadmodel command.

Supported operations are listed in the following table.

There are datums predefined in each model. They are listed in the table below:

A very simple example is given below. It consists of two primitive features (cylinder) and a boolean operation (subtraction).

tool = Cylinder(-10*EY, 10*EY, 2);

pierced_cylinder:
 Cylinder(O, 20*EX, 10, centered)
 -
 tool
;

Geometry symbols can be defined by a "=" or a ":" operator. The difference comes from a possible use of the model as a subassembly later on. Since usually not all defined features in a model are assembly components but some are only intermediate modeling steps, there are these two syntaxes for defining a feature with a subtle difference: "<identifier> = <expression>;" defines an intermediate feature while "<identifier>: <expression>;" does the same geometry operation but marks the result as being an assembly component. In the above example, only the feature "pierced_cylinder" is marked as a component. Thus if the above example would be loaded as a subassembly, only the "pierced_cylinder" will be shown and included in e.g. mass calculations.

In this section, an incomplete subset of the avilable feature commands is described in detail. For a complete list, please refer to the online documentation in the iscad editor (press Ctrl+F).

Transformation of feature f. Translation by vector delta and rotation around axis vector phi (magnitude of phi gives rotation angle).

Places the feature f in a new coordinate system. The new origin is at point p_0, the new x-axis along vector e_x and the new z-direction is e_z.

Imports solid geometry from a file. The format is recognized from the filename extension. Supported formats are IGS, STP, BREP.

Reads a sketch (i.e. a closed contur) from a file. The geometry in the sketch is expected to be in the X-Y-Plane. It is placed on the given plane pl. Sketch file format is recognized from the file name extension. Supported are ".dxf" and ".fcstd" (FreeCAD). The name is interpreted as layer name in DXF and sketch name in FreeCAD files.

For FreeCAD sketches, a list of parameter values can optionally be supplied. Upon loading, the sketch will be regenerated through FreeCAD with these values.

Parses another InsightCAD model (submodel) and inserts a compound of all features into the current model, which were marked as components in the submodel (i.e. which were defined with the colon ":" operator instead of the equal sign "=" in the submodel).

The model filename has to be "<modelname>.iscad". It is searched for in the following directories:

1. the directories listed in the environment variable "ISCAD_MODEL_PATH" (separated by ":")

2. the subdirectory "iscad-library" in InsightCAEs shared file directory

3. in the current directory

Optionally, a list of symbols is inserted into the namespace of the submodel (additional optional parameters).

There are commands for creation of several different geometrical primitives, e.g.

• 1D: Arc, Line, SplineCurve

• 2D: Quad, Tri (triangle), RegPoly (regular polygon), Circle, SplineSurface

• 3D: Sphere, Cylinder, Box, Bar, Cone, Pyramid, Torus

Extrude the feature f with direction and length vector L. When the keyword "centered" is given, the extrusion is centered around f.

Creates a revolution of the planar feature f. The rotation axis is specified by origin point p_0 and the direction vector axis. Revolution angle is specified by phi. By giving the keyword "centered", the revolution is created symmetrically around the base feature.

There are more features available. A comprehensive list is obtained by pressing Ctrl+F in the iscad editor.

ISCAD supports rule based selection of lower dimensional features (i.e. edges or faces of a solid). The selection is generated by a selection command: a question mark, followed by the type of shape to query. The result is a selection object:

<feature expression|feature selection>?<vertices|edges|faces|solids>('<command string>' [, parameter 0 [, ..., parameter n] ] )

It is possible to supply additional arguments to the selection expression, like scalars, vectors or features.

An example: the following expression selects the circumferential face of the cylinder c (all faces, which are not plane) and stores the selection in "shell_faces":

c = Cylinder(O, 5*EZ);
shell_face = c ? faces('!isPlane');
min_end_face = c ? faces('isPlane && minimal(CoG.z)');

The selection command string contains rules for the selection. Finally, the command string is evaluated as a boolean expression comprising comparison operators, boolean operators and query functions. Within these boolean expressions, quantity functions can be used. The available set of query functions and quantity functions depends on the type of shape which shall be queried.

General functions available for all kinds of lower dimensional shapes (Q: returns quantity, B: returns boolean):

Specialized functions:

• Vertices

  Command	Returns	Description
  loc	Q	location of the vertex

• Edges

  Command	Returns	Description
  isLine	B	true, if edge is straight
  isCircle	B	true, if edge is circular
  isEllipse	B	true, if edge is elliptical
  isHyperbola	B	true, if edge is on a hyperbola
  isParabola	B	true, if edge is on a parabola
  isBezierCurve	B	true, if edge is a bezier curve
  isBSplineCurve	B	true, if edge is a BSpline curve
  isOtherCurve	B	true, if edge is none of the above
  isFaceBoundary	B	true, if edge is boundary of some face
  boundaryOfFace(<set>)	B	true, if edge is boundary of one of the faces in set
  isPartOfSolid(<set>)	B	true, if edge is part of one of the solids in set
  isCoincident(<set>)	B	true, if edge is coincident with one of the edges in set
  isIdentical(<set>)	B	true, if edge is identical with one of the edges in set
  projectionIsCoincident(<set>, <vec:p0>, <vec:n>, <vec:up>, <scalar:tol>)	B	true, if projection of edge is coincident with some edge in set
  len	Q	length of edge
  radialLen(<vec:ax>, <vec:p0>)	Q	radial distance between ends with respect to axis (p0,ax)
  CoG	Q	center of gravity of edge
  start	Q	start point coordinates
  end	Q	end point coordinates

• Faces

  Command	Returns	Description
  area	Q	area of the face
  CoG	Q	center of gravity of the face
  cylRadius	Q	radius of a cylindrical face
  cylAxis	Q	axis direction of a cylindrical face
  isPlane	B	true, if is a plane
  isCylinder	B	true, if is a cylindrical surface
  isCone	B	true, if is a conical surface
  isSphere	B	true, if is a spherical surface
  isTorus	B	true, if is a toroidal surface
  isBezierSurface	B	true, if is a bezier surface
  isBSplineSurface	B	true, if is a BSpline surface
  isSurfaceOfRevolution	B	true, if is a surface of revolution
  isSurfaceOfExtrusion	B	true, if is a surface of extrusion
  isOffsetSurface	B	true, if is a offset surface
  isOtherSurface	B	true, if is some other kind of surface
  isPartOfSolid(<set>)	B
  isCoincident(<set>)	B
  isIdentical(<set>)	B
  adjacentToEdges(<set>)	B
  adjacentToFaces(<set>)	B

• Solids

  Command	Returns	Description
  CoG	Q	center of gravity
  volume	Q	volume of the solid

The DXF postprocessing action creates a DXF file for further use in drawings. Several views are derived from the feature f. A <view_definition> takes the following form:

<identifier:viewname> (
<vector:p_0>, <vector:n>, up <vector:e_up>
[, section]
[, poly]
[, skiphl]
[, add [l] [r] [t] [b] [k] ]
)

It defines a view on the point vector p_0 with normal direction vector n of the view plane. The upward direction (Y-direction) is aligned with vector e_up.

The keyword "section" toggles whether only the outline is projected or if the view plane creates a section through the geometry.

If keyword "poly" is given, the DXF geometry will be discretized. This is more robust but creates much larger DXF files.

Keyword "skiphl" toggles whether hidden lines are output.

The keyword "add" followed by the key letters l, r, t, b and/or k enables creation of additional projections from the left, right, top, bottom and/or back, respectively.

An example is given below:

c: Cylinder(O, 100*EX, 20);

@post

DXF("c.dxf") << c
 top ( O, EX, up EY )
 front ( O, EZ, up EY )
;

Generates a (triangular or tetrahedral) mesh for an FEA analysis of the feature f. Gmsh is used as a meshing backend. The mesh format is determined by the outputfile extension (.med = MED format). The label of the mesh is set to l.

The syntax of the <mesh_parameters> are as follows:

L = ( <scalar:Lmax> <scalar:Lmin> )
[linear]
vertexGroups( [ <identifier:group name> = <vertex set> [ @ <scalar:size> ], ... ] )
edgeGroups( [ <identifier:group name> = <edge set> [ @ <scalar:size> ], ... ] )
faceGroups( [ <identifier:group name> = <face set> [ @ <scalar:size> ], ... ] )
[ vertices ( [ <identifier:vertex name> = <vector:location> ], ... ) ]

The general mesh size is set by Lmax and Lmin. The optional keyword "linear" switch from quadratic to linear elements. Named groups of vertices, edges and faces can be created using the keywords "vertexGroups", "edgeGroups" and "faceGroups" repectively. Each group definition takes the form "groupname" = "selection set" (see section "Lower dimensional shape selection" for definition of selection sets). Optionally, a mesh size can be assigned to each defined group by appending an @ sign followed by a scalar value.

An example is given below:

c:
Cylinder(O, 100*EX, 20)
|
Cylinder(100*EX, ax 100*EX, 50)
;

@post

gmsh("c.med") << c as cyl
 L = (10 0.1)
 linear
 vertexGroups()
 edgeGroups()
 faceGroups(
  lo_f = c?faces('isPlane&&minimal(CoG.x)')
  up_f = c?faces('isPlane&&maximal(CoG.x)')
 )
;

Result: ISCAD model (left) and resulting mesh (right):

ISCAD is a graphical editor for InsightCAD scripts. It consists of a text editor for editing the script contents and a 3D view and some other elements for inspecting the resulting model. A screenshot is shown in the figure below.

The model script is entered into the text editor widget right of the 3D display. Once a script shall be evaluated, it can be parsed by clicking in the button "Rebuild" or pressing Ctrl+Return.

After parsing the model, the following results are displayed:

• A list of all created feature symbols in the "Model Steps" list box. If the check box is checked, the 3D geometry is displayed in the 3D view.

• The values of all scalars and vectors in the "Variables" list box.

  For each vector variable, a check box is displayed. If it is checked, the vector is interpreted as a point location and the point is shown in the 3D display window.

• All defined datums are listed in the "Datums" list box. Again, the check box controls, whether the datum is displayed in the 3D view.

• Dragging: Shift + mouse move

• Scaling: Ctrl + horizontal mouse move

• Rotating: Alt + mouse move

When hoovering the mouse pointer over a displayed feature in the 3D geometry window, it is highlighted. The highlighted feature is the one, which would be selected during subsequent mouse clicks.

When the left mouse button is pressed, the highlighted feature is selected and all its contained reference points are displayed.

When the right mouse button is pressed, a context menu for the selected feature is displayed.

The context menu provides these functions:

• The first entry is the feature name. When it is selected, the definition in the script editor is highlighted and the cursor jumps to it.

• "Insert name": inserts the name of the feature symbol at the cursor location

• "Export...": Export the feature geometry to a file (BREP, STP, IGES, STL)

When script code is entered into the text editor window, it is parsed in the background. Once this has been done successfully, some extensions of the context menu is available:

• Context menu on "Sketch" command:

  

  When selecting the "Edit Sketch..." entry, FreeCAD is launched and the sketch editor opened. If the FreeCAD-file or sketch inside it is not yet existing, they are created.

• Context menu on "loadmodel" command:

  

  When selecting the "Edit Model..." entry, another instance of iscad is launched with the specified model script loaded.