PyR3.shortcut package

Submodules

PyR3.shortcut.context module

class PyR3.shortcut.context.Objects(iterable=(), /)

Bases: list

As a class, provides set of static functionalities for managing global selection and currently selected and active objects.

As a instance, is a container for objects with possibility to select or deselect object(s) contained inside.

active: Object = None

Currently active object. It can be set to change active object.

static all()

classmethod delete(*ob: Object) → None

Delete object(s) ob. It keeps previously selected object(s) selected.

Parameters

ob (Object) – Object(s) to select

classmethod delete_all() → None

Deletes all selectable objects.

static deselect(*ob: Object)

Deselect given object(s).

Parameters

ob (Object) – object(s) to deselect

static deselect_all()

Deselects all objects available in viewport.

deselect_contained()

Deselects elements contained in this sequence.

classmethod duplicate(*ob: Object) → None

Duplicates object(s)

Parameters

ob (Object) – object(s) to duplicate

static inverse_selection()

only() → Object

Returns only element in sequence.

Raises

ValueError – If sequence is empty or has more than one element.

Returns

Only element from sequence

Return type

Object

static select(*ob: Object)

Select given object(s).

Parameters

ob (Object) – object(s) to select

static select_all()

Selects all objects available in viewport.

select_contained()

Selects elements contained in this sequence.

classmethod select_only(*ob: Object)

Deselects all objects and selects only given one(s).

Parameters

ob (Object) – Object(s) to select

select_only_contained()

Selects only elements contained in this sequence.

selected: Objects[Object]

List of currently selected objects. This property is read-only. Use methods to alter selection.

PyR3.shortcut.context.cleanScene() → None

Deletes current scene and creates new one.

Be aware that for total clean-up you should call wipeScenes() instead, as it destroys ALL scenes, not only current one, as cleanScene() does.

PyR3.shortcut.context.delScene() → None

Deletes currently used scene.

PyR3.shortcut.context.getScene() → Scene

Returns currently used scene.

Returns

Scene

Return type

bpy.types.Scene

PyR3.shortcut.context.listScenes() → List[Scene]

Returns list of existing scenes.

PyR3.shortcut.context.newScene() → None

Creates new Scene object and automatically sets it as currently used one.

PyR3.shortcut.context.setScene(scene: Scene) → None

Sets new scene to use.

Parameters

scene (bpy.types.Scene) – Scene

PyR3.shortcut.context.temporarily_selected(*ob: Object)

For context manager usage, on enter selects only objects passed to constructor, on exit restores selection on previously selected objects.

PyR3.shortcut.context.temporary_scene()

Creates temporary scene and sets it as currently used. After exit, all objects selected in temporary scene are copied into previous scene and previous scene is set as currently used.

Yield

(new, old) scenes

Return type

Tuple[bpy.types.Scene, bpy.types.Scene]

PyR3.shortcut.context.wipeScenes() → None

Destroys all existing ones and creates new empty one.

PyR3.shortcut.edit module

class PyR3.shortcut.edit.Edit(ob: Object, *more: Object, active: Optional[Object] = None)

Bases: object

class for automatic in-out switching Edit mode.

It is meant to be used as context manager with edited object being passed as param to constructor.

BMESH: BMesh = None

class MeshCompList(iterable=(), /)

Bases: list

selected() → MeshCompList

bevel(offset: float = 0.0, profile_type: Union[int, str] = 'SUPERELLIPSE', offset_pct: float = 0.0, segments: int = 1, profile: float = 0.5, affect: Union[int, str] = 'EDGES', clamp_overlap: bool = False, loop_slide: bool = True, mark_seam: bool = False, mark_sharp: bool = False, material: int = -1, harden_normals: bool = False, face_strength_mode: Union[int, str] = 'NONE', miter_outer: Union[int, str] = 'SHARP', miter_inner: Union[int, str] = 'SHARP', spread: float = 0.1, vmesh_method: Union[int, str] = 'ADJ', release_confirm: bool = False)

Cut into selected items at an angle to create bevel or chamfer

Parameters

