ChromaSense Plugin Documentation¶

Welcome to the ChromaSense Plugin documentation. This plugin provides various functionalities for detecting brightness, unlit colors, and line of sight in Unreal Engine.

ChromaSense Example

Table of Contents¶

Introduction
Installation
Configuration
Usage
Conclusion

Introduction¶

The ChromaSense plugin provides functionalities to:

Detect brightness in specific areas.
Retrieve unlit colors.
Determine line of sight between objects.
Utilize async actions for non-blocking operations.
Compare, contrast, and analyze brightness and unlit colors.

Installation¶

Manual Installation:¶

Follow these steps to get the ChromaSense plugin up and running in your Unreal Engine project:

Clone the plugin repository into your project's Plugins directory: git clone <repo-url> Plugins/
Open your Unreal Engine project.
Go to Edit > Plugins and enable the ChromaSense plugin.
Restart the Unreal Engine editor to apply changes.

Marketplace Installation:¶

Install from Fab or the Unreal Engine Marketplace.
Open your Unreal Engine project.
Go to Edit > Plugins and enable the ChromaSense plugin.
Restart the Unreal Engine editor to apply changes.

When you have successfully installed the plugin, you should place a ChromaSenseContainerActor in your level to manage the capture components.

It will automatically try and create one if you have not, but the best practice is to place one in your level.

Configuration¶

Here are the default configuration settings for the ChromaSense plugin:

Configuration

class UChromaSenseSettings : public UObject
{
    GENERATED_BODY()
public:
    UPROPERTY(config, EditAnywhere, Category = "Async")
    uint8 MaxActiveThreads = 8; // Maximum number of threads

    UPROPERTY(config, EditAnywhere, Category = "Capture")
    FVector2D CaptureResolution = FVector2D(4.0f, 4.0f); // Resolution for capturing

    UPROPERTY(config, EditAnywhere, Category = "Capture")
    float FieldOfView = 2.0f; // Field of view for capturing

    UPROPERTY(config, EditAnywhere, Category = "Capture")
    float BrightnessThreshold = 0.5f; // Brightness threshold

    UPROPERTY(config, EditAnywhere, Category = "Debug")
    float DebugLifetime = 5.0f; // Debug message lifetime

    UPROPERTY(config, EditAnywhere, Category = "Debug")
    float DebugShapeLifetime = 5.0f; // Debug shape lifetime

    UPROPERTY(config, EditAnywhere, Category = "Capture")
    float msCaptureDelay = 0.033f; // Delay between captures

    UPROPERTY(config, EditAnywhere, Category = "Capture")
    bool bAlwaysPersistRenderState = false; // Persist render state setting
};

Usage¶

ChromaSense Function Library¶

The ChromaSense function library provides various static methods to interact with the plugin's functionalities.

Get Brightness

You can use the GetBrightness_Static function to get the brightness of a specific area. Here's how you can use it in Blueprints:

This isn't the preferred method, you should use the async action instead, however this is for immediate calls.

UFUNCTION(BlueprintCallable, Category = "Chroma Sense | Lighting", meta = (ReturnDisplayName = "Get Brightness", WorldContext = "WorldContextObject"))
static float GetBrightness_Static(
    UObject* WorldContextObject,
    FTransform InTransform,
    FColor& LightColor,
    bool bUseAverage = true, 
    UTextureRenderTarget2D* OptionalRenderTarget = nullptr);

Get Brightness Blueprint

Get Unlit Color

You can use the GetUnlitColor_Static function to get the unlit color of a specific area. Here's how you can use it in Blueprints:

UFUNCTION(BlueprintCallable, meta = (WorldContext = "WorldContextObject"), Category = "Chroma Sense | Lighting", meta = (ReturnDisplayName = "Get Unlit Color"))
static FColor GetUnlitColor_Static(
    UObject* WorldContextObject,
    FTransform InTransform,
    float& OutBrightness,
    bool bUseAverage = true, 
    UTextureRenderTarget2D* OptionalRenderTarget = nullptr);

Get Unlit Color Blueprint

ChromaSense Light Async Action¶

This async action retrieves the brightness of a specific area asynchronously.

Example Blueprint Node: GetBrightness_Async¶

You can use the GetBrightness_Async function to asynchronously get the brightness of a specific area. Here's how you can set it up in Blueprints:

UCLASS()
class CHROMASENSE_API UChromaSenseLightAsyncAction : public UBlueprintAsyncActionBase
{
    GENERATED_BODY()
public:
    UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext = "WorldContextObject"), Category = "Chroma Sense | Light")
    static UChromaSenseLightAsyncAction* GetBrightness_Async(
        UObject* WorldContextObject, 
        FTransform InTransform,
        bool bUseAverage, 
        UTextureRenderTarget2D* OptionalRenderTarget);

    UPROPERTY(BlueprintAssignable)
    FOnLightCaptureComplete OnLightCaptureComplete;
};

Get Brightness Async Blueprint

ChromaSense Unlit Async Action¶

This async action retrieves the unlit color of a specific area asynchronously.

Example Blueprint Node: GetUnlitColor_Async¶

You can use the GetUnlitColor_Async function to asynchronously get the unlit color of a specific area. Here's how you can set it up in Blueprints:

UCLASS()
class CHROMASENSE_API UChromaSenseUnlitAsyncAction : public UBlueprintAsyncActionBase
{
    GENERATED_BODY()
public:
    UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext = "WorldContextObject"), Category = "Chroma Sense | Light")
    static UChromaSenseUnlitAsyncAction* GetUnlitColor_Async(
        UObject* WorldContextObject, 
        FTransform InTransform,
        bool bUseAverage, 
        UTextureRenderTarget2D* OptionalRenderTarget);

    UPROPERTY(BlueprintAssignable)
    FOnUnlitCaptureComplete OnUnlitCaptureComplete;
};

Get Unlit Color Async Blueprint

Camera Line of Sight¶

Get Camera Line Of Sight¶

The GetCameraLineOfSight function determines the line of sight between the camera and a vector.

UFUNCTION(BlueprintCallable, Category = "Chroma Sense | Line of Sight", meta = (WorldContext = "WorldContextObject"), meta = (ReturnDisplayName = "Get Camera Line of Sight"))
static void GetCameraLineOfSight(
    UObject* WorldContextObject,
    AActor* CameraActor,
    FVector TargetLocation,
    bool bLineOfSight,
    FVector& EndPositionLOS,
    FVector& AveragePositionLOS);

ChromaSense Camera Line of Sight Blueprint

The EndPositionLOS is the line of sight that has the shortest distance to the camera. AveragePositionLOS is the average of all the line of sight positions.

If bLineOfSight is false, either of these values will be a zero vector.

Get Camera Line Of Sight to Object¶

The GetCameraLineOfSightToObject function determines the line of sight between the camera and an object.

UFUNCTION(BlueprintCallable, Category = "Chroma Sense | Line of Sight", meta = (WorldContext = "WorldContextObject"), meta = (ReturnDisplayName = "Get Camera Line of Sight to Object"))
static void GetCameraLineOfSightToObject(
    UObject* WorldContextObject,
    AActor* CameraActor,
    AActor* TargetActor,
    bool bLineOfSight,
    FVector& EndPositionLOS,
    FVector& AveragePositionLOS);

ChromaSense Camera Line of Sight to Object Blueprint

Get Closest Actor Of Class¶

The GetClosestActorOfClass function retrieves the closest actor of a specific class to the camera.

UFUNCTION(BlueprintCallable, Category = "Chroma Sense | Line of Sight", meta = (WorldContext = "WorldContextObject"), meta = (ReturnDisplayName = "Get Closest Actor of Class"))
static AActor* GetClosestActorOfClass(
    UObject* WorldContextObject,
    AActor* CameraActor,
    TSubclassOf<AActor> ActorClass);

ChromaSense Get Closest Actor of Class Blueprint

Color Functions¶

Here are the various color functions available in the ChromaSense plugin. Their use is fairly self explanatory.

Hover over the nodes in Unreal Engine to see their descriptions.

Color Functions

ChromaSense World Subsystem¶

The ChromaSense World Subsystem manages various components used by the plugin. It provides a centralized location for managing capture components and characters.

Key Components Managed by the Subsystem¶

LightCaptureComponents: Array of extended scene capture components.
ChromaSenseContainerActor: Container actor for managing capture components.
ChromaSenseCharacters: Array of characters using ChromaSense functionalities.

Conclusion¶

This documentation covers the installation, configuration, and usage of the ChromaSense plugin with a focus on Blueprints. Utilize the provided nodes for efficient and asynchronous operations in your Unreal Engine projects.