Merge PR #44: Performance improvements

Around 30% faster and between 20 to 50% less memory usage

Closes #44

Author: ksubileau

lib/ColorThief/ColorThief.php

@@ -137,47 +137,29 @@ public static function getPalette($sourceImage, $colorCount = 10, $quality = 10,
             throw new \InvalidArgumentException('The quality argument must be an integer greater than one.');
         }
 
-        $pixelArray = static::loadImage($sourceImage, $quality, $area);
-        if (!count($pixelArray)) {
+        $histo = [];
+        $numPixelsAnalyzed = static::loadImage($sourceImage, $quality, $histo, $area);
+        if ($numPixelsAnalyzed === 0) {
             throw new \RuntimeException('Unable to compute the color palette of a blank or transparent image.', 1);
         }
 
-        // Send array to quantize function which clusters values
+        // Send histogram to quantize function which clusters values
         // using median cut algorithm
-        $cmap = static::quantize($pixelArray, $colorCount);
+        $cmap = static::quantize($numPixelsAnalyzed, $colorCount, $histo);
         $palette = $cmap->palette();
 
         return $palette;
     }
 
-    /**
-     * Histo: 1-d array, giving the number of pixels in each quantized region of color space.
-     *
-     * @param array $pixels
-     *
-     * @return array
-     */
-    private static function getHisto($pixels)
-    {
-        $histo = [];
-
-        foreach ($pixels as $rgb) {
-            list($red, $green, $blue) = static::getColorsFromIndex($rgb);
-            $bucketIndex = static::getColorIndex($red, $green, $blue);
-            $histo[$bucketIndex] = (isset($histo[$bucketIndex]) ? $histo[$bucketIndex] : 0) + 1;
-        }
-
-        return $histo;
-    }
-
     /**
      * @param mixed      $sourceImage Path/URL to the image, GD resource, Imagick instance, or image as binary string
-     * @param int        $quality
+     * @param int        $quality     Analyze every $quality pixels
+     * @param array      $histo       Histogram
      * @param array|null $area
      *
-     * @return SplFixedArray
+     * @return int
      */
-    private static function loadImage($sourceImage, $quality, array $area = null)
+    private static function loadImage($sourceImage, $quality, array &$histo, array $area = null)
     {
         $loader = new ImageLoader();
         $image = $loader->load($sourceImage);
@@ -197,25 +179,46 @@ private static function loadImage($sourceImage, $quality, array $area = null)
             }
         }
 
-        $pixelCount = $width * $height;
+        // Fill a SplArray with zeroes to initialize the 5-bit buckets and avoid having to check isset in the pixel loop.
+        // There are 32768 buckets because each color is 5 bits (15 bits total for RGB values).
+        $totalBuckets = (1 << (3 * self::SIGBITS));
+        $histoSpl = new SplFixedArray($totalBuckets);
+        for ($i = 0; $i < $totalBuckets; $i++) {
+            $histoSpl[$i] = 0;
+        }
 
-        // Store the RGB values in an array format suitable for quantize function
-        // SplFixedArray is faster and more memory-efficient than normal PHP array.
-        $pixelArray = new SplFixedArray(ceil($pixelCount / $quality));
+        $numUsefulPixels = 0;
+        $pixelCount = $width * $height;
 
