Metadata-Version: 2.4
Name: 3mesh
Version: 1.0.1
Summary: Advanced 3D mesh processing library.
Author-email: alpinebuster <imzqqq@hotmail.com>
License: NON-COMMERCIAL & education LICENSE AGREEMENT
        
        This  agreement  is  between  the  individual below (User) and AMV Consulting, LLC, a 
        Nevada limited liability company (AMV). The AMV source code library software, and all 
        modifications,  enhancements,  technical documentation provided by AMV as part of the 
        Software (Software)  are  licensed  and  are  not  sold.  By  receiving or using this 
        Software, User indicates its acceptance of the terms of this agreement. 
        
        
        TRIAL LICENSE.
        
        Subject to the terms of this agreement, AMV grants User a terminable, non-exclusive, 
        and  non-transferable  license  to  use  the  Software,  solely  for non-commercial, 
        evaluation or educational purposes. 
        
        
        DISCLAIMER.
        
        AMV  DISCLAIMS  ANY AND ALL REPRESENTATIONS OR WARRANTIES OF ANY 
        KIND,  WHETHER  EXPRESS  OR  IMPLIED,  MADE  WITH RESPECT TO THE 
        SOFTWARE,  INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES 
        OF   MERCHANTABILITY,   NON-INFRINGEMENT,   AND  FITNESS  FOR  A 
        PARTICULAR PURPOSE. THE SOFTWARE IS PROVIDED ‘AS IS’ WITHOUT ANY 
        WARRANTY  OF ANY KIND. AMV AND ITS LICENSORS DO NOT WARRANT THAT 
        ANY  SOFTWARE  IS WITHOUT DEFECT OR ERROR, OR THAT THE OPERATION 
        OF ANY SOFTWARE WILL BE UNINTERRUPTED.
        
        
        RESTRICTIONS ON USE.
        
        User may not sell, rent, sublicense, display, modify, or otherwise transfer the Software 
        to any third party. 
        
        
        OWNERSHIP.
        
        All right, title, and interest to the Software are owned by AMV and its licensors, and 
        are  protected by United States and international intellectual property laws. User may 
        not  remove  or alter any copyright or proprietary notice from copies of the Software. 
        AMV reserves all rights not expressly granted to User.
        
        
        TERMINATION.
        
        The  license  in  Section  1 terminates upon AMV’s notice of termination to User. Upon 
        termination of this agreement or a license for any reason, User must discontinue using 
        the  Software, de-install, and destroy the Software and all copies within 5 days. Upon 
        AMV’s  request,  User  will confirm in writing its compliance with this destruction or 
        return requirement.
        
        
        LIABILITY LIMIT.
        
        EXCLUSION  OF  INDIRECT  DAMAGES.  TO THE MAXIMUM EXTENT ALLOWED 
        BY LAW, AMV IS NOT LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, 
        OR  CONSEQUENTIAL  DAMAGES  ARISING  OUT  OF  OR RELATED TO THIS 
        AGREEMENT  (INCLUDING,  WITHOUT LIMITATION, COSTS OF DELAY; LOSS 
        OF  OR  UNAUTHORIZED  ACCESS  TO  DATA  OR INFORMATION; AND LOST 
        PROFITS,  REVENUE,  OR  ANTICIPATED  COST  SAVINGS),  EVEN IF IT 
        KNOWS  OF  THE  POSSIBILITY  OR FORESEEABILITY OF SUCH DAMAGE OR 
        LOSS.
        
        TOTAL  LIMIT ON LIABILITY. TO THE MAXIMUM EXTENT ALLOWED BY LAW, 
        AMV'S  TOTAL  LIABILITY  ARISING  OUT  OF  OR  RELATED  TO  THIS 
        AGREEMENT  (WHETHER  IN  CONTRACT,  TORT, OR OTHERWISE) DOES NOT 
        EXCEED $100.
        
        
        GOVERNING LAW AND FORUM.
        
        This  agreement  is  governed  by  the  laws  of  the  State  of  Nevada  (without regard to 
        conflicts  of  law principles) for any dispute between the parties or relating in any way to 
        the  subject  matter  of  this  agreement.  Any suit or legal proceeding must be exclusively 
        brought  in  the  federal  or  state  courts  for Washoe County, Nevada, and User submits to 
        this  personal  jurisdiction  and  venue.  Nothing  in this  agreement prevents either party 
        from  seeking  injunctive  relief in a court of competent jurisdiction. The prevailing party 
        in any litigation is entitled to recover its attorneys’ fees and costs from the other party.
        
        
        OTHER TERMS.
        
        Entire Agreement and Changes. This agreement constitutes the entire 
        agreement between the parties and supersedes any prior or contemporaneous 
        negotiations or agreements, whether oral or written, related to this subject matter. 
        User is not relying on any representation concerning this subject matter, oral or 
        written, not included in this agreement. No representation, promise, or inducement 
        not included in this agreement is binding. No modification or waiver of any term of 
        this agreement is effective unless both parties sign it.
        
        No Assignment. Neither party may assign or transfer this agreement to a third 
        party, nor delegate any duty, except that the agreement may be assigned, without 
        the consent of the other party, (i) as part of a merger or sale of all or substantially 
        all a party's businesses or assets, of User, and (ii) in the case of AMV at any time 
        to any third party.
        
        Independent Contractors. The parties are independent contractors with respect 
        to each other, and neither party is an agent, employee, or partner of the other 
        party or the other party's affiliates.
        
        Enforceability and Force Majeure. If any term of this agreement is invalid or 
        unenforceable, the other terms remain in effect. Neither party is liable for its non-
        performance due to events beyond its reasonable control, including but not limited 
        to natural weather events and disasters, labor disruptions, and disruptions in the 
        supply of utilities.
        
        Money Damages Insufficient. Any breach by a party of this agreement or 
        violation of the other party’s intellectual property rights could cause irreparable 
        injury or harm to the other party. The other party may seek a court order to stop 
        any breach or avoid any future breach of this agreement.
        
        Survival of Terms. All provisions of this agreement regarding payment, 
        confidentiality, indemnification, limitations of liability, proprietary rights and such 
        other provisions that by fair implication require performance beyond the term of 
        this agreement must survive expiration or termination of this agreement until fully 
        performed or otherwise are inapplicable. The UN Convention on Contracts for the 
        International Sale of Goods does not apply.
        
        Compliance Audit. No more than once in any 12-month period and upon at least 
        30 days’ advance notice, AMV (or its representative) may audit User’s usage of the 
        Software at any User facility. User will cooperate with such audit. User agrees to pay 
        within 30 days of written notification any fees applicable to User’s use of the 
        Software in excess of the license.
        
        Export Compliance. The Software and Confidential Information may be subject to 
        export laws and regulations of the United States and other jurisdictions. Each party 
        represents that it is not named on any U.S. government denied-party list. Neither 
        party will permit its personnel or representatives to access any Software in a U.S.-
        embargoed country or in violation of any applicable export law or regulation.
        
        U.S. Government Restricted Rights. If User is a United States government 
        agency or acquired the license to the Software hereunder pursuant to a 
        government contract or with government funds, then as defined in FAR §2.101, 
        DFAR §252.227-7014(a)(1), and DFAR §252.227-7014(a)(5), or otherwise, all 
        Software provided in connection with this agreement are “commercial items,” 
        “commercial computer software,” or “commercial computer software 
        documentation.” Consistent with DFAR §227.7202 and FAR §12.212, any use, 
        modification, reproduction, release, performance, display, disclosure, or 
        distribution by or for the United States government is governed solely by the 
        terms of this agreement and is prohibited except to the extent permitted by the 
        terms of this agreement.
        
        Open Source Software Licenses. The Software may contain embedded open source 
        software components, which are provided as part of the Software and for 
        which additional terms may be included in the technical documentation.
        
        Feedback. If User provides feedback or suggestions about the Software, then AMV 
        (and those it allows to use its technology) may use such information without 
        obligation to User.
        
Project-URL: Homepage, https://3mesh.tech/
Project-URL: Documentation, https://3mesh.tech/documentation/
Project-URL: Source, https://github.com/alpinebuster/3mesh-sdk
Project-URL: Bug Reports, https://github.com/alpinebuster/3mesh-sdk/issues
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: Free For Educational Use
Classifier: License :: Free for non-commercial use
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Dynamic: license-file

<!-- 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).
