Alternate Python bindings for the Open Asset Import Library (ASSIMP)

Overview

Impasse

Python Test Status codecov

A simple Python wrapper for assimp using cffi to access the library. Requires Python >= 3.7.

It's a fork of PyAssimp, Assimp's official Python port. In contrast to PyAssimp, it strictly targets modern Python 3 and provides type hints. It also aims to allow mutating scenes before exporting by having all wrapper classes operate directly on the underlying C data structures.

Usage

Complete example: 3D viewer

impasse comes with a simple 3D viewer that shows how to load and display a 3D model using a shader-based OpenGL pipeline.

Screenshot

To use it:

python ./scripts/3d_viewer.py <path to your model>

You can use this code as starting point in your applications.

Writing your own code

To get started with impasse, examine the simpler sample.py script in scripts/, which illustrates the basic usage. All Assimp data structures are wrapped using ctypes. All the data+length fields in Assimp's data structures (such as aiMesh::mNumVertices, aiMesh::mVertices) are replaced by list-like wrapper classes, so you can call len() on them to get their respective size and access members using [].

For example, to load a file named hello.3ds and print the first vertex of the first mesh, you would do (proper error handling substituted by assertions ...):

from impasse import load

scene = load('hello.3ds')

assert len(scene.meshes)
mesh = scene.meshes[0]

assert len(mesh.vertices)
print(mesh.vertices[0])

Another example to list the 'top nodes' in a scene:

from impasse import load

scene = load('hello.3ds')
for c in scene.root_node.children:
    print(str(c))

All of assimp's coordinate classes are returned as NumPy arrays, so you can work with them using library for 3d math that handles NumPy arrays. Using transforms.py to modify the scene:

import math

import numpy
import transformations
import impasse

# assimp returns an immutable scene, we have to copy it if we want to change it
scene = impasse.load('hello.3ds').copy_mutable()
transform = scene.root_node.transformation
# Rotate the root node's transform by 180 deg on X
transform = numpy.dot(transformations.rotation_matrix(math.pi, (1, 0, 0)), transform)
scene.root_node.transformation = transform
impasse.export(scene, 'whatever.obj', 'obj')

Installing

Install impasse by running:

pip install impasse

or, if you want to install from the source directory:

pip install -e .

Impasse requires an assimp dynamic library (DLL on Windows, .so on linux, .dynlib on macOS) in order to work. The default search directories are:

  • the current directory
  • on linux additionally: /usr/lib, /usr/local/lib, /usr/lib/ -linux-gnu

To build that library, refer to the Assimp master INSTALL instructions. To look in more places, edit ./impasse/helper.py. There's an additional_dirs list waiting for your entries.

Progress

All features present in PyAssimp are now present in Assimp (plus a few more!) Since the API largely mirrors PyAssimp's, most existing code should work in Impasse with minor changes.

Note that Impasse is not complete. Many assimp features are still missing, mostly around mutating scenes. Notably, anything that would require a new or delete in assimp's C++ API is not supported.

Performance

Impasse tries to avoid unnecessary copies or conversions of data owned by C, and most classes are just thin layers around the underlying CFFI structs. NumPy arrays that directly map to the underlying structs' memory are used for the coordinate structs like Matrix4x4 and Vector3D.

Testing with a similar quicktest.py script against assimp's test model directory:

Impasse

** Loaded 169 models, got controlled errors for 28 files, 0 uncontrolled

real	0m1.460s
user	0m1.676s
sys	0m0.571s

PyAssimp

** Loaded 165 models, got controlled errors for 28 files, 4 uncontrolled

