Domains

Creamas includes some functionality for different artifact domains, e.g. images.

Note

Generally, these modules need extra requirements to be installed:

pip install creamas[extras]

Warning

This functionality is currently being developed.

Images

Genetic Programming

class creamas.domains.image.gp.generator.GPImageGenerator(creator_name, toolbox, pset, generations, pop_size, evaluate_func, shape=(32, 32), super_pset=None)

A generator class producing instances of GPImageArtifact using genetic programming.

The generator uses DEAP in its internal operation, and requires extras to be installed: pip install creamas[extras].

Generator class can be used in two different manners:

• calling only the static functions of the class, or

• creating a new instance of the class associated with a specific agent and calling GPImageGenerator.generate().

Most of the initialization arguments are used as defaults in the calls for generate(), and can be overridden when using it.

Parameters

• creator_name (str) – Name of the creator agent used by generate() as a default.

• toolbox – DEAP’s toolbox used by generate() as a default.

• pset – DEAP’s primitive set which is used to create the images.

• generations – Number of generations to evolve

• pop_size – Population size.

• shape – Shape of the produced images during the evolution. The resolution can be (indefinitely) up-scaled for the accepted artifacts.

• evaluate_func (callable) – A function used to evaluate each image, e.g. evaluate() Function should accept one argument, a GPImageArtifact and return an evaluation of an artifact. Evaluation is supposed to be maximized.

• super_pset – In a case an agent may create artifacts in conjunction with other agents, super_pset should contain all the primitives all the agents may use. If None, this is set to pset.

static create_population(size, pset, generation_method, individual_creator=None, toolbox=None)

Creates a population of randomly generated individuals.

Parameters

• size – The size of the generated population.

• pset – The primitive set used in individual generation.

• generation_method – Generation method to create individuals, e.g. deap.gp.genHalfAndHalf().

• individual_creator – If None calls init_deap_creator() with class suffix “”.

• toolbox – DEAP toolbox. If None a new toolbox is created.

Returns

DEAP toolbox and a list containing the generated population as DEAP individuals.

evaluate_individual(individual, shape)

Evaluates a DEAP individual.

This method inherently changes the individual to GPImageArtifact for the evaluation.

Parameters

• individual – The individual to be evaluated.

• shape – Shape of the image.

Returns

The evaluation.

static evolve_population(population, generations, toolbox, pset, hall_of_fame, cxpb=0.75, mutpb=0.25, injected_individuals=[], use_selection_on_first=True)

Evolves a population of individuals. Applies elitist selection strategy (k=1) in addition to toolbox’s selection strategy to the individuals.

Parameters

• population – A list containing the individuals of the population.

• generations – Number of generations to be evolved.

• toolbox – DEAP toolbox with the necessary functions.

• pset – DEAP primitive set used during the evolution.

• hall_of_fame – DEAP’s hall-of-fame

• cxpb (float) – Crossover probability

• mutpb (float) – Mutation probability

• injected_individuals (list) – A list of individuals which are injected into the starting population

• use_selection_on_first (bool) – If True, uses selection on the first generation before producing offspring, otherwise produces offspring from the

generate(artifacts=1, generations=None, pset=None, pop_size=None, shape=None, old_artifacts=[], mutate_old=True)

Generate new artifacts using instance’s own toolbox and given arguments.

Parameters

• artifacts (int) – The number of the most fit artifacts to be returned.

• generations (int) – Number of generations to be evolved. If None uses initialization parameters.

• pset – DEAP’s primitive set used to create the individuals.

• pop_size (int) – DEAP population size

• shape (tuple) – Shape of the created images. This heavily affects the execution time.

• old_artifacts (list) – A list of existing GPImageArtifact objects, which should be part of the initial population. Each artifact in the list should have the function tree for the individual stored in artifact.framings['function_tree'].

• mutate_old (bool) – If True, forces mutation on the existing individuals from.

Returns

A list of generated GPImageArtifact objects. The artifacts returned do not have their framing information (evaluation, etc.) filled.

static individual_to_artifact(creator_name, individual, shape, pset=None, bw=True)

Convert DEAP´s individual to GPImageArtifact.

This will create the inherent image object, if it is not already present in the individual. If individual has already an image associated with it, that image is used and shape and bw parameters are omitted.

Fails silently if the image creation does not succeed, i.e. deap.gp.compile fails for the given individual and pset, and returns None.

Parameters

• creator_name (str) – Name of the creator of the image.

• individual – Function (DEAP´s individual) of the image.

• shape – Shape of the returned image.

