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
Imutils - A series of convenience functions to make basic image processing operations such as translation, rotation, resizing, skeletonization, and displaying Matplotlib images easier with OpenCV and Python.

imutils A series of convenience functions to make basic image processing functions such as translation, rotation, resizing, skeletonization, and displ

PyImageSearch 4.3k Jan 01, 2023
Paper backup of files using QR codes

Generate paper backups for Linux. Currently command-linux Linux only. Takes any file, and outputs a "paper backup": a printable black-and-white pdf fu

Zachary Vance 27 Dec 28, 2022
Python QR Code image generator

Pure python QR Code generator Generate QR codes. For a standard install (which will include pillow for generating images), run: pip install qrcode[pil

Lincoln Loop 3.5k Dec 31, 2022
The following program is used to swap the faces from two images.

Face-Swapping The following program is used to swap the faces from two images. In today's world deep fake technology has become really popular . As a

1 Jan 19, 2022
Archive of the image generator stuff from my API

alex_api_archive Archive of the image generator stuff from my API FAQ Q: Why? A: Because I am removing these components from the API Q: How do I run i

AlexFlipnote 26 Nov 17, 2022
SGTL - Spectral Graph Theory Library

SGTL - Spectral Graph Theory Library SGTL is a python library of spectral graph theory methods. The library is still very new and so there are many fe

Peter Macgregor 6 Oct 01, 2022
Random collage/montage generator with drop-shadow

Random Collage Example Usage These are the sample input files in $PWD for the below examples: 1.png 2.png 3.png 4.png 5.png 6.png 7.png 8.png 9.png 10

M B 1 Dec 07, 2021
Seeks to remove text from an image in a convincing way.

Text-Removal This is a Computer Vision project that seeks to successfully remove text from an image by covering the text areas in a convincing way. He

6 Nov 22, 2022
3D Reconstruction Software

Meshroom is a free, open-source 3D Reconstruction Software based on the AliceVision Photogrammetric Computer Vision framework. Learn more details abou

AliceVision 8.7k Jan 02, 2023
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
Bot by image recognition simulating (random) human clicks

bbbot22 bot por reconhecimento de imagem simulando cliques humanos (aleatórios) inb4: sim, esse é basicamente o mesmo bot de 2021 porque a Globo não t

Yuri 2 Apr 05, 2022
㊙️ Create standard barcodes with Python. No external dependencies. 100% Organic Python.

python-barcode python-barcode provides a simple way to create barcodes in Python. There are no external dependencies when generating SVG files. Pillow

Hugo Barrera 419 Dec 26, 2022
Javascript image annotation tool based on image segmentation.

JS Segment Annotator Javascript image annotation tool based on image segmentation. Label image regions with mouse. Written in vanilla Javascript, with

Kota Yamaguchi 513 Nov 15, 2022
Demo of using Auto Encoder for Image Denoising

Demo of using Auto Encoder for Image Denoising

2 Aug 04, 2022
Create a 2D mesh for an airfoil in GMSH using python.

GMSHFoil A simple class to create a 2D mesh for an airfoil in GMSH using python. Requirements pip install airfoils

Charilaos Mylonas 1 May 16, 2022
Image generation API.

Image Generator API This is an api im working on Currently its just a test project Im trying to make custom readme images with your discord account pr

Siddhesh Zantye 2 Feb 19, 2022
Tweet2Image - Convert tweets to Instagram-friendly images.

Convert tweets to Instagram-friendly images. How to use If you want to use this repository as a submodule, don't forget to put the fonts d

Janu Lingeswaran 1 Mar 11, 2022
A simple plugin to view APR images in napari

napari-apr-viewer A simple plugin to view APR images in napari This napari plugin was generated with Cookiecutter using @napari's cookiecutter-napari-

5 Jan 24, 2022
A minimal, standalone viewer for 3D animations stored as stop-motion sequences of individual .obj mesh files.

ObjSequenceViewer V0.5 A minimal, standalone viewer for 3D animations stored as stop-motion sequences of individual .obj mesh files. Installation: pip

csmailis 2 Aug 04, 2022
Python Script to generate posters out of the images in directory.

Poster-Maker Python Script to generate posters out of the images in directory. This version is very basic ligthweight code to combine organize images

1 Feb 02, 2022