Skip to content

Commit 0d7a012

Browse files
matas-bitbybit-devmatas-bitbybit-dev
committed
shape docs
1 parent 31419f3 commit 0d7a012

6 files changed

Lines changed: 249 additions & 0 deletions

File tree

‎docs/learn/code/common/occt/_category_.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"label": "Occt",
3+
"position": 1,
4+
"link": {
5+
"type": "generated-index"
6+
}
7+
}

‎docs/learn/code/common/occt/shapes/_category_.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"label": "Shapes",
3+
"position": 1,
4+
"link": {
5+
"type": "generated-index"
6+
}
7+
}

‎docs/learn/code/common/occt/shapes/edge.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
sidebar_position: 2
3+
title: "Working with Edges in OCCT"
4+
sidebar_label: OCCT Edge
5+
description: Learn about OCCT edges, how to create linear and curved edges, analyze their properties, use them to construct wires, and deconstruct other shapes into edges in Bitbybit.
6+
slug: /editors/categories/occt/edge # Or adjust as needed
7+
tags: [occt]
8+
---
9+
10+
# OCCT Shapes: The Edge
11+
12+
<img
13+
src="https://s.bitbybit.dev/assets/icons/white/occt-icon.svg"
14+
alt="OCCT category icon with a stylized logo representation"
15+
width="100"
16+
title="OCCT category icon" />
17+
18+
## Introduction to Edges
19+
20+
In OpenCascade Technology (OCCT), an **Edge** is a fundamental 1D (one-dimensional) shape. It plays a crucial role in constructing more complex geometry:
21+
* Edges are used to build **Wires**.
22+
* Wires, in turn, define the boundaries of **Faces**.
23+
24+
An edge is characterized by:
25+
* **Start and End Points (Vertices):** These define the limits of the edge. An edge can also be closed (like a circle), in which case the start and end points coincide.
26+
* **A Curve:** This defines the geometric path of the edge between its start and end points. Edges can be straight (linear) or curved (e.g., arcs, ellipses, splines).
27+
28+
## How to Create an Edge in Bitbybit
29+
30+
Within Bitbybit, you can create, manipulate, and analyze edges using functions and components typically found under the `bitbybit.occt.shapes.edge...` class.
31+
32+
You can create various types of edges directly:
33+
* **Linear Edges:** Straight lines between two points.
34+
* **Arc Edges:** Circular arcs defined by parameters like center, radius, and angles.
35+
* **Ellipse Edges:** Elliptical arcs.
36+
* **Circle Edges:** Complete circles.
37+
38+
It's also possible to create a single-segment wire first and then convert it into an edge, as long as the wire consists of only one edge segment. Conversely, if you have a wire made of multiple connected edges, you can deconstruct that wire back into its constituent edges.
39+
40+
## Edge Analysis
41+
42+
Bitbybit provides some commands to inspect and analyze the properties of edges, such as these:
43+
44+
* **`getEdgeLength`:** Get the length of the edge.
45+
* **`startPointOnEdge` / `endPointOnEdge`:** Retrieve the start and end vertices of the edge.
46+
* **`edgesToPoints` (Adaptive Subdivision):** This specialized command creates more points in areas of higher curvature along the edge and fewer points on straighter sections. This adaptive subdivision is particularly useful for applications like CNC (Computer Numerical Control) machining paths or when a non-uniform distribution of points is desired for analysis or meshing.
47+
48+
## Constructing Wires from Edges
49+
50+
You can construct a **Wire** by joining multiple edges together. A critical requirement for this is that the **end point of one edge must precisely match the start point of the next edge** in the sequence. If the edges are disconnected or have gaps between their endpoints, a valid wire cannot be formed from them directly.
51+
52+
## Deconstructing Shapes into Edges
53+
54+
Many higher-level OCCT shapes can be deconstructed to extract their constituent edges. This is a powerful feature for various analysis, manipulation, and feature recognition tasks.
55+
56+
* **`getEdges` Command:** You can use a `getEdges` command/component to deconstruct Solids, Shells, Faces, and Wires into a list of their individual edges.
57+
* **Order of Edges:** When you deconstruct shapes like solids or faces into edges using a general `getEdges` function, the resulting list of edges might not be ordered in any specific path-following sequence. However, the order will typically be consistent, often matching the sequence used if you were to draw edge indexes.
58+
59+
### Deconstructing Wires with Ordered Edges
60+
61+
When you specifically want the edges of a wire to be returned in the order they appear along the wire's path, you can use a command like **`getEdgesAlongWire`**. This function offers additional benefits:
62+
* **Ordered Output:** It returns the edges in the sequence they form the wire.
63+
* **Direction Correction:** In OCCT, a wire can be constructed by joining edges that might be oriented in opposing directions relative to the overall wire direction. The `getEdgesAlongWire` command often attempts to reverse such edges so that their individual directions align with the wire's flow. This is very useful when you need a consistently oriented sequence of edges, for example, for path-based operations.
64+
65+
**Note on `getEdgesAlongWire` for Complex Shapes:**
66+
The `getEdgesAlongWire` command typically operates on a single wire. If you need to get ordered edges for all boundaries of a solid, you would generally follow a multi-step process:
67+
1. Deconstruct the solid into its Faces.
68+
2. For each Face, get its boundary Wires.
69+
3. For each Wire, use `getEdgesAlongWire` to get its ordered edges.
70+
This approach allows you to build collections of well-ordered edges for each boundary loop of your model.
71+
72+
Understanding how to create, analyze, and deconstruct edges is fundamental to leveraging the full power of OCCT within Bitbybit for parametric design and geometric manipulation.

