Crop (Abstract Base Class)

The Crop class is the foundation of all cropping strategies in the library. It provides common functionality and defines the interface that all concrete cropping implementations must follow.

Class Overview

1
abstract class drzippie\crop\Crop

This abstract class cannot be instantiated directly. Instead, use one of the concrete implementations:

• CropCenter - Simple center-based cropping
• CropEntropy - Entropy-based intelligent cropping
• CropBalanced - Balanced cropping with weighted center of interest

Constructor

1
public function __construct(string|Imagick|null $image = null)

Creates a new cropping instance with optional image initialization.

Parameters:

• $image - Can be a file path (string), Imagick object, or null

Examples:

1
2
3
4
5
6
7
8
9
// With file path
$crop = new CropCenter('image.jpg');

// With Imagick object
$imagick = new Imagick('image.jpg');
$crop = new CropCenter($imagick);

// Empty instance
$crop = new CropCenter();

Core Methods

resizeAndCrop()

1
public function resizeAndCrop(int $targetWidth, int $targetHeight): Imagick

The main method that performs the resize and crop operation.

Parameters:

• $targetWidth - Target width in pixels
• $targetHeight - Target height in pixels

Returns: Imagick - The processed image

Throws: RuntimeException if no image is set

Example:

1
2
3
$crop = new CropCenter('image.jpg');
$result = $crop->resizeAndCrop(300, 200);
$result->writeImage('output.jpg');

setImage()

1
public function setImage(Imagick $image): self

Sets the image to be processed.

Parameters:

• $image - Imagick object to process

Returns: self for method chaining

setFilter()

1
public function setFilter(int $filter): self

Sets the resize filter to use during processing.

Parameters:

• $filter - Imagick filter constant

Common Filters:

• Imagick::FILTER_LANCZOS - High quality, slower
• Imagick::FILTER_CUBIC - Good quality, default
• Imagick::FILTER_POINT - Fast, lower quality

Returns: self for method chaining

setBlur()

1
public function setBlur(float $blur): self

Sets the blur factor for resizing operations.

Parameters:

• $blur - Blur factor (0.0 to 1.0+)

Returns: self for method chaining

setAutoOrient()

1
public function setAutoOrient(bool $autoOrient): self

Enables or disables automatic orientation based on EXIF data.

Parameters:

• $autoOrient - True to enable, false to disable

Returns: self for method chaining

Getter Methods

getFilter()

1
public function getFilter(): int

Returns the current resize filter setting.

getBlur()

1
public function getBlur(): float

Returns the current blur factor.

getAutoOrient()

1
public function getAutoOrient(): bool

Returns the current auto-orientation setting.

Utility Methods

Profiling

1
2
public static function start(): void
public static function mark(): string

Static methods for performance profiling:

• start() - Begins timing
• mark() - Returns elapsed time since start()

Example:

1
2
3
4
Crop::start();
$crop = new CropCenter('image.jpg');
$result = $crop->resizeAndCrop(300, 200);
echo "Processing time: " . Crop::mark();

Entropy Calculation

1
public function getEntropyFromArray(array $histogram): float

Calculates entropy from a histogram array. Used internally by entropy-based cropping strategies.

Parameters:

• $histogram - Array of color frequency data

Returns: float - Calculated entropy value

Abstract Methods

getSpecialOffset()

1
2
3
4
5
abstract protected function getSpecialOffset(
    Imagick $original, 
    int $targetWidth, 
    int $targetHeight
): array

Abstract method that must be implemented by concrete classes to define their specific cropping logic.

Parameters:

• $original - Original image
• $targetWidth - Target width
• $targetHeight - Target height

Returns: array - Array containing x and y offset coordinates

Method Chaining

All setter methods return $this, allowing for fluent interface usage:

1
2
3
4
5
$result = (new CropCenter('image.jpg'))
    ->setFilter(Imagick::FILTER_LANCZOS)
    ->setBlur(0.8)
    ->setAutoOrient(true)
    ->resizeAndCrop(400, 300);

Error Handling

The class throws RuntimeException when:

• No image is set before calling resizeAndCrop()
• Image processing fails
• Invalid parameters are provided

Performance Considerations

• The base class handles common operations efficiently
• Concrete implementations vary in performance:
  • CropCenter: Fastest
  • CropBalanced: Moderate
  • CropEntropy: Slowest but highest quality

See Also

• CropCenter - Simple center cropping
• CropEntropy - Entropy-based cropping
• CropBalanced - Balanced cropping
• API Reference - Complete API documentation