Object(ID)

Basic Object Operations Example

This script demonstrates basic operations on object like creating new object, placing it into a view layer, selecting it and making it active.

import bpy

view_layer = bpy.context.view_layer

# Create new light data-block.
light_data = bpy.data.lights.new(name="New Light", type='POINT')

# Create new object with our light data-block.
light_object = bpy.data.objects.new(name="New Light", object_data=light_data)

# Link light object to the active collection of current view layer,
# so that it'll appear in the current scene.
view_layer.active_layer_collection.collection.objects.link(light_object)

# Place light to a specified location.
light_object.location = (5.0, 5.0, 5.0)

# And finally select it and make it active.
light_object.select_set(True)
view_layer.objects.active = light_object

base classes — bpy_struct, ID

class bpy.types.Object(ID)

Object data-block defining an object in a scene

active_material

Active material being displayed

Type:

Material

active_material_index

Index of active material slot (in [0, inf], default 0)

Type:

int

active_selection_set

Index of the currently active selection set (in [-inf, inf], default 0)

Type:

int

active_shape_key

Current shape key (readonly)

Type:

ShapeKey

active_shape_key_index

Current shape key index (in [-32768, 32767], default 0)

Type:

int

add_rest_position_attribute

Add a “rest_position” attribute that is a copy of the position attribute before shape keys and modifiers are evaluated (default False)

Type:

bool

animation_data

Animation data for this data-block (readonly)

Type:

AnimData

animation_visualization

Animation data for this data-block (readonly, never None)

Type:

AnimViz

bgelogic_treelist

(default None, readonly)

Type:

bpy_prop_collection[LogicNodeTreeReference]

bound_box

Object’s bounding box in object-space coordinates, all values are -1.0 when not available (multi-dimensional array of 8 * 3 items, in [-inf, inf], default ((0.0, 0.0, 0.0), (0.0, 0.0, 0.0), (0.0, 0.0, 0.0), (0.0, 0.0, 0.0), (0.0, 0.0, 0.0), (0.0, 0.0, 0.0), (0.0, 0.0, 0.0), (0.0, 0.0, 0.0)), readonly)

Type:

bpy_prop_array[float]

collision

Settings for using the object as a collider in physics simulation (readonly)

Type:

CollisionSettings

color

Object color and alpha, used when the Object Color mode is enabled (array of 4 items, in [0, inf], default (1.0, 1.0, 1.0, 1.0))

Type:

bpy_prop_array[float]

constraints

Constraints affecting the transformation of the object (default None, readonly)

Type:

ObjectConstraints[Constraint]

data

Object data

Type:

ID

delta_location

Extra translation added to the location of the object (array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0))

Type:

mathutils.Vector

delta_rotation_euler

Extra rotation added to the rotation of the object (when using Euler rotations) (array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0))

Type:

mathutils.Euler

delta_rotation_quaternion

Extra rotation added to the rotation of the object (when using Quaternion rotations) (array of 4 items, in [-inf, inf], default (1.0, 0.0, 0.0, 0.0))

Type:

mathutils.Quaternion

delta_scale

Extra scaling added to the scale of the object (array of 3 items, in [-inf, inf], default (1.0, 1.0, 1.0))

Type:

mathutils.Vector

dimensions

Absolute bounding box dimensions of the object. Warning: Assigning to it or its members multiple consecutive times will not work correctly, as this needs up-to-date evaluated data

(array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0))

Type:

mathutils.Vector

display

Object display settings for 3D viewport (readonly, never None)

Type:

ObjectDisplay

display_bounds_type

Object boundary display type (default 'BOX')

• BOX Box – Display bounds as box.

• SPHERE Sphere – Display bounds as sphere.

• CYLINDER Cylinder – Display bounds as cylinder.

• CONE Cone – Display bounds as cone.

• CAPSULE Capsule – Display bounds as capsule.

Type:

Literal[‘BOX’, ‘SPHERE’, ‘CYLINDER’, ‘CONE’, ‘CAPSULE’]

display_type

How to display object in viewport (default 'TEXTURED')

• BOUNDS Bounds – Display the bounds of the object.

• WIRE Wire – Display the object as a wireframe.

• SOLID Solid – Display the object as a solid (if solid drawing is enabled in the viewport).

• TEXTURED Textured – Display the object with textures (if textures are enabled in the viewport).

Type:

Literal[‘BOUNDS’, ‘WIRE’, ‘SOLID’, ‘TEXTURED’]

empty_display_size

Size of display for empties in the viewport (in [0.0001, 1000], default 1.0)

Type:

float

empty_display_type

Viewport display style for empties (default 'PLAIN_AXES')

Type:

Literal[Object Empty Drawtype Items]

