Adv2 1.0.0

Adv2reader reads version 2 Astro Digital Video files.

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.