OCCT Shapes: Building Blocks of 3D Geometry
Introduction to OCCT Shape Hierarchy
OpenCascade Technology (OCCT) defines several fundamental types of geometric shapes. Understanding the hierarchical relationship between these shapes is crucial for effective 3D modeling with OCCT. The basic hierarchy, from the simplest to the most complex, is generally as follows:
- Vertex: A single point in 3D space. It represents a location and has no dimension.
- Edge: A curve bounded by one or two vertices. It represents a 1D boundary of a face.
- Wire: A sequence of connected edges. A wire can be open or closed. Closed wires typically form the boundaries of faces.
- Face: A bounded portion of a surface. The boundaries of a face are defined by one or more wires. It represents a 2D region.
- Shell: A collection of connected faces. A shell can be open (like a surface model) or closed (forming an enclosed volume).
- Solid: A region of 3D space enclosed by one or more closed shells. Solids represent volumetric objects.
This hierarchy means you can conceptually (and sometimes programmatically) build up complex shapes from simpler ones:
- Vertices can be used to define an edge.
- Edges can be connected to form a wire.
- Wires can define the boundary of a face.
- Faces can be stitched together to create a shell.
- A closed shell (or shells) can define a solid.
Here one outline climbs that ladder, left to right: four vertices, the closed wire through them, the face the wire bounds, and the solid the face extrudes into. Each step is made from the one before it. The order of the points matters at the face: it sets which way the face looks, by the right-hand rule, and this order makes it look up. Listed the other way round it would look down, and from above you would see its back, which the editors draw blue. The solid comes out the same either way.