empty_image_depth

Determine which other objects will occlude the image (default 'DEFAULT')

Type:

Literal[‘DEFAULT’, ‘FRONT’, ‘BACK’]

empty_image_offset

Origin offset distance (array of 2 items, in [-inf, inf], default (-0.5, -0.5))

Type:

bpy_prop_array[float]

empty_image_side

Show front/back side (default 'DOUBLE_SIDED')

Type:

Literal[‘DOUBLE_SIDED’, ‘FRONT’, ‘BACK’]

field

Settings for using the object as a field in physics simulation (readonly)

Type:

FieldSettings

game

Game engine related settings for the object (readonly, never None)

Type:

GameObjectSettings

hide_probe_plane

Globally disable in planar light probes (default False)

Type:

bool

hide_probe_sphere

Globally disable in spherical light probes (default False)

Type:

bool

hide_probe_volume

Globally disable in volume probes (default False)

Type:

bool

hide_render

Globally disable in renders (default False)

Type:

bool

hide_select

Disable selection in viewport (default False)

Type:

bool

hide_surface_pick

Disable surface influence during selection, snapping and depth-picking operators. Usually used to avoid semi-transparent objects to affect scene navigation (default False)

Type:

bool

hide_viewport

Globally disable in viewports (default False)

Type:

bool

image_user

Parameters defining which layer, pass and frame of the image is displayed (readonly, never None)

Type:

ImageUser

instance_collection

Instance an existing collection

Type:

Collection

instance_faces_scale

Scale the face instance objects (in [0.001, 10000], default 1.0)

Type:

float

instance_type

If not None, object instancing method to use (default 'NONE')

• NONE None.

• VERTS Vertices – Instantiate child objects on all vertices.

• FACES Faces – Instantiate child objects on all faces.

• COLLECTION Collection – Enable collection instancing.

Type:

Literal[‘NONE’, ‘VERTS’, ‘FACES’, ‘COLLECTION’]

is_from_instancer

Object comes from a instancer (default False, readonly)

Type:

bool

is_from_set

Object comes from a background set (default False, readonly)

Type:

bool

is_holdout

Render objects as a holdout or matte, creating a hole in the image with zero alpha, to fill out in compositing with real footage or another render (default False)

Type:

bool

is_instancer

(default False, readonly)

Type:

bool

is_shadow_catcher

Only render shadows and reflections on this object, for compositing renders into real footage. Objects with this setting are considered to already exist in the footage, objects without it are synthetic objects being composited into it. (default False)

Type:

bool

light_linking

Light linking settings (readonly, never None)

Type:

ObjectLightLinking

lightgroup

Lightgroup that the object belongs to (default “”, never None)

Type:

str

lineart

Line Art settings for the object (readonly)

Type:

ObjectLineArt

location

Location of the object (array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0))

Type:

mathutils.Vector

lock_location

Lock editing of location when transforming (array of 3 items, default (False, False, False))

Type:

bpy_prop_array[bool]

lock_rotation

Lock editing of rotation when transforming (array of 3 items, default (False, False, False))

Type:

bpy_prop_array[bool]

lock_rotation_w

Lock editing of ‘angle’ component of four-component rotations when transforming (default False)

Type:

bool

lock_rotations_4d

Lock editing of four component rotations by components (instead of as Eulers) (default True)

Type:

bool

lock_scale

Lock editing of scale when transforming (array of 3 items, default (False, False, False))

Type:

bpy_prop_array[bool]

lod_factor

The factor applied to distance computed in Lod (in [0, inf], default 1.0)

Type:

float

lod_levels

A collection of detail levels to automatically switch between (default None, readonly)

Type:

bpy_prop_collection[LodLevel]

logic_trees

(default None, readonly)

Type:

bpy_prop_collection[LogicNodeTreeReference]

material_slots

Material slots in the object (default None, readonly)

Type:

bpy_prop_collection[MaterialSlot]

matrix_basis

Matrix access to location, rotation and scale (including deltas), before constraints and parenting are applied (multi-dimensional array of 4 * 4 items, in [-inf, inf], default ((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0)))

Type:

mathutils.Matrix

matrix_local

Parent relative transformation matrix. Warning: Only takes into account object parenting, so e.g. in case of bone parenting you get a matrix relative to the Armature object, not to the actual parent bone

(multi-dimensional array of 4 * 4 items, in [-inf, inf], default ((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0)))

Type:

mathutils.Matrix

matrix_parent_inverse

Inverse of object’s parent matrix at time of parenting (multi-dimensional array of 4 * 4 items, in [-inf, inf], default ((1.0, 0.0, 0.0, 0.0), (0.0, 1.0, 0.0, 0.0), (0.0, 0.0, 1.0, 0.0), (0.0, 0.0, 0.0, 1.0)))