real	0m7.607s
user	0m7.746s
sys	0m0.579s
Comments
  • Nicer way of referring to material property keys

    Nicer way of referring to material property keys

        ('$mat.twosided', 0): [0]
        ('$mat.refracti', 0): [1.]
        ('$mat.bumpscaling', 0): [1.]
        ('$clr.specular', 0): [1. 1. 1.]
    

    Those keys are in the data returned by assimp, but I'm not sure if the prefix is that meaningful. PyAssimp strips off everything before the first .. If they're meaningful or there are collisions without those prefixes, we should keep a string enum of common ones that's easier to refer to.

    enhancement 
    opened by SaladDais 3
  • Rebase on top of original assimp sources to keep PyAssimp's commit history intact

    Rebase on top of original assimp sources to keep PyAssimp's commit history intact

    Now that I think of it, it's preferable to keep the commit history for assimp even if most of it's unrelated to PyAssimp. Make a commit deleting all assimp sources and moving PyAssimp to the repo root, then rebase impasse on top of that.

    Rewriting history isn't nice since I've already based my sources on top of a squashed commit, but impact should be mininal since nobody's using this yet.

    opened by SaladDais 1
  • Make mapping classes mix-ins

    Make mapping classes mix-ins

    Other than name collisions with keys / values, I don't think there's any reason to keep the explicit as_mapping() method rather than just putting them on a mixin for the SerializeableStructs. Can define manual renames for any of those.

    This'd give us a closer API to what PyAssimp already has

    enhancement 
    opened by SaladDais 1
  • Add accessors for mesh and texture that return instances rather than indexes

    Add accessors for mesh and texture that return instances rather than indexes

    All of the struct wrapper have a _scene member that should allow them to transparently look up the texture / material by the index in the attr they wrap.

    enhancement 
    opened by SaladDais 1
  • Get scene mutability working

    Get scene mutability working

    Per the C api you have to create a copy of the scene to get a non-const version: https://github.com/assimp/assimp/blob/master/include/assimp/cexport.h#L109-L123 . Right now all the structs we return have wrappers enforcing the const-ness of scene returned from the the aiImportFile() function. Need to expose the copying functions so people can get a scene they can modify before export.

    enhancement 
    opened by SaladDais 1
  • Package assimp shared library so assimp isn't required to be on the system

    Package assimp shared library so assimp isn't required to be on the system

    Would be nice so people don't have to do some weird conda thing if they want to install the package including assimp.

    I think it should be enough to have osx aarch64, osx x64, linux x64 and windows x64 packages. We don't need to do python version-specific builds, since we'll just be building the assimp library itself and binding against it with cffi. It should be provided in an optional, separate package with the shared library in the package data for the given platform's build.

    enhancement 
    opened by SaladDais 0
  • Add ability to alloc new structs, append to sequences

    Add ability to alloc new structs, append to sequences

    This is tricky since assimp makes liberal use of new[] and delete[] on types that have non-trivial destructors (like aiTexture.) malloc()ing and free()ing those is technically possible but inadvisable, and requires knowledge of the platform / compiler's C++ ABI.

    Likewise, assimp's C API doesn't appear to expose a wrapper around those new[] and delete[] calls. Adding functions to assimp to do those would be the least nasal demon-y approach but wouldn't be available in stable distros' libs.

    A third approach would be to have Scenes keep track of the original values of mutated ptrs, then put everything back in place when the GC happens so anything that'd been internally alloc'd with new could be deleted by assimp. Would also have to keep a list of things we'd malloc()d in our own code to manually free(). Can see a lot of nasty corner cases with this one.

    enhancement help wanted 
    opened by SaladDais 0
Releases(v5.2.0)
Owner
Salad Dais
Code as craft
Salad Dais
🎶😤 Generate an image indicating what you are listening to 😳

I'm Listening to This (song that I've sent you an image about detailing its metadata in a nifty way) Few lines describing your project. 📝 Table of Co

Connor B - Viibrant 4 Nov 03, 2021
QR fixer part is standalone but for image to FQR conversion

