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 Returns a list of paths used in the current blend file.
45
46 @type link: int
47 @param link: 0 (default if no args given) for all library paths, 1 for directly linked library paths only, 2 for indirectly linked library paths only.
48 @rtype: List
49 @return: return a list of path strings.
50 """
51
53 """
54 Replaces an existing directly linked path.
55
56 @type pathFrom: string
57 @param pathFrom: An existing library path.
58 @type pathTo: string
59 @param pathTo: A new library path.
60 """
61
63 """
64 The Library object
65 ==================
66 This class provides a unified way to access and manipulate library types
67 in Blender.
68 It provides access to scenes, objects, meshes, curves, metaballs,
69 materials, textures, images, lattices, lamps, cameras, ipos, worlds,
70 fonts, texts, sounds, groups, armatures, and actions.
71 @ivar filename: The filename of the library, as supplied by user.
72 @type filename: string
73 @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.
74 @type name: string
75 @ivar scenes: library L{scene<Scene.Scene>} data
76 @type scenes: L{LibData}
77 @ivar objects: library L{object<Object.Object>} data
78 @type objects: L{LibData}
79 @ivar meshes: library L{mesh<Mesh.Mesh>} data
80 @type meshes: L{LibData}
81 @ivar curves: library L{curve<Curve.Curve>} data
82 @type curves: L{LibData}
83 @ivar metaballs: library L{metaball<Metaball.Metaball>} data
84 @type metaballs: L{LibData}
85 @ivar materials: library L{material<Material.Material>} data
86 @type materials: L{LibData}
87 @ivar textures: library L{texture<Texture.Texture>} data
88 @type textures: L{LibData}
89 @ivar images: library L{image<Image.Image>} data
90 @type images: L{LibData}
91 @ivar lattices: library L{lattice<Lattice.Lattice>} data
92 @type lattices: L{LibData}
93 @ivar lamps: library L{lamp<Lamp.Lamp>} data
94 @type lamps: L{LibData}
95 @ivar cameras: library L{camera<Camera.Camera>} data
96 @type cameras: L{LibData}
97 @ivar ipos: library L{ipo<Ipo.Ipo>} data
98 @type ipos: L{LibData}
99 @ivar worlds: library L{world<World.World>} data
100 @type worlds: L{LibData}
101 @ivar fonts: library L{font<Font.Font>} data
102 @type fonts: L{LibData}
103 @ivar texts: library L{text<Text.Text>} data
104 @type texts: L{LibData}
105 @ivar sounds: library L{sound<Sound.Sound>} data
106 @type sounds: L{LibData}
107 @ivar groups: library L{group<Group.Group>} data
108 @type groups: L{LibData}
109 @ivar armatures: library L{armature<Armature.Armature>} data
110 @type armatures: L{LibData}
111 @ivar actions: library L{action<NLA.Action>} data
112 @type actions: L{LibData}
113 """
114
116 """
117 Generic Library Data Access
118 ===========================
119 This class provides access to a specific type of library data.
120 """
121
123 """
124 Append a new datablock from a library. The new copy
125 is added to the current .blend file.
126
127 B{Note}: Blender Objects cannot be appended or linked without linking
128 them to a scene. For this reason, lib.objects.append() returns a
129 special "wrapper object" which must be passed to Scene.objects.link()
130 or bpy.data.scenes.active.link() in order to actually create the object.
131 So the following code will not create a new object::
132 import bpy
133
134 scn= bpy.data.scenes.active # get current scene
135 lib = bpy.libraries.load('//file.blend') # open file.blend
136 pseudoOb = lib.objects.append('Cube')) # get an object wrapper
137 But this code will::
138 import bpy
139
140 scn= bpy.data.scenes.active # get current scene
141 lib = bpy.libraries.load('//file.blend') # open file.blend
142 pseudoOb = lib.objects.append('Cube')) # get an object wrapper
143 ob = scn.objects.link(pseudoOb) # link to scene
144 @rtype: Blender data
145 @return: return a Blender datablock or object
146 @raise IOError: library cannot be read
147 @raise ValueError: library does not contain B{name}
148 """
149
151 """
152 Link a new datablock from a library. The linked data is not copied
153 into the local .blend file.
154
155 See L{append} for notes on special handling of Blender Objects.
156 @rtype: Blender data
157 @return: return a Blender datablock or object
158 @raise IOError: library cannot be read
159 @raise ValueError: library does not contain B{name}
160 """
161