Object(ID)

Basic Object Operations Example

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

import bpy
from mathutils import Matrix

scene = bpy.context.scene

# Create new lamp datablock
lamp_data = bpy.data.lamps.new(name="New Lamp", type='POINT')

# Create new object with our lamp datablock
lamp_object = bpy.data.objects.new(name="New Lamp", object_data=lamp_data)

# Link lamp object to the scene so it'll appear in this scene
scene.objects.link(lamp_object)

# Place lamp to a specified location
lamp_object.location = (5.0, 5.0, 5.0)

# And finally select it make active
lamp_object.select = True
scene.objects.active = lamp_object

base classes — bpy_struct, ID

class bpy.types.Object(ID)

Object datablock 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 datablock

Type:AnimData, (readonly)

animation_visualization

Animation data for this datablock

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 array of 24 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 (0.0, 0.0, 0.0, 0.0)

constraints

Constraints affecting the transformation of the object

Type:ObjectConstraints bpy_prop_collection of Constraint, (readonly)

cycles

Cycles object settings

Type:CyclesObjectBlurSettings, (readonly)

cycles_visibility

Cycles visibility settings

Type:CyclesVisibilitySettings, (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

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

draw_bounds_type

Object boundary display type

• BOX Box, Draw bounds as box.
• SPHERE Sphere, Draw bounds as sphere.
• CYLINDER Cylinder, Draw bounds as cylinder.
• CONE Cone, Draw bounds as cone.
• CAPSULE Capsule, Draw bounds as capsule.

Type:enum in [‘BOX’, ‘SPHERE’, ‘CYLINDER’, ‘CONE’, ‘CAPSULE’], default ‘BOX’

draw_type

Maximum draw type to display object with in viewport

• BOUNDS Bounds, Draw the bounds of the object.
• WIRE Wire, Draw the object as a wireframe.
• SOLID Solid, Draw the object as a solid (if solid drawing is enabled in the viewport).
• TEXTURED Textured, Draw the object with textures (if textures are enabled in the viewport).

Type:enum in [‘BOUNDS’, ‘WIRE’, ‘SOLID’, ‘TEXTURED’], default ‘BOUNDS’

dupli_faces_scale

Scale the DupliFace objects

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

dupli_frames_end

End frame for DupliFrames

Type:int in [-300000, 300000], default 0

dupli_frames_off

Recurring frames to exclude from the Dupliframes

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

dupli_frames_on

Number of frames to use between DupOff frames

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

dupli_frames_start

Start frame for DupliFrames

Type:int in [-300000, 300000], default 0

dupli_group

Instance an existing group

Type:Group

dupli_list

Object duplis

Type:bpy_prop_collection of DupliObject, (readonly)

dupli_type

If not None, object duplication method to use

• NONE None.
• FRAMES Frames, Make copy of object for every frame.
• VERTS Verts, Duplicate child objects on all vertices.
• FACES Faces, Duplicate child objects on all faces.
• GROUP Group, Enable group instancing.

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

empty_draw_size

Size of display for empties in the viewport

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

empty_draw_type

Viewport display style for empties

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

empty_image_offset

Origin offset distance

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

field

Settings for using the object as a field in physics simulation

Type:FieldSettings, (readonly)

game

Game engine related settings for the object

Type:GameObjectSettings, (readonly, never None)

grease_pencil

Grease Pencil datablock

Type:GreasePencil

hide

Restrict visibility in the viewport

Type:boolean, default False

hide_render

Restrict renderability

Type:boolean, default False

hide_select

Restrict selection in the viewport

Type:boolean, default False

image_user

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

Type:ImageUser, (readonly, never None)

is_duplicator

Type:boolean, default False, (readonly)

layers

Layers the object is on

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

layers_local_view

3D local view layers the object is on

Type:boolean array of 8 items, default (False, False, False, False, False, False, False, False), (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 in the interface

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

lock_rotation

Lock editing of rotation in the interface

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

lock_rotation_w

Lock editing of ‘angle’ component of four-component rotations in the interface

Type:boolean, default False

lock_rotations_4d

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

Type:boolean, default False

lock_scale

Lock editing of scale in the interface

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

lod_levels

A collection of detail levels to automatically switch between

Type:bpy_prop_collection of LodLevel, (readonly)

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 array of 16 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

Type:float array of 16 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 array of 16 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_world

Worldspace transformation matrix

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

mode

Object interaction mode

Type:enum in [‘OBJECT’, ‘EDIT’, ‘POSE’, ‘SCULPT’, ‘VERTEX_PAINT’, ‘WEIGHT_PAINT’, ‘TEXTURE_PAINT’, ‘PARTICLE_EDIT’], 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.
• CURVE Curve, The object is parented to a curve.
• KEY Key.
• 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’, ‘CURVE’, ‘KEY’, ‘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 IndexOB render pass

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

pose

Current pose for armatures

Type:Pose, (readonly)

pose_library

Action used as a pose library for armatures

Type:Action

proxy

Library object this proxy object controls

Type:Object, (readonly)

proxy_group

Library group duplicator object this proxy object controls

Type:Object, (readonly)

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 ‘QUATERNION’

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)

select

Object selection state

Type:boolean, default False

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_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 (unsupported for duplicator drawing)

Type:boolean, default False

show_wire

Add the object’s wireframe over solid drawing

Type:boolean, default False

show_x_ray

Make the object draw in front of others (unsupported for duplicator drawing)

Type:boolean, default False

slow_parent_offset

Delay in the parent relationship

Type:float in [-300000, 300000], default 0.0

soft_body

Settings for soft body simulation

Type:SoftBodySettings, (readonly)

track_axis

Axis that points in ‘forward’ direction (applies to DupliFrame when parent ‘Follow’ 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’, ‘ARMATURE’, ‘LATTICE’, ‘EMPTY’, ‘CAMERA’, ‘LAMP’, ‘SPEAKER’], default ‘EMPTY’, (readonly)

up_axis

Axis that points in the upward direction (applies to DupliFrame when parent ‘Follow’ is enabled)

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

use_dupli_faces_scale

Scale dupli based on face size

Type:boolean, default False

use_dupli_frames_speed

Set dupliframes to use the current frame instead of parent curve’s evaluation time

Type:boolean, default False

use_dupli_vertices_rotation

Rotate dupli according to vertex normal

Type:boolean, default False

use_dynamic_topology_sculpting

Type:boolean, default False, (readonly)

use_extra_recalc_data

Refresh this object’s data again on frame changes, dependency graph hack

Type:boolean, default False

use_extra_recalc_object

Refresh this object again on frame changes, dependency graph hack

Type:boolean, default False

use_shape_key_edit_mode

Apply shape keys in edit mode (for Meshes only)

Type:boolean, default False

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)

