SOLUTION Thanks to s_ha_dum
function get_avg_luminance($filename, $num_samples=10) {
$img = imagecreatefromjpeg($filename);
$width = imagesx($img);
$height = imagesy($img);
$x_step = intval($width/$num_samples);
$y_step = intval($height/$num_samples);
$total_lum = 0;
$sample_no = 1;
for ($x=0; $x<$width; $x+=$x_step) {
for ($y=0; $y<$height; $y+=$y_step) {
$rgb = imagecolorat($img, $x, $y);
$r = ($rgb >> 16) & 0xFF;
$g = ($rgb >> 8) & 0xFF;
$b = $rgb & 0xFF;
// choose a simple luminance formula from here
// http://stackoverflow.com/questions/596216/formula-to-determine-brightness-of-rgb-color
$lum = ($r+$r+$b+$g+$g+$g)/6;
$total_lum += $lum;
$sample_no++;
}
}
// work out the average
$avg_lum = $total_lum/$sample_no;
return $avg_lum;
// assume a medium gray is the threshold, #acacac or RGB(172, 172, 172)
// this equates to a luminance of 170
}
function insert_luminance_data($post_ID) {
$src = wp_get_attachment_image_src( $post_ID, 'large' )[0];
$lum = get_avg_luminance($src, 10, true);
add_post_meta( $post_ID, 'image_lum', $lum, true ) || update_post_meta( $post_ID, 'image_lum', $lum );
return $post_ID;
}
add_filter('add_attachment', 'insert_luminance_data', 10, 2);
this creates a number between 0 and 255 that represents the luminance of the image.. this is particularly useful if you are layering text over a background image and wish to know if the image is mostly light or mostly dark.