1
2
3 """
4 The bpy.libraries submodule.
5
6 Libraries
7 =========
8
9 This module provides access to objects stored in .blend files. With it scripts
10 can append from Blender files to the current scene, like the File->Append
11 menu entry in Blender does. It allows programmers to use .blend files as
12 data files for their scripts.
13
14 @warn: This module is new and being considered as a replacement for the
15 L{original Library<Library>} module. Users should stay tuned to see
16 which module is supported in the end.
17
18 Example::
19 import bpy
20
21 scn= bpy.data.scenes.active # get current scene
22 lib = bpy.libraries.load('//file.blend') # open file.blend
23 ob = scn.objects.link(lib.objects.append('Cube')) # append Cube object from library to current scene
24 mat = lib.objects.link('Material') # get a link to a material
25 me = ob.getData(mesh=1) # get mesh data
26 me.materials[0] = mat # assign linked material to mesh
27 """
28
29 -def load(filename,relative=False):
30 """
31 Select an existing .blend file for use as a library. Unlike the
32 Library module, multiple libraries can be defined at the same time.
33
34 @type filename: string
35 @param filename: The filename of a Blender file. Filenames starting with "//" will be loaded relative to the blend file's location.
36 @type relative: boolean
37 @param relative: Convert relative paths to absolute paths (default). Setting this parameter to True will leave paths relative.
38 @rtype: Library
39 @return: return a L{Library} object.
40 """
41
43 """
44 The Library object
45 ==================
46 This class provides a unified way to access and manipulate library types
47 in Blender.
48 It provides access to scenes, objects, meshes, curves, metaballs,
49 materials, textures, images, lattices, lamps, cameras, ipos, worlds,
50 fonts, texts, sounds, groups, armatures, and actions.
51 @ivar filename: The filename of the library, as supplied by user.
52 @type filename: string
53 @ivar name: The path to the library, as used by Blender. If the filename supplied by the user is relative, but the relative option to L{library.load()<load>} is False, the name will be the absolute path.
54 @type name: string
55 @ivar scenes: library L{scene<Scene.Scene>} data
56 @type scenes: L{LibData}
57 @ivar objects: library L{object<Object.Object>} data
58 @type objects: L{LibData}
59 @ivar meshes: library L{mesh<Mesh.Mesh>} data
60 @type meshes: L{LibData}
61 @ivar curves: library L{curve<Curve.Curve>} data
62 @type curves: L{LibData}
63 @ivar metaballs: library L{metaball<Metaball.Metaball>} data
64 @type metaballs: L{LibData}
65 @ivar materials: library L{material<Material.Material>} data
66 @type materials: L{LibData}
67 @ivar textures: library L{texture<Texture.Texture>} data
68 @type textures: L{LibData}
69 @ivar images: library L{image<Image.Image>} data
70 @type images: L{LibData}
71 @ivar lattices: library L{lattice<Lattice.Lattice>} data
72 @type lattices: L{LibData}
73 @ivar lamps: library L{lamp<Lamp.Lamp>} data
74 @type lamps: L{LibData}
75 @ivar cameras: library L{camera<Camera.Camera>} data
76 @type cameras: L{LibData}
77 @ivar ipos: library L{ipo<Ipo.Ipo>} data
78 @type ipos: L{LibData}
79 @ivar worlds: library L{world<World.World>} data
80 @type worlds: L{LibData}
81 @ivar fonts: library L{font<Font.Font>} data
82 @type fonts: L{LibData}
83 @ivar texts: library L{text<Text.Text>} data
84 @type texts: L{LibData}
85 @ivar sounds: library L{sound<Sound.Sound>} data
86 @type sounds: L{LibData}
87 @ivar groups: library L{group<Group.Group>} data
88 @type groups: L{LibData}
89 @ivar armatures: library L{armature<Armature.Armature>} data
90 @type armatures: L{LibData}
91 @ivar actions: library L{action<NLA.Action>} data
92 @type actions: L{LibData}
93 """
94
96 """
97 Generic Library Data Access
98 ===========================
99 This class provides access to a specific type of library data.
100 """
101
103 """
104 Append a new datablock from a library. The new copy
105 is added to the current .blend file.
106
107 B{Note}: Blender Objects cannot be appended or linked without linking
108 them to a scene. For this reason, lib.objects.append() returns a
109 special "wrapper object" which must be passed to Scene.objects.link()
110 or bpy.data.scenes.active.link() in order to actually create the object.
111 So the following code will not create a new object::
112 import bpy
113
114 scn= bpy.data.scenes.active # get current scene
115 lib = bpy.libraries.load('//file.blend') # open file.blend
116 pseudoOb = lib.objects.append('Cube')) # get an object wrapper
117 But this code will::
118 import bpy
119
120 scn= bpy.data.scenes.active # get current scene
121 lib = bpy.libraries.load('//file.blend') # open file.blend
122 pseudoOb = lib.objects.append('Cube')) # get an object wrapper
123 ob = scn.objects.link(pseudoOb) # link to scene
124 @rtype: Blender data
125 @return: return a Blender datablock or object
126 @raise IOError: library cannot be read
127 @raise ValueError: library does not contain B{name}
128 """
129
131 """
132 Link a new datablock from a library. The linked data is not copied
133 into the local .blend file.
134
135 See L{append} for notes on special handling of Blender Objects.
136 @rtype: Blender data
137 @return: return a Blender datablock or object
138 @raise IOError: library cannot be read
139 @raise ValueError: library does not contain B{name}
140 """
141