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 datablock.
light_data = bpy.data.lights.new(name="New Light", type='POINT')

# Create new object with our light datablock.
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

Type: int in [0, inf], default 0

active_shape_key

Current shape key

Type: ShapeKey, (readonly)

active_shape_key_index

Current shape key index

Type: int in [-32768, 32767], default 0

animation_data

Animation data for this data-block

Type: AnimData, (readonly)

animation_visualization

Animation data for this data-block

Type: AnimViz, (readonly, never None)

bound_box

Object’s bounding box in object-space coordinates, all values are -1.0 when not available

Type: float 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)

collision

Settings for using the object as a collider in physics simulation

Type: CollisionSettings, (readonly)

color

Object color and alpha, used when faces have the ObColor mode enabled

Type: float array of 4 items in [0, inf], default (1.0, 1.0, 1.0, 1.0)

constraints

Constraints affecting the transformation of the object

Type: ObjectConstraints bpy_prop_collection of Constraint, (readonly)

cycles

Cycles object settings

Type: CyclesObjectSettings, (readonly)

data

Object data

Type: ID

delta_location

Extra translation added to the location of the object

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

delta_rotation_euler

Extra rotation added to the rotation of the object (when using Euler rotations)

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

delta_rotation_quaternion

Extra rotation added to the rotation of the object (when using Quaternion rotations)

Type: float array of 4 items in [-inf, inf], default (1.0, 0.0, 0.0, 0.0)

delta_scale

Extra scaling added to the scale of the object

Type: float array of 3 items in [-inf, inf], default (1.0, 1.0, 1.0)

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

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

display

Object display settings for 3D viewport

Type: ObjectDisplay, (readonly, never None)

display_bounds_type

Object boundary display type

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: enum in [‘BOX’, ‘SPHERE’, ‘CYLINDER’, ‘CONE’, ‘CAPSULE’], default ‘BOX’

display_type

How to display object in viewport

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: enum in [‘BOUNDS’, ‘WIRE’, ‘SOLID’, ‘TEXTURED’], default ‘TEXTURED’

empty_display_size

Size of display for empties in the viewport

Type: float in [0.0001, 1000], default 1.0

empty_display_type

Viewport display style for empties

Type: enum in [‘PLAIN_AXES’, ‘ARROWS’, ‘SINGLE_ARROW’, ‘CIRCLE’, ‘CUBE’, ‘SPHERE’, ‘CONE’, ‘IMAGE’], default ‘PLAIN_AXES’

empty_image_depth

Determine which other objects will occlude the image

Type: enum in [‘DEFAULT’, ‘FRONT’, ‘BACK’], default ‘DEFAULT’

empty_image_offset

Origin offset distance

Type: float array of 2 items in [-inf, inf], default (-0.5, -0.5)

empty_image_side

Show front/back side

Type: enum in [‘DOUBLE_SIDED’, ‘FRONT’, ‘BACK’], default ‘DOUBLE_SIDED’

face_maps

Maps of faces of the object

Type: FaceMaps bpy_prop_collection of FaceMap, (readonly)

field

Settings for using the object as a field in physics simulation

Type: FieldSettings, (readonly)

grease_pencil_modifiers

Modifiers affecting the data of the grease pencil object

Type: ObjectGpencilModifiers bpy_prop_collection of GpencilModifier, (readonly)

hide_render

Globally disable in renders

Type: boolean, default False

hide_select

Disable selection in viewport

Type: boolean, default False

hide_viewport

Globally disable in viewports

Type: boolean, default False

image_user

Parameters defining which layer, pass and frame of the image is displayed

Type: ImageUser, (readonly, never None)

instance_collection

Instance an existing collection

Type: Collection

instance_faces_scale

Scale the face instance objects

Type: float in [0.001, 10000], default 1.0

instance_type

If not None, object instancing method to use

NONE None.
VERTS Vertices – Instantiate child objects on all vertices.
FACES Faces – Instantiate child objects on all faces.
COLLECTION Collection – Enable collection instancing.

Type: enum in [‘NONE’, ‘VERTS’, ‘FACES’, ‘COLLECTION’], default ‘NONE’

