Source code for machine_common_sense.goal_metadata
import logging
from enum import Enum, unique
from typing import List, Optional
import typeguard
from .action import Action
from .stringifier import Stringifier
logger = logging.getLogger(__name__)
[docs]class GoalMetadata:
"""
Defines metadata for a goal in the MCS 3D environment.
Attributes
----------
action_list : list of lists of (string, dict) tuples, or None
The list of all actions that are available for the scene at each step
(outer list). Each inner list is the list of all actions that are
available for the single step corresponding to the inner list's index
within the outer list. Each action is returned as a tuple containing
the action string and the action's restricted paramters, if any.
For example: ("Pass", {}) forces a Pass action; ("PickupObject", {})
forces a PickupObject action with any parameters; and
("PickupObject", {"objectId": "a"}) forces a PickupObject action with
the specific parameters objectId=a.
An action_list of None means that all actions are always available.
An empty inner list means that all actions will be available on that
specific step.
See :mod:`StepMetadata.action_list <machine_common_sense.StepMetadata>`
for the available actions of the current step.
May be a subset of all possible actions. See
:mod:`Action <machine_common_sense.Action>`.
category : string
The category that describes this goal and the properties in its
metadata. See :mod:`Goal <machine_common_sense.GoalCategory>`.
description : string
A human-readable sentence describing this goal and containing
the target task(s) and object(s).
Sizes:
- tiny: near the size of a baseball
- small: near the size of a baby
- medium: near the size of a child
- large: near the size of an adult
- huge: near the size of a sofa
Weights:
- light: can be held by a baby
- heavy: cannot be held by a baby, but can be pushed or pulled
- massive: cannot be moved by a baby
Colors:
black, blue, brown, green, grey, orange, purple, red, white, yellow
Materials:
See :mod:`Material <machine_common_sense.Material>`.
habituation_total : int
The total count of habituation trials that will be in this scene.
last_preview_phase_step : integer
The last step of the Preview Phase of this scene, if a Preview Phase is
scripted in the scene configuration. Each step of a Preview Phase
normally has a single specific action defined in this goal's
action_list property for the performer to choose, like ['Pass'].
Default: 0 (no Preview Phase)
last_step : integer
The last step of this scene. This scene will automatically end
following this step.
metadata : dict
The metadata specific to this goal. See
:mod:`Goal <machine_common_sense.GoalCategory>`.
steps_allowed_in_lava : integer
The number of steps allowed in lava before the scene ends
triggered_by_target_sequence : List of strings
The target sequence the performer must open containers to trigger
the targets placement by a placer for imitation tasks.
"""
# Don't allow a user to call the EndHabituation action unless it's
# specifically configured in the action_list of the scene file.
DEFAULT_ACTIONS = [
(item.value, {}) for item in Action
if item not in [Action.END_HABITUATION, Action.INITIALIZE]
]
# Each passive scene should have its own action_list, but if it doesn't for
# some reason, then only allow calling Pass actions by default.
DEFAULT_PASSIVE_SCENE_ACTIONS = [('Pass', {})]
def __init__(
self,
action_list=None,
category='',
description='',
habituation_total=0,
last_preview_phase_step=0,
last_step=None,
metadata=None,
steps_allowed_in_lava=0,
triggered_by_target_sequence=None
):
# The action_list must be None by default
self.action_list = action_list
self.category = category
self.description = description
self.habituation_total = habituation_total
self.last_preview_phase_step = last_preview_phase_step
self.last_step = last_step
self.metadata = {} if metadata is None else metadata
self.steps_allowed_in_lava = steps_allowed_in_lava
self.triggered_by_target_sequence = triggered_by_target_sequence
def __str__(self):
return Stringifier.class_to_str(self)
# Allows converting the class to a dictionary, along with allowing
# certain fields to be left out of output file
def __iter__(self):
yield 'action_list', self.action_list
yield 'category', self.category
yield 'description', self.description
# yield 'domain_list', self.domain_list
# yield 'info_list', self.info_list
yield 'last_preview_phase_step', self.last_preview_phase_step
yield 'last_step', self.last_step
# yield 'type_list', self.type_list
yield 'metadata', self.metadata
yield 'triggered_by_target_sequence', self.triggered_by_target_sequence
[docs] @typeguard.typechecked
def retrieve_action_list_at_step(
self,
step_number: int,
steps_in_lava: Optional[int] = 0,
triggered_by_sequence_incorrect: Optional[bool] = False,
is_passive_scene: bool = False
) -> List:
"""Return the action list from the given goal at the given step as a
a list of actions tuples by default."""
action_list = self._retrieve_unfiltered_action_list(
step_number, steps_in_lava,
triggered_by_sequence_incorrect, is_passive_scene)
# remove EndHabituation parameters
return [
(action, params)
if action != 'EndHabituation' else ('EndHabituation', {})
for (action, params) in action_list
]
def _retrieve_unfiltered_action_list(
self,
step_number: int,
steps_in_lava: Optional[int] = 0,
triggered_by_sequence_incorrect: Optional[bool] = False,
is_passive_scene: bool = False
) -> List:
# If steps in lava is greater than allowed, over ride
# action list and only return EndScene
if steps_in_lava is not None and (
steps_in_lava > self.steps_allowed_in_lava):
return [("EndScene", {})]
if triggered_by_sequence_incorrect:
return [("EndScene", {})]
'''Unfiltered action list from goal'''
if self.action_list is not None:
if step_number < self.last_preview_phase_step:
return [('Pass', {})]
if self.last_step is not None and step_number >= self.last_step:
return []
adjusted_step = step_number - self.last_preview_phase_step
if (
len(self.action_list) > adjusted_step and
len(self.action_list[adjusted_step]) > 0
):
return [
action if isinstance(action, tuple) else
Action.input_to_action_and_params(action)
for action in self.action_list[adjusted_step]
]
if is_passive_scene:
logger.warning(
'Passive scene should have an action_list but does not; '
'allowing only Pass actions by default.'
)
return GoalMetadata.DEFAULT_PASSIVE_SCENE_ACTIONS
return GoalMetadata.DEFAULT_ACTIONS
[docs]@unique
class GoalCategory(Enum):
"""
Each goal dict will have a "category" string that describes the type of
scene (or, the type of task within the scene) being run. Each goal dict
will also have a "metadata" dict containing one or more properties
depending on the "category".
"""
AGENTS = "agents"
"""
In a trial that has an Agents goal, you must sit and observe a scene as one
or more simulation-controlled agents act in predefined ways within your
camera's viewport, and then decide whether the scene is "expected" or
"unexpected". The camera will always be positioned at an isometric
perspective, like you're standing on an elevated platform looking down at
the scene. Each scene will consist of eight sequential habituation trials,
depicting expected agent behaviors and separated by EndHabituation actions
(each of which generates a black frame image when called), immediately
followed by the test trial, depicting either an expected or unexpected
agent behavior. All nine of these trials happen within the same "scene".
These trials will demand a "common sense" understanding of agents, their
behaviors, and their interactions with objects in the environment.
This goal category is only used for the **passive/VoE agent tasks**. All
interactive agent tasks will use either the `retrieval` or
`multi retrieval` goal category.
Notes
-----
You are required to call `controller.end_scene()` at the end of each scene
with a continuous plausibility `rating`, from 0.0 (completely implausible)
to 1.0 (completely plausible). You are not required to also pass it a
`score`.
"""
IMITATION = "imitation"
"""
In a trial that has an imitation goal, you must imitate the actions of
another agent in the scene to find and pickup a target object. Executing
the same actions, on the same objects, in the same order, is of critical
importance; if you do not imitate the actions correctly, you will be
forced to end the scene (by calling end_scene, or using the END_SCENE
action), without achieving the reward. In MCS Evaluation 4 and onward, the
target object will always be a soccer ball (football), and, in MCS
Evaluation 6, the imitated actions will always be opening containers of
various colors and shapes (using the normal OpenObject action).
Notes
-----
At `oracle` metadata level, the `metadata` dict property of this
GoalMetadata object will contain a `target` property, which is a dict
containing the following parameters:
Parameters
----------
id : string
The unique objectId of the target object to retrieve.
"""
INTUITIVE_PHYSICS = "intuitive physics"
"""
In a trial that has an Intuitive Physics goal, you must sit and observe a
scene as objects move across your camera's viewport, and then decide
whether the scene is "plausible" or "implausible". These trials will demand
a "common sense" understanding of basic ("intuitive") physics, like object
permanence or shape constancy. Inspired by Emmanuel Dupoux's "IntPhys: A
Benchmark for Visual Intuitive Physics Reasoning" (http://intphys.com).
Notes
-----
You are required to call `controller.end_scene()` at the end of each scene
with a binary plausibility `rating` -- either 0 (implausible) or 1
(plausible) -- and a continuous plausibility `score` -- from 0.0
(completely implausible) to 1.0 (completely plausible). This is also
where you would submit any retrospective reporting on a per step basis via
`report`.
"""
PASSIVE = "passive"
"""
In a trial that has a Passive goal, you must sit and observe a scene as
action unfolds in your camera's viewport, and then decide whether the scene
is "plausible" or "implausible". These trials will demand a "common sense"
understanding of places, objects, or agency. This goal category covers all
passive scenes that do not fall under the "agents" or "intuitive physics"
categories.
Notes
-----
You are required to call `controller.end_scene()` at the end of each scene
with a binary plausibility `rating` -- either 0 (implausible) or 1
(plausible) -- and a continuous plausibility `score` -- from 0.0
(completely implausible) to 1.0 (completely plausible). This is also
where you would submit any retrospective reporting on a per step basis via
`report`.
"""
RETRIEVAL = "retrieval"
"""
In a trial that has a retrieval goal, you must find and pickup a target
object. In MCS Evaluation 4 and onward, the target object will always be a
soccer ball (football).
This may involve exploring the scene, avoiding obstacles,
interacting with objects (like closed containers) or agents, and tracking
moving objects. These trials will demand a "common sense" understanding of
self navigation (how to move and rotate yourself within a scene and around
obstacles), object interaction (how objects work, including opening
containers), the basic physics of movement (kinematics, gravity, friction,
etc.), and agency (identifying people and using them to achieve a goal).
Notes
-----
At `oracle` metadata level, the `metadata` dict property of this
GoalMetadata object will contain a `target` property, which is a dict
containing the following parameters:
Parameters
----------
id : string
The unique objectId of the target object to retrieve.
"""
MULTI_RETRIEVAL = "multi retrieval"
"""
In a trial that has a multi retrieval goal, you must find and pickup one or
more target objects. In MCS Evaluation 4 and onward, the target object will
always be a soccer ball (football).
This may involve exploring the scene, avoiding obstacles,
interacting with objects (like closed containers) or agents, and tracking
moving objects. These trials will demand a "common sense" understanding of
self navigation (how to move and rotate yourself within a scene and around
obstacles), object interaction (how objects work, including opening
containers), the basic physics of movement (kinematics, gravity, friction,
etc.), and agency (identifying people and using them to achieve a goal).
Notes
-----
At `oracle` metadata level, the `metadata` dict property of this
GoalMetadata object will contain a `targets` property, which is a list of
dicts that each contain the following parameters:
Parameters
----------
id : string
The unique objectId of one of the target objects to retrieve.
"""