Metadata-Version: 2.1
Name: Adv2
Version: 1.2.0
Summary: Adv2reader reads version 2 Astro Digital Video files.
Home-page: https://github.com/bob-anderson-ok/adv2reader
Author: Bob Anderson
Author-email: bob.anderson.ok@gmail.com
Maintainer: Bob Anderson
Maintainer-email: bob.anderson.ok@gmail.com
License: License :: OSI Approved :: MIT License
Keywords: ADV file reader,Astro Digital Video version 2 file reader
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: numpy

Adv2
====

This package provides a 'reader' for .adv (AstroDigitalVideo) Version 2 files.

It is the result of a collaborative effort involving Bob Anderson and Hristo Pavlov.

The specification for Astro Digital Video files can be 
found at: <http://www.astrodigitalvideoformat.org/spec.html>

To install this package on your system:

    pip install Adv2

Then, sample usage from within your Python code is:

    from pathlib import Path

    from Adv2.Adv2File import Adv2reader

    try:
        # Create a platform agnostic path to your .adv file (use forward slashes)
        file_path = str(Path('path/to/your/file.adv'))  # Python will make Windows version as needed

        # Create a 'reader' for the given file
        rdr = Adv2reader(file_path)

    except AdvLibException as adverr:
        print(repr(adverr))
        exit()

    except IOError as ioerr:
        print(repr(ioerr))
        exit()

Now that the file has been opened and a 'reader' (rdr) created for it, 
there are instance variables available that will be useful.
Here is how to print some of those out (these give the image size and number of images in the file):

    print(f'Width: {rdr.Width}  Height: {rdr.Height}  NumMainFrames: {rdr.CountMainFrames}')

There is also an composite instance variable called `FileInfo` which gives access to all
of the values defined in the structure `AdvFileInfo` (there are 20 of them).

For example:

    print(rdr.FileInfo.UtcTimestampAccuracyInNanoseconds)

To get (and show) the file metadata (returned as a Dict[str, str]):

    print(f'\nADV_FILE_META_DATA:')
    meta_data = rdr.getAdvFileMetaData()
    for key in meta_data:
        print(f'    {key}: {meta_data[key]}')

The main thing that one will want to do is read image data, timestamps, and frame status information
from image frames.

Continuing with the example and assuming that the adv file contains a MAIN stream (it
might also contain a CALIBRATION stream):


    for frame in range(rdr.CountMainFrames):

        # status is a Dict[str, str]
        err, image, frameInfo, status = rdr.getMainImageAndStatusData(frameNumber=frame)
        # To get frames from a CALIBRATION stream, use rdr.getCalibImageAndStatusData()

        if not err:
            # If timestamp info was not present in the file (highly unlikely),
            # the timestamp string returned will be empty (== '')
            if frameInfo.StartOfExposureTimestampString:
                print(frameInfo.DateString, frameInfo.StartOfExposureTimestampString)
            print(f'\nframe: {frame} STATUS:')
            for entry in status:
                print(f'    {entry}: {status[entry]}')
        else:
            print(err)

`err` is a string that will be empty if image bytes and metadata where successfully extracted.
In that case, `image` will contain a numpy array of uint16 values. If `err` is not empty, it will contain
a human-readable description of the error encountered.

The 'shape' of image will be `image[Height, Width]` for grayscale images. Color video
files are not yet supported.

Finally, the file should closed as in the example below:

    print(f'closeFile returned: {rdr.closeFile()}')
    rdr = None

The value returned will be the version number (2) of the file closed or 0, which indicates an attempt to close a file that was
already closed.