Welcome to xiuminglib’s documentation!

xiuminglib includes daily classes and functions that are useful for my computer vision/graphics research. Noteworthily, it contains many useful functions for 3D modeling and rendering with Blender.

The source code is available in the repo. For issues or questions, please open an issue there.

Installation

Simply clone the repo and add it to your PYTHONPATH:

cd <your_local_dir>
git clone https://github.com/xiumingzhang/xiuminglib.git
export PYTHONPATH="<your_local_dir>/xiuminglib/":"$PYTHONPATH"

The library is being developed and tested with Python 3.6.3.

Dependencies

Besides super standard packages (like NumPy), you need:

SciPy

If you use conda, it’s as easy as conda install scipy.

OpenCV 3.3.0

Do conda install -c conda-forge opencv=3.3.0. If any lib*.so* is missing at runtime, the easiest fix is to conda install the missing library to the same environment, maybe followed by some symlinking (like linking libjasper.so to libjasper.so.1) inside <anaconda_dir>/envs/<env_name>/lib. This is cleaner and easier than apt-get, which may break other things and usually requires sudo.

Matplotlib 2.0.2

Some functions are known to be buggy with 3.0.0. If you use conda, do conda install -c conda-forge matplotlib=2.0.2.

Depending on what functions you want to use, you may also need to install:

Blender 2.79

Note this is different from installing Blender as an application, which has Python bundled. Rather, this is installing Blender as a Python module: you’ve succeeded if you find bpy.so in the build’s bin folder and can import bpy in your Python (not the Blender-bundled Python) after you add it to your PYTHONPATH.

Ubuntu

I did this “the hard way”: first building all dependencies from source manually, and then building Blender from source with -DWITH_PYTHON_MODULE=ON for CMake, primarily because I wanted to build to an NFS location so that a cluster of machines on the NFS can all use the build.

If you only need Blender on a local machine, for which you can sudo, then dependency installations are almost automatic – just run install_deps.sh, although when I did this, I had to skip-osl to complete the run, for some reason I didn’t take time to find out.

Blender 2.80 made some API changes that are incompatible with this library, so please make sure after git clone, you check out the correct tag with git checkout v2.79b, followed by git submodule update to ensure the submodules are of the correct versions.

If import bpy throws Segmentation fault, try again with Python 3.6.3.

macOS

This instruction wasn’t very helpful, so below documents each step I took to finally get it working (though with some non-fatal warnings).

First, install Xcode 9.4 to build against the old libstdc++ (instead of Xcode 10+ that forces the use of the newer libc++). Then, brew install CMake.

Install Python Framework 3.6.3. I tried to use an Anaconda Python, but to no avail.

Clone the Blender repo., check out v2.79b, and make sure submodules are consistent.

mkdir ~/blender-git && cd ~/blender-git
git clone https://git.blender.org/blender.git && cd blender
git checkout v2.79b # may also work: git reset --hard v2.79b
git submodule update --init --recursive
git submodule foreach git checkout master
git submodule foreach git pull --rebase origin master

Download the pre-built libraries, and move them to the correct place.

cd ~/blender-git
svn export https://svn.blender.org/svnroot/bf-blender/tags/blender-2.79-release/lib/darwin-9.x.universal/
mkdir lib && mv darwin-9.x.universal lib/

Edit ~/blender-git/blender/build_files/cmake/platform/platform_apple.cmake to replace set(PYTHON_VERSION 3.5) with set(PYTHON_VERSION 3.6).

Make bpy.so by running cd ~/blender-git/blender && make bpy. You may also need cd ~/blender-git/build_darwin_bpy && make install. Upon success, bpy.so is in ~/blender-git/build_darwin_bpy/bin/, and so is 2.79/.

For scripts/modules to be found during import, do

mkdir ~/blender-git/build_darwin_bpy/Resources
cp -r ~/blender-git/build_darwin_bpy/bin/2.79 ~/blender-git/build_darwin_bpy/Resources/

Add the bin folder to PYTHONPATH with export PYTHONPATH="~/blender-git/build_darwin_bpy/bin/":"$PYTHONPATH".

Verify your success with

/Library/Frameworks/Python.framework/Versions/3.6/bin/python3.6 \
    -c 'import bpy; bpy.ops.render.render(write_still=True)'

but expect the aforementioned “non-fatal warnings”:

Traceback (most recent call last):
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/modules/addon_utils.py", line 331, in enable
    mod = __import__(module_name)
ModuleNotFoundError: No module named 'io_scene_3ds'
Traceback (most recent call last):
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/modules/addon_utils.py", line 331, in enable
    mod = __import__(module_name)
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/addons/io_scene_fbx/__init__.py", line 52, in <module>
    from bpy_extras.io_utils import (
ImportError: cannot import name 'orientation_helper'
Traceback (most recent call last):
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/modules/addon_utils.py", line 331, in enable
    mod = __import__(module_name)
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/addons/io_anim_bvh/__init__.py", line 49, in <module>
    from bpy_extras.io_utils import (
ImportError: cannot import name 'orientation_helper'
Traceback (most recent call last):
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/modules/addon_utils.py", line 331, in enable
    mod = __import__(module_name)
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/addons/io_mesh_ply/__init__.py", line 56, in <module>
    from bpy_extras.io_utils import (
ImportError: cannot import name 'orientation_helper'
Traceback (most recent call last):
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/modules/addon_utils.py", line 331, in enable
    mod = __import__(module_name)
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/addons/io_scene_obj/__init__.py", line 48, in <module>
    from bpy_extras.io_utils import (
ImportError: cannot import name 'orientation_helper'
Traceback (most recent call last):
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/modules/addon_utils.py", line 331, in enable
    mod = __import__(module_name)
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/addons/io_scene_x3d/__init__.py", line 48, in <module>
    from bpy_extras.io_utils import (
ImportError: cannot import name 'orientation_helper'
Traceback (most recent call last):
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/modules/addon_utils.py", line 331, in enable
    mod = __import__(module_name)
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/addons/io_mesh_stl/__init__.py", line 66, in <module>
    from bpy_extras.io_utils import (
ImportError: cannot import name 'orientation_helper'
Exception in module register(): '/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/addons/io_curve_svg/__init__.py'
Traceback (most recent call last):
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/modules/addon_utils.py", line 350, in enable
    mod.register()
  File "/Users/xiuming/blender-git/build_darwin_bpy/Resources/2.79/scripts/addons/io_curve_svg/__init__.py", line 70, in register
    bpy.types.TOPBAR_MT_file_import.append(menu_func_import)
AttributeError: 'RNA_Types' object has no attribute 'TOPBAR_MT_file_import'
Trimesh

See their installation guide.

OpenEXR

pip install OpenEXR worked for me, but conda install -c conda-forge openexr didn’t. You may need to install sudo apt-get install libopenexr-dev first if you don’t have it yet.

The library uses “on-demand” imports whenever possible, so that it won’t fail on imports that you don’t need.

Indices and tables