Metadata-Version: 2.3
Name: holonote
Version: 0.2.0
Summary: Annotate your data
License: Copyright (c) 2023, HoloViz team (holoviz.org).
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are
        met:
        
         * Redistributions of source code must retain the above copyright
           notice, this list of conditions and the following disclaimer.
        
         * Redistributions in binary form must reproduce the above copyright
           notice, this list of conditions and the following disclaimer in the
           documentation and/or other materials provided with the
           distribution.
        
         * Neither the name of the copyright holder nor the names of any
           contributors may be used to endorse or promote products derived
           from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
        "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
        LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
        A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
        OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
        LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
        DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
        THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE.txt
Keywords: annotation,holoviews,tools
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: holoviews>=1.18.0
Requires-Dist: pandas
Provides-Extra: examples
Requires-Dist: dask[dataframe]; extra == 'examples'
Requires-Dist: datashader; extra == 'examples'
Requires-Dist: fastparquet; extra == 'examples'
Requires-Dist: hvplot; extra == 'examples'
Requires-Dist: jupyterlab; extra == 'examples'
Requires-Dist: jupyterlab-myst; extra == 'examples'
Requires-Dist: scipy; extra == 'examples'
Provides-Extra: recommended
Requires-Dist: dask[dataframe]; extra == 'recommended'
Requires-Dist: datashader; extra == 'recommended'
Requires-Dist: fastparquet; extra == 'recommended'
Requires-Dist: hvplot; extra == 'recommended'
Requires-Dist: scipy; extra == 'recommended'
Provides-Extra: tests
Requires-Dist: pytest; extra == 'tests'
Description-Content-Type: text/markdown

# `holonote`

The `holonote` library offers tools to create, edit and persist
annotated regions for [HoloViews](https://holoviews.org/).

<img src="https://assets.holoviz.org/holonote/demo.gif">

An annotated region marks a region-of-interest that is overlaid on top
of the visual representation of a HoloViews element. Such a region has a
unique identifier as well as additional domain-specific information
associated with it. What `holonote` offers is a flexible way to
interactively work with these visual regions as well as tools to add,
update and delete whatever domain-specific information you want to
associate with them.

There are two primary components currently offered by `holonote`:

1. `Annotators`: These classes offer the ability to interactively define
   regions, add associated domain-specific information and then persist
   this information to a database. You can interactively add, delete and
   update these annotation regions as well as their associated
   domain-specific data.

2. `Editors`: These tools are designed to let you interactively
   manipulate and edit the visual regions themselves. These regions are in
   fact HoloViews elements which means you can use these editors as
   generic edit tools for the corresponding HoloViews elements.

By default, annotators automatically persist any annotations you create
to a local SQLite database file. This is a very convenient way to get
started with your annotation task, allowing you to immediate begin the
process of collecting useful information.

For production usage where you are investing significant resources
authoring annotations, it is advisable that you define a custom
connector to a more appropriate database system. You can also use
connectors to load annotations from existing databases of annotation
data.

**Do not use the SQLite connector when deploying to production. It is
intended for use only during local development. It is not designed to
be particularly efficient, stable, or secure.**

## Terminology

There are two particularly important pieces of terminology that are used
throughout this library to be aware of:

1. _Regions_: These denote the visual regions-of-interest with a final
   visual representation as a HoloViews element. These may be one or two
   dimensional, may have different visual representations for the same data
   (e.g. a point marker or a crosshair to mark a point in 2D space) and
   have different types:

- _Points_: A single value of interest in an N-dimensional space. For
  instance, on a time axis, this corresponds to a moment in time
  which may be represented visually as a vertical line. On an image,
  this can ve visually represented with a crosshair.
- _Ranges_: A range is an axis-aligned span between a start and end
  point. For instance, along a time axis, this corresponds to a time interval and
  on an image, this corresponds to a 2D box.

2. _Fields_: These are the domain-specific component of the annotation
   data, containing information that is not to be visualized by
   `holonote`. These are defined by the user or application and can have
   arbitrary types and contents. A complete set of fields together with one
   or more regions constitutes an annotation.
