Module Image

Source Code for Module Image

  1  # Blender.Image module and the Image PyType object 
  2   
  3  """ 
  4  The Blender.Image submodule. 
  5   
  6  Image 
  7  ===== 
  8   
  9  B{New}: L{Image.clampX}, L{Image.clampY}. 
 10   
 11  This module provides access to B{Image} objects in Blender. 
 12   
 13  Example:: 
 14          import Blender 
 15          from Blender import Image 
 16          # 
 17          image = Image.Load("/path/to/my/image.png")    # load an image file 
 18          print "Image from", image.getFilename(), 
 19          print "loaded to obj", image.getName()) 
 20          image.setXRep(4)                               # set x tiling factor 
 21          image.setYRep(2)                               # set y tiling factor 
 22          print "All Images available now:", Image.Get() 
 23   
 24  @type Sources: readonly dictionary 
 25  @var Sources: The available Image Source. 
 26                  - STILL: Single image file 
 27                  - MOVIE: Movie file 
 28                  - SEQUENCE: Multiple image files, as sequence 
 29                  - GENERATED: Generated image 
 30  """ 
 31   
32 -def Load (filename):
33 """ 34 Load the image called 'filename' into an Image object. 35 @type filename: string 36 @param filename: The full path to the image file. 37 @rtype: Blender Image 38 @return: A Blender Image object with the data from I{filename}. 39 """
40
41 -def New (name, width, height, depth):
42 """ 43 Create a new Image object. 44 @type name: string 45 @param name: The name of the new Image object. 46 @type width: int 47 @param width: The width of the new Image object, between 1 and 5000. 48 @type height: int 49 @param height: The height of the new Image object, between 1 and 5000. 50 @type depth: int 51 @param depth: The color depth of the new Image object. (32:RGBA 8bit channels, 128:RGBA 32bit high dynamic range float channels). 52 @rtype: Blender Image 53 @return: A new Blender Image object. 54 """
55
56 -def Get (name = None):
57 """ 58 Get the Image object(s) from Blender. 59 @type name: string 60 @param name: The name of the Image object. 61 @rtype: Blender Image or a list of Blender Images 62 @return: It depends on the I{name} parameter: 63 - (name): The Image object called I{name}, None if not found; 64 - (): A list with all Image objects in the current scene. 65 """
66
67 -def GetCurrent ():
68 """ 69 Get the currently displayed Image from Blenders UV/Image window. 70 When multiple images are displayed, the last active UV/Image windows image is used. 71 @rtype: Blender Image 72 @return: The Current Blender Image, If there is no current image it returns None. 73 """
74 75 from IDProp import IDGroup, IDArray
76 -class Image:
77 """ 78 The Image object 79 ================ 80 This object gives access to Images in Blender. 81 @ivar filename: The filename (path) to the image file loaded into this Image 82 object. 83 @type filename: string 84 @ivar size: The [width, height] dimensions of the image (in pixels). 85 @type size: list 86 @ivar depth: The pixel depth of the image, read only. [8, 16, 18, 24, 32, 128 (for 32bit float color channels)] 87 @type depth: int 88 @ivar xrep: Texture tiling: the number of repetitions in the x (horizontal) 89 axis. [1, 16]. 90 @ivar yrep: Texture tiling: the number of repetitions in the y (vertical) 91 axis [1, 16]. 92 @type xrep: int 93 @type yrep: int 94 @ivar start: Texture's animation start frame [0, 128]. 95 @type start: int 96 @ivar end: Texture's animation end frame [0, 128]. 97 @type end: int 98 @ivar speed: Texture's animation speed [1, 100]. 99 @type speed: int 100 @ivar packed: True when the Texture is packed (readonly). 101 @type packed: boolean 102 @ivar has_data: True when the image has pixel data (readonly). 103 @type has_data: boolean 104 @ivar fields: enable or disable the fields option for this image. 105 @type fields: boolean 106 @ivar fields_odd: enable or disable the odd fields option for this image. 107 @type fields_odd: boolean 108 @ivar antialias: enable or disable the antialias option for this image. 109 @type antialias: boolean 110 @ivar bindcode: Texture's bind code (readonly). 111 @type bindcode: int 112 @ivar source: Image source type. See L{the Sources dictionary<Sources>} . 113 @type source: int 114 @ivar clampX: When true the image will not tile horizontally. 115 @type clampX: bool 116 @ivar clampY: When true the image will not tile vertically. 117 @type clampY: bool 118 """ 119
120 - def getName():
121 """ 122 Get the name of this Image object. 123 @rtype: string 124 """
125
126 - def getFilename():
127 """ 128 Get the filename of the image file loaded into this Image object. 129 @rtype: string 130 """
131
132 - def getSize():
133 """ 134 Get the [width, height] dimensions (in pixels) of this image. 135 @rtype: list of 2 ints 136 """
137
138 - def getDepth():
139 """ 140 Get the pixel depth of this image. [8,16,24,32,128 for 32bit float images] 141 @rtype: int 142 """
143
144 - def getPixelHDR(x, y):
145 """ 146 Get the the colors of the current pixel in the form [r,g,b,a]. 147 For float image types, returned values can be greater then the useual [0.0, 1.0] range. 148 Pixel coordinates are in the range from 0 to N-1. See L{getMaxXY} 149 @returns: [ r, g, b, a] 150 @rtype: list of 4 floats 151 @type x: int 152 @type y: int 153 @param x: the x coordinate of pixel. 154 @param y: the y coordinate of pixel. 155 """
156
157 - def getPixelF(x, y):
158 """ 159 Get the the colors of the current pixel in the form [r,g,b,a]. 160 Returned values are floats normalized to 0.0 - 1.0. 161 Pixel coordinates are in the range from 0 to N-1. See L{getMaxXY} 162 @returns: [ r, g, b, a] 163 @rtype: list of 4 floats 164 @type x: int 165 @type y: int 166 @param x: the x coordinate of pixel. 167 @param y: the y coordinate of pixel. 168 """
169
170 - def getPixelI(x, y):
171 """ 172 Get the the colors of the current pixel in the form [r,g,b,a]. 173 Returned values are ints normalized to 0 - 255. 174 Pixel coordinates are in the range from 0 to N-1. See L{getMaxXY} 175 @returns: [ r, g, b, a] 176 @rtype: list of 4 ints 177 @type x: int 178 @type y: int 179 @param x: the x coordinate of pixel. 180 @param y: the y coordinate of pixel. 181 """
182
183 - def getMaxXY():
184 """ 185 Get the x & y size for the image. Image coordinates range from 0 to size-1. 186 @returns: [x, y] 187 @rtype: list of 2 ints 188 """
189
190 - def getMinXY():
191 """ 192 Get the x & y origin for the image. Image coordinates range from 0 to size-1. 193 @returns: [x, y] 194 @rtype: list of 2 ints 195 """
196
197 - def getXRep():
198 """ 199 Get the number of repetitions in the x (horizontal) axis for this Image. 200 This is for texture tiling. 201 @rtype: int 202 """
203
204 - def getYRep():
205 """ 206 Get the number of repetitions in the y (vertical) axis for this Image. 207 This is for texture tiling. 208 @rtype: int 209 """
210
211 - def getBindCode():
212 """ 213 Get the Image's bindcode. This is for texture loading using BGL calls. 214 See, for example, L{BGL.glBindTexture} and L{glLoad}. 215 @rtype: int 216 """
217
218 - def getStart():
219 """ 220 Get the Image's start frame. Used for animated textures. 221 @rtype: int 222 """
223
224 - def getEnd():
225 """ 226 Get the Image's end frame. Used for animated textures. 227 @rtype: int 228 """
229
230 - def getSpeed():
231 """ 232 Get the Image's speed (fps). Used for animated textures. 233 @rtype: int 234 """
235
236 - def reload():
237 """ 238 Reloads this image from the filesystem. If used within a loop you need to 239 redraw the Window to see the change in the image, e.g. with 240 Window.RedrawAll(). 241 @warn: if the image file is corrupt or still being written, it will be 242 replaced by a blank image in Blender, but no error will be returned. 243 @returns: None 244 """
245
246 - def updateDisplay():
247 """ 248 Update the display image from the floating point buffer (if it exists) 249 @returns: None 250 """
251
252 - def glLoad():
253 """ 254 Load this image's data into OpenGL texture memory, if it is not already 255 loaded (image.bindcode is 0 if it is not loaded yet). 256 @note: Usually you don't need to call this method. It is only necessary 257 if you want to draw textured objects in the Scripts window and the 258 image's bind code is zero at that moment, otherwise Blender itself can 259 take care of binding / unbinding textures. Calling this method for an 260 image with nonzero bind code simply returns the image's bind code value 261 (see L{getBindCode}). 262 @rtype: int 263 @returns: the texture's bind code. 264 """
265
266 - def glFree():
267 """ 268 Delete this image's data from OpenGL texture memory, only (the image itself 269 is not removed from Blender's memory). Internally, glDeleteTextures (see 270 L{BGL.glDeleteTextures}) is used, but this method also updates Blender's 271 Image object so that its bind code is set to 0. See also L{Image.glLoad}, 272 L{Image.getBindCode}. 273 """
274
275 - def setName(name):
276 """ 277 Set the name of this Image object. 278 @type name: string 279 @param name: The new name. 280 """
281
282 - def setFilename(name):
283 """ 284 Change the filename of this Image object. 285 @type name: string 286 @param name: The new full filename. 287 @warn: use this with caution and note that the filename is truncated if 288 larger than 160 characters. 289 """
290
291 - def setXRep(xrep):
292 """ 293 Texture tiling: set the number of x repetitions for this Image. 294 @type xrep: int 295 @param xrep: The new value in [1, 16]. 296 """
297
298 - def setYRep(yrep):
299 """ 300 Texture tiling: set the number of y repetitions for this Image. 301 @type yrep: int 302 @param yrep: The new value in [1, 16]. 303 """
304
305 - def setStart(start):
306 """ 307 Get the Image's start frame. Used for animated textures. 308 @type start: int 309 @param start: The new value in [0, 128]. 310 """
311
312 - def setEnd(end):
313 """ 314 Set the Image's end frame. Used for animated textures. 315 @type end: int 316 @param end: The new value in [0, 128]. 317 """
318
319 - def setSpeed(speed):
320 """ 321 Set the Image's speed (fps). Used for animated textures. 322 @type speed: int 323 @param speed: The new value in [1, 100]. 324 """
325
326 - def setPixelHDR(x, y, (r, g, b,a )):
327 """ 328 Set the the colors of the current pixel in the form [r,g,b,a]. 329 For float image types, returned values can be greater then the useual [0.0, 1.0] range. 330 Pixel coordinates are in the range from 0 to N-1. See L{getMaxXY} 331 @type x: int 332 @type y: int 333 @type r: float 334 @type g: float 335 @type b: float 336 @type a: float 337 @returns: nothing 338 @rtype: none 339 """
340
341 - def setPixelF(x, y, (r, g, b,a )):
342 """ 343 Set the the colors of the current pixel in the form [r,g,b,a]. 344 Color values must be floats in the range 0.0 - 1.0. 345 Pixel coordinates are in the range from 0 to N-1. See L{getMaxXY} 346 @type x: int 347 @type y: int 348 @type r: float 349 @type g: float 350 @type b: float 351 @type a: float 352 @returns: nothing 353 @rtype: none 354 """
355
356 - def setPixelI(x, y, (r, g, b, a)):
357 """ 358 Set the the colors of the current pixel in the form [r,g,b,a]. 359 Color values must be ints in the range 0 - 255. 360 Pixel coordinates are in the range from 0 to N-1. See L{getMaxXY} 361 @type x: int 362 @type y: int 363 @type r: int 364 @type g: int 365 @type b: int 366 @type a: int 367 @returns: nothing 368 @rtype: none 369 """
370
371 - def save():
372 """ 373 Saves the current image to L{filename} 374 @note: Saving to a directory that doent exist will raise an error. 375 @note: Saving a packed image will make a unique (numbered) name if the file alredy exists. Remove the file first to be sure it will not be renamed. 376 @returns: None 377 """
378
379 - def pack():
380 """ 381 Packs the image into the current blend file. 382 383 Since 2.44 new images without valid filenames can be packed. 384 385 If the image is alredy packed, it will be repacked. 386 387 @returns: nothing 388 @rtype: none 389 """
390
391 - def unpack(mode):
392 """ 393 Unpacks the image to the images filename. 394 @param mode: One of the values in L{Blender.UnpackModes}. 395 @note: An error will be raised if the image is not packed or the filename path does not exist. 396 @returns: nothing 397 @rtype: none 398 @type mode: int 399 """
400 - def makeCurrent():
401 """ 402 Set the currently displayed Image from Blenders UV/Image window. 403 When multiple images are displayed, the last active UV/Image windows image is used. 404 @warn: Deprecated, set bpy.data.images.active = image instead. 405 @rtype: bool 406 @return: True if the current image could be set, if no window was available, return False. 407 """
408 import id_generics 409 Image.__doc__ += id_generics.attributes 410