‎docs/learn/code/common/occt/shapes/shapes.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
sidebar_position: 1
3+
title: "Understanding OCCT Shape Types and Hierarchy"
4+
sidebar_label: OCCT Shapes
5+
description: Explore the different types of shapes in OpenCascade Technology (OCCT) and understand their hierarchical relationship, from vertices to solids and compounds.
6+
tags: [occt]
7+
---
8+
9+
# OCCT Shapes: Building Blocks of 3D Geometry
10+
11+
<img
12+
class="category-icon-small"
13+
src="https://s.bitbybit.dev/assets/icons/white/occt-icon.svg"
14+
alt="OCCT category icon with a stylized logo representation"
15+
width="100"
16+
title="OCCT category icon" />
17+
18+
## Introduction to OCCT Shape Hierarchy
19+
20+
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:
21+
22+
1. **Vertex:** A single point in 3D space. It represents a location and has no dimension.
23+
2. **Edge:** A curve bounded by one or two vertices. It represents a 1D boundary of a face.
24+
3. **Wire:** A sequence of connected edges. A wire can be open or closed. Closed wires typically form the boundaries of faces.
25+
4. **Face:** A bounded portion of a surface. The boundaries of a face are defined by one or more wires. It represents a 2D region.
26+
5. **Shell:** A collection of connected faces. A shell can be open (like a surface model) or closed (forming an enclosed volume).
27+
6. **Solid:** A region of 3D space enclosed by one or more closed shells. Solids represent volumetric objects.
28+
29+
This hierarchy means you can conceptually (and sometimes programmatically) build up complex shapes from simpler ones:
30+
* Vertices can be used to define an edge.
31+
* Edges can be connected to form a wire.
32+
* Wires can define the boundary of a face.
33+
* Faces can be stitched together to create a shell.
34+
* A closed shell (or shells) can define a solid.
35+
36+
### The Compound Shape
37+
38+
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:
39+
* Organize multiple shapes as a single entity.
40+
* Apply the same transformation or operation to a group of shapes simultaneously.
41+
42+
## Can You Create a Solid Without Manually Building Up the Hierarchy?
43+
44+
**Yes, absolutely!**
45+
46+
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.
47+
48+
For example:
49+
* You can create a **cube solid** directly using a `createCube` function.
50+
* You can create a **cylinder solid** directly using a `createCylinder` function.
51+
* You can create a **sphere solid** directly using a `createSphere` function.
52+
53+
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.
54+
55+
However, it's still valuable to understand the fundamental hierarchy because:
56+
* It helps in debugging and understanding the structure of complex models.
57+
* 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).
58+
* Many OCCT operations (like booleans, fillets, chamfers) operate on or produce these different shape types.
59+
60+
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.