is_from_instancer

Object comes from a instancer

Type: boolean, default False, (readonly)

is_from_set

Object comes from a background set

Type: boolean, default False, (readonly)

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

Type: boolean, default False

is_instancer

Type: boolean, default False, (readonly)

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

Type: boolean, default False

lightgroup

Lightgroup that the object belongs to

Type: string, default “”, (never None)

lineart

Line art settings for the object

Type: ObjectLineArt, (readonly)

location

Location of the object

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

lock_location

Lock editing of location when transforming

Type: boolean array of 3 items, default (False, False, False)

lock_rotation

Lock editing of rotation when transforming

Type: boolean array of 3 items, default (False, False, False)

lock_rotation_w

Lock editing of ‘angle’ component of four-component rotations when transforming

Type: boolean, default False

lock_rotations_4d

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

Type: boolean, default True

lock_scale

Lock editing of scale when transforming

Type: boolean array of 3 items, default (False, False, False)

material_slots

Material slots in the object

Type: bpy_prop_collection of MaterialSlot, (readonly)

matrix_basis

Matrix access to location, rotation and scale (including deltas), before constraints and parenting are applied

Type: float 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))

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

Type: float 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))

matrix_parent_inverse

Inverse of object’s parent matrix at time of parenting

Type: float 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))

matrix_world

Worldspace transformation matrix

Type: float 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))

mode

Object interaction mode

OBJECT Object Mode.
EDIT Edit Mode.
POSE Pose Mode.
SCULPT Sculpt Mode.
VERTEX_PAINT Vertex Paint.
WEIGHT_PAINT Weight Paint.
TEXTURE_PAINT Texture Paint.
PARTICLE_EDIT Particle Edit.
EDIT_GPENCIL Edit Mode – Edit Grease Pencil Strokes.
SCULPT_GPENCIL Sculpt Mode – Sculpt Grease Pencil Strokes.
PAINT_GPENCIL Draw Mode – Paint Grease Pencil Strokes.
WEIGHT_GPENCIL Weight Paint – Grease Pencil Weight Paint Strokes.
VERTEX_GPENCIL Vertex Paint – Grease Pencil Vertex Paint Strokes.
SCULPT_CURVES Sculpt Mode.

Type: enum in [‘OBJECT’, ‘EDIT’, ‘POSE’, ‘SCULPT’, ‘VERTEX_PAINT’, ‘WEIGHT_PAINT’, ‘TEXTURE_PAINT’, ‘PARTICLE_EDIT’, ‘EDIT_GPENCIL’, ‘SCULPT_GPENCIL’, ‘PAINT_GPENCIL’, ‘WEIGHT_GPENCIL’, ‘VERTEX_GPENCIL’, ‘SCULPT_CURVES’], default ‘OBJECT’, (readonly)

modifiers

Modifiers affecting the geometric data of the object

Type: ObjectModifiers bpy_prop_collection of Modifier, (readonly)

motion_path

Motion Path for this element

Type: MotionPath, (readonly)

parent

Parent object

Type: Object

parent_bone

Name of parent bone in case of a bone parenting relation

Type: string, default “”, (never None)

parent_type

Type of parent relation

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: enum in [‘OBJECT’, ‘ARMATURE’, ‘LATTICE’, ‘VERTEX’, ‘VERTEX_3’, ‘BONE’], default ‘OBJECT’

parent_vertices

Indices of vertices in case of a vertex parenting relation

Type: int array of 3 items in [0, inf], default (0, 0, 0)

particle_systems

Particle systems emitted from the object

Type: ParticleSystems bpy_prop_collection of ParticleSystem, (readonly)

pass_index

Index number for the “Object Index” render pass

Type: int in [0, 32767], default 0

pose

Current pose for armatures

Type: Pose, (readonly)

pose_library

Deprecated, will be removed in Blender 3.3. Action used as a pose library for armatures

Type: Action

rigid_body

Settings for rigid body simulation

Type: RigidBodyObject, (readonly)

rigid_body_constraint

Constraint constraining rigid bodies

Type: RigidBodyConstraint, (readonly)

rotation_axis_angle