• pset – DEAP’s primitive set used to compile the individual.

• bw – If True, the individual is assumed to represent grayscale image, otherwise it is assumed to be an RGB image.

Returns

GPImageArtifact or None

static init_deap_creator(class_suffix, pset)

Initializes the DEAP deap.creator by creating classes which use the wanted primitive set to maximize fitness.

The created classes are found from deap.creator with names FitnessMax-[class_suffix] and Individual-[class_suffix] using, e.g. getattr(deap.creat or, "FitnessMax-{}".format(class_suffix)). The method should be called only once per class_suffix as subsequent calls will erase previously created classes.

Parameters

• class_suffix (str) – Suffix for the created fitness and individual classes.

• pset – Primitive set used by the individual creator.

Returns

Created classes

static initial_population(toolbox, pset, pop_size, individual_creator=None, old_artifacts=[], mutate_old=True)

Create initial population for new evolution.

Population is formed by first creating individuals from old_artifacts and then the rest of the population is generated using deap.gp.genHalfAndHalf() with given pset.

Parameters

• toolbox – DEAP toolbox.

• pset – Primitive set for the population’s new individuals.

• pop_size – Size of the population.

• individual_creator – Class used to create new individuals, if None tries to use deap.creator.Individual.

• old_artifacts (list) – A list of existing GPImageArtifact objects, which should be part of the initial population. Each artifact in the list should have the function tree for the individual stored in artifact.framings['function_tree'].

• mutate_old (bool) – If True, forces mutation on the existing individuals from.

Returns

Created population

class creamas.domains.image.gp.artifact.GPImageArtifact(creator, obj, function_tree, string_repr=None)

An artifact implementation for the images created using genetic programming, GPImageArtifact requiring pip install creamas[extras]. The artifact implementation is coupled with GPImageGenerator, the generator producing evolutionary art using genetic programming.

Each GPImageArtifact.obj should be a numpy array with a data type np.uint8.

Parameters

• creator – Name of the creator agent.

• obj – Image generated, numpy array with dtype==np.uint8.

• function_tree – Function from which the image was generated. This is stored to framings[‘function_tree’].

• string_repr – String representation of the function. This is stored to framings[‘string_repr’].

add_feature_value(feat, val)

Add objective feature value for given feature.

static artifact_from_file(creator_name, individual_file, pset, shape=(32, 32), bw=True)

Create an artifact object from given function file.

Parameters

• creator_name (str) – Name of the creator

• individual_file – Path to the function

• pset – Primitive set to recreate the image

• shape – Dimensions of the image

• bw (bool) – If True, creates a grayscale image (2D numpy.array), otherwise creates 3D numpy.array.

static distance(artifact1, artifact2)

Euclidean distance between two artifact’s which objects are images.

Images are expected to be of type np.uint8. The intensity values are converted to floats in [0, 1] before computing the distance.

get_feature_value(feat)

Return objective feature value for given feature, or None if it is not found.

static image_from_file(individual_file, image_file, pset, color_map=None, shape=(400, 400))

Save an individual saved as a string into a file as a new image with given color mapping and resolution.

The function uses scipy.misc.imsave().

Parameters

• individual_file (str) – Path to the file with the string representation of the individual.

• image_file (str) – Path to the file where image is saved. The image type is defined by the file type.

• pset – DEAP’s primitive set required to compile string representation of the individual into an individual.

• color_map – Color map used to colorize a greyscale image, e.g. one of the matplotlib’s color maps.

• shape (tuple) – Shape of the generated image. Default is (400, 400).

static image_from_function(func, shape=(32, 32), bw=True)

Generate image from the given function.

Parameters

• func – A function returned by deap.gp.compile() used to compute the color values.

• shape – Shape of the returned image.

• bw (bool) – If True, func is assumed to represent a grayscale image, otherwise it is assumed to be an RGB image.

Returns

A numpy array containing the color values. The format is np.uint8 for opencv compatibility.

If any errors occur during the image creation, fails silently and returns a black image.

static max_distance(shape, bw=True)

Maximum distance between two images is calculated as the euclidean distance between an image filled with zeros and an image filled with 255.

static png_compression_ratio(artifact)

Compute png compression ratio for the image of the given artifact.

PNG compression ratio: size(png) / size(bmp)

If ratio is low (< 0.08), then the image can be seen as uninteresting.

static save(artifact, image_file, pset, color_map=None, shape=(400, 400), string_file=None)

Saves an artifact as an image.

Parameters

• artifact – The artifact to be saved.

