https://github.com/paulbuechner/occutils

🔧 A utility library providing high-level functions and algorithms to empower OpenCASCADE-based engineering tasks.
https://github.com/paulbuechner/occutils

cad opencascade

Last synced: 4 months ago
JSON representation

🔧 A utility library providing high-level functions and algorithms to empower OpenCASCADE-based engineering tasks.

Host: GitHub
URL: https://github.com/paulbuechner/occutils
Owner: paulbuechner
License: apache-2.0
Created: 2022-11-21T12:58:58.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2026-01-19T18:44:14.000Z (4 months ago)
Last Synced: 2026-01-20T00:51:41.787Z (4 months ago)
Topics: cad, opencascade
Language: C++
Homepage:
Size: 801 KB
Stars: 7
Watchers: 0
Forks: 0
Open Issues: 12
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

occutils

A utility library providing high-level functions and algorithms to empower OpenCASCADE-based engineering tasks, such as mesh generation, shape modeling, Boolean operations, intersection and distance calculations, and CAD data import/export.

## Design goals

`occutils` strives to be a contemporary, user-friendly, and modular utility
library for OpenCASCADE, specifically designed for seamless integration and
enhanced functionality:

* **Simple to use**: Most tasks should be accomplishable in *one line of code*.
* **Aid rapid development**: No need to write tons of utility functions; no
need to wait for long compile-times
* **Modular**: Pull in only what you need, or just copy the underlying
sourcecode.
* **Clear**: What you write should be what you mean: `Edge::FromPoints()`
instead of `BRepBuilderAPI_MakeEdge` three-liners.
* **High-Level**: Common tasks in 3D engineering should be accomplishable
without diving into low level OpenCASCADE code
* **Modern**: Uses features from C++17, because those make your code more
readable.
* **Minimal dependencies**: Only depends on OpenCASCADE and a few Boost
packages.
* **Liberally licensed**: occutils is licensed under Apache License v2.0,
allowing you to copy & modify the sourcecode for use in your commercial
projects for free. Keep in mind that OpenCASCADE is still LGPL licensed.

Note that occutils is very young and, although it is used in multiple production
projects, it might not have all the functionality you want or need, and might
have some bugs.

