tests/phpunit/includes/api/RandomImageGenerator.php

   1 <?php
   2
   3 /*
   4  * RandomImageGenerator -- does what it says on the tin.
   5  * Requires Imagick, the ImageMagick library for PHP, or the command line equivalent (usually 'convert').
   6  *
   7  * Because MediaWiki tests the uniqueness of media upload content, and filenames, it is sometimes useful to generate
   8  * files that are guaranteed (or at least very likely) to be unique in both those ways.
   9  * This generates a number of filenames with random names and random content (colored triangles)
  10  *
  11  * It is also useful to have fresh content because our tests currently run in a "destructive" mode, and don't create a fresh new wiki for each
  12  * test run.
  13  * Consequently, if we just had a few static files we kept re-uploading, we'd get lots of warnings about matching content or filenames,
  14  * and even if we deleted those files, we'd get warnings about archived files.
  15  *
  16  * This can also be used with a cronjob to generate random files all the time -- I use it to have a constant, never ending supply when I'm
  17  * testing interactively.
  18  *
  19  * @file
  20  * @author Neil Kandalgaonkar <neilk@wikimedia.org>
  21  */
  22
  23 /**
  24  * RandomImageGenerator: does what it says on the tin.
  25  * Can fetch a random image, or also write a number of them to disk with random filenames.
  26  */
  27 class RandomImageGenerator {
  28
  29         private $dictionaryFile;
  30         private $minWidth = 400;
  31         private $maxWidth = 800;
  32         private $minHeight = 400;
  33         private $maxHeight = 800;
  34         private $shapesToDraw = 5;
  35         private $imageWriteMethod;
  36
  37         /**
  38          * Orientations: 0th row, 0th column, EXIF orientation code, rotation 2x2 matrix that is opposite of orientation
  39          * n.b. we do not handle the 'flipped' orientations, which is why there is no entry for 2, 4, 5, or 7. Those
  40          * seem to be rare in real images anyway
  41          * (we also would need a non-symmetric shape for the images to test those, like a letter F)
  42          */
  43         private static $orientations = array(
  44                 array(
  45                         '0thRow' => 'top',
  46                         '0thCol' => 'left',
  47                         'exifCode' => 1,
  48                         'counterRotation' => array( array( 1, 0 ), array( 0, 1 ) )
  49                 ),
  50                 array(
  51                         '0thRow' => 'bottom',
  52                         '0thCol' => 'right',
  53                         'exifCode' => 3,
  54                         'counterRotation' => array( array( -1, 0 ), array( 0, -1 ) )
  55                 ),
  56                 array(
  57                         '0thRow' => 'right',
  58                         '0thCol' => 'top',
  59                         'exifCode' => 6,
  60                         'counterRotation' => array( array( 0, 1 ), array( 1, 0 ) )
  61                 ),
  62                 array(
  63                         '0thRow' => 'left',
  64                         '0thCol' => 'bottom',
  65                         'exifCode' => 8,
  66                         'counterRotation' => array( array( 0, -1 ), array( -1, 0 ) )
  67                 )
  68         );
  69
  70
  71         public function __construct( $options = array() ) {
  72                 foreach ( array( 'dictionaryFile', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight', 'shapesToDraw' ) as $property ) {
  73                         if ( isset( $options[$property] ) ) {
  74                                 $this->$property = $options[$property];
  75                         }
  76                 }
  77
  78                 // find the dictionary file, to generate random names
  79                 if ( !isset( $this->dictionaryFile ) ) {
  80                         foreach ( array(
  81                                         '/usr/share/dict/words',
  82                                         '/usr/dict/words',
  83                                         dirname( __FILE__ ) . '/words.txt' )
  84                                         as $dictionaryFile ) {
  85                                 if ( is_file( $dictionaryFile ) and is_readable( $dictionaryFile ) ) {
  86                                         $this->dictionaryFile = $dictionaryFile;
  87                                         break;
  88                                 }
  89                         }
  90                 }
  91                 if ( !isset( $this->dictionaryFile ) ) {
  92                         throw new Exception( "RandomImageGenerator: dictionary file not found or not specified properly" );
  93                 }
  94
  95                 if ( !class_exists( 'Imagick' ) ) {
  96                         throw new Exception( 'No Imagick extension' );
  97                 }
  98                 global $wgExiv2Command;
  99                 if ( !$wgExiv2Command || !is_executable( $wgExiv2Command ) ) {
 100                         throw new Exception( 'exiv2 not executable or $wgExiv2Command not set' );
 101                 }
 102         }
 103
 104         /**
 105          * Writes random images with random filenames to disk in the directory you specify, or current working directory
 106          *
 107          * @param $number Integer: number of filenames to write
 108          * @param $format String: optional, must be understood by ImageMagick, such as 'jpg' or 'gif'
 109          * @param $dir String: directory, optional (will default to current working directory)
 110          * @return Array: filenames we just wrote
 111          */
 112         function writeImages( $number, $format = 'jpg', $dir = null ) {
 113                 $filenames = $this->getRandomFilenames( $number, $format, $dir );
 114                 $imageWriteMethod = $this->getImageWriteMethod( $format );
 115                 foreach( $filenames as $filename ) {
 116                         $this->{$imageWriteMethod}( $this->getImageSpec(), $format, $filename );
 117                 }
 118                 return $filenames;
 119         }
 120
 121
 122         /**
 123          * Figure out how we write images. This is a factor of both format and the local system
 124          * @param $format (a typical extension like 'svg', 'jpg', etc.)
 125          */
 126         function getImageWriteMethod( $format ) {
 127                 global $wgUseImageMagick, $wgImageMagickConvertCommand;
 128                 if ( $format === 'svg' ) {
 129                         return 'writeSvg';
 130                 } else {
 131                         // figure out how to write images
 132                         if ( class_exists( 'Imagick' ) ) {
 133                                 return 'writeImageWithApi';
 134                         } elseif ( $wgUseImageMagick && $wgImageMagickConvertCommand && is_executable( $wgImageMagickConvertCommand ) ) {
 135                                 return 'writeImageWithCommandLine';
 136                         }
 137                 }
 138                 throw new Exception( "RandomImageGenerator: could not find a suitable method to write images in '$format' format" );
 139         }
 140
 141         /**
 142          * Return a number of randomly-generated filenames
 143          * Each filename uses two words randomly drawn from the dictionary, like elephantine_spatula.jpg
 144          *
 145          * @param $number Integer: of filenames to generate
 146          * @param $extension String: optional, defaults to 'jpg'
 147          * @param $dir String: optional, defaults to current working directory
 148          * @return Array: of filenames
 149          */
 150         private function getRandomFilenames( $number, $extension = 'jpg', $dir = null ) {
 151                 if ( is_null( $dir ) ) {
 152                         $dir = getcwd();
 153                 }
 154                 $filenames = array();
 155                 foreach( $this->getRandomWordPairs( $number ) as $pair ) {
 156                         $basename = $pair[0] . '_' . $pair[1];
 157                         if ( !is_null( $extension ) ) {
 158                                 $basename .= '.' . $extension;
 159                         }
 160                         $basename = preg_replace( '/\s+/', '', $basename );
 161                         $filenames[] = "$dir/$basename";
 162                 }
 163
 164                 return $filenames;
 165
 166         }
 167
 168
 169         /**
 170          * Generate data representing an image of random size (within limits),
 171          * consisting of randomly colored and sized upward pointing triangles against a random background color
 172          * (This data is used in the writeImage* methods).
 173          * @return {Mixed}
 174          */
 175         public function getImageSpec() {
 176                 $spec = array();
 177
 178                 $spec['width'] = mt_rand( $this->minWidth, $this->maxWidth );
 179                 $spec['height'] = mt_rand( $this->minHeight, $this->maxHeight );
 180                 $spec['fill'] = $this->getRandomColor();
 181
 182                 $diagonalLength = sqrt( pow( $spec['width'], 2 ) + pow( $spec['height'], 2 ) );
 183
 184                 $draws = array();
 185                 for ( $i = 0; $i <= $this->shapesToDraw; $i++ ) {
 186                         $radius = mt_rand( 0, $diagonalLength / 4 );
 187                         if ( $radius == 0 ) {
 188                                 continue;
 189                         }
 190                         $originX = mt_rand( -1 * $radius, $spec['width'] + $radius );
 191                         $originY = mt_rand( -1 * $radius, $spec['height'] + $radius );
 192                         $angle = mt_rand( 0, ( 3.141592/2 ) * $radius ) / $radius;
 193                         $legDeltaX = round( $radius * sin( $angle ) );
 194                         $legDeltaY = round( $radius * cos( $angle ) );
 195
 196                         $draw = array();
 197                         $draw['fill'] = $this->getRandomColor();
 198                         $draw['shape'] = array(
 199                                 array( 'x' => $originX,                 'y' => $originY - $radius ),
 200                                 array( 'x' => $originX + $legDeltaX,    'y' => $originY + $legDeltaY ),
 201                                 array( 'x' => $originX - $legDeltaX,    'y' => $originY + $legDeltaY ),
 202                                 array( 'x' => $originX,                 'y' => $originY - $radius )
 203                         );
 204                         $draws[] = $draw;
 205
 206                 }
 207
 208                 $spec['draws'] = $draws;
 209
 210                 return $spec;
 211         }
 212
 213         /**
 214          * Given array( array('x' => 10, 'y' => 20), array( 'x' => 30, y=> 5 ) )
 215          * returns "10,20 30,5"
 216          * Useful for SVG and imagemagick command line arguments
 217          * @param $shape: Array of arrays, each array containing x & y keys mapped to numeric values
 218          * @return string
 219          */
 220         static function shapePointsToString( $shape ) {
 221                 $points = array();
 222                 foreach ( $shape as $point ) {
 223                         $points[] = $point['x'] . ',' . $point['y'];
 224                 }
 225                 return join( " ", $points );
 226         }
 227
 228         /**
 229          * Based on image specification, write a very simple SVG file to disk.
 230          * Ignores the background spec because transparency is cool. :)
 231          * @param $spec: spec describing background and shapes to draw
 232          * @param $format: file format to write (which is obviously always svg here)
 233          * @param $filename: filename to write to
 234          */
 235         public function writeSvg( $spec, $format, $filename ) {
 236                 $svg = new SimpleXmlElement( '<svg/>' );
 237                 $svg->addAttribute( 'xmlns', 'http://www.w3.org/2000/svg' );
 238                 $svg->addAttribute( 'version', '1.1' );
 239                 $svg->addAttribute( 'width', $spec['width'] );
 240                 $svg->addAttribute( 'height', $spec['height'] );
 241                 $g = $svg->addChild( 'g' );
 242                 foreach ( $spec['draws'] as $drawSpec ) {
 243                         $shape = $g->addChild( 'polygon' );
 244                         $shape->addAttribute( 'fill', $drawSpec['fill'] );
 245                         $shape->addAttribute( 'points', self::shapePointsToString( $drawSpec['shape'] ) );
 246                 };
 247                 if ( ! $fh = fopen( $filename, 'w' ) ) {
 248                         throw new Exception( "couldn't open $filename for writing" );
 249                 }
 250                 fwrite( $fh, $svg->asXML() );
 251                 if ( !fclose($fh) ) {
 252                         throw new Exception( "couldn't close $filename" );
 253                 }
 254         }
 255
 256         /**
 257          * Based on an image specification, write such an image to disk, using Imagick PHP extension
 258          * @param $spec: spec describing background and circles to draw
 259          * @param $format: file format to write
 260          * @param $filename: filename to write to
 261          */
 262         public function writeImageWithApi( $spec, $format, $filename ) {
 263                 // this is a hack because I can't get setImageOrientation() to work. See below.
 264                 global $wgExiv2Command;
 265
 266                 $image = new Imagick();
 267                 /**
 268                  * If the format is 'jpg', will also add a random orientation -- the image will be drawn rotated with triangle points
 269                  * facing in some direction (0, 90, 180 or 270 degrees) and a countering rotation should turn the triangle points upward again
 270                  */
 271                 $orientation = self::$orientations[0]; // default is normal orientation
 272                 if ( $format == 'jpg' ) {
 273                         $orientation = self::$orientations[ array_rand( self::$orientations ) ];
 274                         $spec = self::rotateImageSpec( $spec, $orientation['counterRotation'] );
 275                 }
 276
 277                 $image->newImage( $spec['width'], $spec['height'], new ImagickPixel( $spec['fill'] ) );
 278
 279                 foreach ( $spec['draws'] as $drawSpec ) {
 280                         $draw = new ImagickDraw();
 281                         $draw->setFillColor( $drawSpec['fill'] );
 282                         $draw->polygon( $drawSpec['shape'] );
 283                         $image->drawImage( $draw );
 284                 }
 285
 286                 $image->setImageFormat( $format );
 287
 288                 // this doesn't work, even though it's documented to do so...
 289                 // $image->setImageOrientation( $orientation['exifCode'] );
 290
 291                 $image->writeImage( $filename );
 292
 293                 // because the above setImageOrientation call doesn't work... nor can I get an external imagemagick binary to do this either...
 294                 // hacking this for now (only works if you have exiv2 installed, a program to read and manipulate exif)
 295                 if ( $wgExiv2Command ) {
 296                         $cmd = wfEscapeShellArg( $wgExiv2Command )
 297                                 . " -M "
 298                                 . wfEscapeShellArg( "set Exif.Image.Orientation " . $orientation['exifCode'] )
 299                                 . " "
 300                                 . wfEscapeShellArg( $filename );
 301
 302                         $retval = 0;
 303                         $err = wfShellExec( $cmd, $retval );
 304                         if ( $retval !== 0 ) {
 305                                 print "Error with $cmd: $retval, $err\n";
 306                         }
 307                 }
 308
 309
 310         }
 311
 312         /**
 313          * Given an image specification, produce rotated version
 314          * This is used when simulating a rotated image capture with EXIF orientation
 315          * @param $spec Object returned by getImageSpec
 316          * @param $matrix 2x2 transformation matrix
 317          * @return transformed Spec
 318          */
 319         private static function rotateImageSpec( &$spec, $matrix ) {
 320                 $tSpec = array();
 321                 $dims = self::matrixMultiply2x2( $matrix, $spec['width'], $spec['height'] );
 322                 $correctionX = 0;
 323                 $correctionY = 0;
 324                 if ( $dims['x'] < 0 ) {
 325                         $correctionX = abs( $dims['x'] );
 326                 }
 327                 if ( $dims['y'] < 0 ) {
 328                         $correctionY = abs( $dims['y'] );
 329                 }
 330                 $tSpec['width'] = abs( $dims['x'] );
 331                 $tSpec['height'] = abs( $dims['y'] );
 332                 $tSpec['fill'] = $spec['fill'];
 333                 $tSpec['draws'] = array();
 334                 foreach( $spec['draws'] as $draw ) {
 335                         $tDraw = array(
 336                                 'fill' => $draw['fill'],
 337                                 'shape' => array()
 338                         );
 339                         foreach( $draw['shape'] as $point ) {
 340                                 $tPoint = self::matrixMultiply2x2( $matrix, $point['x'], $point['y'] );
 341                                 $tPoint['x'] += $correctionX;
 342                                 $tPoint['y'] += $correctionY;
 343                                 $tDraw['shape'][] = $tPoint;
 344                         }
 345                         $tSpec['draws'][] = $tDraw;
 346                 }
 347                 return $tSpec;
 348         }
 349
 350         /**
 351          * Given a matrix and a pair of images, return new position
 352          * @param $matrix: 2x2 rotation matrix
 353          * @param $x: x-coordinate number
 354          * @param $y: y-coordinate number
 355          * @return Array transformed with properties x, y
 356          */
 357         private static function matrixMultiply2x2( $matrix, $x, $y ) {
 358                 return array(
 359                         'x' => $x * $matrix[0][0] + $y * $matrix[0][1],
 360                         'y' => $x * $matrix[1][0] + $y * $matrix[1][1]
 361                 );
 362         }
 363
 364
 365         /**
 366          * Based on an image specification, write such an image to disk, using the command line ImageMagick program ('convert').
 367          *
 368          * Sample command line:
 369          *    $ convert -size 100x60 xc:rgb(90,87,45)  \
 370                  *      -draw 'fill rgb(12,34,56)   polygon 41,39 44,57 50,57 41,39' \
 371                  *      -draw 'fill rgb(99,123,231) circle 59,39 56,57' \
 372                  *      -draw 'fill rgb(240,12,32)  circle 50,21 50,3'  filename.png
 373          *
 374          * @param $spec: spec describing background and shapes to draw
 375          * @param $format: file format to write (unused by this method but kept so it has the same signature as writeImageWithApi)
 376          * @param $filename: filename to write to
 377          */
 378         public function writeImageWithCommandLine( $spec, $format, $filename ) {
 379                 global $wgImageMagickConvertCommand;
 380                 $args = array();
 381                 $args[] = "-size " . wfEscapeShellArg( $spec['width'] . 'x' . $spec['height'] );
 382                 $args[] = wfEscapeShellArg( "xc:" . $spec['fill'] );
 383                 foreach( $spec['draws'] as $draw ) {
 384                         $fill = $draw['fill'];
 385                         $polygon = self::shapePointsToString( $draw['shape'] );
 386                         $drawCommand = "fill $fill  polygon $polygon";
 387                         $args[] = '-draw ' . wfEscapeShellArg( $drawCommand );
 388                 }
 389                 $args[] = wfEscapeShellArg( $filename );
 390
 391                 $command = wfEscapeShellArg( $wgImageMagickConvertCommand ) . " " . implode( " ", $args );
 392                 $retval = null;
 393                 wfShellExec( $command, $retval );
 394                 return ( $retval === 0 );
 395         }
 396
 397         /**
 398          * Generate a string of random colors for ImageMagick or SVG, like "rgb(12, 37, 98)"
 399          *
 400          * @return {String}
 401          */
 402         public function getRandomColor() {
 403                 $components = array();
 404                 for ($i = 0; $i <= 2; $i++ ) {
 405                         $components[] = mt_rand( 0, 255 );
 406                 }
 407                 return 'rgb(' . join(', ', $components) . ')';
 408         }
 409
 410         /**
 411          * Get an array of random pairs of random words, like array( array( 'foo', 'bar' ), array( 'quux', 'baz' ) );
 412          *
 413          * @param $number Integer: number of pairs
 414          * @return Array: of two-element arrays
 415          */
 416         private function getRandomWordPairs( $number ) {
 417                 $lines = $this->getRandomLines( $number * 2 );
 418                 // construct pairs of words
 419                 $pairs = array();
 420                 $count = count( $lines );
 421                 for( $i = 0; $i < $count; $i += 2 )  {
 422                         $pairs[] = array( $lines[$i], $lines[$i+1] );
 423                 }
 424                 return $pairs;
 425         }
 426
 427
 428         /**
 429          * Return N random lines from a file
 430          *
 431          * Will throw exception if the file could not be read or if it had fewer lines than requested.
 432          *
 433          * @param $number_desired Integer: number of lines desired
 434          * @return Array: of exactly n elements, drawn randomly from lines the file
 435          */
 436         private function getRandomLines( $number_desired ) {
 437                 $filepath = $this->dictionaryFile;
 438
 439                 // initialize array of lines
 440                 $lines = array();
 441                 for ( $i = 0; $i < $number_desired; $i++ ) {
 442                         $lines[] = null;
 443                 }
 444
 445                 /*
 446                  * This algorithm obtains N random lines from a file in one single pass. It does this by replacing elements of
 447                  * a fixed-size array of lines, less and less frequently as it reads the file.
 448                  */
 449                 $fh = fopen( $filepath, "r" );
 450                 if ( !$fh ) {
 451                          throw new Exception( "couldn't open $filepath" );
 452                 }
 453                 $line_number = 0;
 454                 $max_index = $number_desired - 1;
 455                 while( !feof( $fh ) ) {
 456                         $line = fgets( $fh );
 457                         if ( $line !== false ) {
 458                                 $line_number++;
 459                                 $line = trim( $line );
 460                                 if ( mt_rand( 0, $line_number ) <= $max_index ) {
 461                                         $lines[ mt_rand( 0, $max_index ) ] = $line;
 462                                 }
 463                         }
 464                 }
 465                 fclose( $fh );
 466                 if ( $line_number < $number_desired ) {
 467                         throw new Exception( "not enough lines in $filepath" );
 468                 }
 469
 470                 return $lines;
 471         }
 472
 473 }