• image_file (str) – Path to the file where image is saved. The image type is defined by the file type.

• pset – DEAP’s primitive set required to compile string representation of the individual into an individual.

• color_map – Color map used to colorize a greyscale image, e.g. one of the matplotlib’s color maps.

• shape (tuple) – Shape of the generated image. Default is (400, 400).

• string_file (str) – If not None saves also the function associated with the artifact as txt in to the given file.

property feature_values

Values for all features extracted from the image.

Tools

Utilities for the GPImageGenerator and agents utilizing it requiring pip install creamas[extras].

creamas.domains.image.gp.tools.create_sample_pset(bw=True, sample_size=8)

Create a sampled pset from all primitives.

creamas.domains.image.gp.tools.create_super_pset(bw=True)

Create super pset which contains all the primitives for DEAP.

Parameters

bw (bool) – If True the returned primitive set is primed to create grayscale images, otherwise it will create RGB images.

Returns

Created primitive set

creamas.domains.image.gp.tools.create_toolbox(pset)

Creates a DEAP toolbox with some reasonable defaults:

• toolbox.expr creates new individuals with deap.gp.genHalfAndHalf() with depth in [2, 6].

• toolbox.mate Uses deap.gp.cxOnePoint() enforcing GP_TREE_MAX_DEPTH

• toolbox.mutate Uses deap.gp.mutUniform() enforcing GP_TREE_MAX_DEPTH

• toolbox.select Uses deap.tools.selDoubleTournament() with fitness_size=3, parsimony_size=1.4, fitness_first=True

Parameters

pset – Primitive set

Returns

deap.base.Toolbox

creamas.domains.image.gp.tools.subtree_mutate(individual, pset, expr)

Choose a random node and generate a subtree to that node using expr and pset.

Features

Various feature implementations for images requiring pip install creamas[extras].

class creamas.domains.image.features.ImageComplexityFeature

Feature that estimates the fractal dimension of an image. The color values must be in range [0, 255] and type int. Returns a float.

extract(artifact, canny_threshold1=100, canny_threshold2=200)

Extract fractal dimension estimate from the given image artifact.

The method first extracts edges using cv2.Canny and the resulting edge image is passed down to the fractal dimension estimator.

class creamas.domains.image.features.ImageRednessFeature

Feature that measures the redness of an RGB image. Returns a float in range [0, 1].

extract(artifact)

Get redness of the image.

class creamas.domains.image.features.ImageGreennessFeature

Feature that measures the greenness of an RGB image. Returns a float in range [0, 1].

extract(artifact)

Get greenness of the image.

class creamas.domains.image.features.ImageBluenessFeature

Feature that measures the blueness of an RGB image. Returns a float in range [0, 1].

extract(artifact)

Get blueness of the image.

class creamas.domains.image.features.ImageIntensityFeature

Feature that measures the intensity of an image. Returns a float in range [0, 1].

extract(artifact)

Get average intensity of the image.

class creamas.domains.image.features.ImageBenfordsLawFeature

Feature that computes the Benford’s Law for the image.

See also

Benford’s Law

extract(artifact)

Extract feature’s value from an artifact.

If artifact with a domain not in domains is used as a parameter, the function should return None.

Returns

Value extracted from the artifact.

Return type

rtype or None

class creamas.domains.image.features.ImageEntropyFeature(normalize=False)

Compute entropy of an image and normalize it to interval [0, 1].

Entropy computation uses 256 bins and a grey scale image.

Parameters

normalize (bool) – Should the returned entropy value be normalized.

extract(artifact)

Extract feature’s value from an artifact.

If artifact with a domain not in domains is used as a parameter, the function should return None.

Returns

Value extracted from the artifact.

Return type

rtype or None

class creamas.domains.image.features.ImageSymmetryFeature(axis, use_entropy=True)

Compute symmetry of the image in given ax or combination of axis.

Feature also allows adding the computed symmetry with “liveliness” of the image using use_entropy=True. If entropy is not used, simple images (e.g. plain color images) will give high symmetry values.

Parameters

• axis –

  ImageSymmetryFeature.HORIZONTAL, ImageSymmetryFeature.VERTICAL, ImageSymmetryFeature.DIAGONAL, ImageSymmetryFeature.ALL_AXES

  These can be combined, e.g. axis=ImageSymmetryFeature.HORIZONTAL+ ImageSymmetryFeature.VERTICAL.

• use_entropy (bool) – If True multiples the computed symmetry value with image’s entropy (“liveliness”).

extract(artifact)

Return symmetry of the image.

Other domains

Other domains are currently being developed