search

MeshInspector / MeshLib

Mesh processing library
https://meshlib.io
Other
512 stars 58 forks source link
3d cpp cross-platform distance-map geometry library mesh mesh-analysis mesh-boolean mesh-decimation mesh-processing mesh-registration mesh-segmentation mesh-smoothing point-cloud pointcloud pointcloud-triangulation python voxel voxel-segmentation

readme

Open in Gitpod

build-test-distribute PyPI version Python Downloads

MeshInspector/MeshLib

Welcome to the MeshLib!

3D scanning is becoming more and more ubiquitous. Robotic automation, self-driving cars and multitude of other industrial, medical and scientific applications require advanced computer vision to deliver the levels of automation customers expect these days. The great rise of AI gave another boost to computer vision and the need to utilize 3D data to make machines smarter. Not only are tasks at hand becoming more complex, but the size of data grows exponentially.

There is a multitude of general purpose libraries which deal with 3D data. Some stem from popular CAD packages, some are open source. The commercial ones tend to be quite expensive while open source are free though tend to be limited in functionality provided. Also those libraries value generality above other features to allow maximum number of applications, but with the growing amounts of 3D data, performance is critical as it never has been. Some of it can be addressed by using the scale of a commercial cloud, last generation CPU or GPU but underlying complexity of data representation makes it very hard and laborsome.

The goal which we set when designing MeshLib was to value simplicity and performance while providing a wide gamut of useful computational algorithms. The library also supports the most important data structures today’s sensors can produce - pointcloud, mesh, volume and more. For example, mesh is represented by half-edge data structure and cannot be made non-manifold. Some applications may require non-manifoldness, but most practical scans can be represented as manifoldness meshes without an issue.

Some useful links

Major features

This list is not full and updating each day

Math basics

Python integration

Although MeshLib is written in C++, all functions are exposed to Python as well. Python code can be executed both from within a MeshLib-based C++ application (embedded mode) and from python interpreter directly, which imports MeshLib modules.

Moreover, the latest MeshLib released version can be easily installed as a Python 3.8 - 3.12 package using pip install:

Latest version of meshlib in python has almost all c++ functionality, but also can have slightly different signatures from old versions. One can install it if specify version explicitly pip install meshlib==3.0.0.40

NOTE: we have no available Python3.8 package on macOS x86

  • On Windows via 
    py -3 -m pip install --upgrade pip
py -3 -m pip install --upgrade meshlib
  • On Linuxes supporting manylinux_2_31+, including Ubuntu 20+ and Fedora 32+ via 
    sudo apt install python3-pip
python3 -m pip install --upgrade pip
python3 -m pip install --upgrade meshlib
  • On macOS 12.0+ via 
    pip install --upgrade pip
pip install --upgrade meshlib

See Python Basic Examples here or search for more complex ones on stackoverflow.com.

.NET integration

Also you can integrate MeshLib into your .NET project via NuGet. The package can be installed from .NET command-line interface, VisualStudio, or downloaded from NuGet website.

Installation via .NET command-line interface

# Create a new directory for your project
mkdir TestProject
# Move to the directory
cd TestProject
# Create a new console project
dotnet new console
# Install MeshLib package
dotnet add package MeshLib

Installation via VisualStudio

Installation of downloaded .nupkg file

NOTE: MeshLib package is built for x64 architecture, so make sure that your solution platform is x64. Correct working for other platforms is not guaranteed.

Build

Windows

MeshLib can be build on Windows using either Visual Studio 2019 or Visual Studio 2022, both of which support c++20 language standard. 

git clone https://github.com/MeshInspector/MeshLib.git
cd MeshLib
git submodule update --init --recursive
cd ..

Note: following below steps will take about 40Gb of your disk space.

Preparing Third Parties

Some third parties are taken from vcpkg, while others (missing in vcpkg) are configured as git submodules.

CUDA

Windows version of MeshLib is configured to use

Please install CUDA from the official site. If you would like to use another version of CUDA, please modify MRCudaVersion in MeshLib/source/platform.props.

Vcpkg

  1. Please install vcpkg, and integrate it into Visual Studio (note that vcpkg requires English language pack in Visual Studio, and vcpkg cannot be installed on FAT volumes, only on NTFS):

    git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
git checkout 2024.07.12
.\bootstrap-vcpkg.bat
.\vcpkg integrate install (with admin rights)

    More details here: vcpkg.

  2. (Optional, but recommended) Install AWS CLI v2. Once installed, reopen PowerShell or CMD. This will allow you to use the vcpkg binary cache from our aws s3, which will speed up the installation process and reduce the required disk space.

  3. Execute MeshLib/thirdparty/install.bat having previously installed vcpkg as the current working directory (or simply add vcpkg to PATH environment variable).

  4. Open solution file MeshLib/source/MeshLib.sln in Visual Studio. Build it and run.