• offset_type (Union[int, str]) – Width Type, The method for determining the size of the bevel * OFFSET Offset, Amount is offset of new edges from original. * WIDTH Width, Amount is width of new face. * DEPTH Depth, Amount is perpendicular distance from original edge to bevel face. * PERCENT Percent, Amount is percent of adjacent edge length. * ABSOLUTE Absolute, Amount is absolute distance along adjacent edge.

• offset (float) – Width, Bevel amount

• profile_type (Union[int, str]) – Profile Type, The type of shape used to rebuild a beveled section * SUPERELLIPSE Superellipse, The profile can be a concave or convex curve. * CUSTOM Custom, The profile can be any arbitrary path between its endpoints.

• offset_pct (float) – Width Percent, Bevel amount for percentage method

• segments (int) – Segments, Segments for curved edge

• profile (float) – Profile, Controls profile shape (0.5 = round)

• affect (Union[int, str]) – Affect, Affect edges or vertices * VERTICES Vertices, Affect only vertices. * EDGES Edges, Affect only edges.

• clamp_overlap (bool) – Clamp Overlap, Do not allow beveled edges/vertices to overlap each other

• loop_slide (bool) – Loop Slide, Prefer sliding along edges to even widths

• mark_seam (bool) – Mark Seams, Mark Seams along beveled edges

• mark_sharp (bool) – Mark Sharp, Mark beveled edges as sharp

• material (int) – Material Index, Material for bevel faces (-1 means use adjacent faces)

• harden_normals (bool) – Harden Normals, Match normals of new faces to adjacent faces

• face_strength_mode (Union[int, str]) – Face Strength Mode, Whether to set face strength, and which faces to set face strength on * NONE None, Do not set face strength. * NEW New, Set face strength on new faces only. * AFFECTED Affected, Set face strength on new and modified faces only. * ALL All, Set face strength on all faces.

• miter_outer (Union[int, str]) – Outer Miter, Pattern to use for outside of miters * SHARP Sharp, Outside of miter is sharp. * PATCH Patch, Outside of miter is squared-off patch. * ARC Arc, Outside of miter is arc.

• miter_inner (Union[int, str]) – Inner Miter, Pattern to use for inside of miters * SHARP Sharp, Inside of miter is sharp. * ARC Arc, Inside of miter is arc.

• spread (float) – Spread, Amount to spread arcs for arc inner miters

• vmesh_method (Union[int, str]) – Vertex Mesh Method, The method to use to create meshes at intersections * ADJ Grid Fill, Default patterned fill. * CUTOFF Cutoff, A cutoff at each profile’s end before the intersection.

• release_confirm (bool) – Confirm on Release

collapse()

Collapse isolated edge and face regions, merging data such as UV’s and vertex colors. This can collapse edge-rings as well as regions of connected faces into vertices

delete_edges()

Delete selected edges.

delete_faces()

Delete selected faces.

delete_vertices()

Delete selected vertices.

deselect_all()

Deselects whole mesh.

duplicate(mode: int = 1)

Duplicate selected.

edge_face_add()

Add an edge or face to selected

edges() → MeshCompList[BMEdge]

Provides access to edited object bmesh attribute holding reference to list of all edges of edited mesh.

Returns

List of edges.

Return type

MeshCompList[BMEdge]

extrude(use_dissolve_ortho_edges: bool = False, mirror: bool = False)

Extrude region of faces

Parameters

• use_normal_flip (bool) – Flip Normals

• use_dissolve_ortho_edges (bool) – Dissolve Orthogonal Edges

• mirror (bool) – Mirror Editing

extrude_individual_faces(mirror: bool = False)

Extrude individual edges only

Parameters

• use_normal_flip (bool) – Flip Normals

• mirror (bool) – Mirror Editing

extrude_repeat(offset: List[float] = (0.0, 0.0, 0.0), scale_offset: float = 1.0)

Extrude selected vertices, edges or faces repeatedly

Parameters

• steps (int) – Steps

• offset (List[float]) – Offset, Offset vector

• scale_offset (float) – Scale Offset

faces() → MeshCompList[BMFace]

Provides access to edited object bmesh attribute holding reference to list of all faces of edited mesh.

Returns

List of faces.

