File Coverage

lib/Graphics/Toolkit/Color.pm

Criterion	Covered	Total	%
statement	264	298	88.5
branch	166	218	76.1
condition	81	116	69.8
subroutine	30	37	81.0
pod	21	26	80.7
total	562	695	80.8

# public user level API: doc summary, help msg and arg cleaning

package Graphics::Toolkit::Color;
our $VERSION = '2.22';
use v5.12;
use warnings;
use Graphics::Toolkit::Color::Error       qw/error/;
use Graphics::Toolkit::Color::Space::Util qw/is_nr/;
use Graphics::Toolkit::Color::SetCalculator;

## import export, error handling #######################################
use Exporter;
our @ISA = qw(Exporter);
our @EXPORT_OK = qw/color is_in_gamut/;

sub import {
    my ($class, @args) = @_;
    my @export_symbols;
    push @export_symbols, shift @args while @args and lc $args[0] ne 'error';
    Graphics::Toolkit::Color::Error::change_mode( $args[1] );
    $class->Exporter::export_to_level(1, $class, @export_symbols);
}

## constructor #########################################################
my $POD_link = ' Type "perldoc Graphics::Toolkit::Color" for more help.';
sub new {
    my ($pkg, @args) = @_;
    my $help = 'method "new" accepts the arguments: "color" (color definition), "raw", '.
               '"range" and "in" (space name). "color" is the required and default argument.'.$POD_link;
	my ($color_def, $space_name, $range_def, $is_raw);
    if (@args > 0 and not @args % 2){
		my %h = @args;
		return error('got an argument twice') if keys(%h) * 2 < int(@args);
		($color_def, $space_name, $range_def, $is_raw) = ($h{'color'}, $h{'in'}, $h{'range'}, $h{'raw'} // 0);
	}
    $color_def = _color_def_into_scalar( @args ) unless defined $color_def;
    return error($help) unless defined $color_def;
    my $self = _new_from_scalar_def( $color_def, $space_name, $range_def, $is_raw );
	return (ref $self) ? $self : error($self);
}
sub color {
	my $self = _new_from_scalar_def( _color_def_into_scalar( @_ ) );
	return (ref $self) ? $self : error($self);
}
sub _color_def_into_scalar {
    my (@args) = @_;
    return if @args < 1 or @args > 8 or @args == 7;
    return $args[0] if @args == 1; # pass names
    return [@args]  if @args <= 5; # lists and named lists --> array and named array
    return {@args};                # hashes without curly braces --> hash
}
sub _new_from_scalar_def {
    my ($color_def, $space_name, $range_def, $is_raw) = @_;
    return $color_def if ref $color_def eq __PACKAGE__;
    return _new_from_value_obj( Graphics::Toolkit::Color::Values->new_from_any_input( $color_def, $space_name, $range_def, $is_raw ) );
}
sub _new_from_value_obj {
    my ($value_obj) = @_;
    return $value_obj unless ref $value_obj eq 'Graphics::Toolkit::Color::Values';
    return bless {values => $value_obj};
}
sub values_object { $_[0]->{'values'} if ref $_[0] eq __PACKAGE__}

sub is_in_gamut {
    my ($self, $space_name, $named_arg) = @_;
    return is_in_gamut_sub (@_) if ref $self ne __PACKAGE__;
    my $help = 'The method "is_in_gamut" accepts one optional, positional argument, a color space name, '.
               'which defaults to the space the color was defined in'.$POD_link;
	$space_name = $named_arg if defined $space_name and $space_name eq 'in' and defined $named_arg;
    my $space = Graphics::Toolkit::Color::Space::Hub::get_space( $space_name );
	return error($help) if defined $space_name and not ref $space;
    $self->values_object->is_in_gamut( (ref $space) ? $space->name : undef );
}
sub is_in_gamut_sub {
    my (@color) = @_;
	my $values = Graphics::Toolkit::Color::Values->new_from_any_input(
		_color_def_into_scalar( @_ ), undef, undef, 1
	);
	return error($values.$POD_link) unless ref $values;
    $values->is_in_gamut( );
}

########################################################################
sub _split_named_args {
    my ($raw_args, $only_parameter, $required_parameter, $optional_parameter, $parameter_alias) = @_;
    @$raw_args = %{$raw_args->[0]} if @$raw_args == 1 and ref $raw_args->[0] eq 'HASH' and not
                  (defined $only_parameter and $only_parameter eq 'to' and ref _new_from_scalar_def( $raw_args ) );

    if (@$raw_args == 1 and defined $only_parameter and $only_parameter){
        return "The one default argument can not cover multiple, required parameter !" if @$required_parameter > 1;
        return "The default argument does not cover the required argument!"
            if @$required_parameter and $required_parameter->[0] ne $only_parameter;

        my %defaults = %$optional_parameter;
        delete $defaults{$only_parameter};
        return {$only_parameter => $raw_args->[0], %defaults};
    }
    my %clean_arg;
    if (@$raw_args % 2) {
        return (defined $only_parameter and $only_parameter)
             ? "Got odd number of arguments, please use key value pairs as arguments or one default argument !\n"
             : "Got odd number of values, please use key value pairs as arguments !\n"
    }
    my %arg_hash = @$raw_args;
    for my $parameter_name (@$required_parameter){
        if (ref $parameter_alias eq 'HASH' and exists $parameter_alias->{ $parameter_name }
            and exists $arg_hash{ $parameter_alias->{$parameter_name} }){
            $arg_hash{ $parameter_name } = delete $arg_hash{ $parameter_alias->{$parameter_name} };
        }
        return "Argument '$parameter_name' is missing!\n" unless exists $arg_hash{$parameter_name};
        $clean_arg{ $parameter_name } = delete $arg_hash{ $parameter_name };
    }
    for my $parameter_name (keys %$optional_parameter){
        if (ref $parameter_alias eq 'HASH' and exists $parameter_alias->{ $parameter_name }
            and exists $arg_hash{ $parameter_alias->{$parameter_name} }){
            $arg_hash{ $parameter_name } = delete $arg_hash{ $parameter_alias->{$parameter_name} };
        }
        $clean_arg{ $parameter_name } = exists $arg_hash{$parameter_name}
                                      ? delete $arg_hash{ $parameter_name }
                                      : $optional_parameter->{ $parameter_name };
    }
    return "Inserted unknown argument(s): ".(join ',', keys %arg_hash)."\n" if %arg_hash;
    return \%clean_arg;
}

### getter #############################################################
my $default_space_name = Graphics::Toolkit::Color::Space::Hub::default_space_name();
sub values       {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'in', [],
                               { in => $default_space_name, as => 'list', raw => 0,
                                 precision => undef, range => undef, suffix => undef } );
    my $help = 'The method "values" returns numeric color values and accepts six named, optional arguments: '.
               '"in" (color space name - default arg), "as" (color definition format), "raw", "range", "precision" and "suffix"!';
    return error($arg.$help.$POD_link) unless ref $arg;
    my @result = $self->values_object->formatted( @$arg{qw/in as suffix range precision raw/} );
    return error(${$result[0]}.$help.$POD_link) if ref $result[0] eq 'SCALAR';
    return wantarray ? @result : $result[0];
}