‎docs/learn/code/common/occt/shapes/wire.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
sidebar_position: 3
3+
title: "Working with Wires in OCCT"
4+
sidebar_label: OCCT Wire
5+
description: Learn about OCCT wires, how to create them from edges or points (polylines, splines, Bezier curves), their role in constructing faces, and how faces can have multiple wires (e.g., for holes).
6+
tags: [occt]
7+
---
8+
9+
# OCCT Shapes: The Wire
10+
11+
<img
12+
src="https://s.bitbybit.dev/assets/icons/white/occt-icon.svg"
13+
alt="OCCT category icon with a stylized logo representation"
14+
width="100"
15+
title="OCCT category icon" />
16+
17+
## Introduction to Wires
18+
19+
In OpenCascade Technology (OCCT), a **Wire** is a fundamental shape typically composed of one or more connected **Edges**. Wires are crucial as they form the boundaries used to construct **Faces**.
20+
21+
Key characteristics of wires:
22+
* **Composition:** Made from a sequence of connected edges. A wire can even consist of a single edge.
23+
* **Curve Types:** Wires can represent various curve types, including BSplines, Bezier curves, and other complex paths, depending on the edges they are made from or the method used for their creation.
24+
* **More Creation Methods:** Bitbybit often provides a broader range of direct creation methods for wires compared to individual edges. If a direct method to create a specific type of curved edge isn't immediately apparent, you might find a corresponding wire creation tool. You can then, if needed, deconstruct that single-segment wire into its constituent edge.
25+
26+
## Creating Wire Primitives
27+
28+
Bitbybit offers many straightforward ways to create common wire shapes (primitives) directly. These include:
29+
* **Squares and Rectangles**
30+
* **Circles and Ellipses**
31+
* **N-gons (Polygons with N sides)**
32+
* Even more complex predefined shapes like **Stars, Hearts, or Christmas Trees**.
33+
34+
These wire primitives serve as excellent starting points for creating faces, which can then be extruded or otherwise manipulated to form shells or solids.
35+
36+
## Creating Wires from Points
37+
38+
Another popular and versatile method for creating wires is by using a collection of 3D points as input. These points can define the path of the wire in various ways:
39+
40+
* **Polyline:** This is perhaps the most basic type of wire created from points. Bitbybit can transform a list of 3D points into a 3D polyline wire, which is a series of straight edge segments connecting the points in sequence.
41+
* **Curved Wires (BSplines, Bezier Curves, Interpolations):**
42+
* **Interpolation:** If you choose to interpolate points into a wire, the resulting curve will pass *through* all the specified points, but its path between the points will be smoothly curved. Interpolated wires can also be made **closed** and **periodic** (smoothly continuous at the seam). Such periodic wires typically avoid sharp corners.
43+
* **Bezier Curves:** A Bezier algorithm creates a smooth curve that is influenced by a set of control points. The curve aims to follow the general shape defined by these points but does *not necessarily pass through all of them* (except typically the start and end points).
44+
* **BSplines:** BSplines offer even more control and flexibility for creating complex, smooth curves defined by control points, knots, and degrees.
45+
46+
## Wires as Boundaries of Faces ("Face Wires")
47+
48+
As mentioned, wires are fundamental for constructing faces and, by extension, shells.
49+
* **Outer Boundary:** Typically, a face has one **closed wire** that defines its outer boundary.
50+
* **Holes (Inner Boundaries):** A face can also have one or more holes. In such cases, the face will be defined by multiple wires:
51+
* One wire for the outer boundary.
52+
* Additional, separate closed wires for each inner hole.
53+
54+
Understanding this relationship is key when working with faces that have complex topologies. When you deconstruct a face, you might get multiple wires if it contains holes.
55+
56+
The "Wire" category in Bitbybit editors provides a rich set of tools for creating these essential 1D constructs, bridging the gap between simple points/edges and 2D faces, forming the backbone of many surface and solid modeling operations.

