<!-- cSpell:disable -->
<p align="center">
<img src="https://github.com/alpinebuster/3mesh-sdk/actions/workflows/build-test-distribute.yml/badge.svg?branch=main">
<img alt="GitHub License" src="https://img.shields.io/github/license/alpinebuster/3mesh-sdk">
<img alt="GitHub Issues or Pull Requests" src="https://img.shields.io/github/v/release/alpinebuster/3mesh-sdk">
<img alt="GitHub Issues or Pull Requests" src="https://img.shields.io/github/issues/alpinebuster/3mesh-sdk">
</p>

<!-- <p align="center">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="front_page.png">
  <source media="(prefers-color-scheme: light)" srcset="front_page.png">
  <img alt="Front Page" width="544">
</picture>
</p> -->
<!-- cSpell:enable -->

<h1 align="center">3MeshSDK</h1>

<p align="center">
<b>Advanced algorithms for 3D mesh processing with AI agents!</b>
</p>

3MeshSDK provides a robust foundation for 3D data processing, supporting all essential formats like point clouds, meshes, and volumes continuously generated by modern sensors. The powerful half-edge data structure ensures manifold compliance for precise, reliable mesh representation.

## AI Driven Mesh Modeling
- Generative AI / LLM & VLM tools for geometry creation and editing
- 3D reconstruction, point-cloud fusion & odometry
- Geometry-aware deep learning for defect detection & segmentation
- To be continued...

## Core Algorithms
- **3D Boolean** performs fast, highly optimized mesh- and voxel-based operations.
- **Mesh Repair** eliminates self-intersections, fills holes, and removes degeneracies.
- **Mesh Offsetting** controls surface thickness with multiple precise modes for 3D printing and machining.
- **Hole Filling** fills flat and curved surfaces, connects or separates holes, and builds bridges.
- **Mesh Simplification** optimizes mesh complexity while keeping details within set tolerance. We provide remeshing, and subdivision options as well.
- **Collision Detection** verifies intersections between models for further operations.
- **Extensive File Format Support** enables importing a wide range of file formats for meshes, point clouds, CT scans, polylines, distance maps, and G-code. Export functionalities—and support for color and texture data—are available for select formats, too.
- **Triangulation** converts point clouds into meshes with accurate normal creation.
- **ICP** precisely aligns meshes using point-to-point and point-to-plane transformations.
- **Segmentation** performs semi-automatic segmentation based on curvature for meshes and voxels.
- **Deformation** applies Laplacian, freeform, and relaxation smoothing for fine mesh adjustments.
- **Support of Distance Maps and Polylines** allows to generate distance maps and iso-lines and performs projection and intersection.

## Getting Started
This guide explains how to set up 3MeshSDK for C++ development on Windows, Linux, macOS, and docker, and also shows how to build WebAssembly modules using 3MeshSDK with Emscripten. It covers all the prerequisites and setup steps for each platform, making it easy to get started.

### Linux
> Install Clang 18+ first.

```sh
wget https://apt.llvm.org/llvm.sh
chmod u+x llvm.sh
sudo ./llvm.sh 18

sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-14 100 # (optional)
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-18 200
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-14 100 # (optional)
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-18 200
sudo update-alternatives --install /usr/bin/llvm-config llvm-config /usr/bin/llvm-config-14 100 # (optional)
sudo update-alternatives --install /usr/bin/llvm-config llvm-config /usr/bin/llvm-config-18 200
sudo update-alternatives --config clang
sudo update-alternatives --config clang++
clang --version
clang++ --version
llvm-config --version

export CC=gcc
export CXX=g++
export CMAKE_C_COMPILER=gcc
export CMAKE_CXX_COMPILER=g++
export PATH=/usr/bin:$PATH

sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 2
sudo update-alternatives --config python3
python3.12 -m ensurepip --upgrade
python3.12 -m pip install --upgrade pip
```

Install/Build Dependencies and Compile:

```sh
git submodule update --init

./scripts/build_thirdparty.sh
./scripts/build_source.sh
```

Create and Install Package:

For Ubuntu:
```sh
./scripts/distribution.sh
sudo apt install ./distr/meshsdk-dev.deb
```