sub name         {
    my ($self, @args) = @_;
    return $self->values_object->name unless @args;
    my $arg = _split_named_args( \@args, 'from', [], {from => 'default', all => 0, full => 0, distance => 0}, {distance => 'd'});
    my $help = 'The method "name" returns one, several or no (empty) color name strings and accepts four named, optional arguments: '.
               '"from" (scheme name - default arg), "all" (color names), "full" (name) and "distance" (or "d")!';
    return error($arg.$help.$POD_link) unless ref $arg;
    Graphics::Toolkit::Color::Name::from_values( $self->values_object->shaped, @$arg{qw/from all full distance/});
}

sub closest_name {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'from', [], {from => 'default', all => 0, full => 0});
    my $help = 'The method "closest_name" returns one or several (in an ARRAY) color name strings and in list context also '.
			    'the numeric distance and accepts three named, optional arguments: '.
               '"from" (scheme name - default arg), "all" (color names) and "full" (name)!';
    return error($arg.$help.$POD_link) unless ref $arg;
    my ($name, $distance) = Graphics::Toolkit::Color::Name::closest_from_values(
                                $self->values_object->shaped, @$arg{qw/from all full/});
    return wantarray ? ($name, $distance) : $name;
}

sub distance {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'to', ['to'], {in => $default_space_name, only => undef, range => undef}, {only => 'select'});
    my $help = 'The method "distance" returns one numeric distance value and accepts four named arguments, the first being default '.
               'and required: "to" (definition of second color), "in" (color space name), "only" (axis selection) and "range"!';
    return error($arg.$help.$POD_link) unless ref $arg;
    my $target_color = _new_from_scalar_def( $arg->{'to'} );
    return error("target color definition: $arg->{to} is ill formed".$help.$POD_link) unless ref $target_color;
    my $color_space = Graphics::Toolkit::Color::Space::Hub::try_get_space( $arg->{'in'} );
    return error($color_space.$help.$POD_link) unless ref $color_space;
    if (defined $arg->{'only'}){
        if (not ref $arg->{'only'}){
			return error($arg->{'only'}." is not an axis name or role in color space: ".$color_space->name.$help.$POD_link)
                unless $color_space->is_axis_role( $arg->{'only'} );
        } elsif (ref $arg->{'only'} eq 'ARRAY'){
            for my $axis_name (@{$arg->{'only'}}) {
				return error( $axis_name." is not an axis name or role in color space: ".$color_space->name.$help.$POD_link)
					unless $color_space->is_axis_role( $axis_name );
            }
        } else { return error('The "only" argument needs one axis name or an ARRAY with several axis names from '.
			                  'the same color space!'.$help.$POD_link) }
    }
    my $range_def = $color_space->shape->try_check_range_definition( $arg->{'range'} );
    return error($range_def.$help.$POD_link) unless ref $range_def;
    Graphics::Toolkit::Color::Space::Hub::distance(
        $self->values_object->normalized, $target_color->values_object->normalized, $color_space->name, $arg->{'only'}, $range_def );
}