Return type

MeshCompList[BMFace]

get_selected_vertices() → List[BMVert]

invert_selection()

Invertices selection of mesh components.

static isEditMode()

normals_make_consistent()

Make face and vertex normals point either outside or inside the mesh

Parameters

inside (bool) – Inside

ob: Object

remove_doubles(use_unselected: bool = False, use_sharp_edge_from_normals: bool = False)

Merge vertices based on their proximity

Parameters

• threshold (float) – Merge Distance, Maximum distance between elements to merge

• use_unselected (bool) – Unselected, Merge selected to other unselected vertices

• use_sharp_edge_from_normals (bool) – Sharp Edges, Calculate sharp edges using custom normal data (when available)

select_all()

Selects whole mesh.

select_edges(condition: Callable[[Vector, Vector], bool])

Selects edges, when condition function returns true.

Parameters

condition (Callable[[Vector, Vector], bool]) – Test callable. It will be given edge vertice coordinate as parameter.

select_facing(direction: Vector) → Edit

select_vertices(condition: Callable[[Vector], bool])

Selects vertices, when condition function returns true.

Parameters

condition (Callable[Vector], bool]) – test callable. It will be given vertice coordinate as parameter.

vertices() → MeshCompList[BMVert]

Access to edited object bmesh vertice table.

Returns

Vertices

Return type

MeshCompList[BMVert]

exception PyR3.shortcut.edit.OperationCancelled

Bases: Exception

PyR3.shortcut.edit.manual_set_edit_mode()

PyR3.shortcut.edit.manual_set_object_mode()

PyR3.shortcut.io module

IO module provides import/export functions with ability to recognize file format from filename. It’s limited but handy solution, hence available here. Recognized formats are:

• GLB : glTF Binary (.glb), Exports a single file, with all data packed in binary form.

• GLTF : glTF Embedded (.gltf), Exports a single file, with all data packed in JSON.

• FBX : Autodesk Filmbox (.fbx)

• X3D : Extensible 3D Graphics (.x3d)

• OBJ : Wavefront OBJ (.obj)

• PLY : Polygon File Format / Polygon File Format (.ply)

• STL : STL triangle mesh data (.stl)

• BLEND / BLEND1 : Blender file format (.blend/.blend1) be aware that it causes to overwrite current scene on import.

PyR3.shortcut.io.export_to(filepath: str, **kwargs)

Export all objects into file. Format is determined from file extension. kwargs will be forwarded to bpy method call coresponding to selected format.

Parameters

filepath (str) – _Path to the file to export to.

Raises

KeyError – if format is not recognized.

PyR3.shortcut.io.import_from(filepath: str, **kwargs)

Import data from file. Format is determined from file extension. kwargs will be forwarded to bpy method call coresponding to selected format.

Parameters

filepath (str) – _Path to file to import.

Raises

KeyError – if format is not recognized.

PyR3.shortcut.material module

PyR3.shortcut.material.new_node_material(name: str = 'material')

PyR3.shortcut.material.set_material(ob: Object, material: Material)

PyR3.shortcut.material.update_BSDF_node(material: Material, color: Optional[Tuple[float, float, float, float]] = None, subsurface: Optional[float] = None, subsurfaceRadius: Optional[Tuple[float, float, float]] = None, subsurfaceColor: Optional[Tuple[float, float, float, float]] = None, metallic: Optional[float] = None, specular: Optional[float] = None, specularTint: Optional[float] = None, roughness: Optional[float] = None, anisotropic: Optional[float] = None, anisotropicRotation: Optional[float] = None, sheen: Optional[float] = None, sheenTint: Optional[float] = None, clearcoat: Optional[float] = None, clearcoatRoughness: Optional[float] = None, IOR: Optional[float] = None, transmission: Optional[float] = None, transmissionRoughness: Optional[float] = None, emission: Optional[Tuple[float, float, float, float]] = None, emissionStrength: Optional[float] = None, alpha: Optional[float] = None) → None

Updates default values in Principled BSDF node of material. None params are ignored and doesn’t modify node.

Parameters

• material (bpy.types.Material) – Material to modify.

