Swift Assimp

This is a thin Swift wrapper around the popular and excellent Open Asset Import Library library.
It provides a swifty and typesafe API.

Open Asset Import Library (short name: Assimp) is a portable Open Source library to import various well-known 3D model formats in a uniform manner. The most recent version also knows how to export 3d files and is therefore suitable as a general-purpose 3D model converter. Loads 40+ 3D file formats into one unified and clean data structure.
~ www.assimp.org

🚀 Getting Started

These instructions will get your copy of the project up and running on your local machine and provide a code example.

📋 Prerequisites

Swift Package Manager (SPM)
Open Asset Import Library (Assimp)
SwiftEnv for Swift version management - (optional)
Swiftlint for linting - (optional)

💻 Installing

Swift Assimp is available for all platforms that support Swift 5.1 and higher and the Swift Package Manager (SPM).

Extend your Package.swift file with the following lines or use it to create a new project.

For package manifests using the Swift 5.1 toolchain use:

// swift-tools-version:5.1
import PackageDescription

let package = Package(
    name: "YourPackageName",
    dependencies: [
        .package(url: "https://github.com/ctreffs/SwiftAssimp.git", from: "1.3.1")
    ],
    targets: [
        .target(
            name: "YourTargetName",
            dependencies: ["Assimp"])
    ]
)

or for package manifests using the Swift 5.2+ toolchain use:

// swift-tools-version:5.2
import PackageDescription

let package = Package(
    name: "YourPackageName",
    dependencies: [
        .package(name: "Assimp", url: "https://github.com/ctreffs/SwiftAssimp.git", from: "1.3.1")
    ],
    targets: [
        .target(
            name: "YourTargetName",
            dependencies: ["Assimp"])
    ]
)

Since it's a system library wrapper you need to install the assimp library (>=5.0.0) either via

brew install assimp

apt-get install libassimp-dev

depending on you platform.

⚠️ Caution macOS homebrew users

Swift package manager relies on the pkg-config tool to find system installed libraries. Assimp version 5 contains a regression, which provides a broken pkg-config file (assimp.pc). Therefore SPM is not able to find the include headers out of the box resulting in the error: shims.h:1:10: error: 'assimp/cimport.h' file not found. This is a known bug and is tracked here https://github.com/assimp/assimp/issues/3174 and here https://github.com/assimp/assimp/issues/2804. However there is a fix that requires one manual step.

Depending on your assimp version run the following command in your Terminal:

print the currently installed assimp version: printBrewAssimpVersion
- for version 5.0.0: make copyMacPkgConfig500
- for version 5.0.1: make copyMacPkgConfig501

This will copy a corrected pkg-config file to the appropriate library location. You will need to repeat this step when updating assimp via homebrew until a fix is provided by the assimp developers. Be sure to close Xcode before retrying to build.

📝 Code Example

import Assimp

let scene: AiScene = try AiScene(file: <path/to/model/file.obj>, 
                                 flags: [.removeRedundantMaterials, .genSmoothNormals]))

// get meshes
let meshes: [AiMesh] = scene.meshes

// get materials
let matrials: [AiMaterial] = scene.materials

// get the root node of the scene graph
let rootNode: [AiNode] = scene.rootNode

See the unit tests for more examples.

💁 Help needed

This project is in an early stage and needs a lot of love. If you are interested in contributing, please feel free to do so!

Things that need to be done are, among others:

Wrap more assimp functions and types
Support for Cocoapods packaging
Support for Carthage packaging
Write some additional tests to improve coverage

🏷️ Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

✍️ Authors

Christian Treffs

See also the list of contributors who participated in this project.

🔏 Licenses

This project is licensed under the 3-Clause BSD License - see the LICENSE file for details.

assimp licensed under 3-clause BSD license

🙏 Original code

Since Swift Assimp is merely a wrapper around assimp it obviously depends on it.
Support them if you can!

Open Asset Import Library (assimp)

From assimp/assimp/Readme.md:

A library to import and export various 3d-model-formats including scene-post-processing to generate missing render data.

One-off donations via PayPal:

Swift Package Index

Assimp

Swift Version Compatibility

Platform Compatibility