added id_attributes.py, this containes ID doc strings, all datablocks that have use...
[blender.git] / source / blender / python / api2_2x / doc / Lattice.py
1 # Blender.Lattice module and the Lattice PyType object
2
3 """
4 The Blender.Lattice submodule.
5
6 Lattice Object
7 ==============
8
9 This module provides access to B{Lattice} object in Blender.
10
11 Example::
12         import Blender
13         from Blender import Lattice, Object, Scene, Modifier
14
15         # Make new lattice data
16         lattice_data = Lattice.New()
17         lattice_data.setPartitions(5,5,5)
18         lattice_data.setKeyTypes(Lattice.LINEAR, Lattice.CARDINAL, Lattice.BSPLINE)
19         lattice_data.setMode(Lattice.OUTSIDE)
20
21         for y in range(125):
22                 vec = lattice_data.getPoint(y)
23                 co1 = vec[0] + vec[0] / 5
24                 co2 = vec[1] - vec[2] * 0.3
25                 co3 = vec[2] * 3
26                 lattice_data.setPoint(y,[co1,co2,co3])
27         
28         # Create a new object from the lattice in the current scene
29         scn = Scene.GetCurrent()
30         ob_lattice = scn.objects.new(lattice_data)
31         
32         # Get an object to deform with this lattice
33         mySphere = Object.Get('Sphere')
34
35         # Apply lattice modifier
36         mod= mySphere.modifiers.append(Modifier.Type.LATTICE)
37         mod[Modifier.Settings.OBJECT] = ob_lattice
38         mySphere.makeDisplayList()
39
40         Blender.Redraw()
41 """
42
43 def New (name = None):
44         """
45         Create a new Lattice object.
46         Passing a name to this function will name the Lattice
47         datablock, otherwise the Lattice data will be given a 
48         default name.
49         @type name: string
50         @param name: The Lattice name.
51         @rtype: Blender Lattice
52         @return: The created Lattice Data object.
53         """
54
55 def Get (name = None):
56         """
57         Get the Lattice object(s) from Blender.
58         @type name: string
59         @param name: The name of the Lattice object.
60         @rtype: Blender Lattice or a list of Blender Lattices
61         @return: It depends on the 'name' parameter:
62                         - (name): The Lattice object with the given name;
63                         - ():     A list with all Lattice objects in the current scene.
64         """
65
66 class Lattice:
67         """
68         The Lattice object
69         ==================
70                 This object gives access to Lattices in Blender.
71         @ivar width: The number of x dimension partitions.
72         @ivar height: The number of y dimension partitions.
73         @ivar depth: The number of z dimension partitions.
74         @ivar widthType: The x dimension key type.
75         @ivar heightType: The y dimension key type.
76         @ivar depthType: The z dimension key type.
77         @ivar mode: The current mode of the Lattice.
78         @ivar latSize: The number of points in this Lattice (width*height*depth).
79         @cvar key: The L{Key.Key} object associated with this Lattice or None.
80         """
81
82         def getName():
83                 """
84                 Get the name of this Lattice datablock.
85                 @rtype: string
86                 @return: The name of the Lattice datablock.
87                 """
88
89         def setName(name):
90                 """
91                 Set the name of this Lattice datablock.
92                 @type name: string
93                 @param name: The new name.
94                 """
95
96         def getPartitions():
97                 """
98                 Gets the number of 'walls' or partitions that the Lattice has 
99                 in the x, y, and z dimensions.
100                 @rtype: list of ints
101                 @return: A list corresponding to the number of partitions: [x,y,z]
102                 """
103
104         def setPartitions(x,y,z):
105                 """
106                 Set the number of 'walls' or partitions that the 
107                 Lattice will be created with in the x, y, and z dimensions.
108                 @type x: int
109                 @param x: The number of partitions in the x dimension of the Lattice.
110                 @type y: int
111                 @param y: The number of partitions in the y dimension of the Lattice.
112                 @type z: int
113                 @param z: The number of partitions in the z dimension of the Lattice.
114                 """
115
116         def getKeyTypes():
117                 """
118                 Returns the deformation key types for the x, y, and z dimensions of the
119                 Lattice.
120                 @rtype: list of strings
121                 @return: A list corresponding to the key types will be returned: [x,y,z]
122                 """
123
124         def setKeyTypes(xType,yType,zType):
125                 """
126                 Sets the deformation key types for the x, y, and z dimensions of the
127                 Lattice.
128                 There are three key types possible:
129                         -  Lattice.CARDINAL
130                         -  Lattice.LINEAR
131                         -  Lattice.BSPLINE
132                 @type xType: enum constant
133                 @param xType: the deformation key type for the x dimension of the Lattice
134                 @type yType: enum constant
135                 @param yType: the deformation key type for the y dimension of the Lattice
136                 @type zType: enum constant
137                 @param zType: the deformation key type for the z dimension of the Lattice
138                 """
139
140         def getMode():
141                 """
142                 Returns the current Lattice mode
143                 @rtype: string
144                 @return: A string representing the current Lattice mode
145                 """
146
147         def setMode(modeType):
148                 """
149                 Sets the current Lattice mode
150                 There are two Lattice modes possible:
151                         -  Lattice.GRID
152                         -  Lattice.OUTSIDE
153                 @type modeType: enum constant
154                 @param modeType: the Lattice mode
155                 """
156
157         def getPoint(index):
158                 """
159                 Returns the coordinates of a point in the Lattice by index.
160                 @type index: int
161                 @param index: The index of the point on the Lattice you want returned
162                 @rtype: list of floats
163                 @return: The x,y,z coordiates of the Lattice point : [x,y,z]
164                 """
165
166         def setPoint(index, position):
167                 """
168                 Sets the coordinates of a point in the Lattice by index.
169                 @type index: int
170                 @param index: The index of the point on the Lattice you want set
171                 @type position: list of floats
172                 @param position: The x,y,z coordinates that you want the point to be: [x,y,z]
173                 """
174
175         def getKey():
176                 """
177                 Returns the L{Key.Key} object associated with this Lattice.
178                 @rtype: L{Key.Key}
179                 @return: A key object representing the keyframes of the lattice or None.
180                 """
181
182         def insertKey(frame):
183                 """
184                 Inserts the current state of the Lattice as a new absolute keyframe
185
186                 B{Example}::
187                         for z in range(5):
188                                 for y in range(125):
189                                         vec = myLat.getPoint(y)
190                                         co1 = vec[0] + vec[2]
191                                         co2 = vec[1] - vec[2]
192                                         co3 = vec[2] + vec[1]
193                                         myLat.setPoint(y,[co1,co2,co3])
194                                 w = (z + 1) * 10
195                                 myLat.insertKey(w)
196
197                 @type frame: int
198                 @param frame: the frame at which the Lattice will be set as a keyframe
199                 """
200
201         def __copy__ ():
202                 """
203                 Make a copy of this lattice
204                 @rtype: Lattice
205                 @return:  a copy of this lattice
206                 """
207
208 import id_generics
209 Lattice.__doc__ += id_generics.attributes