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
GPU-accelerated image processing using cupy and CUDA

napari-cupy-image-processing GPU-accelerated image processing using cupy and CUDA This napari plugin was generated with Cookiecutter using with @napar

Robert Haase 16 Oct 26, 2022
Computational Xmas Tree lights!

Computational Xmas Tree This repo contains the code for the computational illumination of a Christmas Tree! It is based on the work by Matt Parker fro

GSD6338 146 Dec 23, 2022
This is an app that allows users to upload photos and display and store the photos in a file until the user deletes them.

Qt Photo App This is an app that allows users to upload photos and display and store the photos in a file until the user deletes them. Setup python3 -

Kathy Yang 5 Jan 22, 2022
Open source software for image correlation, distance and analysis

Douglas-Quaid Project Open source software for image correlation, distance and analysis. Strongly related to : Carl-Hauser Problem statement (@CIRCL)

Dominik Dancs 2 May 01, 2022
Image enhancing model for making a blurred image to be somehow clearer than before

This is a very small prject which helps in enhancing the images by taking a Input images. This project has many features like detcting the faces and enhaning the faces itself and also a feature which

3 Dec 03, 2021
Demo of using Auto Encoder for Image Denoising

Demo of using Auto Encoder for Image Denoising

2 Aug 04, 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
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
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
Py3D - A 3d rendering engine written entirely in python

Py3D is a 3d rendering engine written entirely in python. It is a simple and eas

1up Community 2 Nov 14, 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
Convert Image to ASCII Art

Convert Image to ASCII Art Persiapan aplikasi ini menggunakan bahasa python dan beberapa package python. oleh karena itu harus menginstall python dan

Huda Damar 48 Dec 20, 2022
Detecting haze image with hazer.

hazer-py Detecting haze image with hazer. What is hazer Hazer is a lib for getting "haze degree". This repository is python version of hazer: https://

Joey777210 2 Dec 27, 2021
💯 Watermark your images with one line of command

Watermarker 💯 Watermark your images with one line of command 🧐 $ pip3 install

Orhan Emre Dikicigil 3 May 01, 2022
Anime2Gif - an algorithm that detects scenes in a video and generates gifs from it

Anime2Gif Anime2Gif is an algorithm that detects scenes in a video and generates gifs from it. How to use To use it, first, you'll need to install it'

1 Dec 09, 2021
HCaptcha solver using requests and an image recognition package!

HCaptcha solver using requests and an image recognition package! Report Bug · Request Feature Features Image recognition Requests base

dropout 6 Oct 22, 2021
Combinatorial image generator for generative NFT art.

ImageGen Stitches multiple image layers together into one image. Run usage: stitch.py [-h] backgrounds_dir dinos_dir traits_dir texture_file

Dinosols NFT 19 Sep 16, 2022
Plots the graph of a function with ASCII characters.

ASCII Graph Plotter Plots the graph of a function with ASCII characters. See the change log here. Developed by InformaticFreak (c) 2021 How to use py

InformaticFreak 2 Apr 29, 2022
reversable image censoring tool

StupidCensor a REVERSABLE image censoring tool to reversably mosiac censor jpeg files to temporarily remove image details not allowed on most websites

2 Jan 28, 2022
Simple to use image handler for python sqlite3.

SQLite Image Handler Simple to use image handler for python sqlite3. Functions Function Name Parameters Returns init databasePath : str tableName : st

Mustafa Ozan Çetin 7 Sep 16, 2022