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¶

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 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:	`CyclesObjectSettings`, (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 [-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_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 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` 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 - 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` 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 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 [-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` 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]

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]

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:	`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 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

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

Object(ID)¶

Basic Object Operations Example¶

Table Of Contents

Previous topic

Next topic