Class AgentVis

Class Documentation

class AgentVis

This provides an interface for managing the render options for all agents of a specific type State() can be called to specialise options for agents within a specific state TODO: Block everything non-const from being called whilst VIS is active

Public Functions

explicit AgentVis(std::shared_ptr<AgentVisData> data)
AgentStateVis State(const std::string &state_name)

Returns the configuration handler for the named state On first use for each state this will assign the state a color from the AutoPalette if available Clear the autopalette first if you wish for it to use the default color

void setXVariable(const std::string &var_name)

Set the name of the variable representing the agents x/y/z location coordinates

Note

unnecessary if the variables are named “x”, “y”, “z” respectively

Note

Implicitly calls clearXYVariable(), clearXYZVariable()

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[1]

void setYVariable(const std::string &var_name)
void setZVariable(const std::string &var_name)
void setXYVariable(const std::string &var_name)

Set the name of the array variable (length 2) representing the agents x/y location coordinates

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[2]

void setXYZVariable(const std::string &var_name)

Set the name of the array variable (length 3) representing the agents x/y/z location coordinates

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[3]

void setForwardXVariable(const std::string &var_name)

Set the name of the variable representing the agents x direction vector components Single axis rotation only requires x/z components Double axis rotation requires all 3 components Triple axis rotation requires all 3 components and additionally all 3 Up components

Note

setForwardXVariable() and setForwardZVariable() are an alternate to providing a yaw angle

Note

Forward is a synonym for Direction

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[1]

void setForwardYVariable(const std::string &var_name)

Set the name of the variable representing the agents y direction vector components Single axis rotation only requires x/z components Double axis rotation requires all 3 components Triple axis rotation requires all 3 components and additionally all 3 Up components

Note

setForwardYVariable() is an alternate to providing a pitch angle

Note

Forward is a synonym for Direction

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[1]

void setForwardZVariable(const std::string &var_name)

Set the name of the variable representing the agents z direction vector components Single axis rotation only requires x/z components Double axis rotation requires all 3 components Triple axis rotation requires all 3 components and additionally all 3 Up components

Note

setForwardXVariable() and setForwardZVariable() are an alternate to providing a yaw angle

Note

Forward is a synonym for Direction

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[1]

void setForwardXZVariable(const std::string &var_name)

Set the name of the array variable (length 2) representing the agents x/z direction vector components Single axis rotation only requires x/z components

Note

setForwardXVariable() and setForwardZVariable() are an alternate to providing a yaw angle, setting either of these will erase yaw if bound

Note

setForwardYVariable() is an alternate to providing a pitch angle, setting this will erase pitch if bound

Note

Forward is a synonym for Direction

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[2]

void setForwardXYZVariable(const std::string &var_name)

Set the name of the array variable (length 3) representing the agents x/y/z direction vector components Single axis rotation only requires x/z components Double axis rotation requires all 3 components Triple axis rotation requires all 3 components and additionally all 3 Up components

Note

setForwardXVariable() and setForwardZVariable() are an alternate to providing a yaw angle, setting either of these will erase yaw if bound

Note

setForwardYVariable() is an alternate to providing a pitch angle, setting this will erase pitch if bound

Note

Forward is a synonym for Direction

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[3]

void setUpXVariable(const std::string &var_name)

Set the name of the variable representing the agents x/y/z UP vector This should be 90 degrees perpendicular to the direction vector

Note

setUpXVariable(), setUpYVariable() and setUpZVariable() are an alternate to providing a roll angle, setting any of these will erase roll if bound

Note

Up can only be used in combination with Forward x/y/z (and not Yaw, Pitch or directionYP)

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[1]

void setUpYVariable(const std::string &var_name)
void setUpZVariable(const std::string &var_name)
void setUpXYZVariable(const std::string &var_name)

Set the name of the array variable (length 3) representing the agents x/y/z UP vector This should be 90 degrees perpendicular to the direction vector

Note

setUpXVariable(), setUpYVariable() and setUpZVariable() are an alternate to providing a roll angle, setting any of these will erase roll if bound

Note

Up can only be used in combination with Forward x/y/z (and not Yaw, Pitch or directionYP)

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[3]

void setYawVariable(const std::string &var_name)

Set the name of the variable representing the agents yaw rotation angle (radians)

Note