Type:boolean, default False

vertex_groups

Vertex groups of the object

Type:VertexGroups bpy_prop_collection of VertexGroup, (readonly)

children

All the children of this object (readonly)

users_group

The groups this object is in (readonly)

users_scene

The scenes this object is in (readonly)

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 array of 16 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 gobal space in Blender.
  • POSE Pose Space, The pose space of a bone (its armature’s object space).
  • LOCAL_WITH_PARENT Local With Parent, The local space of a bone’s parent bone.
  • 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 gobal space in Blender.
  • POSE Pose Space, The pose space of a bone (its armature’s object space).
  • LOCAL_WITH_PARENT Local With Parent, The local space of a bone’s parent bone.
  • LOCAL Local Space, The local space of an object/bone.

Returns:

The transformed matrix

Return type:

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

to_mesh(scene, apply_modifiers, settings, calc_tessface=True, calc_undeformed=False)

Create a Mesh datablock with modifiers applied

Parameters:

• scene (Scene, (never None)) – Scene within which to evaluate modifiers
• apply_modifiers (boolean) – Apply modifiers
• settings (enum in [‘PREVIEW’, ‘RENDER’]) –

  Modifier settings to apply

  • PREVIEW Preview, Apply modifier preview settings.
  • RENDER Render, Apply modifier render settings.
• calc_tessface (boolean, (optional)) – Calculate Tessellation, Calculate tessellation faces
• calc_undeformed (boolean, (optional)) – Calculate Undeformed, Calculate undeformed vertex coordinates

Returns:

Mesh created from object, remove it if it is only used for export

Return type:

Mesh

dupli_list_create(scene, settings='VIEWPORT')

Create a list of dupli objects for this object, needs to be freed manually with free_dupli_list to restore the objects real matrix and layers

Parameters:

• scene (Scene, (never None)) – Scene within which to evaluate duplis
• settings (enum in [‘VIEWPORT’, ‘PREVIEW’, ‘RENDER’], (optional)) –

  Generate texture coordinates for rendering

  • VIEWPORT Viewport, Generate duplis using viewport settings.
  • PREVIEW Preview, Generate duplis using preview settings.
  • RENDER Render, Generate duplis using render settings.

dupli_list_clear()

Free the list of dupli objects

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 an object

Parameters:

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

Returns:

New shape keyblock

Return type:

ShapeKey

ray_cast(start, end)

Cast a ray onto in object space

Return (location, normal, index):  

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 no intersection is found, int in [-inf, inf]

closest_point_on_mesh(point, max_dist=1.84467e+19)

Find the nearest point on the object

Return (location, normal, index):  

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 no closest point is found, int in [-inf, inf]

is_visible(scene)

Determine if object is visible in a given scene

Returns:Object visibility Return type:boolean