## single color creation methods #######################################
# --- lightweight designer API ---
my $design_default = 'OKHSL';
sub lighten {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'by', ['by'], {in => $design_default});
    return "The only argument or named argument 'by' has to be a number between 0 and 1!" unless ref $arg;
	_new_from_value_obj( Graphics::Toolkit::Color::Calculator::lighten( $self->values_object, $arg->{'by'}, $arg->{'in'} ) );
}
sub darken {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'by', ['by'], {in => $design_default});
    return "The only argument or named argument 'by' has to be a number between 0 and 1!" unless ref $arg;
	_new_from_value_obj( Graphics::Toolkit::Color::Calculator::darken( $self->values_object, $arg->{'by'}, $arg->{'in'} ) );
}
sub saturate {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'by', ['by'], {in => $design_default});
    return "The only argument or named argument 'by' has to be a number between 0 and 1!" unless ref $arg;
	_new_from_value_obj( Graphics::Toolkit::Color::Calculator::saturate( $self->values_object, $arg->{'by'}, $arg->{'in'} ) );
}
sub desaturate {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'by', ['by'], {in => $design_default});
    return "The only argument or named argument 'by' has to be a number between 0 and 1!" unless ref $arg;
	_new_from_value_obj( Graphics::Toolkit::Color::Calculator::desaturate( $self->values_object, $arg->{'by'}, $arg->{'in'} ) );
}
sub tint {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'by', ['by'], {in => $design_default});
    return "The only argument or named argument 'by' has to be a number between 0 and 1!" unless ref $arg;
	_new_from_value_obj( Graphics::Toolkit::Color::Calculator::tint( $self->values_object, $arg->{'by'}, $arg->{'in'} ) );
}
sub tone {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'by', ['by'], {in => $design_default});
    return "The only argument or named argument 'by' has to be a number between 0 and 1!" unless ref $arg;
	_new_from_value_obj( Graphics::Toolkit::Color::Calculator::tone( $self->values_object, $arg->{'by'}, $arg->{'in'} ) );
}
sub shade {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'by', ['by'], {in => $design_default});
    return "The only argument or named argument 'by' has to be a number between 0 and 1!" unless ref $arg;
	_new_from_value_obj( Graphics::Toolkit::Color::Calculator::shade( $self->values_object, $arg->{'by'}, $arg->{'in'} ) );
}

# --- low level complex API ---