Angle of Rotation for Axis-Angle rotation representation

Type: float array of 4 items in [-inf, inf], default (0.0, 0.0, 1.0, 0.0)

rotation_euler

Rotation in Eulers

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

rotation_mode

QUATERNION Quaternion (WXYZ) – No Gimbal Lock.
XYZ XYZ Euler – XYZ Rotation Order - prone to Gimbal Lock (default).
XZY XZY Euler – XZY Rotation Order - prone to Gimbal Lock.
YXZ YXZ Euler – YXZ Rotation Order - prone to Gimbal Lock.
YZX YZX Euler – YZX Rotation Order - prone to Gimbal Lock.
ZXY ZXY Euler – ZXY Rotation Order - prone to Gimbal Lock.
ZYX ZYX Euler – ZYX Rotation Order - prone to Gimbal Lock.
AXIS_ANGLE Axis Angle – Axis Angle (W+XYZ), defines a rotation around some axis defined by 3D-Vector.

Type: enum in [‘QUATERNION’, ‘XYZ’, ‘XZY’, ‘YXZ’, ‘YZX’, ‘ZXY’, ‘ZYX’, ‘AXIS_ANGLE’], default ‘XYZ’

rotation_quaternion

Rotation in Quaternions

Type: float array of 4 items in [-inf, inf], default (1.0, 0.0, 0.0, 0.0)

scale

Scaling of the object

Type: float array of 3 items in [-inf, inf], default (1.0, 1.0, 1.0)

shader_effects

Effects affecting display of object

Type: ObjectShaderFx bpy_prop_collection of ShaderFx, (readonly)

show_all_edges

Display all edges for mesh objects

Type: boolean, default False

show_axis

Display the object’s origin and axes

Type: boolean, default False

show_bounds

Display the object’s bounds

Type: boolean, default False

show_empty_image_only_axis_aligned

Only display the image when it is aligned with the view axis

Type: boolean, default False

show_empty_image_orthographic

Display image in orthographic mode

Type: boolean, default False

show_empty_image_perspective

Display image in perspective mode

Type: boolean, default False

show_in_front

Make the object display in front of others

Type: boolean, default False

show_instancer_for_render

Make instancer visible when rendering

Type: boolean, default True

show_instancer_for_viewport

Make instancer visible in the viewport

Type: boolean, default True

show_name

Display the object’s name

Type: boolean, default False

show_only_shape_key

Always show the current shape for this object

Type: boolean, default False

show_texture_space

Display the object’s texture space

Type: boolean, default False

show_transparent

Display material transparency in the object

Type: boolean, default False

show_wire

Display the object’s wireframe over solid shading

Type: boolean, default False

soft_body

Settings for soft body simulation

Type: SoftBodySettings, (readonly)

track_axis

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

Type: enum in [‘POS_X’, ‘POS_Y’, ‘POS_Z’, ‘NEG_X’, ‘NEG_Y’, ‘NEG_Z’], default ‘POS_X’

type

Type of object

Type: enum in [‘MESH’, ‘CURVE’, ‘SURFACE’, ‘META’, ‘FONT’, ‘CURVES’, ‘POINTCLOUD’, ‘VOLUME’, ‘GPENCIL’, ‘ARMATURE’, ‘LATTICE’, ‘EMPTY’, ‘LIGHT’, ‘LIGHT_PROBE’, ‘CAMERA’, ‘SPEAKER’], default ‘EMPTY’, (readonly)

up_axis

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

Type: enum in [‘X’, ‘Y’, ‘Z’], default ‘X’

use_camera_lock_parent

View Lock 3D viewport camera transformation affects the object’s parent instead

Type: boolean, default False

use_dynamic_topology_sculpting

Type: boolean, default False, (readonly)

use_empty_image_alpha

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

Type: boolean, default False

use_grease_pencil_lights

Lights affect grease pencil object

Type: boolean, default True

use_instance_faces_scale

Scale instance based on face size

Type: boolean, default False

use_instance_vertices_rotation

Rotate instance according to vertex normal

Type: boolean, default False

use_mesh_mirror_x

Enable mesh symmetry in the X axis

Type: boolean, default False

