prevo


Nameprevo JSON
Version 0.19.1 PyPI version JSON
download
home_pagehttps://github.com/ovinc/prevo
SummaryRecord arbitrary sensors periodically in an asynchronous manner. Control their properties in real time from CLI. Graph/view tools to visualize live data/images are also provided.
upload_time2024-02-23 09:20:07
maintainer
docs_urlNone
authorOlivier Vincent
requires_python>=3.6
license
keywords periodic recording data
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            About
=====

**P**eriodic **RE**cording and **V**isualization of (sensor) **O**bjects

This package provides classes to rapidly create interactive data recording for various applications (e.g. recording of temperature, time-lapses with cameras etc.).

Sensors are read in an asynchronous fashion and can have different time intervals for data reading (or be continuous, i.e. as fast as possible). Synchronous recording is also possible (although not the main goal of this package) by defining a super-sensor object that reads all sensors (and which is itself probed at regular intervals).

Tools for graphical visualizations of data during recording are also provided (updated numerical graphs, oscilloscope-like graphs, image viewers for cameras etc.)

The package contains various modules:

- `prevo.record`: record sensors periodically, CLI interface, trigger GUI tools from CLI,

- `prevo.control`: control device properties, create pre-defined temporal evolutions of settings for sensors, devices and recording properties,

- `prevo.plot`: plot numerical data in real time (regular plots, oscilloscope-like graphs etc.),

- `prevo.viewers`: live view of images from camera-like sensors,

- `prevo.csv`: read / save data with CSV/TSV files

- `prevo.parser`: parse command line arguments to trigger functions or class methods

- `prevo.measurements`: additional tools to format measurements for `Record`-like classes.

- `prevo.misc`: miscellaneous tools, including dummy sensors and devices.

See Jupyter notebooks in `examples/` and docstrings for more help.

Below are also minimal examples showing implementation of periodic recording and image viewers.


Install
=======

```bash
pip install prevo
```


Record sensors periodically
===========================

For using the package for asynchronous recording of data, three base classes must/can be subclassed:
- `SensorBase`
- `RecordingBase` (children: `NumericalRecording`, `ImageRecording`)
- `Record` (children: `NumericalRecord`, `ImageRecord`)

A minimal example is provided below, to record pressure and temperature asynchronously into a CSV file, assuming the user already has classes (`Temp`, `Gauge`) to take single-point measurements (it could be functions as well). See `examples/Record.ipynb` for more detailed examples, including periodic recording of images from several cameras.

1) **Define the sensors**

    ```python
    from prevo.record import SensorBase


    class TemperatureSensor(SensorBase):

        name = 'T'

        def _get_data(self):
            return Temp.read()


    class PressureSensor(SensorBase):

        name = 'P'

        def _get_data(self):
            return Gauge.read()
    ```

    Note: context managers also possible (i.e. define `__enter__` and `__exit__` in `Sensor` class) e.g. if sensors have to be opened once at the beginning and closed in the end.


2) **Define the individual recordings**

    ```python
    from prevo.record.numerical import NumericalRecording

    # Because timestamp and time uncertaintyare added automatically in data
    # Can be renamed to have different time column titles in csv file.
    time_columns = ('time (unix)', 'dt (s)')

    # Note: NumericalRecording can also be subclassed for simpler use
    # (see examples/Record.ipynb Jupyter notebook)

    recording_P = NumericalRecording(
        Sensor=PressureSensor,
        filename='Pressure.csv',
        column_names=time_columns + ('P (mbar)',),
    )

    recording_T = NumericalRecording(
        Sensor=TemperatureSensor,
        filename='Temperature.csv',
        column_names=time_columns + ('T (°C)',),
    )
    ```

    **NOTE**: the recordings are already usable as is if one does not need fancy functionality.
    For example, one can start a periodic recording of pressure every two seconds with

    ```python
    recording.start(dt=2)
    ```

    And the following methods and attributes are available:
    ```python
    # can be set to True or False to pause/resume recording
    recording.active

    # can be set to True or False to pause/resume saving to file
    # (e.g. to continue live view of data without saving)
    recording.saving

    # Equivalent to playing with .active:
    recording.pause()
    recording.resume()

    recording_P.stop()
    # After a stop(), it is possible to call start() again.

    # To change the time interval between data:
    recording.timer.interval = ...

    # To record data as fast as possible:
    recording.continuous = True
    ```

    **NOTE**: `recording.start()` is non-blocking, so several independent recordings can be started at the same time, and can be changed in real time with the methods/attribute above. However, a convenient interface to manage several recordings simultaneously is provided by the `Record` class, see below.