For Fedora**:
```sh
./scripts/distribution_rpm.sh
sudo rpm -i ./distr/meshsdk-dev.rpm
```

### Docker
```sh
`docker compose up --build 3mesh-emscripten-build`

`docker compose up 3mesh-emscripten-build`
`docker compose up 3mesh-emscripten-build -d`

`docker compose --profile singlethreaded up 3mesh-emscripten-build-singlethreaded`
`docker compose --profile wasm64 up 3mesh-emscripten-build-wasm64`

#
# To run custom build commands:
#
`docker compose exec 3mesh-emscripten-build bash`
`docker compose exec 3mesh-emscripten-build-singlethreaded bash`
`docker compose exec 3mesh-emscripten-build-wasm64 bash`
```

### MacOS
> Prerequisites

1. Install Homebrew
Run the following command in your terminal to install [Homebrew](https://brew.sh/):
`/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`

2. Update Homebrew
Make sure Homebrew is up to date:
`brew update`

3. Install Git Using Homebrew
Once Homebrew is installed and added to your PATH, you can proceed to install Git:
`brew install git`

> Compile Locally
4. Install/Build Dependencies and Compile:
    ```sh
    git submodule update --init

    ./scripts/build_thirdparty.sh
    ./scripts/build_source.sh
    ```

5. Run example We suggest starting with the mesh loading and saving example, which demonstrates how to work with mesh files programmatically.

### Windows (Desktop)
Compile locally from sources.

#### Prerequisites
1. **Git**
  - [Install Git](https://git-scm.com/) to manage repositories and submodules, which is also required to install `vcpkg`.
2. **Visual Studio 2019 or 2022**
  - [Download and install either Visual Studio 2019 or 2022](https://visualstudio.microsoft.com/). During installation, make sure to:
   - Select the "Desktop development with C++" workload.
   - Include support for the C++ programming language.
   - Ensure the English language pack is installed (required for `vcpkg`).
3. **CUDA Toolkit**
  - For **Visual Studio 2019**: Install [CUDA v11.4](https://developer.nvidia.com/cuda-11-4-0-download-archive)
  - For **Visual Studio 2022**: Install [CUDA v12.0](https://developer.nvidia.com/cuda-12-0-0-download-archive)
 Choose the appropriate version based on your Visual Studio installation.
4. **vcpkg**
  - To install `vcpkg`, follow these steps:
   1. **Open a command prompt (CMD) or PowerShell window**.
   2. **Navigate to parent directory to install** `vcpkg`:
      ```cmd
      cd ../
      ```
   3. **Clone the** `vcpkg` **repository**:
      ```cmd
      git clone https://github.com/microsoft/vcpkg.git
      ```
   4. **Navigate to the** `vcpkg` **directory**:
      ```cmd
      cd vcpkg
      git checkout git checkout 2026.02.27
      ```
      If you're using **Visual Studio 2022**, you can use the latest version of vcpkg: `git checkout 2026.02.27`
      The version `2024.10.21` is required only for compatibility with **Visual Studio 2019**.

   5. **Run the bootstrap script to build the** `vcpkg` **executable**:
      ```cmd
      bootstrap-vcpkg.bat
      ```
   6. **Integrate** `vcpkg` **with Visual Studio (requires Administrator access)**:
      ```cmd
      vcpkg integrate install
      ```

[Learn more about](https://github.com/Microsoft/vcpkg) `vcpkg`.

#### Building
The following steps will require approximately 40 GB of disk space.

1. **Fetch the Submodules**:
    ```cmd
    cd ../3mesh-sdk
    git submodule update --init
    ```
2. (Optional) **Speed Up with AWS CLI**
  - Optionally, [install AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to speed up the process before using the Installation Script. Restart your terminal after installation.
3. **Install Third-Party Dependencies**
  - Execute the following commands to run the third-party installation script:
      ```cmd
      cd ../vcpkg
      ..\3mesh-sdk\thirdparty\install.bat
      ```
  - This script automates the installation of necessary third-party dependencies.
4. **Build and Run Visual Studio Solution**
  - Open `3mesh-sdk/source/MeshSDK.sln` in Visual Studio.
  - Build the solution and run the application.
5. **Build and Run CMake Project**
  - Make sure you have the "C++ CMake tools for Windows" component installed.
  - Open `3mesh-sdk/CMakeLists.txt` in Visual Studio (File - Open - CMake).
  - Build the project and run the application.

## Generate Bindings
### JavaScript/TypeScript
[Emscripten](https://emscripten.org/docs/getting_started/downloads.html) is required to compile C++ code into WebAssembly. You can install Emscripten by following the steps below.

```sh
# Fetch the latest version of the emsdk (not needed the first time you clone)
git pull

# Download and install the latest SDK tools.
# ./emsdk install latest # ⚠️ NOT supported
./emsdk install 4.0.10

# Make the "latest" SDK "active" for the current user. (writes .emscripten file)
# ./emsdk activate latest # ⚠️ NOT supported
./emsdk activate 4.0.10

# Activate PATH and other environment variables in the current terminal
source ./emsdk_env.sh
```

Only web and worker environments (i.e. web browsers) are officially supported.

```sh
git submodule update --init

./scripts/build_thirdparty.sh
./scripts/build_source.sh
```

### Python
Build `3meshsdk` from source code, see more details in [README-generating](./scripts/3mbind/README-generating.md).

```sh
curl -Ls https://astral.sh/uv/install.sh | sh
source ~/.bashrc
# At project's root dir
sudo ${PWD}/scripts/3mbind/install_deps_ubuntu.sh

./scripts/3mbind/install_3mbind_ubuntu.sh
make -f ${PWD}/scripts/3mbind/generate.mk -B --trace ENABLE_CUDA=1
# **`shims` — add support for multiple Python versions.**
make shims -f ${PWD}/scripts/3mbind/generate.mk -B --trace ENABLE_CUDA=1 PYTHON_VERSIONS=3.12

# Create and fix wheel
python -m venv ./wheel_venv
source ./wheel_venv/bin/activate
python -m pip install patchelf
# This will generate the `3meshsdk` wheel to `./scripts/wheel/meshsdk`
python ${PWD}/scripts/wheel/build_wheel.py --version 'v1.0.1'
# Install the built `3meshsdk`
cd ${PWD}/scripts/wheel/meshsdk
pip install .
# Check the installed `3meshsdk`
pip list | grep 3mesh

# Publish
pip install --upgrade build twine
python -m build

'''
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = <u-token>
[testpypi]
username = __token__
password = <u-token>
'''
vi ~/.pyirc

# test
#pip install -i https://test.pypi.org/simple 3meshsdk
twine upload --repository testpypi dist/* --verbose
# official
#pip install 3meshsdk
twine upload dist/* --verbose
```

> Run the generator on different platforms

* **On Windows:** `scripts\3mbind\generate_win.bat -B --trace` from the VS developer command prompt (use the `x64 Native` one!).

  When generating the Python bindings, the current directory matters, as this will look for 3MeshSDK in `./source/x64/Release`. Add `VS_MODE=Debug` at the end if you built 3MeshSDK in debug mode.

  The `generate_win.bat` file merely calls `generate.mk` (see below) inside of MSYS2 shell. You can use that directly if you want.

* **On Linux:** `make -f scripts/3mbind/generate.mk -B --trace`

  This will look for 3MeshSDK in `./build/Release/bin`. Pass `MESHSDK_SHLIB_DIR=path/to/bin` for a different directory.

* **On MacOS:** Same as on Linux, but before running the command you must adjust the PATH. On Arm Macs: `export PATH="/opt/homebrew/opt/make/libexec/gnubin:$PATH"`, and on x86 Macs `/usr/local/...` instead of `/opt/homebrew/...`. This adds the version of Make installed in Homebrew to PATH, because the default one is outdated. Confirm the version with `make --version`, it must be 4.x or newer.

## Installation
### JavaScript/TypeScript
Install with npm or yarn:

```sh
npm install 3meshsdk
```

### Python
For Python, simply install via pip:  

```sh
pip install 3meshsdk
```

## **License**
Here, you can access our Non-Commercial Free License with a Commercial License Requirement. Also, see [license](./LICENSE).