Type:

mathutils.Matrix

matrix_world

Worldspace transformation matrix (multi-dimensional array of 4 * 4 items, in [-inf, inf], default ((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0)))

Type:

mathutils.Matrix

mode

Object interaction mode (default 'OBJECT', readonly)

Type:

Literal[Object Mode Items]

modifiers

Modifiers affecting the geometric data of the object (default None, readonly)

Type:

ObjectModifiers[Modifier]

motion_path

Motion Path for this element (readonly)

Type:

MotionPath

override_game_transform_priority

Override logic transform with depsgraph autotransform (default False)

Type:

bool

parent

Parent object

Type:

Object

parent_bone

Name of parent bone in case of a bone parenting relation (default “”, never None)

Type:

str

parent_type

Type of parent relation (default 'OBJECT')

• OBJECT Object – The object is parented to an object.

• ARMATURE Armature.

• LATTICE Lattice – The object is parented to a lattice.

• VERTEX Vertex – The object is parented to a vertex.

• VERTEX_3 3 Vertices.

• BONE Bone – The object is parented to a bone.

Type:

Literal[‘OBJECT’, ‘ARMATURE’, ‘LATTICE’, ‘VERTEX’, ‘VERTEX_3’, ‘BONE’]

parent_vertices

Indices of vertices in case of a vertex parenting relation (array of 3 items, in [0, inf], default (0, 0, 0))

Type:

bpy_prop_array[int]

particle_systems

Particle systems emitted from the object (default None, readonly)

Type:

ParticleSystems[ParticleSystem]

pass_index

Index number for the “Object Index” render pass (in [0, 32767], default 0)

Type:

int

pose

Current pose for armatures (readonly)

Type:

Pose

reverb_samples

Samples used by this reverb volume. More samples mean a longer reverberation (in [0, 30], default 10)

Type:

int

reverb_volume

Whether this volume will cause sound to reverberate (Range Limit: 50m) (default False)

Type:

bool

rigid_body

Settings for rigid body simulation (readonly)

Type:

RigidBodyObject

rigid_body_constraint

Constraint constraining rigid bodies (readonly)

Type:

RigidBodyConstraint

rotation_axis_angle

Angle of Rotation for Axis-Angle rotation representation (array of 4 items, in [-inf, inf], default (0.0, 0.0, 1.0, 0.0))

Type:

bpy_prop_array[float]

rotation_euler

Rotation in Eulers (array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0))

Type:

mathutils.Euler

rotation_mode

The kind of rotation to apply, values from other rotation modes are not used (default 'XYZ')

Type:

Literal[Object Rotation Mode Items]

rotation_quaternion

Rotation in Quaternions (array of 4 items, in [-inf, inf], default (1.0, 0.0, 0.0, 0.0))

Type:

mathutils.Quaternion

scale

Scaling of the object (array of 3 items, in [-inf, inf], default (1.0, 1.0, 1.0))

Type:

mathutils.Vector

selection_sets

List of groups of bones for easy selection (default None, readonly)

Type:

bpy_prop_collection[SelectionSet]

shader_effects

Effects affecting display of object (default None, readonly)

Type:

ObjectShaderFx[ShaderFx]

shadow_terminator_geometry_offset

Offset rays from the surface to reduce shadow terminator artifact on low poly geometry. Only affects triangles at grazing angles to light (in [0, inf], default 0.1)

Type:

float

shadow_terminator_normal_offset

Offset rays from the surface to reduce shadow terminator artifact on low poly geometry. Only affect triangles that are affected by the geometry offset (in [0, inf], default 0.0)

Type:

float

shadow_terminator_shading_offset

Push the shadow terminator towards the light to hide artifacts on low poly geometry (in [0, inf], default 0.0)

Type:

float

show_all_edges

Display all edges for mesh objects (default False)

Type:

bool

show_axis

Display the object’s origin and axes (default False)

Type:

bool

show_bounds

Display the object’s bounds (default False)

Type:

bool

show_empty_image_only_axis_aligned

Only display the image when it is aligned with the view axis (default False)

Type:

bool

show_empty_image_orthographic

Display image in orthographic mode (default True)

Type:

bool

show_empty_image_perspective

Display image in perspective mode (default True)

Type:

bool

show_in_front

Make the object display in front of others (default False)

Type:

bool

show_instancer_for_render

Make instancer visible when rendering (default True)

Type:

bool

show_instancer_for_viewport

Make instancer visible in the viewport (default True)

Type:

bool

show_name

Display the object’s name (default False)

Type:

bool

show_only_shape_key

Only show the active shape key at full value (default False)

Type:

