Package: imgstore-shaliulab
IMGStore - Houses Your Video And DataImgstore is a container for video frames and metadata. It allows efficient storage and seeking
through recordings from hours to weeks in duration. It supports compressed and uncompressed formats.Imgstore allows reading (and writing) videos recorded with
loopbio'sMotifrecording system.IntroductionThe ConceptVideo data is broken into chunks, which can be individual video filesVideoImgStore, or
a directory full of imagesDirectoryImgStore. The format of the chunks determines if the store is
compressed, uncompressed, lossless or lossy.Along side the video data Imgstore can also record different types of metadata:Recording (User) Metadata:This includes information set at the time of recording, such as 'genotype', that is constant
for the entire duration of recording.Frame Metadata:This is theframe_numberandframe_timestampfor every frame in the imgstoreExtra Data:This is DAQ and Audio data recorded byMotifat a rate different, and
often faster than, the video framerate.SeeExtracting Metadata.Basic APIThere are only a few public API entry points exposed (most operations are
done onImgStoreobjects (see writing and reading examples below).new_for_filename(path)- Open a store for readingnew_for_format(format, path, **kwargs)Open a store for writingYou also need to passimgshape=andimgdtypeNote:imgshapeis the array shape, i.e.(h,w,d)and not(w,h)get_supported_formats()- list supports formats (remember to test after install)extract_only_frame(path, frame_index)- extract a single frame at givenindexfrom fileExample: Write a storeimportimgstoreimportnumpyasnpimportcv2importtimeheight=width=500blank_image=np.zeros((height,width,3),np.uint8)store=imgstore.new_for_format('npy',# numpy format (uncompressed raw image frames)mode='w',basedir='mystore',imgshape=blank_image.shape,imgdtype=blank_image.dtype,chunksize=1000)# 1000 files per chunk (directory)foriinrange(40):img=blank_image.copy()cv2.putText(img,str(i),(0,300),cv2.FONT_HERSHEY_SIMPLEX,4,255)store.add_image(img,i,time.time())store.close()You can also add additional (JSON serialable) data at any time, and this will be stored
with a reference to the currentframe_numberso that it can be retrieved
and easily combined later.store.add_extra_data(temperature=42.5,humidity=12.4)Example: Read a storefromimgstoreimportnew_for_filenamestore=new_for_filename('mystore/metadata.yaml')print'frames in store:',store.frame_countprint'min frame number:',store.frame_minprint'max frame number:',store.frame_max# read first frameimg,(frame_number,frame_timestamp)=store.get_next_image()print'framenumber:',frame_number,'timestamp:',frame_timestamp# read last frameimg,(frame_number,frame_timestamp)=store.get_image(store.frame_max)print'framenumber:',frame_number,'timestamp:',frame_timestampExtracting frames: frame index vs frame numberStores maintain two separate and distinct concepts, 'frame number', which
is any integer value associated with a single frame, and 'frame index', which is numbered
from 0 to the number of frames in the store. This difference is visible in the API withclassImgStoredefget_image(self,frame_number,exact_only=True,frame_index=None):passwhere 'frame index' OR 'frame number' can be passed.Extracting MetadataTo get the Recording (user) metadata access theImgStore.user_metadataproperty.To get all the image metadata at once you can callImgStore.get_frame_metadata()which will return a dictionary containing allframe_numberandframe_timestamps.To retrieve a pandas DataFrame of all extra data and associatedframe_numberandframe_timestamps callImgStore.get_extra_data()Command line toolsSome simple tools for creating, converting and viewing imgstores are providedimgstore-view /path/to/storeview an imgstoreimgstore-save --format 'avc1/mp4' --source /path/to/input.mp4 /path/to/store/to/save--sourceif omitted will be the first webcamimgstore-testrun extensive tests to check opencv build has mp4 support and trustworthy encoding/decodingInstallIMGStoredepends on reliable OpenCV builds, and built with mp4/h264 support for
writing mp4s.You can install opencv from pip or conda if you wish, or on linux you can use the system apt-get
installed opencv if you create a virtual environment with--system-site-packages.Once you have a python (virtual) environment with a recent and reliable OpenCV build,
you can install IMGStore from pip$ pip install imgstoreAfter installing imgstore from any location, you should check it's tests pass to guarantee that
you have a trustworthy OpenCV versionPost install testingYou should always run the commandimgstore-testafter installing imgstore. If your
environment is working correctly you should see a lot of text printed, followed by the
text==== 66 passed, ..... ======To test against the package without installing first, runpython -m pytestNote: by running pytest through it's python module interface, the interpreter addspwdto
top ofPYTHONPATH, as opposed to running tests throughpy.testwhich doesn't.Note: if you recieve many failed tests with the error message 'The opencv backend does not actually have write support'
or 'Your opencv build does support writing this codec', this isnot an imgestore bug- it is a warning that
you have an OpenCV version that does not supportWritingh264 encoded videos. This is often the case on
windows.Even if somewritetests fail due to these issues, you can stil use the imgstore package toreadh264 encoded
video files.