• color (Color_T, optional) – Diffuse or metal surface color.

• subsurface (float, optional) – Mix between diffuse and subsurface scattering. Rather than being a simple mix between Diffuse and Subsurface Scattering, it acts as a multiplier for the Subsurface Radius.

• subsurfaceRadius (Tuple[float, float, float], optional) – Average distance that light scatters below the surface. Higher radius gives a softer appearance, as light bleeds into shadows and through the object. The scattering distance is specified separately for the RGB channels, to render materials such as skin where red light scatters deeper. The X, Y and Z values are mapped to the R, G and B values, respectively.

• subsurfaceColor (Color_T, optional) – Subsurface scattering base color.

• metallic (float, optional) – Blends between a non-metallic and metallic material model. A value of 1.0 gives a fully specular reflection tinted with the base color, without diffuse reflection or transmission. At 0.0 the material consists of a diffuse or transmissive base layer, with a specular reflection layer on top.

• specular (float, optional) – Amount of dielectric specular reflection. Specifies facing (along normal) reflectivity in the most common 0 - 8% range.

• specularTint (float, optional) – Tints the facing specular reflection using the base color, while glancing reflection remains white.

• roughness (float, optional) – Specifies microfacet roughness of the surface for diffuse and specular reflection.

• anisotropic (float, optional) – Amount of anisotropy for specular reflection. Higher values give elongated highlights along the tangent direction; negative values give highlights shaped perpendicular to the tangent direction.

• anisotropicRotation (float, optional) – Rotates the direction of anisotropy, with 1.0 going full circle.

• sheen (float, optional) – Amount of soft velvet like reflection near edges, for simulating materials such as cloth.

• sheenTint (float, optional) – Mix between white and using base color for sheen reflection.

• clearcoat (float, optional) – Extra white specular layer on top of others. This is useful for materials like car paint and the like.

• clearcoatRoughness (float, optional) – Roughness of clearcoat specular.

• IOR (float, optional) – Index of refraction for transmission.

• transmission (float, optional) – Mix between fully opaque surface at zero and fully glass like transmission at one.

• transmissionRoughness (float, optional) – With GGX distribution controls roughness used for transmitted light.

• emission (Color_T, optional) – Light emission from the surface, like the Emission shader.

• emissionStrength (float, optional) – Strength of the emitted light. A value of 1.0 will ensure that the object in the image has the exact same color as the Emission Color, i.e. make it ‘shadeless’.

• alpha (float, optional) – Controls the transparency of the surface, with 1.0 fully opaque. Usually linked to the Alpha output of an Image Texture node.

PyR3.shortcut.mesh module

Mesh operation shortcuts, including creation, bounding box calculations and more.

PyR3.shortcut.mesh.addCircle(vertices: int = 32, radius: float = 1, fill_type: str | int = 'NOTHING', location: List[float] = (0, 0, 0), rotation: List[float] = (0, 0, 0), scale: List[float] = (0, 0, 0)) → Object

Shortcut for creating circle mesh. It returns created object.

Parameters

• vertices (int, optional) – number of vertices in arc, defaults to 32

• radius (float, optional) – circle radius, defaults to 1

• fill_type (str, optional) – face/no face to fill, defaults to “NOTHING”

• location (List[float], optional) – world location of circle mesh, defaults to (0, 0, 0)

• rotation (List[float], optional) – rotation of a mesh, defaults to (0, 0, 0)

• scale (List[float], optional) – scale of a mesh, defaults to (0, 0, 0)

Returns

newly created Object.

Return type

Object

PyR3.shortcut.mesh.addCone(vertices: int = 32, radius1: float = 1, radius2: float = 0, depth: float = 2, end_fill_type: str | int = 'NGON', location: List[float] = (0, 0, 0), rotation: List[float] = (0, 0, 0), scale: List[float] = (0, 0, 0)) → Object

Shortcut for creating cone. It returns created object.

Parameters

• vertices (int, optional) – number of vertices in arc, defaults to 32

• radius1 (float, optional) – radius 1, defaults to 1

• radius2 (float, optional) – radius 2, defaults to 0

• depth (float, optional) – cone length, defaults to 2