bool

show_texture_space

Display the object’s texture space (default False)

Type:

bool

show_transparent

Display material transparency in the object (default False)

Type:

bool

show_wire

Display the object’s wireframe over solid shading (default False)

Type:

bool

slow_parent_offset

Delay in the parent relationship (in [-1.04857e+06, 1.04857e+06], default 0.0)

Type:

float

soft_body

Settings for soft body simulation (readonly)

Type:

SoftBodySettings

sound_blocking

The amount of sound blocking caused by this wall. A value of 1 will block all sound (in [0, 1], default 0.05)

Type:

float

sound_occluder

Whether this object will dampen sound (default True)

Type:

bool

track_axis

Axis that points in the ‘forward’ direction (applies to Instance Vertices when Align to Vertex Normal is enabled) (default 'POS_X')

Type:

Literal[Object Axis Items]

type

Type of object (default 'EMPTY', readonly)

Type:

Literal[Object Type Items]

up_axis

Axis that points in the upward direction (applies to Instance Vertices when Align to Vertex Normal is enabled) (default 'X')

Type:

Literal[‘X’, ‘Y’, ‘Z’]

use_camera_lock_parent

View Lock 3D viewport camera transformation affects the object’s parent instead (default False)

Type:

bool

use_dynamic_topology_sculpting

(default False, readonly)

Type:

bool

use_empty_image_alpha

Use alpha blending instead of alpha test (can produce sorting artifacts) (default False)

Type:

bool

use_grease_pencil_lights

Lights affect Grease Pencil object (default True)

Type:

bool

use_instance_faces_scale

Scale instance based on face size (default False)

Type:

bool

use_instance_vertices_rotation

Rotate instance according to vertex normal (default False)

Type:

bool

use_lod_physics

Update LOD physics shape in the same time than render shape (default False)

Type:

bool

use_mesh_mirror_x

Enable mesh symmetry in the X axis (default False)

Type:

bool

use_mesh_mirror_y

Enable mesh symmetry in the Y axis (default False)

Type:

bool

use_mesh_mirror_z

Enable mesh symmetry in the Z axis (default False)

Type:

bool

use_parent_final_indices

Use the final evaluated indices rather than the original mesh indices (default False)

Type:

bool

use_shape_key_edit_mode

Display shape keys in edit mode (for meshes only) (default False)

Type:

bool

use_simulation_cache

Cache frames during simulation nodes playback (default True)

Type:

bool

use_slow_parent

Create a delay in the parent relationship (beware: this isn’t renderfarm safe and may be invalid after jumping around the timeline) (default False)

Type:

bool

vertex_groups

Vertex groups of the object (default None, readonly)

Type:

VertexGroups[VertexGroup]

visible_camera

Object visibility to camera rays (default True)

Type:

bool

visible_diffuse

Object visibility to diffuse rays (default True)

Type:

bool

visible_glossy

Object visibility to glossy rays (default True)

Type:

bool

visible_shadow

Object visibility to shadow rays (default True)

Type:

bool

visible_transmission

Object visibility to transmission rays (default True)

Type:

bool

visible_volume_scatter

Object visibility to volume scattering rays (default True)

Type:

bool

children

All the children of this object.

Type:

tuple[Object, …]

Note

Takes O(len(bpy.data.objects)) time.

(readonly)

children_recursive

A list of all children from this object.

Type:

list[Object]

Note

Takes O(len(bpy.data.objects)) time.

(readonly)

users_collection

The collections this object is in.

Type:

tuple[Collection, …]

Note

Takes O(len(bpy.data.collections) + len(bpy.data.scenes)) time.

(readonly)

users_scene

The scenes this object is in.

Type:

tuple[Scene, …]

Note

Takes O(len(bpy.data.scenes) * len(bpy.data.objects)) time.

(readonly)

select_get(*, view_layer=None)

Test if the object is selected. The selection state is per view layer.

Parameters:

view_layer (ViewLayer) – Use this instead of the active view layer (optional)

Returns:

Object selected

Return type:

bool

select_set(state, *, view_layer=None)

Select or deselect the object. The selection state is per view layer.

Parameters:

• state (bool) – Selection state to define

• view_layer (ViewLayer) – Use this instead of the active view layer (optional)

hide_get(*, view_layer=None)

Test if the object is hidden for viewport editing. This hiding state is per view layer.

Parameters:

view_layer (ViewLayer) – Use this instead of the active view layer (optional)

Returns:

Object hidden

Return type:

bool

hide_set(state, *, view_layer=None)

Hide the object for viewport editing. This hiding state is per view layer.

Parameters:

• state (bool) – Hide state to define

• view_layer (ViewLayer) – Use this instead of the active view layer (optional)