‎docs/learn/code/common/occt/what-is-occt.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
sidebar_position: 1
3+
title: "Understanding the OCCT (OpenCascade Technology) Category"
4+
sidebar_label: OCCT Category
5+
description: Learn about OpenCascade Technology (OCCT), its role as a powerful open-source 3D geometry kernel in Bitbybit, OpenCascade.js, and the @bitbybit-dev/occt NPM package.
6+
tags: [occt]
7+
---
8+
9+
# The OCCT (OpenCascade Technology) Category
10+
11+
<img
12+
src="https://s.bitbybit.dev/assets/icons/white/occt-icon.svg"
13+
alt="OCCT category icon with a stylized logo representation"
14+
width="100"
15+
title="OCCT category icon" />
16+
17+
## What is OCCT?
18+
19+
[Open CASCADE Technology (OCCT)](https://dev.opencascade.org/) is a professional-grade, open-source software development platform for 3D CAD/CAM/CAE applications. At its core is a powerful **3D geometry kernel**, which is the only full-scale, open-source option of its kind.
20+
21+
In Bitbybit, we build various sophisticated 3D algorithms on top of this robust OCCT kernel and selectively expose its functionalities to our users through our editors and API. This means we utilize the most relevant and impactful parts of OCCT for web-based parametric design and 3D modeling, rather than the entire library. As Bitbybit evolves, we continuously expand the range of OCCT features available to our users.
22+
23+
## Why OCCT?
24+
25+
OCCT is our choice for advanced geometric modeling for several key reasons:
26+
* **Open-Source Leadership:** It is currently the best and arguably the only comprehensive open-source 3D [Boundary Representation (B-rep)](https://en.wikipedia.org/wiki/Boundary_representation) geometry kernel that can be effectively compiled for and used within a web browser environment.
27+
* **Power and Complexity:** OCCT is exceptionally powerful, capable of handling very complex 3D modeling scenarios, precision geometry, and advanced CAD operations like booleans, fillets, chamfers, and more.
28+
29+
## What is OpenCascade.js (OCJS)?
30+
31+
[OpenCascade.js (OCJS)](https://ocjs.org/) is an innovative project spearheaded by [Sebastian Alff (donalffons)](https://github.com/donalffons). He developed a Python-based toolchain that takes the original C++ library of OCCT and compiles it into **WebAssembly (WASM)**. This WASM code can then be executed efficiently in web browsers and NodeJS applications.
32+
33+
Bitbybit utilizes a **custom build of OCCT** that is compiled using the OpenCascade.js Docker package. This allows us to:
34+
* **Selectively Include Modules:** We carefully pick and choose which parts of the vast OCCT library are included in our WASM bundle.
35+
* **Optimize for Web:** Using the full OCCT build directly on the web is often impractical due to its very large size, which would significantly slow down the loading times of our platform and user applications. Our custom builds are optimized for web delivery.
36+
37+
## NPM Package: `@bitbybit-dev/occt`
38+
39+
Beyond just compiling OCCT to WASM, interacting directly with raw WASM code can be complex and requires specialized expertise. To address this, we have developed and maintain an NPM package called [**`@bitbybit-dev/occt`**](https://www.npmjs.com/package/@bitbybit-dev/occt).
40+
41+
This package:
42+
* **Wraps the OCCT WASM code:** It provides a higher-level, more JavaScript/TypeScript-friendly API over the underlying WASM functionalities.
43+
* **Simplifies Interaction:** It makes it much easier for our users and other JavaScript developers to leverage OCCT's power without needing to delve into the intricacies of WASM interoperation.
44+
* **Core of Bitbybit:** This package is used extensively within our own editors (TypeScript, Blockly, Rete).
45+
* **Open-Source and Available:** `@bitbybit-dev/occt` is open-source and readily available on the NPM package registry for you to use in your own web projects.
46+
47+
The OCCT category in our editors directly exposes the functionalities made accessible through this `@bitbybit-dev/occt` wrapper, allowing you to perform advanced CAD modeling operations visually or programmatically.

0 commit comments

Comments
 (0)