use_mesh_mirror_y

Enable mesh symmetry in the Y axis

Type: boolean, default False

use_mesh_mirror_z

Enable mesh symmetry in the Z axis

Type: boolean, default False

use_shape_key_edit_mode

Apply shape keys in edit mode (for meshes only)

Type: boolean, default False

vertex_groups

Vertex groups of the object

Type: VertexGroups bpy_prop_collection of VertexGroup, (readonly)

visible_camera

Object visibility to camera rays

Type: boolean, default False

visible_diffuse

Object visibility to diffuse rays

Type: boolean, default False

visible_glossy

Object visibility to glossy rays

Type: boolean, default False

visible_shadow

Object visibility to shadow rays

Type: boolean, default False

visible_transmission

Object visibility to transmission rays

Type: boolean, default False

visible_volume_scatter

Object visibility to volume scattering rays

Type: boolean, default False

children

All the children of this object.

Note

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

(readonly)

children_recursive

A list of all children from this object.

Note

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

(readonly)

users_collection

The collections this object is in.

Note

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

(readonly)

users_scene

The scenes this object is in.

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, (optional)) – Use this instead of the active view layer
Returns: Object selected
Return type: boolean

select_set(state, view_layer=None)

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

Parameters

state (boolean) – Selection state to define
view_layer (ViewLayer, (optional)) – Use this instead of the active view layer

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, (optional)) – Use this instead of the active view layer
Returns: Object hidden
Return type: boolean

hide_set(state, view_layer=None)

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

Parameters

state (boolean) – Hide state to define
view_layer (ViewLayer, (optional)) – Use this instead of the active view layer

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, (optional)) – Use this instead of the active view layer
viewport (SpaceView3D, (optional)) – Use this instead of the active 3D viewport

Returns

Object visible

Return type

boolean

holdout_get(view_layer=None)

Test if object is masked in the view layer

Parameters: view_layer (ViewLayer, (optional)) – Use this instead of the active view layer
Returns: Object holdout
Return type: boolean

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, (optional)) – Use this instead of the active view layer
Returns: Object indirect only
Return type: boolean

local_view_get(viewport)

Get the local view state for this object

Parameters: viewport (SpaceView3D) – Viewport in local view
Returns: Object local view state
Return type: boolean

local_view_set(viewport, state)

Set the local view state for this object

Parameters

viewport (SpaceView3D) – Viewport in local view
state (boolean) – 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
Returns: Object viewport visibility
Return type: boolean

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, (optional)) – Bone to use to define spaces (may be None, in which case only the two ‘WORLD’ and ‘LOCAL’ spaces are usable)
matrix (float multi-dimensional array of 4 * 4 items in [-inf, inf], (optional)) – The matrix to transform
from_space (enum in ['WORLD', 'POSE', 'LOCAL_WITH_PARENT', 'LOCAL'], (optional)) –
The space in which ‘matrix’ is currently
- 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 (thus matrix includes parent transforms).
- LOCAL Local Space – The local space of an object/bone.
to_space (enum in ['WORLD', 'POSE', 'LOCAL_WITH_PARENT', 'LOCAL'], (optional)) –
The space to which you want to transform ‘matrix’
- 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 (thus matrix includes parent transforms).
- LOCAL Local Space – The local space of an object/bone.

Returns

The transformed matrix

Return type

float multi-dimensional array of 4 * 4 items in [-inf, inf]

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 in [0, inf], (optional)) – Width of the render area
y (int in [0, inf], (optional)) – Height of the render area
scale_x (float in [1e-06, inf], (optional)) – Width scaling factor
scale_y (float in [1e-06, inf], (optional)) – Height scaling factor

Returns

The camera projection matrix

Return type

float multi-dimensional array of 4 * 4 items in [-inf, inf]

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 (float array of 1 items in [-inf, inf], (never None)) – Coordinates to fit in

Return (co_return, scale_return)

co_return, The location to aim to be able to see all given points, float array of 3 items in [-inf, inf]

scale_return, The ortho scale to aim to be able to see all given points (if relevant), float in [-inf, inf]

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 in [-inf, inf], (optional)) – vertex_index
displacement (float array of 3 items in [-inf, inf], (optional)) – displacement