visible_get(*, view_layer=None, viewport=None)

Test if the object is visible in the 3D viewport, taking into account all visibility settings

Parameters:

• view_layer (ViewLayer) – Use this instead of the active view layer (optional)

• viewport (SpaceView3D) – Use this instead of the active 3D viewport (optional)

Returns:

Object visible

Return type:

bool

holdout_get(*, view_layer=None)

Test if object is masked in the view layer

Parameters:

view_layer (ViewLayer) – Use this instead of the active view layer (optional)

Returns:

Object holdout

Return type:

bool

indirect_only_get(*, view_layer=None)

Test if object is set to contribute only indirectly (through shadows and reflections) in the view layer

Parameters:

view_layer (ViewLayer) – Use this instead of the active view layer (optional)

Returns:

Object indirect only

Return type:

bool

local_view_get(viewport)

Get the local view state for this object

Parameters:

viewport (SpaceView3D) – Viewport in local view (never None)

Returns:

Object local view state

Return type:

bool

local_view_set(viewport, state)

Set the local view state for this object

Parameters:

• viewport (SpaceView3D) – Viewport in local view (never None)

• state (bool) – Local view state to define

visible_in_viewport_get(viewport)

Check for local view and local collections for this viewport and object

Parameters:

viewport (SpaceView3D) – Viewport in local collections (never None)

Returns:

Object viewport visibility

Return type:

bool

convert_space(*, pose_bone=None, matrix=((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0)), from_space='WORLD', to_space='WORLD')

Convert (transform) the given matrix from one space to another

Parameters:

• pose_bone (PoseBone) – Bone to use to define spaces (may be None, in which case only the two ‘WORLD’ and ‘LOCAL’ spaces are usable) (optional)

• matrix (mathutils.Matrix) – The matrix to transform (multi-dimensional array of 4 * 4 items, in [-inf, inf], optional)

• from_space (Literal['WORLD', 'POSE', 'LOCAL_WITH_PARENT', 'LOCAL']) –

  The space in which ‘matrix’ is currently (optional)

  • WORLD World Space – The most global space in Blender.

  • POSE Pose Space – The pose space of a bone (its armature’s object space).

  • LOCAL_WITH_PARENT Local With Parent – The rest pose local space of a bone (this matrix includes parent transforms).

  • LOCAL Local Space – The local space of an object/bone.

• to_space (Literal['WORLD', 'POSE', 'LOCAL_WITH_PARENT', 'LOCAL']) –

  The space to which you want to transform ‘matrix’ (optional)

  • WORLD World Space – The most global space in Blender.

  • POSE Pose Space – The pose space of a bone (its armature’s object space).

  • LOCAL_WITH_PARENT Local With Parent – The rest pose local space of a bone (this matrix includes parent transforms).

  • LOCAL Local Space – The local space of an object/bone.

Returns:

The transformed matrix (multi-dimensional array of 4 * 4 items, in [-inf, inf])

Return type:

mathutils.Matrix

calc_matrix_camera(depsgraph, *, x=1, y=1, scale_x=1.0, scale_y=1.0)

Generate the camera projection matrix of this object (mostly useful for Camera and Light types)

Parameters:

• depsgraph (Depsgraph) – Depsgraph to get evaluated data from

• x (int) – Width of the render area (in [0, inf], optional)

• y (int) – Height of the render area (in [0, inf], optional)

• scale_x (float) – Width scaling factor (in [1e-06, inf], optional)

• scale_y (float) – Height scaling factor (in [1e-06, inf], optional)

Returns:

The camera projection matrix (multi-dimensional array of 4 * 4 items, in [-inf, inf])

Return type:

mathutils.Matrix

camera_fit_coords(depsgraph, coordinates)

Compute the coordinate (and scale for ortho cameras) given object should be to ‘see’ all given coordinates

Parameters:

• depsgraph (Depsgraph) – Depsgraph to get evaluated data from

• coordinates (Sequence[float]) – Coordinates to fit in (array of 1 items, in [-inf, inf], never None)

Returns:

co_return, The location to aim to be able to see all given points, mathutils.Vector

scale_return, The ortho scale to aim to be able to see all given points (if relevant), float

Return type:

tuple[mathutils.Vector, float]

crazyspace_eval(depsgraph, scene)

Compute orientation mapping between vertices of an original object and object with shape keys and deforming modifiers applied.The evaluation is to be freed with the crazyspace_eval_free function

Parameters:

• depsgraph (Depsgraph) – Dependency Graph, Evaluated dependency graph

• scene (Scene) – Scene, Scene of the object

crazyspace_displacement_to_deformed(*, vertex_index=0, displacement=(0.0, 0.0, 0.0))

