Entity Styles

interface IStyle {
    // Unique ID for the Style. When unset and saved, one will be generated.
    ID: number;
    // User friendly name.
    Name: string;
    // The Style settings, this differs based on the type of Style it is.
    Settings: {
        // Settings are split up by the visual's type.
        // We will cover these below as separate case studies.
        pointStyle?: any,
        polygonStyle?: any,
        polylineStyle?: any,
        // 3D model styling is used for both Tileset Entities and 3D model Entities.
        modelStyle?: any
    };
    // The type of Style. In this case we're covering Entity Styles.
    // When unset, we assume it is an Entity Style as it is the original type.
    Type: "ENTITY";
}

// Available calculator item types.
enum EValueType {
    // Color is a fixed css color value.
    Color = 0,
    // Input is a fixed or attribute value.
    // You can either specify an exact value, or an attribute path which will grab the value from the rendered Entity.
    Input = 1,
    // A gradient item is calculated using an Entity number attribute.
    // For example you can have a gradient that changes the color of an Entity based on its height.
    Gradient = 2,
    // A mapping item is calculated by an Entity string or number attribute.
    // For example you might have a region attribute and map those regions to different colours.
    Mapping = 3,
    // Tag color will use the first tag on the Entity that has a color.
    // For example if an Entity is tagged with "New Zealand" in green, and "Auckland city" as yellow, then it'll be green.
    TagColor = 4,
    // Random color will generate a random color for each Entity.
    // This is useful for debugging... Not recommended for production.
    RandomColor = 5
}

// The base calculator item.
// A Style property typically is set to an array of these.
// The first to resolve with a value will be applied.
interface IField {
    value: IGradientValue | IMappingValue | string | number;
    type: EValueType;
}

/// Gradient field. ///

// A gradient item is calculated using an Entity number attribute.
// For example you can have a gradient that changes the color of an Entity based on its height.

interface IGradientValue {
    // This is an attribute path to load a value from the rendered Entity.
    // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
    field: string;

    // This is a range of values to map the gradient to.
    // For example you can have a point at "0" then a point at "100".
    // If the attribute value is "50" then it'll be half way between the two points and a gradient between those two colours would be calculated.
    points: IGradientPoint[];
}

interface IGradientPoint {
    // The value of this point within the gradient range.
    position: number;
    // CSS colour string.
    color: string;
}


/// Mapping field. ///

// A mapping item is calculated by an Entity string or number attribute.
// For example you might have a region attribute and map those regions to different colours.

interface IMappingValue {
    // This is an attribute path to load a value from the rendered Entity.
    // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
    field: string;

    // The attribute value will be compared with these options to find a match.
    values: IMappingOption[];
}

interface IMappingOption {
    // This is a possible value to match against.
    // In the case of string values we will do direct comparisons.
    // In the case of number values you can specify ranges or direct values.
    // For example you can either specify "5" directly, or "1-5" as a range.
    fieldValue: string;

    // This is the result of a successful match.
    // If this Style is dictating a colour then this would be a css colour string.
    appliedValue: string;
}

enum EOptionId {
    // When set to absolute the terrain is ignored and the altitude is set to whatever is specified.
    Absolute = 0,
    // Altitude is set to the terrain. The Entity altitude is ignored.
    ClampToGround = 1,
    // Altitude is set as an offset from the terrain.
    // Eg: an altitude of 5m would be 5 meters above the ground at that spot.
    RelativeToGround = 2
}

interface IAltitudeOption {
    id: EOptionId;
    // Backwards compatibility name.
    // Some of our older data exports require this set but for rendering in the Navigator this is unused.
    name?: "Absolute position" | "Clamp to ground" | "Reference to ground";
}

// Points come primarily as icons or pixel points.
EPointType {
    // Point types are rendered at a specific pixel size.
    Point = "POINT",
    // Icons are points that render an image instead of a circle.
    Icon = "ICON"
}

interface IPointSettings {
    // The type of point. This helps dictate what settings are relevant.
    // The default when unspecific will be "POINT".
    Type?: EPointType;
    // The size in pixels of the point.
    // This is only relevant for "POINT" types. For "ICON" types the size is dictated by the icon image itself.
    // This must resolve in a number to be valid, otherwise it'll default to the application's default value.
    size?: IField[];
    // The url to load an icon from.
    // This is only relevant for "ICON" types.
    iconUrl?: IField[];
    // The scale factor of the icon.
    // This is only relevant for "ICON" types.
    // For example a 50x50 icon with a scale of 2 will render as 100x100 on the screen.
    // This must resolve in a number to be valid, otherwise it'll default to the application's default value.
    iconScale?: IField[];
    // The colour of the point.
    // This is only relevant for "POINT" types.
    // This must resolve into a css colour string to be valid, otherwise it'll default to the application's default value.
    color?: IField[];
    // This dictates what the altitude value of an Entity should mean.
    // For example if you set this to be clamp-to-ground then the altitude value will be ignored.
    // Default is clamped to ground.
    altitudeOption?: IAltitudeOption;
}

