title	author	date
Spheres environment	a.whit ([email](mailto:nml@whit.contact))	November 2022

Spheres virtual environment

This Python package provides a framework for a virtual environment in which spherical objects interact in a 3D space. This is primarily intended for use in the development of behavioral tasks for experimental science.

Installation

The package can be used as-is, so long as the Python path is set appropriately.

However, pyoproject.toml and setup.cfg files have been provided, to facilitate package installation via setuptools. Package installation can be accomplished via the pip install command:

pip install path/to/spheres_environment

The update, user, and editable / development flags are common options that can be added to the command:

pip install -e -U --user path/to/spheres_environment

Testing

Forthcoming.

Example

Initialize an environment instance.

>>> import spheres_environment
>>> environment = spheres_environment.Environment()

Add a pair of spheres to the environment.

>>> sphere_a = environment.initialize_object('sphere_a')
>>> sphere_b = environment.initialize_object('sphere_b')

Verify that the spheres overlap, given the default property values.

>>> def spheres_are_overlapping():
...     p_a = sphere_a.position
...     p_b = sphere_b.position
...     d = sum([(p_b[k] - p_a[k])**2 for k in ['x', 'y', 'z']])
...     return d <= (sphere_a.radius + sphere_b.radius)**2
>>> spheres_are_overlapping()
True

Change the position of sphere_b and verify that it still overlaps with sphere_a.

>>> sphere_b.position = (1, 1, 1)
>>> spheres_are_overlapping()
True

Decrease the radius of sphere_a and confirm that the two spheres no longer overlap.

>>> sphere_a.radius = 0.1
>>> spheres_are_overlapping()
False

At its core, the environment and all objects in the environment are structured as Python mapping data types. The current state of the environment can be represented, completely, by converting all objects in the environment into dict records.

>>> records = [o.data for o in environment.values()]
>>> import pprint
>>> pprint.pp(records)
[{'position/x': 0.0,
  'position/y': 0.0,
  'position/z': 0.0,
  'radius': 0.1,
  'key': 'sphere_a'},
 {'position/x': 1.0,
  'position/y': 1.0,
  'position/z': 1.0,
  'radius': 1.0,
  'key': 'sphere_b'}]

License

Copyright 2022 Neuromechatronics Lab, Carnegie Mellon University

Contributors:

• a. whit. (nml@whit.contact)

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.