EasyBPY
An easier way to use the Python API for Blender.
How to install it…
Place the easybpy.py module in the ‘modules’ folder of your Blender user preferences. On windows, this will be located in:
C:\Users\USER\AppData\Roaming\Blender Foundation\Blender\{version}\scripts\modules
If any of the folders do not exist, create them! Blender will look for them when you start the program. Please watch the introduction video to see how this works.
from easybpy import * <- Use this line in the text editor or Python console to import the module.
If using EasyBPY in a separate addon, remember to package it inside your addon folder and point to it directly when importing the functions, to prevent conflicts with the user’s installed module:
from . easybpy import * <- Use this line if you are importing inside of a packaged addon.
Where to begin…
Grabbing Objects
active_object() - This will get the actively-selected object (the last one clicked on).
selected_objects() - This will get a list of all selected objects.
Convenience Functions
Lots of functions in EasyBPY have ‘convenience’ alternatives, which are easy to remember and behave like shortcuts to other functions. For example:
ao() - This will call active_object()
so() - This will call selected_objects()
Try some of these other functions for basic object selection:
The select_all_lights() function works for other types as well. Replace the last word with one of the following to select other types of objects:meshes, curves, surfaces, metas, text, hair, point_clouds, volumes, armatures, lattices, empties, grease_pencils, cameras, speakers, light_probes
Argument Context
Many functions in EasyBPY have been designed to accept a range of different types of inputs (arguments) - sometimes they can even accept no arguments and still perform their task, by assuming that you want to perform an action on the active object. Let’s take a look at some examples:
Shading Objects
Duplicating / Instancing Objects
There are a collection of functions to help with duplicating and instancing objects. These functions also have unique behaviors depending on which arguments are provided:
Converting Objects / Curves / Grease Pencil
Be the Master of Primitives
Creating primitives is easy, just describe what you want to make - we threw in a few convenience functions for you as well.
Give them a try!
Mode Selection
You can easily get and set modes on a per-object basis, great for workflow tools.
Visibility
Showing and hiding objects is also very easy to do. The functions ‘hide’ and ‘show’ represent the ‘H’ and ‘Alt+H’ keyboard shortcuts respectively.
As you can see above, you are also able to change the display mode for objects with a simple function. This is equivalent to the settings in the Viewport Display section of the Object Properties in the regular interface.
Transformations
We have a lot of options for transformations in EasyBPY, going beyond the functionality provided by the regular Python API. As well as having multi-context easy to understand functions, there are also functions available for more specific use-cases. Explore the available options below.
Moving Objects
You can either specify an axis using a Vector, or use one of the convenience functions to choose an axis (global or local), and provide a value to move the object by.
Tip: If you don’t provide an object reference, EasyBPY will automatically move the active object!
Rotating Objects
Rotating objects around the global or local axes is also very simple, just describe what you want to do in plain-English words. Remember: you don’t have to provide the ‘object’ argument. If you only provide the degrees, then EasyBPY will automatically perform the action on the actively selected object for you.
Scaling Objects
Just like the translation and rotation functions, scaling can also be easily done in the global or local space, with consideration for multiple argument contexts.
Applying Transforms
The regular Ctrl+A shortcuts are also available to apply / normalize transformation data for an object - namely location, rotation and scale.
Multi-Purpose Functions
There are 3 main multi-purpose functions that are great for getting and setting location, rotation and scale data on objects.
They are, appropriately: location(), rotation() and scale().
Advanced Selection
We’ve also added some functions for getting / selecting objects including certain strings in their name, and filtering by vertex count.
The second argument finding objects by vertex determines the comparison type: GREATER, LESS, EQUAL. They also accept: MORE, FEWER, SAME.
3D Cursor, Pivots and Origins
The 3D cursor, as well as origins and pivot points, are essential features for laying out content in the 3D viewport. We have simplified functions for any of the shortcut actions you can do to move the cursor, objects and origin, as well as set the different pivot point modes.
Collection Management
Being able to effectively manage collections is the key to good organization in Blender. EasyBPY offers a collection of simple commands to help with this.
Modifiers
Modifiers form an important part of Blender’s non-destructive workflows. Add and grab references to them quickly with simple descriptive functions. All you need to do is type ‘add_’ followed by the modifier of choice, then pass the target object as an argument (an optional second argument is the new name of the modifier).
Example:
add_subsurf(object)
See the full list of functions on the GitHub Wiki.
Materials
Just like any other type of data in the blend file, materials can be created and managed through EasyBPY. Combining this with the node functionality outlined below will let you build new materials and node graphs with ease.
Nodes
Nodes can be a bit tricky to understand if you have never used them before. Connecting inputs and outputs will still require an understanding of indexes, but we’ve tried to make the process as simple as possible.
In the following example, you can see a script using EasyBPY, which takes the material on the active object, creates a Texture Input node, connects it to the pre-existing Principled BSDF shader, links the two nodes together, then creates a new image texture in the blend file and assigns it to the texture node.
Textures and Images
Textures and images are two different types of data in Blender, both of them can be created and managed with EasyBPY.
Keyframes and Drivers
For anyone looking to write animation and driver scripts, we have simplified functions to help you add keyframes and drivers to values. The pattern of arguments typically goes: object first, then a string for the data path, then a frame value (for the keyframes). If no frame is provided, then EasyBPY will set the data on the current frame by default.
Object Constraints
Constraints can be added and received from objects using the appropriate functions. See a full list of available functions on the GitHub Wiki page.
Thank you to all of the supporters and Patrons, as well as contributors to the project.
Contributors: JYoshi, 3D_Bubble, Yohello, Charan (Just 3D Things), Pvn31