{
    color: [
        // Mapping based on 'rent' attribute.
        {
            value: {
                field: "rent",
                values: [
                    {
                        fieldValue: "£208",
                        appliedValue: "rgba(50, 180, 50, 0.8)"
                    }
                ]
            },
            type: EValueType.Mapping
        },
        // Gradient based on 'location' -> 'longitude' attribute.
        {
            value: {
                // If you're using the web libraries we recommend using the 'PathUtils' utility to wrap these for you.
                // Eg: BModels.PathUtils.Wrap(["location", "longitude"]);
                field: "\"location"/"longitude\"",
                points: [
                    {
                        position: -1.099,
                        color: "rgba(255, 0, 0, 0.8)"
                    },
                    {
                        position: -1.046,
                        color: "rgba(255, 255, 255, 0.8)"
                    }
                ]
            },
            type: EValueType.Gradient
        },
        // Fallback color in case the above doesn't work.
        {
            value: "rgba(255, 255, 255, 0.4)",
            type: EValueType.Color
        }
    ]
}

interface IPolylineSettings {
    // The colour of the line.
    // This must resolve into a css colour string to be valid, otherwise it'll default to the application's default value.
    lineColor: IField[];
    // The width of the line in either pixels or meters based on the units specified.
    // This must resolve into a number to be valid, otherwise it'll default to the application's default value.
    lineWidth: IField[];
    // Default is "px" for backward compatibility.
    lineWidthUnits?: "px" | "m";
    // Polylines do not support relative to ground positioning.
    // When set to "absolute" then each point's altitude will be used rather than clamping to the ground.
    // Default is clamped to ground.
    altitudeOption?: IAltitudeOption;
    // The z index will dictate what vector appears on top vertically.
    // It is only applied when the altitude option is set to "clamped-to-ground".
    // For example a higher z index will appear on top of a lower z index.
    zIndex?: IField[];
}

interface IPolygonSettings {
    // If the polygon should be extruded.
    useExtrusion: boolean;
    // The height of the extrusion in meters.
    // This must resolve into a number to be valid, otherwise it will not extrude.
    extrusionPath: IField[];
    // The colour of the fill.
    // This must resolve into a css colour string to be valid, otherwise it'll default to the application's default value.
    fillColor: IField[];
    // The colour of the outline.
    // This must resolve into a css colour string to be valid, otherwise it'll default to the application's default value.
    lineColor: IField[];
    // Width of outline in meters.
    // This must resolve into a number to be valid, otherwise it'll default to the application's default value.
    lineWidth: IField[];
    // Default is "m".
    lineWidthUnits?: "px" | "m";
    // The z index will dictate what vector appears on top vertically.
    // It is only applied when the altitude option is set to "clamped-to-ground".
    // For example a higher z index will appear on top of a lower z index.
    zIndex?: IField[];
    // Dictates what the altitude value of an Entity should mean.
    // When not set to "clamp-to-ground" each individual's altitude will be used.
    // Default is clamped to ground.
    altitudeOption?: IAltitudeOption;
}

enum EBlendMode {
    // Multiplies the source color by the target color.
    Highlight = 0,
    // Replaces the source color with the target color.
    Replace = 1,
    // Blends the source color and target color together
    Mix = 2
}

// When dealing with tilesets the only settings that are applied are "customize" and "fillColor".
interface IModelSettings {
    // Indicates if the 3D model should be coloured by the Style.
    // Default is false.
    customize: boolean;
    // The colour to apply to the model if customize is set to true.
    // This must resolve into a css colour string to be valid, otherwise it'll default to the application's default value.
    fillColor: IField[];
    // The model's scale factor.
    // This is multiplied against the Entity's transform scale.
    // For example if the Entity has a scale of 2 and this resolves to 3 then the final scale will be 6.
    // This must resolve into a number to be valid, otherwise it'll default to the application's default value (1).
    scale: IField[];
    // Dictates how the colour specified should be applied to the model.
    fillColorBlendMode?: EBlendMode;
    // If blend is set to "Mix" then this will dictate how much of the source colour should be used.
    // This is value between 0 and 1, default is "0.5". 1 means only the applied colour is used.
    fillColorBlendAmount?: number;
    // Dictates what the altitude value of an Entity should mean.
    // Default is relative to ground.
    altitudeOption?: IAltitudeOption;
}