is_modified(scene, settings)

Determine if this object is modified from the base mesh data

Parameters:settings (enum in [‘PREVIEW’, ‘RENDER’]) –

Modifier settings to apply

• PREVIEW Preview, Apply modifier preview settings.
• RENDER Render, Apply modifier render settings.

Returns:Object visibility Return type:boolean

is_deform_modified(scene, settings)

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

Parameters:settings (enum in [‘PREVIEW’, ‘RENDER’]) –

Modifier settings to apply

• PREVIEW Preview, Apply modifier preview settings.
• RENDER Render, Apply modifier render settings.

Returns:Object visibility Return type:boolean

dm_info(type)

Returns a string for derived mesh data

Parameters:type (enum in [‘SOURCE’, ‘DEFORM’, ‘FINAL’]) –

Modifier settings to apply

• SOURCE Source, Source mesh.
• DEFORM Deform, Objects deform mesh.
• FINAL Final, Objects final mesh.

Returns:result Return type:string, (never None)

update_from_editmode()

Load the objects edit-mode data intp the object data

Returns:Success Return type:boolean

Inherited Properties

bpy_struct.id_data ID.name ID.users ID.use_fake_user ID.tag

ID.is_updated ID.is_updated_data ID.is_library_indirect ID.library

Inherited Functions

bpy_struct.as_pointer bpy_struct.driver_add bpy_struct.driver_remove bpy_struct.get bpy_struct.is_property_hidden 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_resolve bpy_struct.property_unset bpy_struct.type_recast bpy_struct.values ID.copy ID.user_clear ID.animation_data_create ID.animation_data_clear ID.update_tag

References

bpy.context.active_object bpy.context.edit_object bpy.context.image_paint_object bpy.context.object bpy.context.particle_edit_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 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 Camera.dof_object CameraActuator.object CastModifier.object ChildOfConstraint.target ClampToConstraint.target ConstraintTarget.target CopyLocationConstraint.target CopyRotationConstraint.target CopyScaleConstraint.target CopyTransformsConstraint.target Curve.bevel_object Curve.taper_object CurveModifier.object CurveSplines.active DampedTrackConstraint.target DisplaceModifier.texture_coords_object DupliObject.object DynamicPaintSurface.output_exists EditObjectActuator.object EditObjectActuator.track_object EnvironmentMap.viewpoint_object FieldSettings.source_object FloorConstraint.target FollowPathConstraint.target FollowTrackConstraint.camera FollowTrackConstraint.depth_object Group.objects GroupObjects.link GroupObjects.unlink HookModifier.object KinematicConstraint.pole_target KinematicConstraint.target LampTextureSlot.object LatticeModifier.object LimitDistanceConstraint.target LineStyleAlphaModifier_DistanceFromObject.target LineStyleColorModifier_DistanceFromObject.target LineStyleThicknessModifier_DistanceFromObject.target LockedTrackConstraint.target LodLevel.object MaskModifier.armature MaterialTextureSlot.object MeshDeformModifier.object MirrorModifier.mirror_object

Object.find_armature Object.parent Object.proxy Object.proxy_group ObjectActuator.reference_object ObjectBase.object ObjectSolverConstraint.camera OceanTexData.ocean_object ParentActuator.object ParticleEdit.object ParticleHairKey.co_object ParticleInstanceModifier.object ParticleSettings.billboard_object ParticleSettings.dupli_object ParticleSettingsTextureSlot.object ParticleSystem.co_hair ParticleSystem.parent ParticleSystem.reactor_target_object ParticleSystem.set_resolution ParticleTarget.object PivotConstraint.target PointDensity.object PoseBone.custom_shape PropertyActuator.object RenderEngine.bake RenderEngine.camera_override RigidBodyConstraint.object1 RigidBodyConstraint.object2 RigidBodyJointConstraint.child RigidBodyJointConstraint.target RigidBodyWorld.convex_sweep_test Scene.camera Scene.objects Scene.ray_cast SceneActuator.camera SceneObjects.active SceneObjects.link SceneObjects.unlink SceneSequence.scene_camera ScrewModifier.object Sculpt.gravity_object ShaderNodeLampData.lamp_object ShrinkwrapConstraint.target ShrinkwrapModifier.auxiliary_target ShrinkwrapModifier.target SimpleDeformModifier.origin SpaceView3D.camera SpaceView3D.lock_object SplineIKConstraint.target SteeringActuator.navmesh SteeringActuator.target StretchToConstraint.target TextCurve.follow_curve TimelineMarker.camera ToolSettings.etch_template 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 VoxelData.domain_object WarpModifier.object_from WarpModifier.object_to WarpModifier.texture_coords_object WaveModifier.start_position_object WaveModifier.texture_coords_object WorldTextureSlot.object