Page MenuHome

Signifcant Refactor for the Images as Planes Addon

Authored by Ted Schundler (tschundler) on Sep 17 2016, 5:48 AM.



I was running into some annoyances with the Images as Planes Add-on during use for compositing. I noticed there was some existing work on enhancements that all seem to have dead-ended:

I re-implemented all of those features as well as some others, as well as stripping some less useful functionality. Full change set:

  • Internally renamed "align" to "offset" and added support for offsetting the created planes in any major local axis. Defaults to X+, but allows Z+/-, which is very useful using blender for compositing
    • in code: offset_planes
  • Changed offset distance input to be in whatever units are configured (BU, meters, feet, etc)
  • Ability to size relative to the camera view (handy for importing layers to composite)
    • in code: compute_camera_size + compute_plane_size
    • When setting the size to be relative to camera, if z-stacked, images will be aligned within the camera's view
      • in code: center_in_camera
    • If not z-stacked, it will center the images in the axis not used for stacking. (i.e. x-aligned images are centered on the camera's Y axis for convenient panning)
  • Ability to set the orientation of the created planes
    • in code: align_plane
    • Defaults to whatever major axis would make the plane face the camera. (a minor time saver importing trees and such)
    • Allows to align to camera (useful for "billboard" sprites and compositing)
    • Supports any major axis
    • Ability to set a constraint for tracking to the camera (matching rotation) for "billboard" type sprites
  • Support for image sequences, not just movies (very handy when compositing to not need to convert sequences to a video file)
    • in code: load_images + find_image_sequences (I feel there must be a better way to do that) + apply_texture_options
  • Added a work-around movie length bug. (the field needs to be read twice to give a valid value)
    • in code: load_images + apply_texture_options
  • Always match movie length (why would you not want that?)
  • Alpha is enabled by default (if image has no alpha channel, it will do nothing), but it can be turned off. So it will behave as expected without touching it.
  • Automatic setting of sensible alpha setting for Blender Internal (no need to manually set Z Transparency separately since "Mask" and "Raytrace" are not useful in this context)
    • in code: apply_material_options
  • New "Shadeless" shader for cycles that will now up in reflections and refractions but not emit light to diffuse surfaces. (Useful for adding trees and such that should cast shadows but not be impacted by light)
    • in code: get_shadeless_node + create_cycles_material
    • I am considering another option for an emission + addition shader for vfx like muzzle flares, but I'm worried that might be adding features that are too single-purpose. Thoughts?
  • Unified material settings so the interface and behavior is identical in Cycles vs Blender Internal
  • Adjusted UI to new settings, regrouping related functionality and splitting draw functions for each box
  • Don't abort on unknown rendering engine, just warn the user. (Now it works fine when making things for Blend4Web)
  • Option to set up Compositing nodes using drivers and the "Corner Pin" node to inject into compositing
    • in code: setup_compositing + find_plane_corner driver
    • This allows translating the planes for compositing without rendering the image at all (often with compositing, the composited element needs special mix nodes and would need to be split out with an idmask and re-rendered on frame change)
    • Personally this is handy for motion tracked cases where the plane track doesn't make sense because I'm injecting something not flat on a surface (muzzle flare, explosion, blood spurt, etc)
    • The corner pin node has no easy way to be driven by empties or similar, so this uses drivers
    • this required some hacks to make things update properly, especially when not using new deps graph - it watches the scenes for changes
      • in code: check_drivers + register_watched_object + register_driver
    • This mostly relies on object names to get an object's data, but in Blender 2.78, the object name is fed by a driver variable, so renaming the object won't break the corner pin
  • Ability to save presets (with new options and a few common work flows for modeling vs compositing, it's handy)
  • The plugin uses a new operator now: import_image.to_plane_v2. There is an operator with the old name import_image.to_plane that translates it's configuration to the new one. I tested it to make sure it doesn't break these add-ons:
  • Fixes a bug someone found on stack exchange: by changing the extension mode to clip instead of repeat
    • in code: apply_texture_options
  • removed extension selection - it didn't work in 2.77 / 2.78 and it duplicates functionality already in blender's file filters
  • pep8 updates (it was close already)

See also:

Diff Detail

Event Timeline

Ted Schundler (tschundler) retitled this revision from to Signifcant Refactor for the Images as Planes Addon.
Ted Schundler (tschundler) updated this object.

Moving things around seems I lost this

Good patch with really useful additions.
It would be good to have an option to set the image plane's origin at the bottom of the image. For trees, people, etc... it's useful to put them on the ground and be able to scale them without them going underground.
An option to add them to a group of the same name as the image/mesh would also allow quick instancing through dupligroups.
I hope this patch gets reviewed and committed quickly :)

This looks like a really nice update. Well written and good cleanups.
I haven't checked everything but if there are no known problems i would vote to accept this update asap :)

Maybe it would be time to split this into more files now?

Is really is long for one file. I think I saw some other rather large single file add-ons, and so I left it as one. I will split it up if you would prefer it that way - I think it would be easier to read in smaller parts.

Brendon Murphy (meta-androcto) edited edge metadata.

I'm ok with this also.

This revision is now accepted and ready to land.Oct 23 2016, 12:16 AM

It would be good to have an option to set the image plane's origin at the bottom of the image. For trees, people, etc... it's useful to put them on the ground and be able to scale them without them going underground.

I agree: top; centre; bottom