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 data-block defining an object in a scene
-
active_material_index
¶ Index of active material slot
Type: int in [0, inf], default 0
-
active_shape_key_index
¶ Current shape key index
Type: int in [-32768, 32767], default 0
-
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
ofConstraint
, (readonly)
-
cycles
¶ Cycles object settings
Type: CyclesObjectSettings
, (readonly)
-
cycles_visibility
¶ Cycles visibility settings
Type: CyclesVisibilitySettings
, (readonly)
-
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 [-500000, 500000], default 0
-
dupli_frames_off
¶ Recurring frames to exclude from the Dupliframes
Type: int in [0, 500000], default 0
-
dupli_frames_on
¶ Number of frames to use between DupOff frames
Type: int in [0, 500000], default 0
-
dupli_frames_start
¶ Start frame for DupliFrames
Type: int in [-500000, 500000], default 0
-
dupli_list
¶ Object duplis
Type: bpy_prop_collection
ofDupliObject
, (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 data-block
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
ofLodLevel
, (readonly)
-
material_slots
¶ Material slots in the object
Type: bpy_prop_collection
ofMaterialSlot
, (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 - 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 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
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.GPENCIL_EDIT
Edit Strokes, Edit Grease Pencil Strokes.
Type: enum in [‘OBJECT’, ‘EDIT’, ‘POSE’, ‘SCULPT’, ‘VERTEX_PAINT’, ‘WEIGHT_PAINT’, ‘TEXTURE_PAINT’, ‘PARTICLE_EDIT’, ‘GPENCIL_EDIT’], default ‘OBJECT’, (readonly)
-
modifiers
¶ Modifiers affecting the geometric data of the object
Type: ObjectModifiers
bpy_prop_collection
ofModifier
, (readonly)
-
motion_path
¶ Motion Path for this element
Type: MotionPath
, (readonly)
-
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
ofParticleSystem
, (readonly)
-
pass_index
¶ Index number for the “Object Index” render pass
Type: int in [0, 32767], default 0
-
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 [-500000, 500000], 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
ofVertexGroup
, (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]
- pose_bone (
-
calc_matrix_camera
(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 Lamp types)
Parameters: - 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 array of 16 items in [-inf, inf]
-
camera_fit_coords
(scene, coordinates)¶ Compute the coordinate (and scale for ortho cameras) given object should be to ‘see’ all given coordinates
Parameters: - scene (
Scene
) – Scene to get render size information from, if available - 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]
- scene (
-
to_mesh
(scene, apply_modifiers, settings, calc_tessface=True, calc_undeformed=False)¶ Create a Mesh data-block 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: - scene (
-
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.
- scene (
-
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 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:
-
shape_key_remove
(key)¶ Remove a Shape Key from this object
Parameters: key ( ShapeKey
, (never None)) – Keyblock to be removed
-
ray_cast
(origin, direction, distance=1.70141e+38)¶ Cast a ray onto in object space
Parameters: distance (float in [0, inf], (optional)) – Maximum distance
Return (result, location, normal, index): result, 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)¶ Find the nearest point in object space
Parameters: distance (float in [0, inf], (optional)) – Maximum distance
Return (result, location, normal, index): result, 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_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
-
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
-
Inherited Properties
Inherited Functions
References