sub apply { tone_curve(@_) }
sub tone_curve {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, undef, ['gamma'], {in => 'LinearRGB'} );
    my $help = 'The method "tone_curve" returns a GTC object with gamma corrected values and accepts two named arguments, '.
               'the first being required: "gamma", "in" (color space name - default LinearRGB)!';
    return error($arg.$help.$POD_link) unless ref $arg;
    my $color_space = Graphics::Toolkit::Color::Space::Hub::try_get_space( $arg->{'in'} );
    return error($color_space.$help.$POD_link) unless ref $color_space;
	my $result = Graphics::Toolkit::Color::Calculator::apply_gamma( $self->values_object, $arg->{'gamma'}, $color_space );
    return error($result.$help.$POD_link) unless ref $result;
    return _new_from_value_obj( $result );
}

sub set_value {
    my ($self, @args) = @_;
    @args = %{$args[0]} if @args == 1 and ref $args[0] eq 'HASH';
    my $help = 'The method "set_value" returns a GTC object with some values replaced. Arguments are selected axis '.
               'names of target space and optionally "in" for color space disambiguation!';
    return error($help.$POD_link) if @args % 2 or not @args or @args > 10;
    my $partial_color = { @args };
    my $space_name = delete $partial_color->{'in'};
    my $color_space = Graphics::Toolkit::Color::Space::Hub::try_get_space( $space_name );
    return error($color_space.$help.$POD_link) if defined $color_space and not ref $color_space;
    my $result = Graphics::Toolkit::Color::Calculator::set_value( $self->values_object, $partial_color, $space_name );
    return error($result.' '.$help.$POD_link) unless ref $result;
    return _new_from_value_obj( $result );
}
sub add_value {
    my ($self, @args) = @_;
    @args = %{$args[0]} if @args == 1 and ref $args[0] eq 'HASH';
    my $help = 'The method "add_value" returns a GTC object with some values different. Arguments are selected axis '.
               'names of target space and optionally "in" for color space disambiguation!';
    return error($help.$POD_link) if @args % 2 or not @args or @args > 10;
    my $partial_color = { @args };
    my $space_name = delete $partial_color->{'in'};
    my $color_space = Graphics::Toolkit::Color::Space::Hub::try_get_space( $space_name );
    return error($color_space.$help.$POD_link) if defined $color_space and not ref $color_space;
    my $result = Graphics::Toolkit::Color::Calculator::add_value( $self->values_object, $partial_color, $space_name );
    return error($result.' '.$help.$POD_link) unless ref $result;
    return _new_from_value_obj( $result );
}

sub mix {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'to', ['to'], {in => 'OKLAB', by => undef}, {by => 'amount'});
    my $help = 'The method "mix" returns a GTC object, which is a blend between given colors. Arguments are: '.
               '"to" (other color[s]-required and default), "by" (mix amounts) and "in"(color space name, default OKLAB)!';
    return error($arg.' '.$help.$POD_link) unless ref $arg;
    my $color_space = Graphics::Toolkit::Color::Space::Hub::try_get_space( delete $arg->{'in'} );
    return error($color_space.' '.$help.$POD_link) unless ref $color_space;
    my $second_color = _new_from_scalar_def($arg->{'to'});
    if (ref $second_color){ $arg->{'to'} = [$second_color->values_object] }
    else {
        if (ref $arg->{'to'} ne 'ARRAY'){
			return error("Target color definition (argument 'to'): '$arg->{to}' is ill formed. $second_color. ".$POD_link);
        } else {
			my @to = ();
			for my $color_def (@{$arg->{'to'}}){
				if (ref $color_def eq __PACKAGE__) { push @to, $color_def->values_object }
				else {
					$second_color = Graphics::Toolkit::Color::Values->new_from_any_input( $color_def );
					return error("target color definition (argument 'to'). '$color_def' is ill formed: $second_color. ".$POD_link)
						unless ref $second_color;
					push @to, $second_color;
				}
			}
			$arg->{'to'} = \@to;
		}
    }
    # backward compatibility: 'by' > 1 is read as percent (0 .. 100) and mapped to 0 .. 1
    if (defined $arg->{'by'}){
        if (ref $arg->{'by'} eq 'ARRAY') {
			for (@{$arg->{'by'}}) { $_ /= 100 if is_nr($_) and $_ > 1 }
		} elsif (is_nr($arg->{'by'}) and $arg->{'by'} > 1) { $arg->{'by'} /= 100 }
    }
    my $result = Graphics::Toolkit::Color::Calculator::mix( $self->values_object, $arg->{'to'}, $arg->{'by'}, $color_space );
    return error($result.' '.$help.$POD_link) unless ref $result;
    return _new_from_value_obj( $result );
}

