release/scripts/modules/bpy_types.py

   1 # ##### BEGIN GPL LICENSE BLOCK #####
   2 #
   3 #  This program is free software; you can redistribute it and/or
   4 #  modify it under the terms of the GNU General Public License
   5 #  as published by the Free Software Foundation; either version 2
   6 #  of the License, or (at your option) any later version.
   7 #
   8 #  This program is distributed in the hope that it will be useful,
   9 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 #  GNU General Public License for more details.
  12 #
  13 #  You should have received a copy of the GNU General Public License
  14 #  along with this program; if not, write to the Free Software Foundation,
  15 #  Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16 #
  17 # ##### END GPL LICENSE BLOCK #####
  18
  19 # <pep8 compliant>
  20
  21 from _bpy import types as bpy_types
  22 import _bpy
  23
  24 StructRNA = bpy_types.Struct.__bases__[0]
  25 StructMetaPropGroup = _bpy.StructMetaPropGroup
  26 # StructRNA = bpy_types.Struct
  27
  28 bpy_types.BlendDataLibraries.load = _bpy._library_load
  29
  30
  31 class Context(StructRNA):
  32     __slots__ = ()
  33
  34     def copy(self):
  35         from types import BuiltinMethodType
  36         new_context = {}
  37         generic_attrs = list(StructRNA.__dict__.keys()) + ["bl_rna", "rna_type", "copy"]
  38         for attr in dir(self):
  39             if not (attr.startswith("_") or attr in generic_attrs):
  40                 value = getattr(self, attr)
  41                 if type(value) != BuiltinMethodType:
  42                     new_context[attr] = value
  43
  44         return new_context
  45
  46
  47 class Library(bpy_types.ID):
  48     __slots__ = ()
  49
  50     @property
  51     def users_id(self):
  52         """ID datablocks which use this library"""
  53         import bpy
  54
  55         # See: readblenentry.c, IDTYPE_FLAGS_ISLINKABLE, we could make this an attribute in rna.
  56         attr_links = "actions", "armatures", "brushes", "cameras", \
  57                 "curves", "grease_pencil", "groups", "images", \
  58                 "lamps", "lattices", "materials", "metaballs", \
  59                 "meshes", "node_groups", "objects", "scenes", \
  60                 "sounds", "speakers", "textures", "texts", "fonts", "worlds"
  61
  62         return tuple(id_block for attr in attr_links for id_block in getattr(bpy.data, attr) if id_block.library == self)
  63
  64
  65 class Texture(bpy_types.ID):
  66     __slots__ = ()
  67
  68     @property
  69     def users_material(self):
  70         """Materials that use this texture"""
  71         import bpy
  72         return tuple(mat for mat in bpy.data.materials if self in [slot.texture for slot in mat.texture_slots if slot])
  73
  74     @property
  75     def users_object_modifier(self):
  76         """Object modifiers that use this texture"""
  77         import bpy
  78         return tuple(obj for obj in bpy.data.objects if self in [mod.texture for mod in obj.modifiers if mod.type == 'DISPLACE'])
  79
  80
  81 class Group(bpy_types.ID):
  82     __slots__ = ()
  83
  84     @property
  85     def users_dupli_group(self):
  86         """The dupli group this group is used in"""
  87         import bpy
  88         return tuple(obj for obj in bpy.data.objects if self == obj.dupli_group)
  89
  90
  91 class Object(bpy_types.ID):
  92     __slots__ = ()
  93
  94     @property
  95     def children(self):
  96         """All the children of this object"""
  97         import bpy
  98         return tuple(child for child in bpy.data.objects if child.parent == self)
  99
 100     @property
 101     def users_group(self):
 102         """The groups this object is in"""
 103         import bpy
 104         return tuple(group for group in bpy.data.groups if self in group.objects[:])
 105
 106     @property
 107     def users_scene(self):
 108         """The scenes this object is in"""
 109         import bpy
 110         return tuple(scene for scene in bpy.data.scenes if self in scene.objects[:])
 111
 112
 113 class _GenericBone:
 114     """
 115     functions for bones, common between Armature/Pose/Edit bones.
 116     internal subclassing use only.
 117     """
 118     __slots__ = ()
 119
 120     def translate(self, vec):
 121         """Utility function to add *vec* to the head and tail of this bone."""
 122         self.head += vec
 123         self.tail += vec
 124
 125     def parent_index(self, parent_test):
 126         """
 127         The same as 'bone in other_bone.parent_recursive' but saved generating a list.
 128         """
 129         # use the name so different types can be tested.
 130         name = parent_test.name
 131
 132         parent = self.parent
 133         i = 1
 134         while parent:
 135             if parent.name == name:
 136                 return i
 137             parent = parent.parent
 138             i += 1
 139
 140         return 0
 141
 142     @property
 143     def x_axis(self):
 144         """ Vector pointing down the x-axis of the bone.
 145         """
 146         from mathutils import Vector
 147         return self.matrix.to_3x3() * Vector((1.0, 0.0, 0.0))
 148
 149     @property
 150     def y_axis(self):
 151         """ Vector pointing down the x-axis of the bone.
 152         """
 153         from mathutils import Vector
 154         return self.matrix.to_3x3() * Vector((0.0, 1.0, 0.0))
 155
 156     @property
 157     def z_axis(self):
 158         """ Vector pointing down the x-axis of the bone.
 159         """
 160         from mathutils import Vector
 161         return self.matrix.to_3x3() * Vector((0.0, 0.0, 1.0))
 162
 163     @property
 164     def basename(self):
 165         """The name of this bone before any '.' character"""
 166         #return self.name.rsplit(".", 1)[0]
 167         return self.name.split(".")[0]
 168
 169     @property
 170     def parent_recursive(self):
 171         """A list of parents, starting with the immediate parent"""
 172         parent_list = []
 173         parent = self.parent
 174
 175         while parent:
 176             if parent:
 177                 parent_list.append(parent)
 178
 179             parent = parent.parent
 180
 181         return parent_list
 182
 183     @property
 184     def center(self):
 185         """The midpoint between the head and the tail."""
 186         return self.head.lerp(self.tail, 0.5)
 187
 188     @property
 189     def length(self):
 190         """The distance from head to tail, when set the head is moved to fit the length."""
 191         return self.vector.length
 192
 193     @length.setter
 194     def length(self, value):
 195         self.tail = self.head + ((self.tail - self.head).normalized() * value)
 196
 197     @property
 198     def vector(self):
 199         """The direction this bone is pointing. Utility function for (tail - head)"""
 200         return (self.tail - self.head)
 201
 202     @property
 203     def children(self):
 204         """A list of all the bones children."""
 205         return [child for child in self._other_bones if child.parent == self]
 206
 207     @property
 208     def children_recursive(self):
 209         """a list of all children from this bone."""
 210         bones_children = []
 211         for bone in self._other_bones:
 212             index = bone.parent_index(self)
 213             if index:
 214                 bones_children.append((index, bone))
 215
 216         # sort by distance to parent
 217         bones_children.sort(key=lambda bone_pair: bone_pair[0])
 218         return [bone for index, bone in bones_children]
 219
 220     @property
 221     def children_recursive_basename(self):
 222         """
 223         Returns a chain of children with the same base name as this bone
 224         Only direct chains are supported, forks caused by multiple children with matching basenames will
 225         terminate the function and not be returned.
 226         """
 227         basename = self.basename
 228         chain = []
 229
 230         child = self
 231         while True:
 232             children = child.children
 233             children_basename = []
 234
 235             for child in children:
 236                 if basename == child.basename:
 237                     children_basename.append(child)
 238
 239             if len(children_basename) == 1:
 240                 child = children_basename[0]
 241                 chain.append(child)
 242             else:
 243                 if len(children_basename):
 244                     print("multiple basenames found, this is probably not what you want!", self.name, children_basename)
 245
 246                 break
 247
 248         return chain
 249
 250     @property
 251     def _other_bones(self):
 252         id_data = self.id_data
 253         id_data_type = type(id_data)
 254
 255         if id_data_type == bpy_types.Object:
 256             bones = id_data.pose.bones
 257         elif id_data_type == bpy_types.Armature:
 258             bones = id_data.edit_bones
 259             if not bones:  # not in editmode
 260                 bones = id_data.bones
 261
 262         return bones
 263
 264
 265 class PoseBone(StructRNA, _GenericBone, metaclass=StructMetaPropGroup):
 266     __slots__ = ()
 267
 268
 269 class Bone(StructRNA, _GenericBone, metaclass=StructMetaPropGroup):
 270     __slots__ = ()
 271
 272
 273 class EditBone(StructRNA, _GenericBone, metaclass=StructMetaPropGroup):
 274     __slots__ = ()
 275
 276     def align_orientation(self, other):
 277         """
 278         Align this bone to another by moving its tail and settings its roll
 279         the length of the other bone is not used.
 280         """
 281         vec = other.vector.normalize() * self.length
 282         self.tail = self.head + vec
 283         self.roll = other.roll
 284
 285     def transform(self, matrix, scale=True, roll=True):
 286         """
 287         Transform the the bones head, tail, roll and envalope (when the matrix has a scale component).
 288
 289         :arg matrix: 3x3 or 4x4 transformation matrix.
 290         :type matrix: :class:`mathutils.Matrix`
 291         :arg scale: Scale the bone envalope by the matrix.
 292         :type scale: bool
 293         :arg roll: Correct the roll to point in the same relative direction to the head and tail.
 294         :type roll: bool
 295         """
 296         from mathutils import Vector
 297         z_vec = self.matrix.to_3x3() * Vector((0.0, 0.0, 1.0))
 298         self.tail = matrix * self.tail
 299         self.head = matrix * self.head
 300
 301         if scale:
 302             scalar = matrix.median_scale
 303             self.head_radius *= scalar
 304             self.tail_radius *= scalar
 305
 306         if roll:
 307             self.align_roll(matrix * z_vec)
 308
 309
 310 def ord_ind(i1, i2):
 311     if i1 < i2:
 312         return i1, i2
 313     return i2, i1
 314
 315
 316 class Mesh(bpy_types.ID):
 317     __slots__ = ()
 318
 319     def from_pydata(self, vertices, edges, faces):
 320         """
 321         Make a mesh from a list of verts/edges/faces
 322         Until we have a nicer way to make geometry, use this.
 323
 324         :arg vertices: float triplets each representing (X, Y, Z) eg: [(0.0, 1.0, 0.5), ...].
 325         :type vertices: iterable object
 326         :arg edges: int pairs, each pair contains two indices to the *vertices* argument. eg: [(1, 2), ...]
 327         :type edges: iterable object
 328         :arg faces: iterator of faces, each faces contains three or four indices to the *vertices* argument. eg: [(5, 6, 8, 9), (1, 2, 3), ...]
 329         :type faces: iterable object
 330         """
 331         self.vertices.add(len(vertices))
 332         self.edges.add(len(edges))
 333         self.loops.add(sum((len(f) for f in faces)))
 334         self.polygons.add(len(faces))
 335
 336         vertices_flat = [f for v in vertices for f in v]
 337         self.vertices.foreach_set("co", vertices_flat)
 338         del vertices_flat
 339
 340         edges_flat = [i for e in edges for i in e]
 341         self.edges.foreach_set("vertices", edges_flat)
 342         del edges_flat
 343
 344         # this is different in bmesh
 345         loop_index = 0
 346         for i, p in enumerate(self.polygons):
 347             f = faces[i]
 348             loop_len = len(f)
 349             p.loop_start = loop_index
 350             p.loop_total = loop_len
 351             p.vertices = f
 352             loop_index += loop_len
 353
 354     @property
 355     def edge_keys(self):
 356         return [edge_key for face in self.faces for edge_key in face.edge_keys]
 357
 358
 359 class MeshEdge(StructRNA):
 360     __slots__ = ()
 361
 362     @property
 363     def key(self):
 364         return ord_ind(*tuple(self.vertices))
 365
 366
 367 class MeshFace(StructRNA):
 368     __slots__ = ()
 369
 370     @property
 371     def center(self):
 372         """The midpoint of the face."""
 373         face_verts = self.vertices[:]
 374         mesh_verts = self.id_data.vertices
 375         if len(face_verts) == 3:
 376             return (mesh_verts[face_verts[0]].co + mesh_verts[face_verts[1]].co + mesh_verts[face_verts[2]].co) / 3.0
 377         else:
 378             return (mesh_verts[face_verts[0]].co + mesh_verts[face_verts[1]].co + mesh_verts[face_verts[2]].co + mesh_verts[face_verts[3]].co) / 4.0
 379
 380     @property
 381     def edge_keys(self):
 382         verts = self.vertices[:]
 383         if len(verts) == 3:
 384             return ord_ind(verts[0], verts[1]), ord_ind(verts[1], verts[2]), ord_ind(verts[2], verts[0])
 385
 386         return ord_ind(verts[0], verts[1]), ord_ind(verts[1], verts[2]), ord_ind(verts[2], verts[3]), ord_ind(verts[3], verts[0])
 387
 388
 389 class Text(bpy_types.ID):
 390     __slots__ = ()
 391
 392     def as_string(self):
 393         """Return the text as a string."""
 394         return "\n".join(line.body for line in self.lines)
 395
 396     def from_string(self, string):
 397         """Replace text with this string."""
 398         self.clear()
 399         self.write(string)
 400
 401     @property
 402     def users_logic(self):
 403         """Logic bricks that use this text"""
 404         import bpy
 405         return tuple(obj for obj in bpy.data.objects if self in [cont.text for cont in obj.game.controllers if cont.type == 'PYTHON'])
 406
 407 # values are module: [(cls, path, line), ...]
 408 TypeMap = {}
 409
 410
 411 class Sound(bpy_types.ID):
 412     __slots__ = ()
 413
 414     @property
 415     def factory(self):
 416         """The aud.Factory object of the sound."""
 417         import aud
 418         return aud._sound_from_pointer(self.as_pointer())
 419
 420
 421 class RNAMeta(type):
 422     def __new__(cls, name, bases, classdict, **args):
 423         result = type.__new__(cls, name, bases, classdict)
 424         if bases and bases[0] is not StructRNA:
 425             from _weakref import ref as ref
 426             module = result.__module__
 427
 428             # first part of packages only
 429             if "." in module:
 430                 module = module[:module.index(".")]
 431
 432             TypeMap.setdefault(module, []).append(ref(result))
 433
 434         return result
 435
 436     @property
 437     def is_registered(cls):
 438         return "bl_rna" in cls.__dict__
 439
 440
 441 class OrderedDictMini(dict):
 442     def __init__(self, *args):
 443         self.order = []
 444         dict.__init__(self, args)
 445
 446     def __setitem__(self, key, val):
 447         dict.__setitem__(self, key, val)
 448         if key not in self.order:
 449             self.order.append(key)
 450
 451     def __delitem__(self, key):
 452         dict.__delitem__(self, key)
 453         self.order.remove(key)
 454
 455
 456 class RNAMetaPropGroup(RNAMeta, StructMetaPropGroup):
 457     pass
 458
 459
 460 class OrderedMeta(RNAMeta):
 461     def __init__(cls, name, bases, attributes):
 462         if attributes.__class__ is OrderedDictMini:
 463             cls.order = attributes.order
 464
 465     def __prepare__(name, bases, **kwargs):
 466         return OrderedDictMini()  # collections.OrderedDict()
 467
 468
 469 # Only defined so operators members can be used by accessing self.order
 470 # with doc generation 'self.properties.bl_rna.properties' can fail
 471 class Operator(StructRNA, metaclass=OrderedMeta):
 472     __slots__ = ()
 473
 474     def __getattribute__(self, attr):
 475         properties = StructRNA.path_resolve(self, "properties")
 476         bl_rna = getattr(properties, "bl_rna", None)
 477         if bl_rna and attr in bl_rna.properties:
 478             return getattr(properties, attr)
 479         return super().__getattribute__(attr)
 480
 481     def __setattr__(self, attr, value):
 482         properties = StructRNA.path_resolve(self, "properties")
 483         bl_rna = getattr(properties, "bl_rna", None)
 484         if bl_rna and attr in bl_rna.properties:
 485             return setattr(properties, attr, value)
 486         return super().__setattr__(attr, value)
 487
 488     def __delattr__(self, attr):
 489         properties = StructRNA.path_resolve(self, "properties")
 490         bl_rna = getattr(properties, "bl_rna", None)
 491         if bl_rna and attr in bl_rna.properties:
 492             return delattr(properties, attr)
 493         return super().__delattr__(attr)
 494
 495     def as_keywords(self, ignore=()):
 496         """ Return a copy of the properties as a dictionary.
 497         """
 498         ignore = ignore + ("rna_type",)
 499         return {attr: getattr(self, attr) for attr in self.properties.rna_type.properties.keys() if attr not in ignore}
 500
 501
 502 class Macro(StructRNA, metaclass=OrderedMeta):
 503     # bpy_types is imported before ops is defined
 504     # so we have to do a local import on each run
 505     __slots__ = ()
 506
 507     @classmethod
 508     def define(self, opname):
 509         from _bpy import ops
 510         return ops.macro_define(self, opname)
 511
 512
 513 class PropertyGroup(StructRNA, metaclass=RNAMetaPropGroup):
 514         __slots__ = ()
 515
 516
 517 class RenderEngine(StructRNA, metaclass=RNAMeta):
 518     __slots__ = ()
 519
 520
 521 class KeyingSetInfo(StructRNA, metaclass=RNAMeta):
 522     __slots__ = ()
 523
 524
 525 class _GenericUI:
 526     __slots__ = ()
 527
 528     @classmethod
 529     def _dyn_ui_initialize(cls):
 530         draw_funcs = getattr(cls.draw, "_draw_funcs", None)
 531
 532         if draw_funcs is None:
 533
 534             def draw_ls(self, context):
 535                 # ensure menus always get default context
 536                 operator_context_default = self.layout.operator_context
 537
 538                 for func in draw_ls._draw_funcs:
 539                     # so bad menu functions dont stop the entire menu from drawing.
 540                     try:
 541                         func(self, context)
 542                     except:
 543                         import traceback
 544                         traceback.print_exc()
 545
 546                     self.layout.operator_context = operator_context_default
 547
 548             draw_funcs = draw_ls._draw_funcs = [cls.draw]
 549             cls.draw = draw_ls
 550
 551         return draw_funcs
 552
 553     @classmethod
 554     def append(cls, draw_func):
 555         """Append a draw function to this menu, takes the same arguments as the menus draw function."""
 556         draw_funcs = cls._dyn_ui_initialize()
 557         draw_funcs.append(draw_func)
 558
 559     @classmethod
 560     def prepend(cls, draw_func):
 561         """Prepend a draw function to this menu, takes the same arguments as the menus draw function."""
 562         draw_funcs = cls._dyn_ui_initialize()
 563         draw_funcs.insert(0, draw_func)
 564
 565     @classmethod
 566     def remove(cls, draw_func):
 567         """Remove a draw function that has been added to this menu"""
 568         draw_funcs = cls._dyn_ui_initialize()
 569         try:
 570             draw_funcs.remove(draw_func)
 571         except ValueError:
 572             pass
 573
 574
 575 class Panel(StructRNA, _GenericUI, metaclass=RNAMeta):
 576     __slots__ = ()
 577
 578
 579 class Header(StructRNA, _GenericUI, metaclass=RNAMeta):
 580     __slots__ = ()
 581
 582
 583 class Menu(StructRNA, _GenericUI, metaclass=RNAMeta):
 584     __slots__ = ()
 585
 586     def path_menu(self, searchpaths, operator, props_default={}):
 587         layout = self.layout
 588         # hard coded to set the operators 'filepath' to the filename.
 589
 590         import os
 591         import bpy.utils
 592
 593         layout = self.layout
 594
 595         if not searchpaths:
 596             layout.label("* Missing Paths *")
 597
 598         # collect paths
 599         files = []
 600         for directory in searchpaths:
 601             files.extend([(f, os.path.join(directory, f)) for f in os.listdir(directory)])
 602
 603         files.sort()
 604
 605         for f, filepath in files:
 606
 607             if f.startswith("."):
 608                 continue
 609
 610             preset_name = bpy.path.display_name(f)
 611             props = layout.operator(operator, text=preset_name)
 612
 613             for attr, value in props_default.items():
 614                 setattr(props, attr, value)
 615
 616             props.filepath = filepath
 617             if operator == "script.execute_preset":
 618                 props.menu_idname = self.bl_idname
 619
 620     def draw_preset(self, context):
 621         """Define these on the subclass
 622          - preset_operator
 623          - preset_subdir
 624         """
 625         import bpy
 626         self.path_menu(bpy.utils.preset_paths(self.preset_subdir), self.preset_operator)