Image Lightness

Image lightness areas are defined in config/enso/media.php in the light_dark_areas array.

Requirements

This feature requires that you install two additional libraries:

  • composer require ksubileau/color-thief-php
  • composer require mexitek/phpcolors dev-master

This feature should not cause breaking changes should you choose to implement it into an existing project.

Definition

An area must be defined as an array of 4 numbers. There are no default/fallback values.

  • The top-left x-pixel of the area (assuming the top left of the image is 0)
  • The top-left y-pixel of the area (assuming the top left of the image is 0)
  • The width of the area
  • The height of the area

These values may be specified in either as numbers, or as percentage values e.g. '25%'.

Example

The 'full' area covers the entire image. The 'top-left' area covers the top left 25 square pixels of the given image. The middle area the middle 20% of an the image.

'light_dark_areas' => [
    'full' => [0, 0, '100%', '100%'],
    'top-left' => [0, 0, 25, 25],
    'middle' => ['40%', '40%', '20%', '20%'],
]

Value calculation

To avoid uneccesary calculations, these values are only ever stored when a lightDark() call is made on an ImageFile instance. The call should be:

$image->lightDark(['area_name', 'other_area_name']);

and will update the ImageFile's fileinfo array to contain:

[
  'is_light' => [
    ...
    'no_preset' => [
      'area_name' => true,
      'other_area_name' => false,
    ]
    ...
  ]
];

(Note that when not specifying a resize preset, it adds entries to the 'no_preset' array element): You may specify which preset to make lightness assessments for by passing a preset name as the second argument:

$image->lightDark(['area_name', 'other_area_name'], 'preset_name');

Value persistence

Once stored, thie value will not be recalculated. Calling lightDark on an ImageFile multiple times will skip any known value combinations for the provided arguments. However, as image crops can be directly changed when setting a focal point, the 'is_light' data is flushed when this happens.