IColorInImageDetectionΒΆ

interface IColorInImageDetection : System.IDisposable

An interface that represents an implementation which detects the color in images (from a given image source) and returns locations in the image where the color appears in high concentrations.

This interface must be constructed using T:Protogame.IImageProcessingFactory. Because it processes data in a background thread, you must call M:Protogame.IColorInImageDetection.Start to begin the actual image analysis.

float GlobalSensitivity

The global sensitivity used to detect color in the image. This is preset at a sensible default, so you should not really need to change this value.

int ChunkSize

The size of chunks to perform the analysis with. The smaller this value, the exponentially larger number of sections the algorithm has to scan over.

In testing, we have found that for a 640x480 image source, a chunk size of 5 is a reasonable value. This is the default value. If scanning larger images, or if you’re finding the results are being processed too slowly on the background thread, you may need to set this property to a higher value.

Once M:Protogame.IColorInImageDetection.Start has been called, you can not change this value. If you need to change the chunk size after image analysis has been started, you need to M:System.IDisposable.Dispose of this instance and create a new one using the T:Protogame.IImageProcessingFactory factory.

Protogame.ISelectedColorHandle RegisterColorForAnalysis(Color color, string name)

Registers a color for detection. The implementation will continuosly scan the image source on a background thread to detect this color in the image.

You can register multiple colors for detection by calling this method multiple times.

This method returns a handle which you can then use in other methods on this interface to get the results of scanning for this color.

Parameters:
  • color (Microsoft.Xna.Framework.Color) – The color to detect in the image.
  • name (string) – The name of the color for diagnostic purposes.
Returns:
System.Int32[,] GetUnlockedResultsForColor(Protogame.ISelectedColorHandle handle)

Returns a two-dimensional integer array representing the strength of color detected in the image.

When the image is analysed, it is split up into a grid of chunks, where each chunk is P:Protogame.IColorInImageDetection.ChunkSize`x:ref:`P:Protogame.IColorInImageDetection.ChunkSize pixels in size. Each chunk is represented by a single integer in the array. Thus if you map the array returned by this method onto the screen, using a P:Protogame.IColorInImageDetection.ChunkSize`x:ref:`P:Protogame.IColorInImageDetection.ChunkSize rectangle to represent each value going across and then down, you will see the analysis of the original image with the desired color represented as high integer values.

In the returned array, negative values represent a lack of the requested color, while positive values represent a presence of the requested color. Neutral values (close to 0) represent parts of the image which are neither strongly correlated or strongly against the desired color.

For example, if you were detecting the color red, and you had a picture of a blue object in the image source, this array would be filled with a large amount of negative values representing the blue object in the image. If you had a very red object in the image, you would see very high positive integers representing the presence of that object.

In testing, and with the default global sensitivity, we have found that a threshold of positive 100 (after dividing the value by the color’s local sensivity; see M:Protogame.IColorInImageDetection.GetSensitivityForColor(Protogame.ISelectedColorHandle)) represents the precense of a color in an image, while lower values represent neutral or opposite of colors. However, you should be aware that you might need to offer calibration of global sensitivity in your game if your image source is from an external camera, as different lighting conditions may require a different sensitivity level.

Parameters:
  • handle (Protogame.ISelectedColorHandle) – The color handle returned by M:Protogame.IColorInImageDetection.RegisterColorForAnalysis(Microsoft.Xna.Framework.Color,System.String).
Returns:

The two-dimensional integer array representing the strength of color in the image.
float GetSensitivityForColor(Protogame.ISelectedColorHandle handle)

Gets the localised sensitivity value for the specified color.

Because images may contain varying amounts of a specific color in them, the color detection algorithm attempts to normalize the sensitivity on a per-color basis, depending on how much of the image contains that color.

You should divide the integers inside M:Protogame.IColorInImageDetection.GetUnlockedResultsForColor(Protogame.ISelectedColorHandle) by this value to determine the actual score.

Parameters:
  • handle (Protogame.ISelectedColorHandle) – The color handle returned by M:Protogame.IColorInImageDetection.RegisterColorForAnalysis(Microsoft.Xna.Framework.Color,System.String).
Returns:

The sensitivity calculated for the color.
int GetTotalDetectedForColor(Protogame.ISelectedColorHandle handle)

Gets the total amount of color detected in the image.

This value is primarily useful for diagnositic purposes.

Parameters:
  • handle (Protogame.ISelectedColorHandle) – The color handle returned by M:Protogame.IColorInImageDetection.RegisterColorForAnalysis(Microsoft.Xna.Framework.Color,System.String).
Returns:

The total amount of color detected in the image.
string GetNameForColor(Protogame.ISelectedColorHandle handle)

Gets the name of the color when it was originally registered.

Parameters:
  • handle (Protogame.ISelectedColorHandle) – The color handle returned by M:Protogame.IColorInImageDetection.RegisterColorForAnalysis(Microsoft.Xna.Framework.Color,System.String).
Returns:

The name of the color when it was originally registered.
Color GetValueForColor(Protogame.ISelectedColorHandle handle)

Gets the color value of the color when it was originally registered.

Parameters:
  • handle (Protogame.ISelectedColorHandle) – The color handle returned by M:Protogame.IColorInImageDetection.RegisterColorForAnalysis(Microsoft.Xna.Framework.Color,System.String).
Returns:

The color value of the color when it was originally registered.
void Start()

Starts the background image analysis. Until you call this function, no image analysis is performed.