3) **`Record` interface for managing simultaneous recordings**

    `Record` provides a real-time CLI to manage recordings properties in real time as well as live data visualization.

    ```python
    from prevo.record.numerical import NumericalRecord

    recordings = recording_P, recording_T
    record = NumericalRecord(recordings)
    record.start(dt=2)  # time interval of 2 seconds for both sensors
    ```

Many other options and customizations exist See docstrings for more help and `examples/Record.ipynb` for examples.


Live image viewer
=================

Let's assume one gets image data in a queue from a camera.
Individual elements from the `camera.queue` are dictionaries with keys `image` (numpy-like image array) and `num` (image number, an integer). This formatting of elements in the queue is assumed by default, but others are possible (see *examples/Viewers.ipynb*).

It is possible to view the images using either `tkinter`, `opencv` or `matplotlib`. Here we will use tkinter.
One first has to define a *window* in which to display the images, and then a *viewer* to operate and update the window.


```python
from prevo.viewers import TkWindow, TkViewer

# The window will show the (display) fps and the image number in real time
window = TkWindow(camera.queue, show_fps=True, show_num=True)

# It is possible to run several windows in parallel from other image sources
# Here we have just one.
viewer = TkViewer(windows=(window,))
viewer.start()
```

Here again, various options and customizations are possible, see some example in *examples/Viewers.ipynb*.


Misc. info
==========

Module requirements
-------------------

### Packages outside of standard library

(installed automatically by pip if necessary)

- tqdm
- tzlocal < 3.0
- oclock >= 1.3.2 (timing tools)
- clivo >= 0.4.0 (command line interface)
- gittools >= 0.6.0 (metadata saving tools)
- matplotlib >= 3.1 (due to `cache_frame_data` option in `FuncAnimation`)
- numpy

### Optional packages

- pandas (optional, for csv loading methods)
- opencv-python (optional, for specific camera viewers)


Python requirements
-------------------

Python : >= 3.6

Author
------

Olivier Vincent

