navground_core_py

This package provides Python bindings to the core library.

Dependencies

• navground_core the C++ library

• Python >= 3.7 the Python runtime

• pybind11 for binding the C++ library

• This fork of pybind11_mkdoc to extract Python docstrings from the C++ code

• NumPy pybind11 exposes Eigen objects using numpy

• PyYAML to exchange (YAML) schemas between C++ and python

Python packages

navground.core

A Python package with navigation algorithms, controllers, and kinematics, see the API reference.

To use the package

1. add the install path to PYTHONPATH

2. import the package

   from navground import core
   

Libraries

navground_core_py

A C++ headers-only library with utilities for Python bindings for internal use.

Executables

info

Lists registered components (behaviors, kinematics, and behavior modulations). It is equivalent to the C++ version but with additional components implemented in Python.

usage: info [-h] [--no-plugins] [-v] [--build] [--properties] [--description] [--behaviors [BEHAVIORS]] [--kinematics [KINEMATICS]]
            [--modulations [MODULATIONS]]

Named Arguments

--no-plugins

Do not load plugins

-v, --version

show program’s version number and exit

--build

Include build infos

--properties

Include properties

--description

Include property descriptions

--behaviors

selects behaviors

--kinematics

selects kinematics

--modulations

selects modulations

Example

$ info --properties

Installed components
====================
Behaviors
---------
CppPolicy
    flat: False (bool)
    include_angular_speed: False (bool)
    include_target_direction: False (bool)
    include_target_distance: False (bool)
    include_target_speed: False (bool)
    include_velocity: False (bool)
    max_acceleration: 10.0 (float)
    max_angular_acceleration: 0.0 (float)
    policy_path:  (str)
    shared: False (bool)
    use_acceleration_action: False (bool)
Dummy
    environment:  (str)
GroupPolicy
    deterministic: False (bool)
...

echo

Load and then print a YAML representation of an object (behavior, kinematic, or behavior modulation). It is equivalent to the C++ version but with additional components implemented in Python.

usage: echo [-h] [--no-plugins] [-v] [--chdir] kind YAML

Positional Arguments

kind

The kind of object to load: behavior, modulation, kinematics

YAML

YAML string, or path to a YAML file, describing an experiment

Named Arguments

--no-plugins

Do not load plugins

-v, --version

show program’s version number and exit

--chdir

Whether to change working directory to the directory containing the file. Useful when the config contains relative paths.

Example

$ echo behavior "{type: PyDummy}"

type: PyDummy
dummy: true
tired: false
optimal_speed: 0
optimal_angular_speed: 0
rotation_tau: 0.5
safety_margin: 0
horizon: 5
path_look_ahead: 1
path_tau: 0.5
radius: 0
heading: velocity
social_margin:
  modulation:
    type: constant
  default: 0

schema

Print JSON-Schema of YAML-convertible navground core classes. It is equivalent to the C++ version but with additional components implemented in Python.

usage: schema [-h] [--no-plugins] [-v] [--register] [--type TYPE] [{kinematics,core,behavior_modulation,behavior}]

Positional Arguments

kind

Possible choices: kinematics, core, behavior_modulation, behavior

The target type of the scheme

Named Arguments

--no-plugins

Do not load plugins

-v, --version

show program’s version number and exit

--register

Whether to generate the register schema instead of the base class schema

--type

If provided, generates the schema for the sub-class registered under this name

Example

$ schema core

$defs:
  attributes:
    $id: http://navground/attributes
    $schema: https://json-schema.org/draft/2020-12/schema
    additionalProperties:
      anyOf:
      - properties:
          type:
            const: int
          value:
            type: integer
        required:
        - value
        - type
        type: object
        unevaluatedProperties: false
      - properties:
          type:
            const: float
          value:
...

validate

Validates a YAML representation of an object (behavior, kinematic, or behavior modulation) against the schema generated by schema using python-jsonschema.

usage: validate [-h] [--no-plugins] [-v] {behavior,behavior_modulation,kinematics} YAML

Positional Arguments

kind

Possible choices: behavior, behavior_modulation, kinematics

The kind of object to validate

YAML

YAML string, or path to a YAML file, describing an experiment

Named Arguments

--no-plugins

Do not load plugins

-v, --version

show program’s version number and exit

Example

Catching a typo like “whel_axis” instead of wheel_axis:

$ validate kinematics "{type: 2WDiff, whel_axis: 1.0}"

Unevaluated properties are not allowed ('whel_axis' was unexpected)

Failed validating 'unevaluatedProperties' in schema:
    {'type': 'object',
     'unevaluatedProperties': False,
     'properties': {'type': {'type': 'string'},
                    'max_speed': {'type': 'number'},
                    'max_angular_speed': {'type': 'number'}},
     '$id': 'http://navground/kinematics',
     '$schema': 'https://json-schema.org/draft/2020-12/schema',
     '$ref': 'kinematics_register'}

On instance:
    {'type': '2WDiff', 'whel_axis': 1.0}

plugins

Load and list plugins.

usage: plugins [-h] [-v] [--dependencies]

Named Arguments

-v, --version

show program’s version number and exit

--dependencies

Display dependencies of C++ plugins

Example

$ plugins

navground_examples_py
---------------------
Behaviors: PyIdle [Python]


navground_examples
------------------
Behaviors: Idle [C++]

navground.core

Instead of

$ install/lib/navground_core_py/<command> [arguments]

you can call the subcommand (info) from Python, like

$ python -m navground.core [sub-command] [arguments]