From 2a9e5cf551fcb8c115a014da23f1465cf275afa2 Mon Sep 17 00:00:00 2001
From: Andi Gerken <andi.gerken@gmail.com>
Date: Wed, 21 Apr 2021 18:03:58 +0200
Subject: [PATCH] Added docs to be used with pdocs.
---
.gitignore | 2 +-
README.md | 52 ++++++------
docs/entity.md | 84 ++++++++++++++++++
docs/file.md | 48 +++++++++++
docs/img/calc_ori_speed_turn.md | 1 +
docs/img/calc_ori_speed_turn.png | Bin 0 -> 23304 bytes
docs/index.md | 141 +++++++++++++++++++++++++++++++
examples/example_readme.py | 34 +++++---
src/robofish/evaluate/app.py | 25 +++---
src/robofish/io/__init__.py | 7 ++
src/robofish/io/entity.py | 19 +++--
src/robofish/io/file.py | 26 ++++--
12 files changed, 376 insertions(+), 63 deletions(-)
create mode 100644 docs/entity.md
create mode 100644 docs/file.md
create mode 100644 docs/img/calc_ori_speed_turn.md
create mode 100644 docs/img/calc_ori_speed_turn.png
create mode 100644 docs/index.md
diff --git a/.gitignore b/.gitignore
index 5f76274..3825a6a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,7 +8,7 @@ dist
.coverage
report.xml
htmlcov
-docs
+html
env
!tests/resources/*.hdf5
diff --git a/README.md b/README.md
index 5da734e..d421dc1 100644
--- a/README.md
+++ b/README.md
@@ -9,59 +9,61 @@
[](https://git.imp.fu-berlin.de/bioroboticslab/robofish/io/commits/master)
# Robofish IO
-This repository implements an easy to use interface, to create, save, load, and work [specification-compliant](https://git.imp.fu-berlin.de/bioroboticslab/robofish/track_format) hdf5 files, containing 2D swarm data. This repository should be used by the different swarm projects to generate comparable standardized files.
+This repository implements an easy to use interface, to create, save, load, and work with [specification-compliant](https://git.imp.fu-berlin.de/bioroboticslab/robofish/track_format) hdf5 files, containing 2D swarm data. This repository should be used by the different swarm projects to generate comparable standardized files.
## Installation
-Quick variant:
-```
-pip3 install robofish-trackviewer robofish-io --extra-index-url https://git.imp.fu-berlin.de/api/v4/projects/6392/packages/pypi/simple
+Add our [Artifacts repository](https://git.imp.fu-berlin.de/bioroboticslab/robofish/artifacts) to your pip config and install the packagage.
+
+```bash
+python3 -m pip config set global.extra-index-url https://git.imp.fu-berlin.de/api/v4/projects/6392/packages/pypi/simple
+python3 -m pip install robofish-io
```
-Better variant:
-- Follow instructions at [Artifacts repository](https://git.imp.fu-berlin.de/bioroboticslab/robofish/artifacts)
-- ```pip3 install robofish-io```
## Usage
We show a simple example below. More examples can be found in ```examples/```
```python
-import robofish.io
-import numpy as np
-
-
# Create a new robofish io file
f = robofish.io.File(world_size_cm=[100, 100], frequency_hz=25.0)
f.attrs["experiment_setup"] = "This is a simple example with made up data."
-# Create a new robot entity. Positions and orientations are passed
-# separately in this example. Since the orientations have two columns,
-# unit vectors are assumed (orientation_x, orientation_y)
+# Create a new robot entity with 10 timesteps.
+# Positions and orientations are passed separately in this example.
+# Since the orientations have two columns, unit vectors are assumed
+# (orientation_x, orientation_y)
f.create_entity(
category="robot",
name="robot",
- positions=np.zeros((100, 2)),
- orientations=np.ones((100, 2)) * [0, 1],
+ positions=np.zeros((10, 2)),
+ orientations=np.ones((10, 2)) * [0, 1],
)
-# Create a new fish entity.
+# Create a new fish entity with 10 timesteps.
# In this case, we pass positions and orientations together (x, y, rad).
# Since it is a 3 column array, orientations in radiants are assumed.
-poses = np.zeros((100, 3))
-poses[:, 0] = np.arange(-50, 50)
-poses[:, 1] = np.arange(-50, 50)
-poses[:, 2] = np.arange(0, 2 * np.pi, step=2 * np.pi / 100)
+poses = np.zeros((10, 3))
+poses[:, 0] = np.arange(-5, 5)
+poses[:, 1] = np.arange(-5, 5)
+poses[:, 2] = np.arange(0, 2 * np.pi, step=2 * np.pi / 10)
fish = f.create_entity("fish", poses=poses)
fish.attrs["species"] = "My rotating spaghetti fish"
fish.attrs["fish_standard_length_cm"] = 10
-# Show and save the file
-print(f)
-print("Poses Shape: ", f.entity_poses.shape)
+# Some possibilities to access the data
+print(f"The file:\n{f}")
+print(
+ f"Poses Shape:\t{f.entity_poses_rad.shape}.\t"
+ + "Representing(entities, timesteps, pose dimensions (x, y, ori)"
+)
+print(f"The actions of one Fish, (timesteps, (speed, turn)):\n{fish.speed_turn}")
+print(f"Fish poses with calculated orientations:\n{fish.poses_calc_ori_rad}")
-f.save_as(path)
+# Save the file
+f.save_as("example.hdf5")
```
### Evaluation
diff --git a/docs/entity.md b/docs/entity.md
new file mode 100644
index 0000000..119880a
--- /dev/null
+++ b/docs/entity.md
@@ -0,0 +1,84 @@
+Tracks of entities are stored in `robofish.io.entity.Entity` objects. They are created by the `robofish.io.file.File` object. They require a category and can have a name. If no name is given, it will be created, using the category and an id.
+
+```python
+f = robofish.io.File(world_size_cm=[100, 100], frequency_hz=25.0)
+nemo = f.create_entity(category="fish", name="nemo")
+```
+
+The function `create_entity()` returns an entity object. It can be stored but it's not neccessary. The entity is automatically stored in the file.
+
+## Pose options
+
+The poses of an entity can be passed in multiple ways. Poses are divided into `positions` (x, y) and `orientations`.
+Orientations are internally represented in unit vectors but can also be passed in rads.
+The shape of the passed orientation array defines the meaning.
+
+```python
+# Create dummy poses for 100 timesteps
+pos = np.zeros((100, 2))
+ori_vec = np.zeros((100,2)) * [0, 1]
+ori_rad = np.zeros((100,1))
+
+# Creating an entity without orientations. Here we keep the entity object, to use it later.
+f.create_entity(category="fish", positions=pos)
+# Creating an entity using orientation vectors. Keeping the entity object is not neccessary, it is saved in the file.
+f.create_entity(category="fish", positions=pos, orientations=ori_vec)
+# Creating an entity using radiant orientations.
+f.create_entity(category="fish", positions=pos, orientations=ori_rad)
+```
+
+The poses can be also passed in an combined array.
+```python
+# Create an entity using orientation vectors.
+f.create_entity(category="fish", poses=np.ones((100,4)) * np.sqrt(2))
+# Create an entity using radiant orientations
+f.create_entity(category="fish", poses=np.zeros((100,3)))
+```
+
+## Creating multiple entities at once
+
+Multiple entities can be created at once.
+```python
+# Here we create 4 fishes from poses with radiant orientation
+f.create_multiple_entities(category="fish", poses=np.zeros((4,100,3)))
+```
+
+## Attributes
+
+Entities can have attributes to describe them.
+
+The attributes can be set like this:
+```python
+nemo.attrs["species"] = "Clownfish"
+nemo.attrs["fish_standard_length_cm"] = 10
+```
+
+Any attribute is allowed, but some cannonical attributes are prepared:<br>
+`species`: str, `sex`: str, `fish_standard_length_cm`: float
+
+
+## Properties
+
+As described in `robofish.io`, Files and Entities have useful properties.
+
+| Entity function | Description |
+|--------------------------------- |------------------------------------------------------------------------------------------------------- |
+| `robofish.io.entity.Entity.positions` | The positions as a (timesteps, 2 (x, y)) arary. |
+| `robofish.io.entity.Entity.orientations` | The orientations as a (timesteps, 2 (ori_x, ori_y)) arary. |
+| `robofish.io.entity.Entity.orientations_rad` | The orientations as a (timesteps, 1 (ori_rad)) arary. |
+| `robofish.io.entity.Entity.poses` | The poses as a (timesteps, 4 (x, y, x_ori, y_ori)) array. |
+| `robofish.io.entity.Entity.poses_rad` | The poses as a (timesteps, 3(x, y, ori_rad)) array. |
+| `robofish.io.entity.Entity.poses_calc_ori_rad` | The poses with calculated orientations as a<br>(timesteps - 1, 3 (x, y, calc_ori_rad)) array. |
+| `robofish.io.entity.Entity.speed_turn` | The speed and turn as a (timesteps - 2, 2 (speed_cm/s, turn_rad/s)) array. |
+
+### Calculated orientations and speeds.
+
+
+
+The image shows, how the orientations are calculated (`robofish.io.entity.Entity.poses_calc_ori_rad`), the orientations always show away from the last position. In this way, the first position does not have an orientation and the shape of the resulting array is `(timesteps - 1, 3 (x, y, calc_ori_rad))`.
+
+The meaning of the `robofish.io.entity.Entity.speed_turn` can also be explained with the image. The turn is the angle, the agent has to turn, to orientate towards the next position. The speed is the calculated, using the distance between two positions. The resulting turn and speed is converted to `[rad/s]` and `[cm/s]`. The first and last position don't have any action which results in an array shape of `(timesteps - 2, 2 (speed, turn))`.
+
+---
+
+⚠️ Try this out by extending the example of the main doc, so that a new teleporting fish with random positions [-50, 50] is generated. How does that change the output and speed histogram `robofish-io-evaluate speed example.hdf5`? Try writing some attributes.
diff --git a/docs/file.md b/docs/file.md
new file mode 100644
index 0000000..3c5e7fd
--- /dev/null
+++ b/docs/file.md
@@ -0,0 +1,48 @@
+`robofish.io.file.File` objects are the root of the project. The object contains all information about the environment, entities, and time.
+
+In the simplest form we define a new File with a world size in cm and a frequency in hz. Afterwards, we can save it with a path.
+
+```python
+import robofish.io
+
+# Create a new robofish io file
+f = robofish.io.File(world_size_cm=[100, 100], frequency_hz=25.0)
+f.save_as("test.hdf5")
+```
+
+---
+
+The File object can also be generated, with a given path. In this case, we work on the file directly. The `with` block ensures, that the file is validated after the block.
+
+```python
+with robofish.io.File(
+ "test.hdf5", mode="x", world_size_cm=[100, 100], frequency_hz=25.0
+) as f:
+ # Use file f here
+```
+
+When opening a file with a path, a mode should be specified to describe how the file should be opened.
+
+| Mode | Description |
+|------ |---------------------------------------- |
+| r | Readonly, file must exist (default) |
+| r+ | Read/write, file must exist |
+| w | Create file, truncate if exists |
+| x | Create file, fail if exists |
+| a | Read/write if exists, create otherwise |
+
+---
+
+Attributes of the file can be added, to describe the contents.
+The attributes can be set like this:
+```python
+f.attrs["experiment_setup"] = "This file comes from the tutorial."
+f.attrs["experiment_issues"] = "All data in this file is made up."
+```
+
+Any attribute is allowed, but some cannonical attributes are prepared:<br>
+`publication_url, video_url, tracking_software_name, tracking_software_version, tracking_software_url, experiment_setup, experiment_issues`
+
+---
+
+All file functions and their documentation can be found at `robofish.io.file.File`.
\ No newline at end of file
diff --git a/docs/img/calc_ori_speed_turn.md b/docs/img/calc_ori_speed_turn.md
new file mode 100644
index 0000000..7d08ae6
--- /dev/null
+++ b/docs/img/calc_ori_speed_turn.md
@@ -0,0 +1 @@
+testtesttest
\ No newline at end of file
diff --git a/docs/img/calc_ori_speed_turn.png b/docs/img/calc_ori_speed_turn.png
new file mode 100644
index 0000000000000000000000000000000000000000..439d4c95455a2c2ee8f30ee616ccf2420277a5e3
GIT binary patch
literal 23304
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
Jvd$@?2>>qI4E+EA
literal 0
HcmV?d00001
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..ae143c8
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,141 @@
+This package provides you:
+
+- Creation, storing, loading, modifying, inspecting of io-files.
+- Preprocessing (orientation calculation, action calculation, raycasting, ...)
+- Quick and easy evaluation of behavior
+- Data, which is interchangable between labs and tools. No conversions required, since units and coordinate systems are standardized.
+- No custom data import, but just `include robofish.io`
+
+Features coming up:
+
+- Interface for unified behavior models
+- Pytorch Datasets directly from `robofish.io` files.
+
+
+## Installation
+Add our [Artifacts repository](https://git.imp.fu-berlin.de/bioroboticslab/robofish/artifacts) to your pip config and install the packagage.
+
+```bash
+python3 -m pip config set global.extra-index-url https://git.imp.fu-berlin.de/api/v4/projects/6392/packages/pypi/simple
+python3 -m pip install robofish-io robofish-trackviewer
+```
+
+## Usage
+
+This documentation is structured to increase in complexity.
+First we'll execute the example from the README. More examples can be found in ```examples/```.
+
+```python
+# Create a new robofish io file
+f = robofish.io.File(world_size_cm=[100, 100], frequency_hz=25.0)
+f.attrs["experiment_setup"] = "This is a simple example with made up data."
+
+# Create a new robot entity with 10 timesteps.
+# Positions and orientations are passed separately in this example.
+# Since the orientations have two columns, unit vectors are assumed
+# (orientation_x, orientation_y)
+f.create_entity(
+ category="robot",
+ name="robot",
+ positions=np.zeros((10, 2)),
+ orientations=np.ones((10, 2)) * [0, 1],
+)
+
+# Create a new fish entity with 10 timesteps.
+# In this case, we pass positions and orientations together (x, y, rad).
+# Since it is a 3 column array, orientations in radiants are assumed.
+poses = np.zeros((10, 3))
+poses[:, 0] = np.arange(-5, 5)
+poses[:, 1] = np.arange(-5, 5)
+poses[:, 2] = np.arange(0, 2 * np.pi, step=2 * np.pi / 10)
+fish = f.create_entity("fish", poses=poses)
+fish.attrs["species"] = "My rotating spaghetti fish"
+fish.attrs["fish_standard_length_cm"] = 10
+
+# Some possibilities to access the data
+print(f"The file:\n{f}")
+print(
+ f"Poses Shape:\t{f.entity_poses_rad.shape}.\t"
+ + "Representing(entities, timesteps, pose dimensions (x, y, ori)"
+)
+print(f"The actions of one Fish, (timesteps, (speed, turn)):\n{fish.speed_turn}")
+print(f"Fish poses with calculated orientations:\n{fish.poses_calc_ori_rad}")
+
+# Save the file
+f.save_as("example.hdf5")
+```
+
+⚠️ Please try out the example on your computer and read the output.
+
+We created an `robofish.io.file.File` object, then we added two `robofish.io.entity.Entity` objects.
+Afterwards we read some properties of the file and printed them *(more info in [Reading Properties](#reading-properties))*.
+Lastly, we saved the file to `example.hdf5`.
+Congrats, you created your first io file. We'll continue working with it.
+
+---
+
+We can examine the file now by using commandline tools. These are some examples, more details in [Commandline Tools](## Commandline Tools)
+
+```bash
+robofish-io-print example.hdf5
+```
+Checking out the file content.
+
+```bash
+robofish-io-evaluate speed example.hdf5
+```
+Show a histogram of speeds in the file. For more evaluation options check `robofish-io-evaluate --help`
+
+```bash
+robofish-trackviewer example.hdf5
+```
+View a video of the track in an interactive window.
+
+Further details about the commandline tools can be found in `robofish.io.app`.
+
+## Accessing real data
+Until now, we only worked with dummy data. Data from different sources is available in the Trackdb. It is currently stored at the FU Box.
+
+⚠️ If you don't have access to the Trackdb yet, please text Andi by Mail or Mattermost (andi.gerken@gmail.com)
+
+
+## Reading properties
+
+Files and entities have usefull properties to access their content. In this way, positions, orientations, speeds, and turns can be accessed easily.
+
+All shown property functions can be called from a file or on one entity.
+The function names are identical but have a `entity_` prefix.
+
+```python
+f = robofish.io.File(world_size_cm=[100, 100], frequency_hz=25.0)
+nemo = f.create_entity(category='fish', name='nemo', poses=np.zeros((10,3)))
+dori = f.create_entity(category='fish', name='dori', poses=np.zeros((10,3)))
+
+
+# Get the poses of nemo. Resulting in a (10,3) array
+print(nemo.poses_rad)
+
+# Get the poses of all entities. Resulting in a (2,10,3) array.
+print(f.entity_poses_rad)
+```
+
+In the same scheme the following properties are available:
+
+
+| File/ Entity function | Description |
+|--------------------------------- |------------------------------------------------------------------------------------------------------- |
+| *entity_*positions | The positions as a (*entities*, timesteps, 2 (x, y)) arary. |
+| *entity_*orientations | The orientations as a (*entities*, timesteps, 2 (ori_x, ori_y)) arary. |
+| *entity_*orientations_rad | The orientations as a (*entities*, timesteps, 1 (ori_rad)) arary. |
+| *entity_*poses | The poses as a (*entities*, timesteps, 4 (x, y, x_ori, y_ori)) array. |
+| *entity_*poses_rad | The poses as a (*entities*, timesteps, 3(x, y, ori_rad)) array. |
+| *entity_*poses_calc_ori_rad | The poses with calculated orientations as a<br>(*entities*, timesteps - 1, 3 (x, y, calc_ori_rad)) array. |
+| *entity_*speed_turn | The speed and turn as a (*entities*, timesteps - 2, 2 (speed_cm/s, turn_rad/s)) array. |
+
+The functions `robofish.io.entity.Entity.poses_calc_ori_rad` and `robofish.io.entity.Entity.speed_turn` are described in detail in `robofish.io.entity`
+
+## Where to continue?
+We recommend continuing to read advanced options for `robofish.io.file`s and `robofish.io.entity`s.
+Create some files, validate them, look at them in the trackviewer, evaluate them.
+
+If you find bugs or get stuck somewhere, please text `Andi` on Mattermost or by mail (andi.gerken@gmail.com)
\ No newline at end of file
diff --git a/examples/example_readme.py b/examples/example_readme.py
index 197ada6..6798f9d 100644
--- a/examples/example_readme.py
+++ b/examples/example_readme.py
@@ -7,32 +7,38 @@ def create_example_file(path):
f = robofish.io.File(world_size_cm=[100, 100], frequency_hz=25.0)
f.attrs["experiment_setup"] = "This is a simple example with made up data."
- # Create a new robot entity. Positions and orientations are passed
- # separately in this example. Since the orientations have two columns,
- # unit vectors are assumed (orientation_x, orientation_y)
- circle_rad = np.linspace(0, 2 * np.pi, num=100)
+ # Create a new robot entity with 10 timesteps.
+ # Positions and orientations are passed separately in this example.
+ # Since the orientations have two columns, unit vectors are assumed
+ # (orientation_x, orientation_y)
f.create_entity(
category="robot",
name="robot",
- positions=np.stack((np.cos(circle_rad), np.sin(circle_rad))).T * 40,
- orientations=np.stack((-np.sin(circle_rad), np.cos(circle_rad))).T,
+ positions=np.zeros((10, 2)),
+ orientations=np.ones((10, 2)) * [0, 1],
)
- # Create a new fish entity.
+ # Create a new fish entity with 10 timesteps.
# In this case, we pass positions and orientations together (x, y, rad).
# Since it is a 3 column array, orientations in radiants are assumed.
- poses = np.zeros((100, 3))
- poses[:, 0] = np.arange(-50, 50)
- poses[:, 1] = np.arange(-50, 50)
- poses[:, 2] = np.arange(0, 2 * np.pi, step=2 * np.pi / 100)
+ poses = np.zeros((10, 3))
+ poses[:, 0] = np.arange(-5, 5)
+ poses[:, 1] = np.arange(-5, 5)
+ poses[:, 2] = np.arange(0, 2 * np.pi, step=2 * np.pi / 10)
fish = f.create_entity("fish", poses=poses)
fish.attrs["species"] = "My rotating spaghetti fish"
fish.attrs["fish_standard_length_cm"] = 10
- # Show and save the file
- print(f)
- print("Poses Shape: ", f.entity_poses.shape)
+ # Some possibilities to access the data
+ print(f"The file:\n{f}")
+ print(
+ f"Poses Shape:\t{f.entity_poses_rad.shape}.\t"
+ + "Representing(entities, timesteps, pose dimensions (x, y, ori)"
+ )
+ print(f"The actions of one Fish, (timesteps, (speed, turn)):\n{fish.speed_turn}")
+ print(f"Fish poses with calculated orientations:\n{fish.poses_calc_ori_rad}")
+ # Save the file
f.save_as(path)
diff --git a/src/robofish/evaluate/app.py b/src/robofish/evaluate/app.py
index 4d603f3..0b9f3bd 100644
--- a/src/robofish/evaluate/app.py
+++ b/src/robofish/evaluate/app.py
@@ -11,6 +11,7 @@ Functions available to be used in the commandline to evaluate robofish.io files.
import robofish.evaluate
import argparse
+import string
def function_dict():
@@ -41,24 +42,26 @@ def evaluate(args=None):
fdict = function_dict()
+ longest_name = max([len(k) for k in fdict.keys()])
+
parser = argparse.ArgumentParser(
- description="This function can be called from the commandline to evaluate files.\
- Different evaluation methods can be called, which generate graphs from the given files. \
- \
- With the first argument 'analysis_type', the type of analysis is chosen."
+ description="This function can be called from the commandline to evaluate files.\n"
+ + "Different evaluation methods can be called, which generate graphs from the given files.\n"
+ + "With the first argument 'analysis_type', the type of analysis is chosen.",
+ formatter_class=argparse.RawTextHelpFormatter,
)
parser.add_argument(
"analysis_type",
type=str,
choices=fdict.keys(),
- help="The type of analysis.\
- speed - A histogram of speeds\
- turn - A histogram of angular velocities\
- tank_positions - A heatmap of the positions in the tank\
- trajectories - A plot of all the trajectories\
- follow_iid - A plot of the follow metric in relation to iid (inter individual distance)\
- ",
+ help="The type of analysis.\n"
+ + "\n".join(
+ [
+ f"{key}{' ' * (longest_name - len(key))} - {func.__doc__.splitlines()[0]}"
+ for key, func in fdict.items()
+ ]
+ ),
)
parser.add_argument(
"paths",
diff --git a/src/robofish/io/__init__.py b/src/robofish/io/__init__.py
index 5e84ac0..994b49f 100644
--- a/src/robofish/io/__init__.py
+++ b/src/robofish/io/__init__.py
@@ -1,5 +1,12 @@
# SPDX-License-Identifier: LGPL-3.0-or-later
+"""
+The Python package `robofish.io` provides a simple interface to create, load, modify, and inspect files containing tracks of swarms.
+The files are saved in the `.hdf5` format and following the [track_format specification](https://git.imp.fu-berlin.de/bioroboticslab/robofish/track_format/uploads/f76d86e7a629ca38f472b8f23234dbb4/RoboFish_Track_Format_-_1.0.pdf).
+
+.. include:: ../../../docs/index.md
+"""
+
import sys
import logging
diff --git a/src/robofish/io/entity.py b/src/robofish/io/entity.py
index 3759cea..52cfbe4 100644
--- a/src/robofish/io/entity.py
+++ b/src/robofish/io/entity.py
@@ -1,3 +1,7 @@
+"""
+.. include:: ../../../docs/entity.md
+"""
+
import robofish.io
import robofish.io.utils as utils
@@ -137,6 +141,14 @@ class Entity(h5py.Group):
return np.tile([1, 0], (self.positions.shape[0], 1))
return self["orientations"]
+ @property
+ def orientations_rad(self):
+ ori_rad = utils.limit_angle_range(
+ np.arctan2(self.orientations[:, 1], self.orientations[:, 0]),
+ _range=(0, 2 * np.pi),
+ )
+ return ori_rad[:, np.newaxis]
+
@property
def poses_calc_ori_rad(self):
# Diff between positions [t - 1, 2]
@@ -160,12 +172,7 @@ class Entity(h5py.Group):
@property
def poses_rad(self):
- poses = self.poses
- # calculate the angles from the orientation vectors, write them to the third row and delete the fourth row
- ori_rad = utils.limit_angle_range(
- np.arctan2(poses[:, 3], poses[:, 2]), _range=(0, 2 * np.pi)
- )
- return np.concatenate([poses[:, :2], ori_rad[:, np.newaxis]], axis=1)
+ return np.concatenate([self.positions, self.orientations_rad], axis=1)
@property
def speed_turn(self):
diff --git a/src/robofish/io/file.py b/src/robofish/io/file.py
index 616eb92..94512f9 100644
--- a/src/robofish/io/file.py
+++ b/src/robofish/io/file.py
@@ -1,13 +1,14 @@
# -*- coding: utf-8 -*-
+"""
+.. include:: ../../../docs/file.md
+"""
+
# -----------------------------------------------------------
# Utils functions for reading, validating and writing hdf5 files according to
# Robofish track format (1.0 Draft 7). The standard is available at
# https://git.imp.fu-berlin.de/bioroboticslab/robofish/track_format
-#
-# The term track is used to describe a dictionary, describing the track in a dict.
-# To distinguish between attributes, dictionaries and groups, a prefix is used
-# (a_ for attribute, d_ for dictionary, and g_ for groups).
+
#
# Dec 2020 Andreas Gerken, Berlin, Germany
# Released under GNU 3.0 License
@@ -325,7 +326,6 @@ class File(h5py.File):
assert poses.ndim == 3
assert poses.shape[2] in [3, 4]
agents = poses.shape[0]
- timesteps = poses.shape[1]
entity_names = []
for i in range(agents):
@@ -361,9 +361,23 @@ class File(h5py.File):
for name in self.entity_names
]
+ @property
+ def entity_positions(self):
+ return self.select_entity_property(None, entity_property=Entity.positions)
+
+ @property
+ def entity_orientations(self):
+ return self.select_entity_property(None, entity_property=Entity.orientations)
+
+ @property
+ def entity_orientations_rad(self):
+ return self.select_entity_property(
+ None, entity_property=Entity.orientations_rad
+ )
+
@property
def entity_poses(self):
- return self.select_entity_property(None)
+ return self.select_entity_property(None, entity_property=Entity.poses)
@property
def entity_poses_rad(self):
--
GitLab