Returns

displacement_deformed

Return type

float array of 3 items in [-inf, inf]

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

Free evaluated state of crazyspace

Parameters

vertex_index (int in [-inf, inf], (optional)) – vertex_index
displacement (float array of 3 items in [-inf, inf], (optional)) – displacement

Returns

displacement_original

Return type

float array of 3 items in [-inf, inf]

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 can not be used by objects from the main database

Parameters

preserve_all_data_layers (boolean, (optional)) – 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
depsgraph (Depsgraph, (optional)) – Dependency Graph, Evaluated dependency graph which is required when preserve_all_data_layers is true

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 can not be used by objects from the main database

Parameters

depsgraph (Depsgraph) – Dependency Graph, Evaluated dependency graph
apply_modifiers (boolean, (optional)) – Apply the deform modifiers on the control points of the curve. This is only supported for curve objects

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 NULL
Return type: Object

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

Add shape key to this object

Parameters

name (string, (optional, never None)) – Unique name for the new keyblock
from_mix (boolean, (optional)) – Create new shape from existing mix of shapes

Returns

New shape keyblock

Return type

ShapeKey

shape_key_remove(key)

Remove a Shape Key from this object

Parameters: key (ShapeKey, (never None)) – Keyblock to be removed

shape_key_clear(): Remove all Shape Keys from this object

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 (float array of 3 items in [-inf, inf]) – Origin of the ray, in object space
direction (float array of 3 items in [-inf, inf]) – Direction of the ray, in object space
distance (float in [0, inf], (optional)) – Maximum distance
depsgraph (Depsgraph, (optional)) – Depsgraph to use to get evaluated data, when called from original object (only needed if current Context’s depsgraph is not suitable)

Return (result, location, normal, index)

result, Whether the ray successfully hit the geometry, boolean

location, The hit location of this ray cast, float array of 3 items in [-inf, inf]

normal, The face normal at the ray cast hit location, float array of 3 items in [-inf, inf]

index, The face index, -1 when original data isn’t available, int in [-inf, inf]

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 (float array of 3 items in [-inf, inf]) – Point to find closest geometry from (in object space)
distance (float in [0, inf], (optional)) – Maximum distance
depsgraph (Depsgraph, (optional)) – Depsgraph to use to get evaluated data, when called from original object (only needed if current Context’s depsgraph is not suitable)

Return (result, location, normal, index)

result, Whether closest point on geometry was found, boolean

location, The location on the object closest to the point, float array of 3 items in [-inf, inf]

normal, The face normal at the closest point, float array of 3 items in [-inf, inf]

index, The face index, -1 when original data isn’t available, int in [-inf, inf]

is_modified(scene, settings)

Determine if this object is modified from the base mesh data

Parameters

scene (Scene, (never None)) – Scene in which to check the object
settings (enum in ['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

boolean

is_deform_modified(scene, settings)

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

Parameters

scene (Scene, (never None)) – Scene in which to check the object
settings (enum in ['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

boolean

update_from_editmode()

Load the objects edit-mode data into the object data

Returns: Success
Return type: boolean

cache_release(): Release memory used by caches associated with this object. Intended to be used by render engines only

generate_gpencil_strokes(grease_pencil_object, use_collections=True, scale_thickness=1.0, sample=0.0)

Convert a curve object to grease pencil strokes.

Parameters

grease_pencil_object (Object, (never None)) – Grease Pencil object used to create new strokes
use_collections (boolean, (optional)) – Use Collections
scale_thickness (float in [0, inf], (optional)) – Thickness scaling factor
sample (float in [0, inf], (optional)) – Sample distance, zero to disable

Returns

Result

Return type

boolean

classmethod bl_rna_get_subclass(id, default=None)

Parameters: id (string) – The RNA type identifier.
Returns: The RNA type or default when not found.
Return type: bpy.types.Struct subclass

classmethod bl_rna_get_subclass_py(id, default=None)

Parameters: id (string) – The RNA type identifier.
Returns: The class or default when not found.
Return type: type

Inherited Properties

Inherited Functions

References