Voxcell

A Framework for iOS and macOS to generate voxel, convex hull, etc. from MDLMesh

Demo Video

Input

MDLMesh that contains the 3D object
Optional MTLTexture to sample colors

Output

MDLMesh that represents voxelized object (optionally with sampled colors)
Collision Balls for GPU-based collision detection
3D Volume bitmap, where true bits represent the boundary or the inside of the sampled object.
Mass, center of mass, and the inertia tensor based on the sampled volume.
Convex hull in the real Brep (graph embedding with vertices, edges, and faces)
Optimum oriented bounding box in terms of volume.

Supported devices

It should work for the recent Macs, iPhones, and iPads. It's been tested with the following devices and the tool chain.

Mac mini(M1, 2020) macOS Monterey 12.3.1
MacBook Pro (Intel, 13-inch, 2017) macOS Monterey 12.3.1
iPhone 13 mini iOS 15.4.1
Xcode 13.3.1 (13E500a)

Dependencies

Accelerate.framework
Metal.framework
MetalPerformanceShaders.framework

Build XCFramework

$ cd /path/to/your/repo/Voxcell/Voxcell

$ ls #Check if you are in the right directory
Voxcell Voxcell.xcodeproj VoxcellTests module.modulemap

$ xcodebuild archive -scheme Voxcell -configuration Release -destination 'generic/platform=iOS' -archivePath './build/Voxcell.framework-iphoneos.xcarchive' SKIP_INSTALL=NO BUILD_LIBRARIES_FOR_DISTRIBUTION=YES

$ xcodebuild archive -scheme Voxcell -configuration Release -destination 'generic/platform=iOS Simulator' -archivePath './build/Voxcell.framework-iphonesimulator.xcarchive' SKIP_INSTALL=NO BUILD_LIBRARIES_FOR_DISTRIBUTION=YES

$ xcodebuild archive -scheme Voxcell -configuration Release -sdk macosx -archivePath './build/Voxcell.framework-macos.xcarchive' SKIP_INSTALL=NO BUILD_LIBRARIES_FOR_DISTRIBUTION=YES

$ xcodebuild -create-xcframework -framework './build/Voxcell.framework-iphoneos.xcarchive/Products/Library/Frameworks/Voxcell.framework' -framework './build/Voxcell.framework-iphonesimulator.xcarchive/Products/Library/Frameworks/Voxcell.framework' -framework './build/Voxcell.framework-macos.xcarchive/Products/Library/Frameworks/Voxcell.framework' -output './build/Voxcell.xcframework'

(Run sudo xcode-select -s /Applications/Xcode.app/Contents/Developer first, if it's not selected yet.)

This will create a XCFramework in ./build/Voxcell.xcframework.

Usage

API Documentation is found at the bottom of this document.

Overview
VolumeSampler
GridInfo
Brep

Running the accompanying demo App.

Open /path/to/your/repo/Voxcell/VoxcellDemo/VoxcellDemo.xcodeproj, build and run for macOS and iOS.

NOTE:

The 3D model duck is removed from this repo, as its license prohibits distribution in any readable form.

The 3D model cow is provided by Keenan Crane under CC0. 1.0.

Technical Stuff

Depth Peeling in Metal

The volume sampling is done by a technique called 'depth peeling'. In OpenGL it is implemented using two Z-buffers alternatingly, which enable a function 'closest object but that muss be further than X' per pixel. This can not be implemented in Metal. However Metal has a nice ray-intersector, which can be used for depth peeling. Please see VolumeSampler/DepthPeeler.swift and VolumeSampler/DepthPeelerShaders.metal.

Finding Convex Hull.

The implementation is taken from my existing C++ codebase for computational geometry and graph algorithms. The algorithm is based on Computational Geometry Algorithms and Applications, M. de Berg, M. van Kreveld, M. Overmars, and O.Schwartzkopf 2nd Ed, Springer 2000, ISBN 3-540-65620-0. Please see CppCode/manifold_convex_hull.cpp.

Notes on how to build an Apple framework that contains both Swift and C++ code.

Ref: Boris Gromov's Gist

Arrange an adapter class in Obj-c for each C++ class.

( Ex.

@implementation ManifoldObjc
...
-(void) findConvexHullOrOrientedBoundingBox:(const simd_float3 *const) points
                                  numPoints:(const int) numPoints
                     forOrientedBoundingBox:(const bool) orientedBoundingBox
{
    ...
    Manifold convex_hull;
    ...
    convex_hull.findConvexHull(vec, pred);
    ...
}

in SwiftObjcCppInterface/manifold_objc.{h,mm} )

DO NOT create a bridging header file
Arrange an adapter class in Swift for Obj-c class

( Ex.

extension Brep {
    ...
    let mObjc : ManifoldObjc = ManifoldObjc()
    ...
}

in BrepConvexHullExtension.swift )

Set all the Obj-c header files to Target Membership 'Public'

(Ex.

objects = {
    EF6E0C9E28233B5D00E5D6BC /* manifold_objc.h in Headers */ = {isa = PBXBuildFile; fileRef = EF6E0C9A28233B5D00E5D6BC /* manifold_objc.h */; settings = {ATTRIBUTES = (Public, ); }; };
}

in ./Voxcell.xcodeproj/project.pbxproj

Place the Obj-c header filenames under the module definiton file. (Ex. module.modulemap )
TARGETS -> Packaging -> Module Map File = module.modulemap (Ex. buildSettings = {MODULEMAP_FILE = module.modulemap;} in in ./Voxcell.xcodeproj/project.pbxproj )

License

GPL v3.

Commercial use with proper attribution can be considered.

Especially, for indy developers and small businesses, a very favorable licensing can be readily arranged.

Contact

For technical and commercial inquiries, please contact: Shoichiro Yamanishi

yamanishi72@gmail.com

API Guide

Overview

The Voxcell Framework consists of two main classes: VolumeSampler and Brep.

VolumeSampler

VolumeSampler samples the volume represented by the given MDLMesh using the depth peeling technique. It generates a 3D volume bitmap, which is used to generate a voxelized mesh, collision balls, mass, the center of mass, and the inertia tensor. The constructor takes the MDLMesh and other attributes, and generate

Voxcell

Install / Use

README

Voxcell

Input

Output

Supported devices

Dependencies

Build XCFramework

Usage

Table Of Contents

Running the accompanying demo App.

Technical Stuff

Depth Peeling in Metal

Finding Convex Hull.

Notes on how to build an Apple framework that contains both Swift and C++ code.

License

Contact

API Guide

Overview

VolumeSampler