-        $size = 0;
-        for ($i = 0; $i < $pixelCount; $i = $i + $quality) {
+        for ($i = 0; $i < $pixelCount; $i += $quality) {
             $x = $startX + ($i % $width);
             $y = (int) ($startY + $i / $width);
             $color = $image->getPixelColor($x, $y);
 
-            if (static::isClearlyVisible($color) && static::isNonWhite($color)) {
-                $pixelArray[$size++] = static::getColorIndex($color->red, $color->green, $color->blue, 8);
-                // TODO : Compute directly the histogram here ? (save one iteration over all pixels)
+            // Pixel is too transparent. Its alpha value is larger (more transparent) than THRESHOLD_ALPHA.
+            // PHP's transparency range (0-127 opaque-transparent) is reverse that of Javascript (0-255 tranparent-opaque).
+            if ($color->alpha > self::THRESHOLD_ALPHA) {
+                continue;
+            }
+
+            // Pixel is too white to be useful. Its RGB values all exceed THRESHOLD_WHITE
+            if ($color->red > self::THRESHOLD_WHITE && $color->green > self::THRESHOLD_WHITE && $color->blue > self::THRESHOLD_WHITE) {
+                continue;
             }
+
+            // Count this pixel in its histogram bucket.
+            $numUsefulPixels++;
+            $bucketIndex = static::getColorIndex($color->red, $color->green, $color->blue);
+            $histoSpl[$bucketIndex] = $histoSpl[$bucketIndex] + 1;
         }
 
-        $pixelArray->setSize($size);
+        // Copy the histogram buckets that had pixels back to a normal array.
+        $histo = [];
+        foreach ($histoSpl as $bucketInt => $numPixels) {
+            if ($numPixels > 0) {
+                $histo[$bucketInt] = $numPixels;
+            }
+        }
 
         // Don't destroy a resource passed by the user !
         // TODO Add a method in ImageLoader to know if the image should be destroy
@@ -224,31 +227,7 @@ private static function loadImage($sourceImage, $quality, array $area = null)
             $image->destroy();
         }
 
-        return $pixelArray;
-    }
-
-    /**
-     * @param object $color
-     *
-     * @return bool
-     */
-    protected static function isClearlyVisible($color)
-    {
-        return $color->alpha <= self::THRESHOLD_ALPHA;
-    }
-
-    /**
-     * @param object $color
-     *
-     * @return bool
-     */
-    protected static function isNonWhite($color)
-    {
-        return !(
-            $color->red > self::THRESHOLD_WHITE &&
-            $color->green > self::THRESHOLD_WHITE &&
-            $color->blue > self::THRESHOLD_WHITE
-        );
+        return $numUsefulPixels;
     }
 
     /**
@@ -377,15 +356,20 @@ private static function sumColors($axis, $histo, $vBox)
             $sum = 0;
             foreach ($secondRange as $secondColor) {
                 foreach ($thirdRange as $thirdColor) {
-                    list($redBucket, $greenBucket, $blueBucket) = static::rearrangeColors(
-                        $colorIterateOrder,
-                        $firstColor,
-                        $secondColor,
-                        $thirdColor
-                    );
+                    // Rearrange color components
+                    $bucket = [
+                        $colorIterateOrder[0] => $firstColor,
+                        $colorIterateOrder[1] => $secondColor,
+                        $colorIterateOrder[2] => $thirdColor,
+                    ];
 
                     // The getColorIndex function takes RGB values instead of buckets. The left shift converts our bucket into its RGB value.
-                    $bucketIndex = static::getColorIndex($redBucket << self::RSHIFT, $greenBucket << self::RSHIFT, $blueBucket << self::RSHIFT, self::SIGBITS);
+                    $bucketIndex = static::getColorIndex(
+                        $bucket['r'] << self::RSHIFT,
+                        $bucket['g'] << self::RSHIFT,
+                        $bucket['b'] << self::RSHIFT,
+                        self::SIGBITS
+                    );
 
                     if (isset($histo[$bucketIndex])) {
                         $sum += $histo[$bucketIndex];
@@ -399,29 +383,6 @@ private static function sumColors($axis, $histo, $vBox)
         return [$total, $partialSum];
     }
 
-    /**
-     * @param array $order
-     * @param int   $color1
-     * @param int   $color2
-     * @param int   $color3
-     *
-     * @return array
-     */
-    private static function rearrangeColors(array $order, $color1, $color2, $color3)
-    {
-        $data = [
-            $order[0] => $color1,
-            $order[1] => $color2,
-            $order[2] => $color3,
-        ];
-
-        return [
-            $data['r'],
-            $data['g'],
-            $data['b'],
-        ];
-    }
-
     /**
      * @param VBox  $vBox
      * @param array $order
@@ -490,20 +451,24 @@ private static function quantizeIter(&$priorityQueue, $target, $histo)
     }
 
     /**
-     * @param SplFixedArray|array $pixels
+     * @param $numPixels   Number of image pixels analyzed
      * @param $maxColors
+     * @param array $histo Histogram
      *
      * @return bool|CMap
      */
-    private static function quantize($pixels, $maxColors)
+    private static function quantize($numPixels, $maxColors, array &$histo)
     {
-        // short-circuit
-        if (!count($pixels) || $maxColors < 2 || $maxColors > 256) {
-            // echo 'wrong number of maxcolors'."\n";
-            return false;
+        // Short-Circuits
+        if ($numPixels === 0) {
+            throw new \InvalidArgumentException('Zero useable pixels found in image.');
+        }
+        if ($maxColors < 2 || $maxColors > 256) {
+            throw new \InvalidArgumentException('The maxColors parameter must be between 2 and 256 inclusive.');
+        }
+        if (count($histo) === 0) {
+            throw new \InvalidArgumentException('Image produced an empty histogram.');
         }
-
-        $histo = static::getHisto($pixels);
 
         // check that we aren't below maxcolors already
         //if (count($histo) <= $maxcolors) {

lib/ColorThief/VBox.php

@@ -168,10 +168,11 @@ public function contains(array $rgbValue, $rshift = ColorThief::RSHIFT)
      */
     public function longestAxis()
     {
-        $colorWidth['r'] = $this->r2 - $this->r1;
-        $colorWidth['g'] = $this->g2 - $this->g1;
-        $colorWidth['b'] = $this->b2 - $this->b1;
+        // Color-Width for RGB
+        $red = $this->r2 - $this->r1;
+        $green = $this->g2 - $this->g1;
+        $blue = $this->b2 - $this->b1;
 
-        return array_search(max($colorWidth), $colorWidth);
+        return $red >= $green && $red >= $blue ? 'r' : ($green >= $red && $green >= $blue ? 'g' : 'b');
     }
 }

tests/ColorThiefTest.php

@@ -306,26 +306,6 @@ public function testNaturalOrder($left, $right, $expected)
         );
     }
 
-    public function testGetHisto()
-    {
-        $method = new \ReflectionMethod('\ColorThief\ColorThief', 'getHisto');
-        $method->setAccessible(true);
-
-        // [[229, 210, 51], [133, 24, 135], [216, 235, 108], [132, 25, 134], [223, 46, 29],
-        // [135, 28, 132], [233, 133, 213], [225, 212, 48]]
-        $pixels = [15061555, 8722567, 14216044, 8657286, 14626333, 8854660, 15304149, 14799920];
-
-        $expectedHisto = [
-            29510 => 2,
-            16496 => 3,
-            28589 => 1,
-            27811 => 1,
-            30234 => 1,
-        ];
-
-        $this->assertSame($expectedHisto, $method->invoke(null, $pixels));
-    }
-
     public function testVboxFromPixels()
     {
         $method = new \ReflectionMethod('\ColorThief\ColorThief', 'vboxFromHistogram');