Linux

We regularly check that MeshLib can be built successfully on Ubuntu 20.04 LTS, Ubuntu 22.04 LTS (both x64 and ARM), and Fedora 37.

Install/Build dependencies. Build project. Run Test Application

Install CUDA v12.0 from official site

Use automated installation process. It takes ~40 minutes if no required packages are already installed. This approach is useful for new MR developers

Run the following in terminal:

git clone --recurse-submodules https://github.com/MeshInspector/MeshLib.git
cd MeshLib
./scripts/build_thirdparty.sh  # do not select emscripten in the corresponding question
./scripts/build_source.sh  # do not select emscripten in the corresponding question
# create and install package for Ubuntu
./scripts/distribution.sh
sudo apt install ./distr/meshlib-dev.deb
# create and install package for Fedora
./scripts/distribution_rpm.sh
sudo apt install ./distr/meshlib-dev.rpm

NOTE: ./scripts/install*.sh scripts could be used as well, but apt install is preferable.

NOTE: ./scripts/install_thirdparty.sh script copies MR files directly to /usr/local/lib. Remove this directory manually if exists before apt install deb package.

NOTE: You could specify build type to Debug by export MESHLIB_BUILD_TYPE=Debug. Release is default. Set MESHLIB_KEEP_BUILD=ON to suppress full rebuild

WASM/Emscripten

This installation was checked on Ubuntu 22.04 with Emscripten 3.1.48.

Install Emscripten (find more on Emscripten official page)

git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
git pull origin # optional
./emsdk install 3.1.48 # (or another version / latest)
./emsdk activate 3.1.48
source ./emsdk_env.sh

Build

cd ~/MeshLib
./scripts/build_thirdparty.sh # select Emscripten in the corresponding question
./scripts/build_source.sh # select Emscripten in the corresponding question

NOTE: Set MESHLIB_KEEP_BUILD=ON to suppress full rebuild

Run

python3 -m http.server 8000 # note that server should have specific COEP and COOP policies for multithread version
# open in browser 127.0.0.1:8000

Integration

Linux Ubuntu/Fedora

You can download dev package and install it with your Linux OS package manager. Examples of integration with cmake can be found in the ./examples directory.

MacOS

Same as for Linux, but requires brew packages to be installed:

xargs brew install < /Library/Frameworks/MeshLib.framework/Versions/Current/requirements/macos.txt

Windows

There are two general options of integrating MeshLib into your project:

  1. Submodule
  2. Distribution

Submodule

You can have MeshLib as submodule in your repository, and inculde all MeshLib's projects to your solution.

This option requires you to install third-party libraries via vcpkg package mananger.

NOTE: You should use MeshLib/source/common.props in other projects of your solution.

NOTE: You can customize props by defining CustomMRProps.props in directory above common.props.

NOTE: If you would like to set _ITERATOR_DEBUG_LEVEL=1 macro, then please do it in CustomMRProps.props together with MR_ITERATOR_DEBUG_LEVEL=1 macro.

Distribution

You can download zip-archive containing

of both MeshLib and dependant third-party libraries, and make them available during your project building and runtime execution as follows.

Project settings in Visual Studio:

  1. C/C++ -> General -> Additional Include Directories add distribution\install\include;
  2. Linker -> General -> Additional Library Directories add distribution\install\app\$(Configuration);
  3. Linker -> Input -> Additional Dependencies add distribution\install\lib\$(Configuration)\*.lib;
  4. Debug Configuration: C/C++ -> Preprocessor -> Preprocessor Defenitions add _ITERATOR_DEBUG_LEVEL=0;

Make sure you copy all dlls from distribution\install\app\$(Configuration); to your $(TargetDir)

NOTE: MeshLib distribution has x64 build only.

NOTE: Distribution is built with _ITERATOR_DEBUG_LEVEL=0 macro defined in Debug configuration so you will need to setup this for your projects.

Distribution for .NET

You can download zip-archive MeshLibDotNetDist.zip containing dynamic lybraries (.dll) of both MeshLib and dependant third-party libraries, and make them available during your project building and runtime execution as follows.

  1. Create a new C# project in Visual Studio.
  2. Double-click on the project in Solution Explorer. You will see content of the .csproj file

  3. Add the following lines before the </Project> closing tag

    <PropertyGroup>
<AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
<AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>

<ItemGroup>
<Reference Include="MRDotNet">
 <HintPath>path\to\distribution\$(Configuration)\MRDotNet.dll</HintPath>
</Reference>
</ItemGroup>
    1. Extract content of MeshLibDotNetDist.zip to project\bin directory

    You could find examples of usage in this repo in examples\c-sharp-example directory

    NOTE: MeshLib distribution has x64 build only.