f-qr-fixer QR fixer part is standalone but for image to FQR conversion it requires Pillow (can be installed with easy_install), qrtools (on ubuntu the

2 Nov 22, 2022
PSD (Photoshop, Krita, Gimp...) -> Godot.

limage v0.2.2 Features Getting Started Tags Settings Todo Customizer Changes Solutions WARNING: Requires Python to be installed PSD (Photoshop, Krita,

21 Nov 10, 2022
Ascify-Art - An easy to use, GUI based and user-friendly colored ASCII art generator from images!

Ascify-Art This is a python based colored ASCII art generator for free! How to Install? You can download and use the python version if you want, modul

Akash Bora 14 Dec 31, 2022
A 3D structural engineering finite element library for Python.

An easy to use elastic 3D structural engineering finite element analysis library for Python.

Craig 220 Dec 27, 2022
An ascii art generator that's actually good. Does edge detection and selects the most appropriate characters.

Ascii Artist An ascii art generator that's actually good. Does edge detection and selects the most appropriate characters. Installing Installing with

18 Jan 03, 2023
⚡ZenGL is a minimalist Python module providing exactly one way to render scenes with OpenGL.

ZenGL is a minimalist Python module providing exactly one way to render scenes with OpenGL.

Szabolcs Dombi 133 Dec 17, 2022
sK1 2.0 cross-platform vector graphics editor

sK1 2.0 sK1 2.0 is a cross-platform open source vector graphics editor similar to CorelDRAW, Adobe Illustrator, or Freehand. sK1 is oriented for prepr

sK1 Project 238 Dec 04, 2022
Anaglyph 3D Converter - A python script that adds a 3D anaglyph style effect to an image using the Pillow image processing package.

Anaglyph 3D Converter - A python script that adds a 3D anaglyph style effect to an image using the Pillow image processing package.

Kizdude 2 Jan 22, 2022
Visage Differentiation is a GUI application for outlining and labeling the visages in an image.

Visage Differentiation Visage Differentiation is a GUI application for outlining and labeling the visages in an image. The main functionality is provi

Grant Randa 0 Jan 13, 2022
SALaD (Semi-Automatic Landslide Detection) is a landslide mapping system

SALaD (Semi-Automatic Landslide Detection) is a landslide mapping system. SALaD utilizes Object-based Image Analysis and Random Forest to map landslides.

NASA 14 Jan 04, 2023
Create QR Code for link using Python

Quick Response QR is short and named for a quick read from a cell phone. Used to view information from transitory media and put it on your cell phone.

Coding Taggers 1 Jan 09, 2022
With this simple py script you will be able to get all the .png from a folder and generate a yml for Oraxen

Oraxen-item-to-yml With this simple py script you will be able to get all the .png from a folder and generate a yml for Oraxen How to use Install the

Akex 1 Dec 29, 2021
Avatar Generator Python

This is a simple avatar generator project which uses your webcam to take pictures and saves five different types of your images into your device including the original image.

Faisal Ahmed 3 Jan 23, 2022
Nutrify - take a photo of food and learn about it

Nutrify - take a photo of food and learn about it Work in progress. To make this a thing, we're going to need lots of food images... Start uploading y

Daniel Bourke 93 Dec 30, 2022
Leshycam - Generate Inscryption styled portrait sprites from any image

Leshy's Camera Generate Inscryption styled portrait sprites from any image. Setu

3 Sep 27, 2022
MikuMikuRig是一款集生成控制器,自动导入动画,自动布料为一体的blender插件

Miku_Miku_Rig MikuMikuRig是一款集生成控制器,自动导入动画,自动布料为一体的blender插件。 MikumiKurig is a Blender plugin that can generates rig, automatically imports animations

小威廉伯爵 342 Dec 29, 2022
利用近邻法的弱点实现图片缩小后变成另一张图

这是我一个视频的配套代码。 视频是:利用近邻法的弱点实现图片缩小后变成另一张图 https://www.bilibili.com/video/BV1Lf4y1r7dZ 配套代码中,仅generate.py是核心文件,其余的图片神马的,都是赠品。 这个核心文件利用了近邻法缩放的弱点,可以将图a的像素按

偶尔有点小迷糊 182 Dec 19, 2022
An esoteric visual language that takes image files as input based on a multi-tape turing machine, designed for compatibility with C.

vizh An esoteric visual language that takes image files as input based on a multi-tape turing machine, designed for compatibility with C. Overview Her

Sy Brand 228 Dec 17, 2022
Find target hash collisions for Apple's NeuralHash perceptual hash function.💣

neural-hash-collider Find target hash collisions for Apple's NeuralHash perceptual hash function. For example, starting from a picture of this cat, we

Anish Athalye 630 Jan 01, 2023