1 page.title=MonkeyImage 2 parent.title=monkeyrunner 3 parent.link=index.html 4 @jd:body 5 <style> 6 h4.jd-details-title {background-color: #DEE8F1;} 7 </style> 8 9 <p> 10 A monkeyrunner class to hold an image of the device or emulator's screen. The image is 11 copied from the screen buffer during a screenshot. This object's methods allow you to 12 convert the image into various storage formats, write the image to a file, copy parts of 13 the image, and compare this object to other <code>MonkeyImage</code> objects. 14 </p> 15 <p> 16 You do not need to create new instances of <code>MonkeyImage</code>. Instead, use 17 <code><a href="{@docRoot}tools/help/MonkeyDevice.html#takeSnapshot"> 18 MonkeyDevice.takeSnapshot()</a></code> to create a new instance from a screenshot. For example, use: 19 </p> 20 <pre> 21 newimage = MonkeyDevice.takeSnapshot() 22 </pre> 23 <h2>Summary</h2> 24 <table id="pubmethods" class="jd-sumtable"> 25 <tr> 26 <th colspan="12" style="background-color: #E2E2E2">Methods</th> 27 </tr> 28 <tr class="api" > 29 <td class="jd-typecol"> 30 <nobr> 31 <em>string</em> 32 </nobr> 33 </td> 34 <td class="jd-linkcol" width="100%"> 35 <nobr> 36 <span class="sympad"> 37 <a href="#convertToBytes">convertToBytes</a> 38 </span> 39 (<em>string</em> format) 40 </nobr> 41 <div class="jd-descrdiv"> 42 Converts the current image to a particular format and returns it as a 43 <em>string</em> that you can then access as an <em>iterable</em> of binary bytes. 44 </div> 45 </td> 46 </tr> 47 <tr class="api" > 48 <td class="jd-typecol"> 49 <nobr> 50 <em>tuple</em> 51 </nobr> 52 </td> 53 <td class="jd-linkcol" width="100%"> 54 <nobr> 55 <span class="sympad"> 56 <a href="#getRawPixel">getRawPixel</a> 57 </span> 58 (<em>integer</em> x, 59 <em>integer</em> y) 60 </nobr> 61 <div class="jd-descrdiv"> 62 Returns the single pixel at the image location (x,y), as an 63 a <em>tuple</em> of <em>integer</em>, in the form (a,r,g,b). 64 </div> 65 </td> 66 </tr> 67 <tr class="api" > 68 <td class="jd-typecol"> 69 <nobr> 70 <em>integer</em> 71 </nobr> 72 </td> 73 <td class="jd-linkcol" width="100%"> 74 <nobr> 75 <span class="sympad"> 76 <a href="#getRawPixelInt">getRawPixelInt</a> 77 </span> 78 (<em>integer</em> x, 79 <em>integer</em> y) 80 </nobr> 81 <div class="jd-descrdiv"> 82 Returns the single pixel at the image location (x,y), as 83 a 32-bit <em>integer</em>. 84 </div> 85 </td> 86 </tr> 87 <tr class="api" > 88 <td class="jd-typecol"> 89 <nobr> 90 <code> 91 <a href="{@docRoot}tools/help/MonkeyImage.html">MonkeyImage</a> 92 </code> 93 </nobr> 94 </td> 95 <td class="jd-linkcol" width="100%"> 96 <nobr> 97 <span class="sympad"> 98 <a href="#getSubImage">getSubImage</a> 99 </span> 100 (<em>tuple</em> rect) 101 </nobr> 102 <div class="jd-descrdiv"> 103 Creates a new <code>MonkeyImage</code> object from a rectangular selection of the 104 current image. 105 </div> 106 </td> 107 </tr> 108 <tr class="api" > 109 <td class="jd-typecol"> 110 <nobr> 111 <em>boolean</em> 112 </nobr> 113 </td> 114 <td class="jd-linkcol" width="100%"> 115 <nobr> 116 <span class="sympad"> 117 <a href="#sameAs">sameAs</a> 118 </span> 119 (<code><a href="{@docRoot}tools/help/MonkeyImage.html">MonkeyImage</a></code> 120 other, 121 <em>float</em> percent) 122 </nobr> 123 <div class="jd-descrdiv"> 124 Compares this <code>MonkeyImage</code> object to another and returns the result of 125 the comparison. The <code>percent</code> argument specifies the percentage 126 difference that is allowed for the two images to be "equal". 127 </div> 128 </td> 129 </tr> 130 <tr class="api" > 131 <td class="jd-typecol"> 132 <nobr> 133 <em>void</em> 134 </nobr> 135 </td> 136 <td class="jd-linkcol" width="100%"> 137 <nobr> 138 <span class="sympad"> 139 <a href="#writeToFile">writeToFile</a> 140 </span> 141 (<em>string</em> path, 142 <em>string</em> format) 143 </nobr> 144 <div class="jd-descrdiv"> 145 Writes the current image to the file specified by <code>filename</code>, in the 146 format specified by <code>format</code>. 147 </div> 148 </td> 149 </tr> 150 </table> 151 <!-- ========= METHOD DETAIL ======== --> 152 <!-- Public methods --> 153 <h2>Public Methods</h2> 154 <A NAME="convertToBytes"></A> 155 <div class="jd-details api "> 156 <h4 class="jd-details-title"> 157 <span class="normal"> 158 <em>string</em> 159 </span> 160 <span class="sympad">convertToBytes</span> 161 <span class="normal"> 162 ( 163 <em>string</em> format) 164 </span> 165 </h4> 166 <div class="jd-details-descr"> 167 168 <div class="jd-tagdata jd-tagdescr"> 169 <p> 170 Converts the current image to a particular format and returns it as a <em>string</em> 171 that you can then access as an <em>iterable</em> of binary bytes. 172 </p> 173 </div> 174 <div class="jd-tagdata"> 175 <h5 class="jd-tagtitle">Arguments</h5> 176 <table class="jd-tagtable"> 177 <tr> 178 <th>format</th> 179 <td> 180 The desired output format. All of the common raster output formats are supported. 181 The default value is "png" (Portable Network Graphics). 182 </td> 183 </tr> 184 </table> 185 </div> 186 </div> 187 </div> 188 <A NAME="getRawPixel"></A> 189 <div class="jd-details api "> 190 <h4 class="jd-details-title"> 191 <span class="normal"> 192 <em>tuple</em> 193 </span> 194 <span class="sympad">getRawPixel</span> 195 <span class="normal"> 196 (<em>integer</em> x, 197 <em>integer</em> y) 198 </span> 199 </h4> 200 <div class="jd-details-descr"> 201 202 <div class="jd-tagdata jd-tagdescr"> 203 <p> 204 Returns the single pixel at the image location (x,y), as an 205 a <em>tuple</em> of <em>integer</em>, in the form (a,r,g,b). 206 </p> 207 </div> 208 <div class="jd-tagdata"> 209 <h5 class="jd-tagtitle">Arguments</h5> 210 <table class="jd-tagtable"> 211 <tr> 212 <th>x</th> 213 <td> 214 The horizontal position of the pixel, starting with 0 at the left of the screen in the 215 orientation it had when the screenshot was taken. 216 </td> 217 </tr> 218 <tr> 219 <th>y</th> 220 <td> 221 The vertical position of the pixel, starting with 0 at the top of the screen in the 222 orientation it had when the screenshot was taken. 223 </td> 224 </tr> 225 </table> 226 </div> 227 <div class="jd-tagdata"> 228 <h5 class="jd-tagtitle">Returns</h5> 229 <ul class="nolist"> 230 <li> 231 A tuple of integers representing the pixel, in the form (a,r,g,b) where 232 a is the alpha channel value, and r, g, and b are the red, green, and blue values, 233 respectively. 234 </li> 235 </ul> 236 </div> 237 </div> 238 </div> 239 <A NAME="getRawPixelInt"></A> 240 <div class="jd-details api "> 241 <h4 class="jd-details-title"> 242 <span class="normal"> 243 <em>tuple</em> 244 </span> 245 <span class="sympad">getRawPixelInt</span> 246 <span class="normal"> 247 (<em>integer</em> x, 248 <em>integer</em> y) 249 </span> 250 </h4> 251 <div class="jd-details-descr"> 252 253 <div class="jd-tagdata jd-tagdescr"> 254 <p> 255 Returns the single pixel at the image location (x,y), as an 256 an <em>integer</em>. Use this method to economize on memory. 257 </p> 258 </div> 259 <div class="jd-tagdata"> 260 <h5 class="jd-tagtitle">Arguments</h5> 261 <table class="jd-tagtable"> 262 <tr> 263 <th>x</th> 264 <td> 265 The horizontal position of the pixel, starting with 0 at the left of the screen in the 266 orientation it had when the screenshot was taken. 267 </td> 268 </tr> 269 <tr> 270 <th>y</th> 271 <td> 272 The vertical position of the pixel, starting with 0 at the top of the screen in the 273 orientation it had when the screenshot was taken. 274 </td> 275 </tr> 276 </table> 277 </div> 278 <div class="jd-tagdata"> 279 <h5 class="jd-tagtitle">Returns</h5> 280 <ul class="nolist"> 281 <li> 282 The a,r,g, and b values of the pixel as 8-bit values combined into a 32-bit 283 integer, with a as the leftmost 8 bits, r the next rightmost, and so forth. 284 </li> 285 </ul> 286 </div> 287 </div> 288 </div> 289 <A NAME="getSubImage"></A> 290 <div class="jd-details api "> 291 <h4 class="jd-details-title"> 292 <span class="normal"> 293 <code> 294 <a href="{@docRoot}tools/help/MonkeyImage.html">MonkeyImage</a> 295 </code> 296 </span> 297 <span class="sympad">getSubImage</span> 298 <span class="normal"> 299 (<em>tuple</em> rect) 300 </span> 301 </h4> 302 <div class="jd-details-descr"> 303 304 <div class="jd-tagdata jd-tagdescr"> 305 <p> 306 Creates a new <code>MonkeyImage</code> object from a rectangular selection of the 307 current image. 308 </p> 309 </div> 310 <div class="jd-tagdata"> 311 <h5 class="jd-tagtitle">Arguments</h5> 312 <table class="jd-tagtable"> 313 <tr> 314 <th>rect</th> 315 <td> 316 A tuple (x, y, w, h) specifying the selection. x and y specify the 0-based pixel 317 position of the upper left-hand corner of the selection. w specifies the width of the 318 region, and h specifies its height, both in units of pixels. 319 <p> 320 The image's orientation is the same as the screen orientation at the time the 321 screenshot was made. 322 </p> 323 </td> 324 </tr> 325 </table> 326 </div> 327 <div class="jd-tagdata"> 328 <h5 class="jd-tagtitle">Returns</h5> 329 <ul class="nolist"> 330 <li> 331 A new <code>MonkeyImage</code> object containing the selection. 332 </li> 333 </ul> 334 </div> 335 </div> 336 </div> 337 <A NAME="sameAs"></A> 338 <div class="jd-details api "> 339 <h4 class="jd-details-title"> 340 <span class="normal"> 341 <em>boolean</em> 342 </span> 343 <span class="sympad">sameAs</span> 344 <span class="normal"> 345 ( 346 <code> 347 <a href="{@docRoot}tools/help/MonkeyImage.html">MonkeyImage</a> 348 </code> otherImage, 349 <em>float</em> percent 350 ) 351 </span> 352 </h4> 353 <div class="jd-details-descr"> 354 355 <div class="jd-tagdata jd-tagdescr"> 356 <p> 357 Compares this <code>MonkeyImage</code> object to another and returns the result of 358 the comparison. The <code>percent</code> argument specifies the percentage 359 difference that is allowed for the two images to be "equal". 360 </p> 361 </div> 362 <div class="jd-tagdata"> 363 <h5 class="jd-tagtitle">Arguments</h5> 364 <table class="jd-tagtable"> 365 <tr> 366 <th>other</th> 367 <td> 368 Another <code>MonkeyImage</code> object to compare to this one. 369 </td> 370 </tr> 371 <tr> 372 <th> 373 percent 374 </th> 375 <td> 376 A float in the range 0.0 to 1.0, inclusive, indicating 377 the percentage of pixels that need to be the same for the method to return 378 <code>true</code>. The default is 1.0, indicating that all the pixels 379 must match. 380 </td> 381 </tr> 382 </table> 383 </div> 384 <div class="jd-tagdata"> 385 <h5 class="jd-tagtitle">Returns</h5> 386 <ul class="nolist"> 387 <li> 388 Boolean <code>true</code> if the images match, or boolean <code>false</code> otherwise. 389 </li> 390 </ul> 391 </div> 392 </div> 393 </div> 394 <A NAME="writeToFile"></A> 395 <div class="jd-details api "> 396 <h4 class="jd-details-title"> 397 <span class="normal"> 398 void 399 </span> 400 <span class="sympad">writeToFile</span> 401 <span class="normal"> 402 (<em>string</em> filename, 403 <em>string</em> format) 404 </span> 405 </h4> 406 <div class="jd-details-descr"> 407 408 <div class="jd-tagdata jd-tagdescr"> 409 <p> 410 Writes the current image to the file specified by <code>filename</code>, in the 411 format specified by <code>format</code>. 412 </p> 413 </div> 414 <div class="jd-tagdata"> 415 <h5 class="jd-tagtitle">Arguments</h5> 416 <table class="jd-tagtable"> 417 <tr> 418 <th>path</th> 419 <td> 420 The fully-qualified filename and extension of the output file. 421 </td> 422 </tr> 423 <tr> 424 <th> 425 format 426 </th> 427 <td> 428 The output format to use for the file. If no format is provided, then the 429 method tries to guess the format from the filename's extension. If no 430 extension is provided and no format is specified, then the default format of 431 "png" (Portable Network Graphics) is used. 432 </td> 433 </tr> 434 </table> 435 </div> 436 </div> 437 </div> 438