sub invert {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'only', [], {in => undef, only => undef});
    my $help = 'The method "invert" returns a GTC object with inverted ($max - $_) values. Optional arguments are: '.
               '"only" (axis selection, default is all) and "in" (color space name)!';
    return error($arg.$help.$POD_link) unless ref $arg and (not ref $arg->{'only'} or ref $arg->{'only'} eq 'ARRAY');
    my $color_space = Graphics::Toolkit::Color::Space::Hub::try_get_space( $arg->{'in'} );
    return error($color_space.$help.$POD_link) if defined $arg->{'in'} and not ref $color_space;
    $arg->{'in'} = $color_space if defined $arg->{'in'};
    my $default_space = Graphics::Toolkit::Color::Space::Hub::get_space( 'OKHSL' );
	my $result = Graphics::Toolkit::Color::Calculator::invert( $self->values_object, $arg->{'only'}, $arg->{'in'}, $default_space );
    return error($result.$help.$POD_link) unless ref $result;
    return _new_from_value_obj( $result );
}

## color set creation methods ##########################################
sub complement {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'steps', [], {steps => 1, tilt => 0, skew => 0, target => {}, in => $design_default});
    my $help = 'The method "complement" returns a list of GTC objects with complementary colors. Optional arguments are: '.
               '"steps" (color count, default 1 - default argument), "in" (color space name, default "OKHSL", "tilt", "skew" and "target")!';
    return error($arg.$help.$POD_link) unless ref $arg;
    return error('Optional argument "steps" has to be a number ! '.$help.$POD_link) unless is_nr($arg->{'steps'});
    return error('Optional argument "steps" is zero or negative, no complement colors will be computed! '.$help.$POD_link) if $arg->{'steps'} < 1;
    return error('Optional argument "tilt" has to be a number! '.$help.$POD_link) unless is_nr($arg->{'tilt'});
    return error('Optional argument "skew" has to be a number! '.$help.$POD_link) unless is_nr($arg->{'skew'});
    return error('Optional argument "target" has to be a HASH ref! '.$help.$POD_link) if ref $arg->{'target'} ne 'HASH';
    my ($target_delta, $space_name);
    if (keys %{$arg->{'target'}}){
        ($target_delta, $space_name) = Graphics::Toolkit::Color::Space::Hub::deformat_search_partial_hash( $arg->{'target'}, 'HSL' );
        return error('Optional argument "target" got HASH keys that do not fit HSL roles ("h","s","l")! '.$help.$POD_link) unless ref $target_delta;
    } else { $target_delta = [] }
    my $color_space = Graphics::Toolkit::Color::Space::Hub::try_get_space( $arg->{'in'} );
    return error($color_space.$help.$POD_link) unless ref $color_space;
    return error("Need a cylindrical space from the HSL family! ".$help.$POD_link) unless $color_space->family eq 'HSL';

    my @result = Graphics::Toolkit::Color::SetCalculator::complement( $self->values_object, $target_delta, @$arg{qw/steps tilt skew/}, $color_space );
	return error($result[0].$help.$POD_link) unless ref $result[0];
    map {_new_from_value_obj( $_ )} @result;
}

sub analogous {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'to', ['to'], {steps => 4, tilt => 0, in => $design_default});
    my $help = 'The method "analogous" returns a list of GTC objects with analogous colors. Arguments are: "to" (next color - default arg. and required), '.
               '"steps" (max. color count, default 4), "in" (color space name, default "OKHSL" and "tilt"!';
    return error($arg.$help.$POD_link) unless ref $arg;
    my $next_color = _new_from_scalar_def( $arg->{'to'} );
    if  (ref $next_color) { $arg->{'to'} = $next_color->values_object }
    else                  { return error('Argument "to" contains malformed color definition! '.$next_color.$POD_link) }
    return error('Optional argument "steps" has to be a number ! '.$help.$POD_link) unless is_nr($arg->{'steps'});
    return error('Optional argument "steps" has to be a number greater equal two! '.$help.$POD_link) unless is_nr($arg->{'steps'}) and $arg->{'steps'} >= 2;
    return error('Optional argument "tilt" has to be a number! '.$help.$POD_link) unless is_nr($arg->{'tilt'});
    my $color_space = Graphics::Toolkit::Color::Space::Hub::try_get_space( $arg->{'in'} );
    return error($color_space.$help.$POD_link) unless ref $color_space;

    my @result = Graphics::Toolkit::Color::SetCalculator::analogous( $self->values_object, $arg->{'to'}, @$arg{qw/steps tilt/}, $color_space);
	return error($result[0].$help.$POD_link) unless ref $result[0];
    map {_new_from_value_obj( $_ )} @result;
}