This is an alternate to providing a direction vector, setting this will erase forward x/z if bound

Note

Heading is a synonym for Yaw

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[1]

void setPitchVariable(const std::string &var_name)

Set the name of the variable representing the agents pitch rotation angle (radians)

Note

This is an alternate to providing a direction vector, setting this will erase forward y if bound

Parameters

var_name – Name of the agent variable

void setRollVariable(const std::string &var_name)

Set the name of the variable representing the agents yaw rotation angle (radians)

Note

This is an alternate to providing an UP vector, setting this will erase up x/y/z if bound

Note

Bank is a synonym for Roll

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[1]

void setDirectionYPVariable(const std::string &var_name)

Set the name of the array variable (length 2) representing the agents yaw/pitch rotation angles (radians)

Note

This is an alternate to providing a direction vector, setting this will erase forward x/z if bound

Note

Heading is a synonym for Yaw

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[2]

void setDirectionYPRVariable(const std::string &var_name)

Set the name of the array variable (length 3) representing the agents yaw/pitch/roll rotation angles (radians)

Note

This is an alternate to providing a direction vector, setting this will erase forward x/z if bound

Note

Heading is a synonym for Yaw

Note

Bank is a synonym for Roll

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[3]

void setUniformScaleVariable(const std::string &var_name)

Set the name of the variable representing the agents uniform scale multiplier

The scale multiplier is multiplied by the model scale

Note

This is an alternate to providing individual scale components, setting this will erase scale x/y/z if bound

Parameters

var_name – Name of the agent variable

void setScaleXVariable(const std::string &var_name)

Set the name of the variable representing the agents x/y/z scale multiplier components It is not necessary to set all 3 components if only 1 or 2 are required. Unset values will be treated as a 1.0 multiplier

The scale multiplier is multiplied by the model scale

Note

This is an alternate to providing a single uniform scale multiplier, setting this will erase uniform scale if bound

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[1]

void setScaleYVariable(const std::string &var_name)
void setScaleZVariable(const std::string &var_name)
void setScaleXYVariable(const std::string &var_name)

Set the name of the array variable (length 2) representing the agents x/y scale multiplier components It is not necessary to set all 3 components if only 1 or 2 are required. Unset values will be treated as a 1.0 multiplier

The scale multiplier is multiplied by the model scale

Note

This is an alternate to providing a single uniform scale multiplier, setting this will erase uniform scale or individual scale components if bound

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[2]

void setScaleXYZVariable(const std::string &var_name)

Set the name of the array variable (length 3) representing the agents x/y/z scale multiplier components It is not necessary to set all 3 components if only 1 or 2 are required. Unset values will be treated as a 1.0 multiplier

The scale multiplier is multiplied by the model scale

Note

This is an alternate to providing a single uniform scale multiplier, setting this will erase uniform scale or individual scale components if bound

Parameters

var_name – Name of the agent variable

Throws

InvalidAgentVar – If the variable is not type float[3]

void clearXVariable()

Clears the agent’s x/y/z location variable bindings

void clearYVariable()
void clearZVariable()
void clearXYVariable()

Clears the agent’s xy location variable bindings

void clearXYZVariable()

Clears the agent’s xyz location variable bindings

void clearForwardXVariable()

Clears the agent’s x/y/z forward variable bindings

void clearForwardYVariable()
void clearForwardZVariable()
void clearForwardXZVariable()

Clears the agent’s xz forward variable bindings

void clearForwardXYZVariable()

Clears the agent’s xyz forward variable bindings

void clearUpXVariable()

Clears the agent’s x/y/z UP variable bindings

void clearUpYVariable()
void clearUpZVariable()
void clearUpXYZVariable()

Clears the agent’s xyz UP variable bindings

void clearYawVariable()

Clears the agent’s yaw angle variable bindings

void clearPitchVariable()

Clears the agent’s pitch angle variable bindings

void clearRollVariable()

Clears the agent’s roll angle variable bindings

void clearDirectionYPVariable()

Clears the agent’s yaw angle variable bindings

void clearDirectionYPRVariable()

Clears the agent’s yaw angle variable bindings

void clearUniformScaleVariable()

Clears the agent’s uniform scale multiplier variable bindings

void clearScaleXVariable()

Clears the agent’s x/y/z scale multiplier variable bindings