• end_fill_type (str, optional) – face / no face at the end of cone mesh, defaults to “NGON”

• location (List[float], optional) – world location of center of cone, defaults to (0, 0, 0)

• rotation (List[float], optional) – rotation of a mesh, defaults to (0, 0, 0)

• scale (List[float], optional) – scale of a mesh, defaults to (0, 0, 0)

Returns

newly created Object.

Return type

Object

PyR3.shortcut.mesh.addCube(*args, **kwargs)

Shortcut for creating cube. It returns created object.

PyR3.shortcut.mesh.addCylinder(*args, **kwargs)

Shortcut for creating cylinder. It returns created object.

PyR3.shortcut.mesh.addGrid(*args, **kwargs)

Shortcut for creating grid. It returns created object.

PyR3.shortcut.mesh.addIcoSphere(*args, **kwargs)

Shortcut for creating ico sphere. It returns created object.

PyR3.shortcut.mesh.addPlane(*args, **kwargs)

Shortcut for creating plane. It returns created object.

PyR3.shortcut.mesh.addTorus(*args, **kwargs)

Shortcut for creating torus. It returns created object.

PyR3.shortcut.mesh.addUVSphere(*args, **kwargs)

Shortcut for creating uv sphere. It returns created object.

PyR3.shortcut.mesh.boundingBoxCenterPoint(ob: Object) → Vector

Calculates center of bounding box.

Parameters

ob (Object) – Object to calculate for.

Returns

Center point.

Return type

Vector

PyR3.shortcut.mesh.boundingBoxPoints(ob: Object) → float

Calculates object’s bounding box.

Parameters

bpy_obj (Object) – Object to get bbox of.

Returns

List of bounding box points.

Return type

float

PyR3.shortcut.mesh.containingSphereRadius(ob: Object, center: Optional[Vector] = None) → float

Calculate radius of a sphere that bounding box can fit in.

Parameters

• ob (Object) – Object to calculate for

• center (Vector, optional) – Changes center from bbox center, defaults to None

Returns

radius

Return type

float

PyR3.shortcut.mesh.convert(ob: Object, target: str = 'MESH')

Convert object from one type to another.

Parameters

• ob (Object) – Object to transform

• target (str, optional) – target object type, defaults to “MESH”

PyR3.shortcut.mesh.fromPyData(vertexData: List[Tuple[float, float, float]] = [], edgeData: List[Tuple[float, float]] = [], faceData: List[Tuple[float, ...]] = [], *, mesh_name='mesh', object_name='object') → Object

Creates new mesh object from python data.

Parameters

• vertexData (List[Tuple[float, float, float]], optional) – list of vertices, defaults to []

• edgeData (List[Tuple[float, float]], optional) – list of tuples of edges vertices indexes, defaults to []

• faceData (List[Tuple[float, ...]], optional) – list of tuples of faces edge indexes, defaults to []

• mesh_name (str, optional) – name for mesh data object, defaults to “mesh”

• object_name (str, optional) – name for mesh object, defaults to “object”

Returns

created object.

Return type

Object

PyR3.shortcut.mesh.join(target: Object, *rest: Object)

Joins rest objects into target object. This will result in merging meshes into one object’s data.

Parameters

• target (Object) – object to join rest into

• rest (Object) – other objects to join

PyR3.shortcut.modifiers module

class PyR3.shortcut.modifiers.Array(master_object: Object, constant_offset_displace: Tuple[float, float, float] = (0, 0, 0), count: int = 1, use_relative_offset: bool = False, use_constant_offset: bool = True)

Bases: _Modifier

Array modifier wrapper.

For documentation over modifier parameters visit https://docs.blender.org/api/current/bpy.types.ArrayModifier.html

constant_offset_displace: Tuple[float, float, float] = (0, 0, 0)

count: int = 1

master_object: Object

use_constant_offset: bool = True

use_relative_offset: bool = False

class PyR3.shortcut.modifiers.Bevel(master_object: Object, affect: str = 'EDGES', offset_type: str = 'OFFSET', width: float = 0.1, segments: int = 1, limit_method: str = 'NONE', angle_limit: float = 0.5235987755982988, use_clamp_overlap: bool = True)