Convert displacement vector from non-deformed object space to deformed object space

Parameters:

• vertex_index (int) – vertex_index, (in [-inf, inf], optional)

• displacement (mathutils.Vector) – displacement, (array of 3 items, in [-inf, inf], optional)

Returns:

displacement_deformed, (array of 3 items, in [-inf, inf])

Return type:

mathutils.Vector

crazyspace_displacement_to_original(*, vertex_index=0, displacement=(0.0, 0.0, 0.0))

Free evaluated state of crazyspace

Parameters:

• vertex_index (int) – vertex_index, (in [-inf, inf], optional)

• displacement (mathutils.Vector) – displacement, (array of 3 items, in [-inf, inf], optional)

Returns:

displacement_original, (array of 3 items, in [-inf, inf])

Return type:

mathutils.Vector

crazyspace_eval_clear()

crazyspace_eval_clear

to_mesh(*, preserve_all_data_layers=False, depsgraph=None)

Create a Mesh data-block from the current state of the object. The object owns the data-block. To force free it use to_mesh_clear(). The result is temporary and cannot be used by objects from the main database.

Parameters:

• preserve_all_data_layers (bool) – Preserve all data layers in the mesh, like UV maps and vertex groups. By default Blender only computes the subset of data layers needed for viewport display and rendering, for better performance. (optional)

• depsgraph (Depsgraph) – Dependency Graph, Evaluated dependency graph which is required when preserve_all_data_layers is true (optional)

Returns:

Mesh created from object

Return type:

Mesh

to_mesh_clear()

Clears mesh data-block created by to_mesh()

to_curve(depsgraph, *, apply_modifiers=False)

Create a Curve data-block from the current state of the object. This only works for curve and text objects. The object owns the data-block. To force free it, use to_curve_clear(). The result is temporary and cannot be used by objects from the main database.

Parameters:

• depsgraph (Depsgraph) – Dependency Graph, Evaluated dependency graph

• apply_modifiers (bool) – Apply the deform modifiers on the control points of the curve. This is only supported for curve objects. (optional)

Returns:

Curve created from object

Return type:

Curve

to_curve_clear()

Clears curve data-block created by to_curve()

find_armature()

Find armature influencing this object as a parent or via a modifier

Returns:

Armature object influencing this object or nullptr

Return type:

Object

shape_key_add(*, name='Key', from_mix=True)

Add shape key to this object

Parameters:

• name (str) – Unique name for the new key-block (optional, never None)

• from_mix (bool) – Create new shape from existing mix of shapes (optional)

Returns:

New shape key-block

Return type:

ShapeKey

shape_key_remove(key)

Remove a Shape Key from this object

Parameters:

key (ShapeKey) – Key-block to be removed (never None)

shape_key_clear()

Remove all Shape Keys from this object

shape_keys_selected()

Return selected shape keys

Returns:

keyblocks

Return type:

bpy_prop_collection[ShapeKey]

ray_cast(origin, direction, *, distance=1.70141e+38, depsgraph=None)

Cast a ray onto evaluated geometry, in object space (using context’s or provided depsgraph to get evaluated mesh if needed)

Parameters:

• origin (mathutils.Vector) – Origin of the ray, in object space (array of 3 items, in [-inf, inf])

• direction (mathutils.Vector) – Direction of the ray, in object space (array of 3 items, in [-inf, inf])

• distance (float) – Maximum distance (in [0, inf], optional)

• depsgraph (Depsgraph) – Depsgraph to use to get evaluated data, when called from original object (only needed if current Context’s depsgraph is not suitable) (optional)

Returns:

result, Whether the ray successfully hit the geometry, bool

location, The hit location of this ray cast, mathutils.Vector

normal, The face normal at the ray cast hit location, mathutils.Vector

index, The face index, -1 when original data isn’t available, int

Return type:

tuple[bool, mathutils.Vector, mathutils.Vector, int]

closest_point_on_mesh(origin, *, distance=1.84467e+19, depsgraph=None)

Find the nearest point on evaluated geometry, in object space (using context’s or provided depsgraph to get evaluated mesh if needed)

Parameters:

• origin (mathutils.Vector) – Point to find closest geometry from (in object space) (array of 3 items, in [-inf, inf])

• distance (float) – Maximum distance (in [0, inf], optional)

• depsgraph (Depsgraph) – Depsgraph to use to get evaluated data, when called from original object (only needed if current Context’s depsgraph is not suitable) (optional)

Returns:

result, Whether closest point on geometry was found, bool

location, The location on the object closest to the point, mathutils.Vector

normal, The face normal at the closest point, mathutils.Vector

index, The face index, -1 when original data isn’t available, int

Return type:

tuple[bool, mathutils.Vector, mathutils.Vector, int]

is_modified(scene, settings)

Determine if this object is modified from the base mesh data

Parameters:

• scene (Scene) – Scene in which to check the object (never None)

• settings (Literal['PREVIEW', 'RENDER']) –

  Modifier settings to apply

  • PREVIEW Preview – Apply modifier preview settings.

  • RENDER Render – Apply modifier render settings.

Returns:

Whether the object is modified

Return type:

bool

is_deform_modified(scene, settings)

Determine if this object is modified by a deformation from the base mesh data

Parameters:

• scene (Scene) – Scene in which to check the object (never None)

• settings (Literal['PREVIEW', 'RENDER']) –

  Modifier settings to apply

  • PREVIEW Preview – Apply modifier preview settings.

  • RENDER Render – Apply modifier render settings.

Returns:

Whether the object is deform-modified

Return type:

bool

update_from_editmode()

Load the objects edit-mode data into the object data

Returns:

Success

Return type:

bool

cache_release()

Release memory used by caches associated with this object. Intended to be used by render engines only.

evaluated_geometry()

Get the evaluated geometry set of this evaluated object. This only works for objects that contain geometry data like meshes and curves but not e.g. cameras.

Returns:

The evaluated geometry.

Return type:

bpy.types.GeometrySet

classmethod bl_rna_get_subclass(id, default=None, /)

Parameters:

• id (str) – The RNA type identifier.

• default (bpy.types.Struct | None) – The value to return when not found.

Returns:

The RNA type or default when not found.

Return type:

bpy.types.Struct

classmethod bl_rna_get_subclass_py(id, default=None, /)

Parameters:

• id (str) – The RNA type identifier.

• default (type | None) – The value to return when not found.

Returns:

The class or default when not found.

Return type:

type

Inherited Properties

bpy_struct.id_data ID.name ID.name_full ID.id_type ID.session_uid ID.is_evaluated ID.original ID.users ID.use_fake_user ID.use_extra_user ID.is_embedded_data

ID.is_linked_packed ID.is_missing ID.is_runtime_data ID.is_editable ID.tag ID.is_library_indirect ID.library ID.library_weak_reference ID.asset_data ID.override_library ID.preview

Inherited Functions

bpy_struct.as_pointer bpy_struct.driver_add bpy_struct.driver_remove bpy_struct.get bpy_struct.id_properties_clear bpy_struct.id_properties_ensure bpy_struct.id_properties_ui bpy_struct.is_property_hidden bpy_struct.is_property_overridable_library bpy_struct.is_property_readonly bpy_struct.is_property_set bpy_struct.items bpy_struct.keyframe_delete bpy_struct.keyframe_insert bpy_struct.keys bpy_struct.path_from_id bpy_struct.path_from_module bpy_struct.path_resolve bpy_struct.pop bpy_struct.property_overridable_library_set bpy_struct.property_unset bpy_struct.rna_ancestors

bpy_struct.type_recast bpy_struct.values ID.bl_system_properties_get ID.rename ID.evaluated_get ID.copy ID.asset_mark ID.asset_clear ID.asset_generate_preview ID.override_create ID.override_hierarchy_create ID.user_clear ID.user_remap ID.make_local ID.user_of_id ID.animation_data_create ID.animation_data_clear ID.update_tag ID.preview_ensure ID.bl_rna_get_subclass ID.bl_rna_get_subclass_py

References