void clearScaleYVariable()
void clearScaleZVariable()
void clearScaleXYVariable()

Clears the agent’s xy scale multiplier variable bindings

void clearScaleXYZVariable()

Clears the agent’s xyz scale multiplier variable bindings

std::string getXVariable() const

Returns the variable used for the agent’s x/y/z location coordinates

std::string getYVariable() const
std::string getZVariable() const
std::string getXYVariable() const

Returns the variable used for the agent’s xy location coordinates

std::string getXYZVariable() const

Returns the variable used for the agent’s xyz location coordinates

std::string getForwardXVariable() const

Returns the variable used for the agent’s x/y/z forward vector components

std::string getForwardYVariable() const
std::string getForwardZVariable() const
std::string getForwardXZVariable() const

Returns the variable used for the agent’s xz forward vector components

std::string getForwardXYZVariable() const

Returns the variable used for the agent’s xyz forward vector components

std::string getUpXVariable() const

Returns the variable used for the agent’s x/y/z up vector components

std::string getUpYVariable() const
std::string getUpZVariable() const
std::string getUpXYZVariable() const

Returns the variable used for the agent’s xyz up vector components

std::string getYawVariable() const

Returns the variable used for the agent’s yaw angle

std::string getPitchVariable() const

Returns the variable used for the agent’s pitch angle

std::string getRollVariable() const

Returns the variable used for the agent’s roll angle

std::string getDirectionYPVariable() const

Returns the variable used for the agent’s roll angle

std::string getDirectionYPRVariable() const

Returns the variable used for the agent’s roll angle

std::string getUniformScaleVariable() const

Returns the variable used for the agent’s uniform scaling multiplier

std::string getScaleXVariable() const

Returns the variable used for the agent’s x/y/z scale multiplier components

std::string getScaleYVariable() const
std::string getScaleZVariable() const
std::string getScaleXYVariable() const

Returns the variable used for the agent’s xy scale multiplier components

std::string getScaleXYZVariable() const

Returns the variable used for the agent’s xyz scale multiplier components

void setModel(const std::string &modelPath, const std::string &texturePath = "")

Use a model from file

Parameters
  • modelPath – The path to the model’s file (must be .obj)

  • texturePath – Optional path to the texture used by the model

void setModel(const Stock::Models::Model &model)

Use a stock model

Parameters

model – Model from the libraries internal resources

void setKeyFrameModel(const std::string &modelPathA, const std::string &modelPathB, const std::string &lerpVariableName, const std::string &texturePath = "")

Use a keyframe animated model from file

See also

setModel(const std::string &, const std::string &) This version can be used to provide agents a static model

Parameters
  • modelPathA – The path to the model’s first file (must be .obj)

  • modelPathB – The path to the model’s second file (must be .obj, have the same number of vertices/polygons as the first file)

  • lerpVariableName – Name of the agent variable used for controlling linear interpolation between the two frames. This must be a float type variable with a value in the inclusive-inclusive range [0, 1]

  • texturePath – Optional path to the texture used by the two models

void setKeyFrameModel(const Stock::Models::KeyFrameModel &model, const std::string &lerpVariableName)

Use a stock keyframe animated model

See also

setModel(const Stock::Models::Model &) This version can be used to provide agents a static model

Parameters
  • model – Model from the libraries internal resources

  • lerpVariableName – Name of the agent variable used for controlling linear interpolation between the two frames. This must be a float type variable with a value in the inclusive-inclusive range [0, 1]

void setModelScale(float xLen, float yLen, float zLen)

Scale each dimension of the model to the corresponding world scales

Note

Y is considered the vertical axis

Parameters
  • xLen – World scale of the model’s on the x axis

  • yLen – World scale of the model’s on the y axis

  • zLen – World scale of the model’s on the z axis

void setModelScale(float maxLen)

Uniformly scale model so that max dimension equals this

Parameters

maxLen – World scale of the model’s relative to the axis which it is largest

void setAutoPalette(const Palette &ap)

Set the auto-palette used to assign agent-state’s colors

Note

The color is assigned the first time State() is called, otherwise agents use the default color

void setColor(const ColorFunction &cf)

Set a custom color function

Note

Disables the auto-palette

void clearColor()

Disable custom color and/or auto-palette, e.g. if you’re using a textured model