Bases: _Modifier

Solidify modifier wrapper.

For documentation over modifier parameters visit https://docs.blender.org/api/current/bpy.types.BevelModifier.html

affect: str = 'EDGES'

angle_limit: float = 0.5235987755982988

limit_method: str = 'NONE'

master_object: Object

offset_type: str = 'OFFSET'

segments: int = 1

use_clamp_overlap: bool = True

width: float = 0.1

class PyR3.shortcut.modifiers.Boolean(master_object: Object, object: Object, operation: str = 'DIFFERENCE', solver: str = 'EXACT', use_self: bool = False)

Bases: _Modifier

Boolean Modifier wrapper.

For documentation over modifier parameters visit https://docs.blender.org/api/current/bpy.types.BooleanModifier.html

master_object: Object

object: Object

operation: str = 'DIFFERENCE'

solver: str = 'EXACT'

use_self: bool = False

class PyR3.shortcut.modifiers.Decimate(master_object: Object, angle_limit: float = 0.0872665, decimate_type: str = 'COLLAPSE', delimit: FrozenSet[str] = frozenset({'NORMAL'}), invert_vertex_group: bool = False, iterations: int = 0, ratio: float = 1.0, symmetry_axis: str = 'X', use_collapse_triangulate: bool = False, use_dissolve_boundaries: bool = False, vertex_group: str = '', vertex_group_factor: float = 1.0)

Bases: _Modifier

Decimate modifier wrapper.

For documentation over modifier parameters visit https://docs.blender.org/api/current/bpy.types.DecimateModifier.html

angle_limit: float = 0.0872665

decimate_type: str = 'COLLAPSE'

delimit: FrozenSet[str] = frozenset({'NORMAL'})

invert_vertex_group: bool = False

iterations: int = 0

master_object: Object

ratio: float = 1.0

symmetry_axis: str = 'X'

use_collapse_triangulate: bool = False

use_dissolve_boundaries: bool = False

vertex_group: str = ''

vertex_group_factor: float = 1.0

class PyR3.shortcut.modifiers.Solidify(master_object: Object, thickness: float = 0.01, offset: float = -1, use_even_offset: bool = False, use_quality_normals: bool = True)

Bases: _Modifier

Solidify modifier wrapper.

For documentation over modifier parameters visit https://docs.blender.org/api/current/bpy.types.SolidifyModifier.html

master_object: Object

offset: float = -1

thickness: float = 0.01

use_even_offset: bool = False

use_quality_normals: bool = True

PyR3.shortcut.transform module

class PyR3.shortcut.transform.Transform

Bases: object

This class is a container for set of object transforming functions.

They all operate on global (currently selected) object(s).

static apply(do_move: bool = False, do_rotation: bool = False, do_scale: bool = False)

Apply the object’s transformation to its data.

Parameters

• use_move (bool, optional) – applies move if true, defaults to False

• use_rotation (bool, optional) – applies rotation if true, defaults to False

• use_scale (bool, optional) – applies scale if true, defaults to False

classmethod move(vector: Tuple[float, float, float], **kwargs)

Move selected objects.

Parameters

• vector (Tuple[float, float, float], optional) – absolute coordinates to move to

• **kwargs – All from bpy.ops.transform.translate.

classmethod resize(scales: Tuple[float, float, float], **kwargs)

Scale (resize) selected objects.

Parameters

• scales (tuple, optional) – Tuple of scales for each axis, (x, y, z)

• **kwargs – All from bpy.ops.transform.resize.

classmethod rotate(angle: float, orient_axis: str, **kwargs)

Rotate selected objects around orient_axis

Parameters

• angle (float, optional) – rotation angle

• orient_axis (str, optional) – axis to rotate around, either “X”, “Y” or “Z”.

• **kwargs – All from bpy.ops.transform.rotate.

classmethod scale(scales: Tuple[float, float, float], **kwargs)

Scale (resize) selected objects.

Parameters

• scales (tuple, optional) – Tuple of scales for each axis, (x, y, z)

• **kwargs –

  All from bpy.ops.transform.resize.

Module contents