If you are missing functionality, feel free to submit an issue or pull request.
For more information on how to contribute, see the
[CONTRIBUTING](#contributing) section.

## Usage samples

#### Topology creation

```cpp
#include
#include
#include

#include
#include
#include
#include

int main() {
// Create points to build edges from
gp_Pnt aPoint(0, 0, 0);
gp_Pnt anotherPoint(1, 0, 0);
gp_Pnt yetAnotherPoint(0, 1, 0);
// Create edges from points
TopoDS_Edge aEdge = occutils::edge::FromPoints(aPoint, anotherPoint);
TopoDS_Edge anotherEdge = occutils::edge::FromPoints(anotherPoint, yetAnotherPoint);
TopoDS_Edge yetAnotherEdge = occutils::edge::FromPoints(yetAnotherPoint, aPoint);
// Create a wire from edges
TopoDS_Wire aWire = occutils::wire::FromEdges({aEdge, anotherEdge, yetAnotherEdge});
// Create a face from a wire
TopoDS_Face aFace = occutils::face::FromWire(aWire);
}
```

---

#### Boolean operations

```cpp
#include
#include

#include

int main() {
// Create two shapes
TopoDS_Shape aBox = occutils::primitive::MakeBox(2, 2, 2)
TopoDS_Shape anotherBox = occutils::primitive::MakeBox(1, 1, 1)
// Perform a boolean operation
TopoDS_Shape aShape = occutils::boolean::Cut(aBox, anotherBox);
}
```

## Setup

### Prerequisites

To build occutils you need to have the following prerequisites set up:

#### Compiler

The project uses C++17 features and therefore requires a compiler that supports
this standard.

Compiler compatibility (tested):

- Clang/LLVM >= 6
- MSVC++ >= 14.11 / Visual Studio >= 2017
- GCC >= 9

#### CMake

The project uses CMake as a build system. CMake version 3.25 or higher is
required.

#### vcpkg

This project is build with CMake and uses the
[vcpkg](https://vcpkg.io/en/index.html) package manager to install the required
dependencies. The project is configured to use vcpkg as a submodule, allowing it
to integrate with the CI/CD pipeline. Feel free to use this setup or use your
own vcpkg installation.

To fetch vcpkg as a submodule run:

```shell
git submodule update --init --recursive
```

If you prefer a system-wide installation of vcpkg follow their official
guidelines on how to set up
vcpkg [here](https://vcpkg.io/en/getting-started.html).

> Note: For WSL users, make sure to install vcpkg in a directory which grants
> permission for all users. Otherwise, you will get an error when trying to
> access and install vcpkg packages through a non-root user.

#### Python

The OpenCascade build requires python with a version of at least 3.7. However,
this is **only needed when building on Linux**.

To ensure your python3 points to the correct version run:

```shell
ls -l /usr/bin/python3
lrwxrwxrwx 1 root root 9 7. Jan 15:51 /usr/bin/python3 -> python3.7 # required python version >= 3.7
```

#### OpenCascade

The project uses OpenCascade as a geometry kernel. It is automatically
downloaded and build by `vcpkg` package manager.

To build OpenCascade on UNIX like systems, install the following packages:

Ubuntu

```shell
sudo apt-get install software-properties-common
sudo apt-get install libtool autoconf automake gfortran gdebi
sudo apt-get install gcc-multilib libxi-dev libxmu-dev libxmu-headers
sudo apt-get install libx11-dev mesa-common-dev libglu1-mesa-dev
sudo apt-get install libfontconfig1-dev
```

The minimum requirements for third party dependencies to run OpenCascade itself
is Freetype 2.5 and Tcl/TK 8.6:

```shell
sudo apt-get install libfreetype6 libfreetype6-dev
sudo apt-get install tcl tcl-dev tk tk-dev
```

openSUSE

> Note: The documentation is not complete yet. Feel free to contribute.

```shell
sudo zypper install libX11-devel Mesa-libHL-devel libXmu-devel libXi-devel
sudo zypper install bison fontconfig-devel
```

The minimum requirements for third party dependencies to run OpenCascade itself
is Freetype 2.5 and Tcl/TK 8.6:

```shell
sudo apt-get install libfreetype6 libfreetype6-devel
sudo apt-get install tcl tcl-devel tk tk-devel
```

OSX

> Note: The documentation is not complete yet. Feel free to contribute.

### Build

occutils uses CMake as a build system. There are two ways to build project:

#### Using CMakePresets

The first option is to make use of the preconfigured `CMakePresets.json` presets
to build the project. This is the recommended way to build the project, as it
reflects the CI/CD pipeline.

To configure the project run:

```shell
cmake --preset occutils-ninja-multiconfiguration-vcpkg-{{ $os }} # $os = linux, windows, or macos

# Example:
cmake --preset occutils-ninja-multiconfiguration-vcpkg-windows
```

**Note**: The default value for `-DCMAKE_TOOLCHAIN_FILE` refers to
the `submodule` initialized vcpkg installation. If you want to use your own
vcpkg installation, change the value of `-DCMAKE_TOOLCHAIN_FILE` to reflect the
path of your vcpkg installation:

```shell
cmake --preset occutils-ninja-multiconfiguration-vcpkg-{{ $os }} -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
```

To build the project run:

```shell
cmake --build --preset occutils-ninja-multiconfiguration-vcpkg-{{ $os }} # $os = linux, windows, or macos

# Example:
cmake --build --preset occutils-ninja-multiconfiguration-vcpkg-windows
```

**Note**: The default build type is `Release`. To build a different build type,
use the `--config` flag. For example, to build the `Debug` build type, run:

```shell
cmake --build --preset occutils-ninja-multiconfiguration-vcpkg-{{ $os }} --config Debug
```

#### Using plain CMake

Another option is to use plain CMake to build the project. This is useful if you
want to have full control over the build process and underlying configuration.

To configure the project run:

```shell
cmake -S . -B {{ $build_dir }}/{{ $build_type }} -DCMAKE_BUILD_TYPE={{ $build_type }} -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -DOCCUTILS_BUILD_TESTS=ON -DOCCUTILS_BUILD_WARNINGS=ON

# Example:
cmake -S . -B build/Release -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -DOCCUTILS_BUILD_TESTS=ON -DOCCUTILS_BUILD_WARNINGS=ON
```

> Note: Tweak the passed CMake options to your needs,
> whereas `-DOCCUTILS_BUILD_TESTS` decides whether to build the tests and
> `-DOCCUTILS_BUILD_WARNINGS` decides whether to build the project with compiler
> warnings enabled.

> Note: To configure the project on macOS, you need to pass
> the `-DVCPKG_INSTALL_OPTIONS=--allow-unsupported` flag to the CMake command.

To build the project run:

```shell
cmake --build {{ $build_dir }}/{{ $build_type }} --config {{ $build_type }}

# Example:
cmake --build build/Release --config Release
```

## Installation

### System-wide install

The following instructions guide you through the process of
installing `occutils` library system-wide. This is useful if you want to use the
library in other projects.

#### Official GitHub release

The first option is to download the latest release for your platform from the
libraries [GitHub releases page](https://github.com/paulbuechner/occutils/releases/latest).

#### Build and install from source

The second option is to build and install the library from source. To do so,
follow the instructions in the [Build](#build) section. After the build is
complete, run:

```shell
cmake --install {{ $build_dir }}/{{ $build_type }}

# Example:
cmake --install build/Release
```

This will install the library to the system-wide installation directory. On
Windows, this is `C:\Program Files\occutils`. On Linux and macOS, this is
`/usr/local/lib/occutils`.

#### vcpkg

Coming soon.

### Per project install

#### Git submodule

This method involves adding the repository and building it as a subproject of
your CMake-based main project.

To add the repository as a submodule, run:

```shell
git submodule add https://github.com/paulbuechner/occutils.git
```

Then include the library in your CMake project by adding the following lines to
your `CMakeLists.txt`:

```cmake
add_subdirectory(occutils)
```

Lastly, link your project with the `occutils` library. This will set up the
necessary include directories and link the library to your project:

```cmake
target_link_libraries(${PROJECT_NAME} PRIVATE occutils::occutils)
```

#### vcpkg

Coming soon.

## Contributing

Pull requests are welcome. Please open an issue first to discuss what you would
like to change for major changes.

Please read [CONTRIBUTING](CONTRIBUTING.md) for details on the code of conduct,
and the process for submitting pull requests.

### Contributors

_{Uli Köhler}
💻 🚧 📖 🤔

_{Paul Büchner}
💻 🚧 📖 🤔

## License

This project is licensed under the [Apache License 2.0](LICENSE).

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/paulbuechner/occutils

Awesome Lists containing this project

README

occutils