bonjorno7/3dn-bip

A Python library for Blender addons. Blazingly fast preview loads in Blender. Images of arbitrary size. bpy.utils.previews drop-in replacement.

Please note that we’re no longer actively maintaining the library ourselves. If anyone is interested in assuming ownership of the project, feel free to reach out. We’re aware that the library is an essential component of multiple Blender addons, so we trust it will remain in good hands.

3D Ninjas | Blender Image Preview (BIP) Library

Documentation

1. Getting Started (this page)
2. Install Pillow
3. Reference
4. More
5. Development

What is 3DN BIP?

3DN BIP or 3D Ninjas Blender Image Preview is a library, which allows blazingly fast preview image loads in Blender. Furthermore, it can load preview images of arbitrary size. It operates as an bpy.utils.previews drop-in replacement and does all the heavy lifting for you.

Our library enables the following major use cases:

1. Load preview images shipped as BIP images blazingly fast. We recommend this approach in case you can generate the images beforehand. In this case, your users don't need to take any action to enjoy the speed boost.
2. Load regular JPEG or PNG preview images blazingly fast. Recommended in case you need to load images provided by the user or by external software tools. For that, we need Pillow on the user's system. It would be best if you use our prepared InstallPillow operator so that your users can enjoy the speed boost with a simple click.

Notes:

1. Our library will always fall back to bpy.utils.previews if unsupported formats are to be loaded. For this reason, there is absolutely no disadvantage in using this library. In the worst case, we will apply the standard mechanism of Blender.
2. .bip is a highly optimized image format, which can be transferred to Blender's internal data structures immediately. It is always blazingly fast, whether Pillow is installed or not.

Examples

Download the following sample addons. You can easily install the ZIP files in Blender via the addon preferences tab.

• Getting Started: t3dn_bip_getting_started.zip
• Showcase: t3dn_bip_showcase.zip

Library

The latest release of the library can be downloaded here: t3dn_bip.zip

Just extract the zip file and copy the folder into your addon. Take a closer look at the examples given above to learn how to use the library.

In case you want to install the library via PyPI, you can use the following command:

python -m pip install t3dn-bip

Converter

The converter is provided via PyPI. Use the following command for the installation:

python -m pip install t3dn-bip-converter

Use the following command to convert images of various formats into the BIP format:

python -m t3dn_bip_converter source_file.png destination_file.bip

Who is using 3DN BIP?

3DN BIP is a new library and is currently being integrated into various addons. The following addons have already been released with 3DN BIP.

KIT OPS

3dn-bip's Issues

Add function to export render result to BIP (t3dn-bip)

See:

• https://gist.github.com/iyadahmed/7cad21bbf286337604517fad8b17d157
• https://blenderartists.org/t/blazingly-fast-preview-loads-images-of-arbitrary-size-bpy-utils-previews-drop-in-replacement/1303349/15?u=core-process

Videos linked in readme are no longer available

The showcase videos linked in the readme are not available on youtube anymore: https://github.com/3dninjas/3dn-bip#showcases

Background scene

Would be pretty cool if this could be animated. Things could be a lot cleaner. Even being able to stack scenes up on top of each other would be super great if it actually helps with Blender memory issues. If it does this means user could have larger scenes without bumping into larger problems.

blender_oCDj8m5ZR2.mp4

Would like to know why its so blazing fast

Bumped into an addon using this type and was curious about it. I read the intro of the repo and was wonder why its so blazing fast. Why would it for example load jpg or png faster then blender vanilla does

Can't install 3DN BIP!!! Blender crash when try to install! Linux OS

I use addon Brush Manager (https://github.com/tingjoybits/Brush_Manager) I try to install 3DN BIP with Install Pillow button and it work in Window but when I try this button in Linux, my blender crash!
I attached blender console crash and blender crash file for more information! Thank you!
blender.crash.txt

template_icon_view doesn't display icon names correctly when using bip.

When using bip to load previews, the labels in layout.template_icon_view(show_labels=True) display very incorrectly:

Here, the icons' names should just display their index:

for index, path in enumerate(img_paths):
    name = path.name
    icon = pcoll.load_safe(name, str(path), "IMAGE")
    _at_tree_previews.append((name, str(index), name, icon.icon_id, index))

where _at_tree_previews is the return value of the EnumProperty items callback

I also tried this on the example addon provided, and the same problem occurred.
To reproduce this, just set show_labels=True in the template_icon_view method in the example addon

I'm not 100% sure this is caused by bip, but I couldn't replicate it by using the normal bpy.utils.previews method. (Also, just as a side note, otherwise, this is amazing, and it solves a problem I've had for a while with the default blender previews :)

Any plan to support exr/hdr ?

I found it load exr/hdr a little faseter, but still slow