bpy.context.active_object bpy.context.edit_object bpy.context.editable_objects bpy.context.image_paint_object bpy.context.object bpy.context.objects_in_mode bpy.context.objects_in_mode_unique_data bpy.context.particle_edit_object bpy.context.pose_object bpy.context.sculpt_object bpy.context.selectable_objects bpy.context.selected_editable_objects bpy.context.selected_objects bpy.context.vertex_paint_object bpy.context.visible_objects bpy.context.weight_paint_object Action.flip_with_pose ActionConstraint.target ArmatureActuator.secondary_target ArmatureActuator.target ArmatureModifier.object ArrayModifier.curve ArrayModifier.end_cap ArrayModifier.offset_object ArrayModifier.start_cap BlendData.objects BlendDataMeshes.new_from_object BlendDataObjects.new BlendDataObjects.remove BoidRuleAvoid.object BoidRuleFollowLeader.object BoidRuleGoal.object BooleanModifier.object CameraActuator.object CameraDOFSettings.focus_object CastModifier.object ChildOfConstraint.target ClampToConstraint.target Collection.all_objects Collection.objects CollectionActuator.camera CollectionObjects.link CollectionObjects.unlink Constraint.space_object ConstraintTarget.target ConstraintTargetBone.target CopyLocationConstraint.target CopyRotationConstraint.target CopyScaleConstraint.target CopyTransformsConstraint.target Curve.bevel_object Curve.taper_object CurveModifier.object Curves.surface DampedTrackConstraint.target DataTransferModifier.object Depsgraph.objects DepsgraphObjectInstance.instance_object DepsgraphObjectInstance.object DepsgraphObjectInstance.parent DisplaceModifier.texture_coords_object DynamicPaintSurface.output_exists EditObjectActuator.object EditObjectActuator.track_object FieldSettings.source_object FloorConstraint.target FluidDomainSettings.guide_parent FollowPathConstraint.target FollowTrackConstraint.camera FollowTrackConstraint.depth_object GPencilSculptGuide.reference_object GeometryAttributeConstraint.target GeometryNodeInputObject.object GreasePencilArmatureModifier.object GreasePencilArrayModifier.offset_object GreasePencilBuildModifier.object GreasePencilHookModifier.object GreasePencilLatticeModifier.object GreasePencilLayer.parent GreasePencilLineartModifier.light_contour_object GreasePencilLineartModifier.source_camera GreasePencilLineartModifier.source_object GreasePencilMirrorModifier.object GreasePencilOutlineModifier.object GreasePencilShrinkwrapModifier.auxiliary_target GreasePencilShrinkwrapModifier.target GreasePencilTintModifier.object GreasePencilWeightProximityModifier.object HookModifier.object KinematicConstraint.pole_target KinematicConstraint.target LatticeModifier.object LayerObjects.active LayerObjects.selected LimitDistanceConstraint.target LineStyleAlphaModifier_DistanceFromObject.target LineStyleColorModifier_DistanceFromObject.target

LineStyleThicknessModifier_DistanceFromObject.target LockedTrackConstraint.target LodLevel.object LogicNodesGlobalValue.obj_val MaskModifier.armature MeshDeformModifier.object MeshToVolumeModifier.object MirrorModifier.mirror_object NLCameraSocket.default_value NLCameraSocket.value NLGameObjectNameSocket.default_value NLGameObjectNameSocket.value NLGameObjectSocket.default_value NLGameObjectSocket.value NLNavMeshSocket.default_value NLNavMeshSocket.value NLSpeakerSocket.default_value NLSpeakerSocket.value NodeSocketObject.default_value NodeTreeInterfaceSocketObject.default_value NormalEditModifier.target Object.find_armature Object.parent ObjectActuator.reference_object ObjectBase.object ObjectSolverConstraint.camera ParentActuator.object ParticleEdit.object ParticleEdit.shape_object ParticleHairKey.co_object ParticleHairKey.co_object_set ParticleInstanceModifier.object ParticleSettings.instance_object ParticleSettingsTextureSlot.object ParticleSystem.co_hair ParticleSystem.parent ParticleSystem.reactor_target_object ParticleTarget.object PivotConstraint.target PoseBone.custom_shape PropertyActuator.object ProxyObjectProperty.value RenderEngine.bake RenderEngine.camera_model_matrix RenderEngine.camera_override RenderEngine.camera_shift_x RenderEngine.use_spherical_stereo RigidBodyConstraint.object1 RigidBodyConstraint.object2 RigidBodyJointConstraint.child RigidBodyJointConstraint.target RigidBodyWorld.convex_sweep_test BakeSettings.cage_object Scene.camera Scene.objects Scene.ray_cast Scene.uvedit_aspect SceneActuator.camera SceneStrip.scene_camera ScrewModifier.object Sculpt.gravity_object ShaderFxShadow.object ShaderFxSwirl.object ShaderNodeTexCoord.object ShrinkwrapConstraint.target ShrinkwrapModifier.auxiliary_target ShrinkwrapModifier.target SimpleDeformModifier.origin SpaceView3D.camera SpaceView3D.lock_object SplineIKConstraint.target SteeringActuator.navmesh SteeringActuator.target StretchToConstraint.target SurfaceDeformModifier.target TextCurve.follow_curve TimelineMarker.camera ToolSettings.anim_mirror_object ToolSettings.anim_relative_object TrackToConstraint.target TransformConstraint.target UVProjector.object UVWarpModifier.object_from UVWarpModifier.object_to VertexWeightEditModifier.mask_tex_map_object VertexWeightMixModifier.mask_tex_map_object VertexWeightProximityModifier.mask_tex_map_object VertexWeightProximityModifier.target ViewLayer.objects VolumeDisplaceModifier.texture_map_object VolumeToMeshModifier.object WarpModifier.object_from WarpModifier.object_to WarpModifier.texture_coords_object WaveModifier.start_position_object WaveModifier.texture_coords_object XrSessionSettings.base_pose_object