[img_data, info] = prepareImage(input_img [,'target_rect'] [,'max_dims'] [,'rescale'] [,'transparency'] [,'alpha_thresh'] [,'parent'] [,'rotate']) [] = optional parameters '' = parameter-value pairs
PREPAREIMAGE loads or validates an image matrix, and offers various optional image-related convenience features. For example, it can identify the rect describing the image as centered within a particular screen area, scales the size of this target rect up or down based on maximum image dimensions, and handle transparency.
img_data = prepareImage(input_img): when input_img is a filepath or URL to an image, this loads and returns image data from the file. When input_img is a numeric matrix of image data, this returns the matrix along with dimensions of the image. Image data can be either 2D (one channel/ greyscale) or color (typically 2Dx3 or 2Dx4). [img_data, target_rect] = prepareImage(input_img) is the same, but also provides a rectangle (in screen coordinates) in which the image may be inscribed. [img_data, target_rect, info] = prepareImage(input_img) is the same, but also returns a struct containing information about the image, such as the image dimensions, geometry, and alpha channel. [img_data, ...] = prepareImage(input_img,param1,val1,param2,val2...) sets various optional parameters. Parameters are case-insensitive, and each string parameter must be followed by a value as indicated: 'max_dims' Two-element array. A positive two-element array that describes the maximum dimensions of the image (e.g., screen resolution, or the size of a panel you want to fill). Default: [] (i.e, no resizing) 'rescale' Scalar. A scalar describing the multiple by which the image should be resized. For example, 2 would describe an image twice as wide and twice as tall as the source image. This parameter will be ignored if max_dims was also supplied. Default: 1 (i.e., no resizing) 'target_rect' Rect. A rect describing screen coordinate corners of an area in which the image should be centred, as in [left top right bottom]. If neither max_dims nor rescale are specified, max_dims will be obtained from the size of this rect, such that the image will fit inside of it. Default: nan (i.e., top-left) 'transparency' Scalar The image as a whole can be made partially tranparent. Set to 0 for complete opacity, 1 for complete transparency, to an intermediate value for partial opacity, or to nan to ignore this parameter. To use transparency information that is explicitly embedded in graphics already (such as in PNG's), leave this set to nan. Default: nan (i.e., not set) 'alpha_thresh' Scalar or three-element numeric array. A scalar between -1 and 1; zero indicates no transparency. Increasingly positive values will start setting the brightest pixels to transparent and working towards darker ones as the parameter approaches 1; negative values will set the darkest pixels to transparent and work towards brighter ones when approaching -1. This differs from opacity as these brightest/darkest pixels are made fully transparent, as opposed to partial transparency of the image as a whole. Brightness will be ascertained based on overall luminosity (average across color channels). Default: 0 (i.e., no transparency) 'parent' Window pointer. If you supply a Psychtoolbox window pointer, prepareImage will actually draw the image (make a texture, draw it, and close the texture) in the position described by target_rect. This just saves you some trouble: max_dims defaults to the window size if otherwise unspecified, and prepareImage will draw the image for you. If you plan to do anything mildly fancy with your images, e.g., reuse them, move them around or mess with their colors, you should omit this parameter and instead use the output of prepareImage with the Screen functions MakeTexture and DrawTexture. Default: nan 'rotate' Rotation to draw. If you will draw the image by supplying a parent, you can set this rotation parameter to rotate the image within the original square bounds. Range is -/+ 180 degrees. Default: 0
img_data: The image data as read from the supplied file. target_rect: A four-element array defining the pixels at the corners of the area where the image should be presented on the screen. info: A struct containing information about the image, such as its geometry.