sub gradient {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, 'to', ['to'], {steps => 10, tilt => 0, in => 'OKLAB'});
    my $help = 'The method "gradient" returns a list of GTC objects with a gradual transition between colors. Arguments are: '.
               '"to" (next color - default arg. and required), "steps" (color count, default 10), "in" (color space name, default "OKLAB" and "tilt")!';
    return error($arg.$help.$POD_link) unless ref $arg;
    my @colors = ($self->values_object);
    my $target_color = _new_from_scalar_def( $arg->{'to'} );
    if (ref $target_color) {
        push @colors, $target_color->values_object }
    else {
        return error('Argument "to" contains malformed color definition! '.$help.$POD_link) if ref $arg->{'to'} ne 'ARRAY' or not @{$arg->{'to'}};
        for my $color_def (@{$arg->{'to'}}){
            my $target_color = _new_from_scalar_def( $color_def );
            return error('Argument "to" contains malformed color definition: '.$color_def.'! '.$help.$POD_link) unless ref $target_color;
            push @colors, $target_color->values_object;
        }
    }
    return error('Argument "steps" has to be a number greater equel two! '.$help.$POD_link) unless is_nr($arg->{'steps'}) and $arg->{'steps'} >= 2;
    $arg->{'steps'} = int $arg->{'steps'};
    return error('Argument "tilt" has to be a number! '.$help.$POD_link) unless is_nr($arg->{'tilt'});
    my $color_space = Graphics::Toolkit::Color::Space::Hub::try_get_space( $arg->{'in'} );
    return error($color_space.$help.$POD_link) unless ref $color_space;

    my @result = Graphics::Toolkit::Color::SetCalculator::gradient( \@colors, @$arg{qw/steps tilt/}, $color_space);
	return error($result[0].$help.$POD_link) unless ref $result[0];
    map {_new_from_value_obj( $_ )} @result;
}

sub cluster {
    my ($self, @args) = @_;
    my $arg = _split_named_args( \@args, undef, ['radius', 'minimal_distance'], {in => 'OKLAB'}, {radius => 'r', minimal_distance => 'min_d'});
    my $help = 'The method "cluster" returns a list of GTC objects with similar but distinct colors. The arguments are: '.
               '"radius" (max. distance from center, alias "r", required), "minimal_distance" (between colors, required) and "in" (color space name, default "OKLAB")!';
    return error($arg.$help.$POD_link) unless ref $arg;
    my $color_space = Graphics::Toolkit::Color::Space::Hub::try_get_space( $arg->{'in'} );
    return error($color_space.$help.$POD_link) unless ref $color_space;
    return error('Argument "radius" has to be a non-negative number or an ARRAY of numbers that holds for each space axis a radius value. '.$help.$POD_link)
        unless (is_nr($arg->{'radius'}) and $arg->{'radius'} >= 0) or $color_space->is_number_tuple( $arg->{'radius'} );
    return error('Argument "minimal_distance" (or "min_d") has to be a number greater zero! '.$help.$POD_link)
        unless is_nr($arg->{'minimal_distance'}) and $arg->{'minimal_distance'} > 0;
    return error('Ball shaped cluster works only in spaces with three dimensions! '.$help.$POD_link)
        if $color_space->axis_count > 3 and not ref $arg->{'radius'};

    my @result = Graphics::Toolkit::Color::SetCalculator::cluster( $self->values_object, @$arg{qw/radius minimal_distance/}, $color_space);
	return error($result[0].$help.$POD_link) unless ref $result[0];
    map {_new_from_value_obj( $_ )} @result;
}

1;

__END__