- Rete
- Blockly
- TypeScript
{
"id": "rete-v2-json",
"nodes": {
"cornerA": {
"id": "cornerA",
"name": "bitbybit.point.pointXYZ",
"customName": "point xyz",
"async": false,
"drawable": true,
"data": {
"genericNodeData": {
"hide": true,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"x": 0,
"y": 0,
"z": 0
},
"inputs": {},
"position": [
40,
40
]
},
"cornerB": {
"id": "cornerB",
"name": "bitbybit.point.pointXYZ",
"customName": "point xyz",
"async": false,
"drawable": true,
"data": {
"genericNodeData": {
"hide": true,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"x": 0,
"y": 0,
"z": 4
},
"inputs": {},
"position": [
40,
334
]
},
"cornerC": {
"id": "cornerC",
"name": "bitbybit.point.pointXYZ",
"customName": "point xyz",
"async": false,
"drawable": true,
"data": {
"genericNodeData": {
"hide": true,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"x": 4,
"y": 0,
"z": 4
},
"inputs": {},
"position": [
40,
628
]
},
"cornerD": {
"id": "cornerD",
"name": "bitbybit.point.pointXYZ",
"customName": "point xyz",
"async": false,
"drawable": true,
"data": {
"genericNodeData": {
"hide": true,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"x": 4,
"y": 0,
"z": 0
},
"inputs": {},
"position": [
40,
922
]
},
"corners": {
"id": "corners",
"name": "bitbybit.lists.createList",
"customName": "create list",
"async": false,
"drawable": false,
"data": {},
"inputs": {
"listElements": {
"connections": [
{
"node": "cornerA",
"output": "result",
"data": {}
},
{
"node": "cornerB",
"output": "result",
"data": {}
},
{
"node": "cornerC",
"output": "result",
"data": {}
},
{
"node": "cornerD",
"output": "result",
"data": {}
}
]
}
},
"position": [
460,
40
]
},
"vertices": {
"id": "vertices",
"name": "bitbybit.occt.shapes.vertex.verticesFromPoints",
"customName": "vertices from points",
"async": true,
"drawable": true,
"data": {
"genericNodeData": {
"hide": true,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
}
},
"inputs": {
"points": {
"connections": [
{
"node": "corners",
"output": "list",
"data": {}
}
]
}
},
"position": [
880,
40
]
},
"dots": {
"id": "dots",
"name": "bitbybit.draw.optionsOcctShape",
"customName": "options occt shape",
"async": false,
"drawable": false,
"data": {
"genericNodeData": {
"hide": false,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"faceOpacity": 1,
"edgeOpacity": 1,
"edgeColour": "#ffffff",
"faceColour": "#ff0000",
"vertexColour": "#ff9f1c",
"edgeWidth": 2,
"edgeWidthBySize": false,
"vertexSize": 0.3,
"drawEdges": true,
"drawFaces": true,
"drawVertices": true,
"precision": 0.01,
"angularDeflection": 0.5,
"relativeDeflection": false,
"precisionShare": 0,
"drawEdgeIndexes": false,
"edgeIndexHeight": 0.06,
"edgeIndexColour": "#ff00ff",
"drawFaceIndexes": false,
"faceIndexHeight": 0.06,
"faceIndexColour": "#0000ff",
"drawTwoSided": true,
"backFaceColour": "#0000ff",
"backFaceOpacity": 1,
"edgeArrowSize": 0,
"edgeArrowAngle": 15,
"keepMeshData": false,
"allowQualityDecrease": true,
"forceFaceDeflection": false,
"drawIsoCurves": false,
"isoCurvesU": 5,
"isoCurvesV": 5,
"isoCurvesColour": "#808080",
"surfaceAnalysis": "none",
"draftDirection": [
0,
1,
0
]
},
"inputs": {},
"position": [
40,
1216
]
},
"drawVertices": {
"id": "drawVertices",
"name": "bitbybit.draw.drawAnyAsync",
"customName": "draw any async",
"async": true,
"drawable": true,
"data": {
"genericNodeData": {
"hide": false,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
}
},
"inputs": {
"entity": {
"connections": [
{
"node": "vertices",
"output": "result",
"data": {}
}
]
},
"options": {
"connections": [
{
"node": "dots",
"output": "result",
"data": {}
}
]
}
},
"position": [
2560,
40
]
},
"wire": {
"id": "wire",
"name": "bitbybit.occt.shapes.wire.createPolygonWire",
"customName": "polygon wire",
"async": true,
"drawable": true,
"data": {
"genericNodeData": {
"hide": true,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
}
},
"inputs": {
"points": {
"connections": [
{
"node": "corners",
"output": "list",
"data": {}
}
]
}
},
"position": [
880,
280
]
},
"wireAside": {
"id": "wireAside",
"name": "bitbybit.occt.transforms.translate",
"customName": "translate",
"async": true,
"drawable": true,
"data": {
"genericNodeData": {
"hide": false,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"translation": [
6,
0,
0
]
},
"inputs": {
"shape": {
"connections": [
{
"node": "wire",
"output": "result",
"data": {}
}
]
}
},
"position": [
1300,
40
]
},
"face": {
"id": "face",
"name": "bitbybit.occt.shapes.face.createFaceFromWire",
"customName": "face from wire",
"async": true,
"drawable": true,
"data": {
"genericNodeData": {
"hide": true,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"planar": true
},
"inputs": {
"shape": {
"connections": [
{
"node": "wire",
"output": "result",
"data": {}
}
]
}
},
"position": [
1300,
288
]
},
"faceAside": {
"id": "faceAside",
"name": "bitbybit.occt.transforms.translate",
"customName": "translate",
"async": true,
"drawable": true,
"data": {
"genericNodeData": {
"hide": false,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"translation": [
12,
0,
0
]
},
"inputs": {
"shape": {
"connections": [
{
"node": "face",
"output": "result",
"data": {}
}
]
}
},
"position": [
1720,
40
]
},
"solid": {
"id": "solid",
"name": "bitbybit.occt.operations.extrude",
"customName": "extrude",
"async": true,
"drawable": true,
"data": {
"genericNodeData": {
"hide": true,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"direction": [
0,
4,
0
]
},
"inputs": {
"shape": {
"connections": [
{
"node": "face",
"output": "result",
"data": {}
}
]
}
},
"position": [
1720,
288
]
},
"solidAside": {
"id": "solidAside",
"name": "bitbybit.occt.transforms.translate",
"customName": "translate",
"async": true,
"drawable": true,
"data": {
"genericNodeData": {
"hide": false,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"translation": [
18,
0,
0
]
},
"inputs": {
"shape": {
"connections": [
{
"node": "solid",
"output": "result",
"data": {}
}
]
}
},
"position": [
2140,
40
]
},
"view": {
"id": "view",
"name": "bitbybit.babylon.scene.adjustActiveArcRotateCamera",
"customName": "adjust active arc rotate camera",
"async": false,
"drawable": false,
"data": {
"genericNodeData": {
"hide": false,
"oneOnOne": false,
"flatten": 0,
"forceExecution": false
},
"position": [
11,
23,
-29
],
"lookAt": [
11,
1,
2
],
"lowerBetaLimit": 1,
"upperBetaLimit": 179,
"angularSensibilityX": 1000,
"angularSensibilityY": 1000,
"maxZ": 1000,
"panningSensibility": 1000,
"wheelPrecision": 3
},
"inputs": {},
"position": [
2560,
334
]
}
},
"modules": {}
}
<xml xmlns="https://developers.google.com/blockly/xml"><variables><variable id="corners">corners</variable><variable id="wire">wire</variable><variable id="face">face</variable></variables><block type="variables_set" x="40" y="40"><field name="VAR" id="corners">corners</field><value name="VALUE"><block type="lists_create_with"><mutation items="4"></mutation><value name="ADD0"><block type="bitbybit.point.pointXYZ"><value name="X"><block type="math_number"><field name="NUM">0</field></block></value><value name="Y"><block type="math_number"><field name="NUM">0</field></block></value><value name="Z"><block type="math_number"><field name="NUM">0</field></block></value></block></value><value name="ADD1"><block type="bitbybit.point.pointXYZ"><value name="X"><block type="math_number"><field name="NUM">0</field></block></value><value name="Y"><block type="math_number"><field name="NUM">0</field></block></value><value name="Z"><block type="math_number"><field name="NUM">4</field></block></value></block></value><value name="ADD2"><block type="bitbybit.point.pointXYZ"><value name="X"><block type="math_number"><field name="NUM">4</field></block></value><value name="Y"><block type="math_number"><field name="NUM">0</field></block></value><value name="Z"><block type="math_number"><field name="NUM">4</field></block></value></block></value><value name="ADD3"><block type="bitbybit.point.pointXYZ"><value name="X"><block type="math_number"><field name="NUM">4</field></block></value><value name="Y"><block type="math_number"><field name="NUM">0</field></block></value><value name="Z"><block type="math_number"><field name="NUM">0</field></block></value></block></value></block></value><next><block type="bitbybit.draw.drawAnyAsyncNoReturn"><value name="Entity"><block type="bitbybit.occt.shapes.vertex.verticesFromPoints"><value name="Points"><block type="variables_get"><field name="VAR" id="corners">corners</field></block></value></block></value><value name="Options"><block type="bitbybit.draw.optionsOcctShape"><value name="FaceOpacity"><block type="math_number"><field name="NUM">1</field></block></value><value name="EdgeOpacity"><block type="math_number"><field name="NUM">1</field></block></value><value name="EdgeColour"><block type="colour_picker"><field name="COLOUR">#ffffff</field></block></value><value name="FaceColour"><block type="colour_picker"><field name="COLOUR">#ff0000</field></block></value><value name="VertexColour"><block type="colour_picker"><field name="COLOUR">#ff9f1c</field></block></value><value name="EdgeWidth"><block type="math_number"><field name="NUM">2</field></block></value><value name="EdgeWidthBySize"><block type="logic_boolean"><field name="BOOL">FALSE</field></block></value><value name="VertexSize"><block type="math_number"><field name="NUM">0.3</field></block></value><value name="DrawEdges"><block type="logic_boolean"><field name="BOOL">TRUE</field></block></value><value name="DrawFaces"><block type="logic_boolean"><field name="BOOL">TRUE</field></block></value><value name="DrawVertices"><block type="logic_boolean"><field name="BOOL">TRUE</field></block></value><value name="Precision"><block type="math_number"><field name="NUM">0.01</field></block></value><value name="AngularDeflection"><block type="math_number"><field name="NUM">0.5</field></block></value><value name="RelativeDeflection"><block type="logic_boolean"><field name="BOOL">FALSE</field></block></value><value name="PrecisionShare"><block type="math_number"><field name="NUM">0</field></block></value><value name="DrawEdgeIndexes"><block type="logic_boolean"><field name="BOOL">FALSE</field></block></value><value name="EdgeIndexHeight"><block type="math_number"><field name="NUM">0.06</field></block></value><value name="EdgeIndexColour"><block type="colour_picker"><field name="COLOUR">#ff00ff</field></block></value><value name="DrawFaceIndexes"><block type="logic_boolean"><field name="BOOL">FALSE</field></block></value><value name="FaceIndexHeight"><block type="math_number"><field name="NUM">0.06</field></block></value><value name="FaceIndexColour"><block type="colour_picker"><field name="COLOUR">#0000ff</field></block></value><value name="DrawTwoSided"><block type="logic_boolean"><field name="BOOL">TRUE</field></block></value><value name="BackFaceColour"><block type="colour_picker"><field name="COLOUR">#0000ff</field></block></value><value name="BackFaceOpacity"><block type="math_number"><field name="NUM">1</field></block></value><value name="EdgeArrowSize"><block type="math_number"><field name="NUM">0</field></block></value><value name="EdgeArrowAngle"><block type="math_number"><field name="NUM">15</field></block></value><value name="KeepMeshData"><block type="logic_boolean"><field name="BOOL">FALSE</field></block></value><value name="AllowQualityDecrease"><block type="logic_boolean"><field name="BOOL">TRUE</field></block></value><value name="ForceFaceDeflection"><block type="logic_boolean"><field name="BOOL">FALSE</field></block></value><value name="DrawIsoCurves"><block type="logic_boolean"><field name="BOOL">FALSE</field></block></value><value name="IsoCurvesU"><block type="math_number"><field name="NUM">5</field></block></value><value name="IsoCurvesV"><block type="math_number"><field name="NUM">5</field></block></value><value name="IsoCurvesColour"><block type="colour_picker"><field name="COLOUR">#808080</field></block></value><value name="SurfaceAnalysis"><block type="bitbybit.occt.enums.surfaceAnalysisEnum"><field name="bitbybit.occt.enums.surfaceAnalysisEnum">'none'</field></block></value><value name="DraftDirection"><block type="bitbybit.vector.vectorXYZ"><value name="X"><block type="math_number"><field name="NUM">0</field></block></value><value name="Y"><block type="math_number"><field name="NUM">1</field></block></value><value name="Z"><block type="math_number"><field name="NUM">0</field></block></value></block></value></block></value><next><block type="variables_set"><field name="VAR" id="wire">wire</field><value name="VALUE"><block type="bitbybit.occt.shapes.wire.createPolygonWire"><value name="Points"><block type="variables_get"><field name="VAR" id="corners">corners</field></block></value></block></value><next><block type="variables_set"><field name="VAR" id="face">face</field><value name="VALUE"><block type="bitbybit.occt.shapes.face.createFaceFromWire"><value name="Shape"><block type="variables_get"><field name="VAR" id="wire">wire</field></block></value><value name="Planar"><block type="logic_boolean"><field name="BOOL">TRUE</field></block></value></block></value><next><block type="bitbybit.draw.drawAnyAsyncNoReturn"><value name="Entity"><block type="bitbybit.occt.transforms.translate"><value name="Shape"><block type="variables_get"><field name="VAR" id="wire">wire</field></block></value><value name="Translation"><block type="bitbybit.vector.vectorXYZ"><value name="X"><block type="math_number"><field name="NUM">6</field></block></value><value name="Y"><block type="math_number"><field name="NUM">0</field></block></value><value name="Z"><block type="math_number"><field name="NUM">0</field></block></value></block></value></block></value><next><block type="bitbybit.draw.drawAnyAsyncNoReturn"><value name="Entity"><block type="bitbybit.occt.transforms.translate"><value name="Shape"><block type="variables_get"><field name="VAR" id="face">face</field></block></value><value name="Translation"><block type="bitbybit.vector.vectorXYZ"><value name="X"><block type="math_number"><field name="NUM">12</field></block></value><value name="Y"><block type="math_number"><field name="NUM">0</field></block></value><value name="Z"><block type="math_number"><field name="NUM">0</field></block></value></block></value></block></value><next><block type="bitbybit.draw.drawAnyAsyncNoReturn"><value name="Entity"><block type="bitbybit.occt.transforms.translate"><value name="Shape"><block type="bitbybit.occt.operations.extrude"><value name="Shape"><block type="variables_get"><field name="VAR" id="face">face</field></block></value><value name="Direction"><block type="bitbybit.vector.vectorXYZ"><value name="X"><block type="math_number"><field name="NUM">0</field></block></value><value name="Y"><block type="math_number"><field name="NUM">4</field></block></value><value name="Z"><block type="math_number"><field name="NUM">0</field></block></value></block></value></block></value><value name="Translation"><block type="bitbybit.vector.vectorXYZ"><value name="X"><block type="math_number"><field name="NUM">18</field></block></value><value name="Y"><block type="math_number"><field name="NUM">0</field></block></value><value name="Z"><block type="math_number"><field name="NUM">0</field></block></value></block></value></block></value><next><block type="bitbybit.babylon.scene.adjustActiveArcRotateCamera"><value name="Position"><block type="bitbybit.point.pointXYZ"><value name="X"><block type="math_number"><field name="NUM">11</field></block></value><value name="Y"><block type="math_number"><field name="NUM">23</field></block></value><value name="Z"><block type="math_number"><field name="NUM">-29</field></block></value></block></value><value name="LookAt"><block type="bitbybit.point.pointXYZ"><value name="X"><block type="math_number"><field name="NUM">11</field></block></value><value name="Y"><block type="math_number"><field name="NUM">1</field></block></value><value name="Z"><block type="math_number"><field name="NUM">2</field></block></value></block></value><value name="LowerBetaLimit"><block type="math_number"><field name="NUM">1</field></block></value><value name="UpperBetaLimit"><block type="math_number"><field name="NUM">179</field></block></value><value name="AngularSensibilityX"><block type="math_number"><field name="NUM">1000</field></block></value><value name="AngularSensibilityY"><block type="math_number"><field name="NUM">1000</field></block></value><value name="MaxZ"><block type="math_number"><field name="NUM">1000</field></block></value><value name="PanningSensibility"><block type="math_number"><field name="NUM">1000</field></block></value><value name="WheelPrecision"><block type="math_number"><field name="NUM">3</field></block></value></block></next></block></next></block></next></block></next></block></next></block></next></block></next></block></xml>
const corners: Bit.Inputs.Base.Point3[] = [[0, 0, 0], [0, 0, 4], [4, 0, 4], [4, 0, 0]];
const vertices = await bitbybit.occt.shapes.vertex.verticesFromPoints({ points: corners });
const wire = await bitbybit.occt.shapes.wire.createPolygonWire({ points: corners });
const face = await bitbybit.occt.shapes.face.createFaceFromWire({ shape: wire, planar: true });
const solid = await bitbybit.occt.operations.extrude({ shape: face, direction: [0, 4, 0] });
const dots = new Bit.Inputs.Draw.DrawOcctShapeOptions();
dots.drawVertices = true;
dots.vertexSize = 0.3;
dots.vertexColour = "#ff9f1c";
await bitbybit.draw.drawAnyAsync({ entity: vertices, options: dots });
await bitbybit.draw.drawAnyAsync({ entity: await bitbybit.occt.transforms.translate({ shape: wire, translation: [6, 0, 0] }) });
await bitbybit.draw.drawAnyAsync({ entity: await bitbybit.occt.transforms.translate({ shape: face, translation: [12, 0, 0] }) });
await bitbybit.draw.drawAnyAsync({ entity: await bitbybit.occt.transforms.translate({ shape: solid, translation: [18, 0, 0] }) });
bitbybit.babylon.scene.adjustActiveArcRotateCamera({ position: [11, 23, -29], lookAt: [11, 1, 2] });
The Compound Shape
A Compound is a special type of OCCT shape that acts as a container. It can group together any collection of other shape types (vertices, edges, faces, solids, or even other compounds). Compounds are very useful when you want to:
- Organize multiple shapes as a single entity.
- Apply the same transformation or operation to a group of shapes simultaneously.
Can You Create a Solid Without Manually Building Up the Hierarchy?
Yes, absolutely!
While the underlying geometric structure of any valid solid in OCCT adheres to the hierarchy (a solid is composed of shells, shells of faces, etc.), Bitbybit (and OCCT itself) provides many higher-level helper functions and tools to create common and complex shapes directly, without requiring you to manually perform every step of the composition.
For example:
- You can create a cube solid directly using a
createCubefunction. - You can create a cylinder solid directly using a
createCylinderfunction. - You can create a sphere solid directly using a
createSpherefunction.
When you use these convenience functions, OCCT (and our Bitbybit wrappers) automatically handle the creation of the necessary underlying vertices, edges, wires, faces, and shells "behind the scenes" to construct the final solid shape. This makes the modeling process much more efficient and user-friendly for common geometric primitives.
However, it's still valuable to understand the fundamental hierarchy because:
- It helps in debugging and understanding the structure of complex models.
- For advanced or custom modeling scenarios, you might need to work with these lower-level entities directly (e.g., creating a face from a custom wire, or building a shell from a set of faces).
- Many OCCT operations (like booleans, fillets, chamfers) operate on or produce these different shape types.
The OCCT Shapes category in Bitbybit editors provides components and functions for creating both primitive solids directly and for working with the lower-level shape entities when more granular control is needed.