(ovinc.py@gmail.com)

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/ovinc/prevo",
    "name": "prevo",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "",
    "keywords": "periodic,recording,data",
    "author": "Olivier Vincent",
    "author_email": "ovinc.py@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/d0/84/3b0f077faf245dd2b168550dde80dda2a322016e8009ddcc79c84ebc4fef/prevo-0.19.1.tar.gz",
    "platform": null,
    "description": "About\n=====\n\n**P**eriodic **RE**cording and **V**isualization of (sensor) **O**bjects\n\nThis package provides classes to rapidly create interactive data recording for various applications (e.g. recording of temperature, time-lapses with cameras etc.).\n\nSensors are read in an asynchronous fashion and can have different time intervals for data reading (or be continuous, i.e. as fast as possible). Synchronous recording is also possible (although not the main goal of this package) by defining a super-sensor object that reads all sensors (and which is itself probed at regular intervals).\n\nTools for graphical visualizations of data during recording are also provided (updated numerical graphs, oscilloscope-like graphs, image viewers for cameras etc.)\n\nThe package contains various modules:\n\n- `prevo.record`: record sensors periodically, CLI interface, trigger GUI tools from CLI,\n\n- `prevo.control`: control device properties, create pre-defined temporal evolutions of settings for sensors, devices and recording properties,\n\n- `prevo.plot`: plot numerical data in real time (regular plots, oscilloscope-like graphs etc.),\n\n- `prevo.viewers`: live view of images from camera-like sensors,\n\n- `prevo.csv`: read / save data with CSV/TSV files\n\n- `prevo.parser`: parse command line arguments to trigger functions or class methods\n\n- `prevo.measurements`: additional tools to format measurements for `Record`-like classes.\n\n- `prevo.misc`: miscellaneous tools, including dummy sensors and devices.\n\nSee Jupyter notebooks in `examples/` and docstrings for more help.\n\nBelow are also minimal examples showing implementation of periodic recording and image viewers.\n\n\nInstall\n=======\n\n```bash\npip install prevo\n```\n\n\nRecord sensors periodically\n===========================\n\nFor using the package for asynchronous recording of data, three base classes must/can be subclassed:\n- `SensorBase`\n- `RecordingBase` (children: `NumericalRecording`, `ImageRecording`)\n- `Record` (children: `NumericalRecord`, `ImageRecord`)\n\nA minimal example is provided below, to record pressure and temperature asynchronously into a CSV file, assuming the user already has classes (`Temp`, `Gauge`) to take single-point measurements (it could be functions as well). See `examples/Record.ipynb` for more detailed examples, including periodic recording of images from several cameras.\n\n1) **Define the sensors**\n\n    ```python\n    from prevo.record import SensorBase\n\n\n    class TemperatureSensor(SensorBase):\n\n        name = 'T'\n\n        def _get_data(self):\n            return Temp.read()\n\n\n    class PressureSensor(SensorBase):\n\n        name = 'P'\n\n        def _get_data(self):\n            return Gauge.read()\n    ```\n\n    Note: context managers also possible (i.e. define `__enter__` and `__exit__` in `Sensor` class) e.g. if sensors have to be opened once at the beginning and closed in the end.\n\n\n2) **Define the individual recordings**\n\n    ```python\n    from prevo.record.numerical import NumericalRecording\n\n    # Because timestamp and time uncertaintyare added automatically in data\n    # Can be renamed to have different time column titles in csv file.\n    time_columns = ('time (unix)', 'dt (s)')\n\n    # Note: NumericalRecording can also be subclassed for simpler use\n    # (see examples/Record.ipynb Jupyter notebook)\n\n    recording_P = NumericalRecording(\n        Sensor=PressureSensor,\n        filename='Pressure.csv',\n        column_names=time_columns + ('P (mbar)',),\n    )\n\n    recording_T = NumericalRecording(\n        Sensor=TemperatureSensor,\n        filename='Temperature.csv',\n        column_names=time_columns + ('T (\u00b0C)',),\n    )\n    ```\n\n    **NOTE**: the recordings are already usable as is if one does not need fancy functionality.\n    For example, one can start a periodic recording of pressure every two seconds with\n\n    ```python\n    recording.start(dt=2)\n    ```\n\n    And the following methods and attributes are available:\n    ```python\n    # can be set to True or False to pause/resume recording\n    recording.active\n\n    # can be set to True or False to pause/resume saving to file\n    # (e.g. to continue live view of data without saving)\n    recording.saving\n\n    # Equivalent to playing with .active:\n    recording.pause()\n    recording.resume()\n\n    recording_P.stop()\n    # After a stop(), it is possible to call start() again.\n\n    # To change the time interval between data:\n    recording.timer.interval = ...\n\n    # To record data as fast as possible:\n    recording.continuous = True\n    ```\n\n    **NOTE**: `recording.start()` is non-blocking, so several independent recordings can be started at the same time, and can be changed in real time with the methods/attribute above. However, a convenient interface to manage several recordings simultaneously is provided by the `Record` class, see below.\n\n3) **`Record` interface for managing simultaneous recordings**\n\n    `Record` provides a real-time CLI to manage recordings properties in real time as well as live data visualization.\n\n    ```python\n    from prevo.record.numerical import NumericalRecord\n\n    recordings = recording_P, recording_T\n    record = NumericalRecord(recordings)\n    record.start(dt=2)  # time interval of 2 seconds for both sensors\n    ```\n\nMany other options and customizations exist See docstrings for more help and `examples/Record.ipynb` for examples.\n\n\nLive image viewer\n=================\n\nLet's assume one gets image data in a queue from a camera.\nIndividual elements from the `camera.queue` are dictionaries with keys `image` (numpy-like image array) and `num` (image number, an integer). This formatting of elements in the queue is assumed by default, but others are possible (see *examples/Viewers.ipynb*).\n\nIt is possible to view the images using either `tkinter`, `opencv` or `matplotlib`. Here we will use tkinter.\nOne first has to define a *window* in which to display the images, and then a *viewer* to operate and update the window.\n\n\n```python\nfrom prevo.viewers import TkWindow, TkViewer\n\n# The window will show the (display) fps and the image number in real time\nwindow = TkWindow(camera.queue, show_fps=True, show_num=True)\n\n# It is possible to run several windows in parallel from other image sources\n# Here we have just one.\nviewer = TkViewer(windows=(window,))\nviewer.start()\n```\n\nHere again, various options and customizations are possible, see some example in *examples/Viewers.ipynb*.\n\n\nMisc. info\n==========\n\nModule requirements\n-------------------\n\n### Packages outside of standard library\n\n(installed automatically by pip if necessary)\n\n- tqdm\n- tzlocal < 3.0\n- oclock >= 1.3.2 (timing tools)\n- clivo >= 0.4.0 (command line interface)\n- gittools >= 0.6.0 (metadata saving tools)\n- matplotlib >= 3.1 (due to `cache_frame_data` option in `FuncAnimation`)\n- numpy\n\n### Optional packages\n\n- pandas (optional, for csv loading methods)\n- opencv-python (optional, for specific camera viewers)\n\n\nPython requirements\n-------------------\n\nPython : >= 3.6\n\nAuthor\n------\n\nOlivier Vincent\n\n(ovinc.py@gmail.com)\n",
    "bugtrack_url": null,
    "license": "",
    "summary": "Record arbitrary sensors periodically in an asynchronous manner. Control their properties in real time from CLI. Graph/view tools to visualize live data/images are also provided.",
    "version": "0.19.1",
    "project_urls": {
        "Homepage": "https://github.com/ovinc/prevo"
    },
    "split_keywords": [
        "periodic",
        "recording",
        "data"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "2244d63587da6ef8e6586bb997635e3a282420cf6775178af8676b7c29ecce31",
                "md5": "5b852e73d224bbefb27a11e7b6d47850",
                "sha256": "aad4fbb8077e8e45860fd02a773450122d52bc70e7d3b4b281bed8170f0dcd87"
            },
            "downloads": -1,
            "filename": "prevo-0.19.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5b852e73d224bbefb27a11e7b6d47850",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 94571,
            "upload_time": "2024-02-23T09:19:50",
            "upload_time_iso_8601": "2024-02-23T09:19:50.012349Z",
            "url": "https://files.pythonhosted.org/packages/22/44/d63587da6ef8e6586bb997635e3a282420cf6775178af8676b7c29ecce31/prevo-0.19.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d0843b0f077faf245dd2b168550dde80dda2a322016e8009ddcc79c84ebc4fef",
                "md5": "9520891885b6755481b15a535a964958",
                "sha256": "96242cdd5d0e366edc2568db3d08b3317e37006ead0a74bfae34afd6669b29fd"
            },
            "downloads": -1,
            "filename": "prevo-0.19.1.tar.gz",
            "has_sig": false,
            "md5_digest": "9520891885b6755481b15a535a964958",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 629984,
            "upload_time": "2024-02-23T09:20:07",
            "upload_time_iso_8601": "2024-02-23T09:20:07.525818Z",
            "url": "https://files.pythonhosted.org/packages/d0/84/3b0f077faf245dd2b168550dde80dda2a322016e8009ddcc79c84ebc4fef/prevo-0.19.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-02-23 09:20:07",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "ovinc",
    "github_project": "prevo",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "prevo"
}
        
Elapsed time: 0.22285s