Polishing H5 support and simplifying saving/checking logic (#154)

* adds h5py to install guide instructions

* adds ack for the `.h5` contribution

* simplifies and moves inspect_h5 to utils.py

* * adds make_h5_key function to generate h5 group names
* brushes up existance logic and style

* follow up

* raise if .extract is called on BaseExtractor

* adds doc for h5

* pin h5py version

* replaced the exact function with the fn from the map

* slightly improved doc

* simplified saving/checking logic into generic functions
* adds tests for h5
* moves all writes and loads to two functions
* now h5 writing is done per feature key, not all keys at once
* feature path construction now supports h5 as well as prev formats

* puts back the default output feat keys

* fixes bug for a test

Author: v-iashin

README.md

@@ -51,7 +51,7 @@ conda env create -f conda_env.yml
 conda activate video_features
 
 # extract r(2+1)d features for the sample videos
-# (defaults to printing; use on_extraction=save_numpy or save_h5 to save to disk)
+# (defaults to printing; use on_extraction=save_numpy or save_h5 or save_pickle to save to disk)
 python main.py \
     feature_type=r21d \
     device="cuda:0" \
@@ -94,14 +94,7 @@ Output is defined by the `on_extraction` argument; by default it prints the feat
 Possible values of output are `['print', 'save_numpy', 'save_pickle', 'save_h5']`.
 
 * **`save_numpy` / `save_pickle`**: Saves the features in the `output_path` folder with the same name as the input video file but with the `.npy` or `.pkl` extension.
-* **`save_h5`**: Saves features into a single HDF5 file per device in the `output_path` (e.g. `video_features_cuda0.h5` or `video_features_cpu.h5`). The features are stored as datasets inside the file, using the video filename as the group key.
-> **Tip for HDF5:** Since `save_h5` appends to the same file (e.g. `video_features_cuda0.h5`), we recommend using different `output_path` directories for different datasets (e.g. `./output/train` vs `./output/test`) to keep your data logically separate.
-### Inspecting H5 Files
-If you used `save_h5`, you can verify the contents of the generated file using the provided utility script. This will print the video names and feature shapes stored inside.
-
-```bash
-python utils/inspect_h5.py ./output/r21d/video_features_cuda.h5
-```
+* **`save_h5`**: Saves features into a single HDF5 file per device in the `output_path` (e.g. `video_features_cuda0.h5`) with video path as keys (`/`/`\\` replaced by `_`). Structure: `file.h5 / video_key (group) / feature_name (rgb, flow, fps etc)`. Use `utils.py/inspect_h5()` to explore the content.
 
 
 ## Used in
@@ -119,6 +112,7 @@ Please, let me know if you found this repo useful for your projects or papers.
 - [@ohjho](https://github.com/ohjho): added support of 37-layer R(2+1)d favors.
 - [@borijang](https://github.com/borijang): for solving bugs with file names, I3D checkpoint loading enhancement and code style improvements.
 - [@bjuncek](https://github.com/bjuncek): for helping with timm models and offline discussion.
+- [@VivekNarula7](https://github.com/VivekNarula7): for adding support for `.h5` output format.
 
 ## Citation
 

conda_env.yml

@@ -59,7 +59,7 @@ dependencies:
   - gstreamer-orc=0.4.34=hd590300_0
   - harfbuzz=6.0.0=h8e241bc_0
   - hdf5=1.14.0=nompi_hb72d44e_103
-  - h5py
+  - h5py=3.15.1
   - icu=70.1=h27087fc_0
   - idna=3.4=py311h06a4308_0
   - iniconfig=2.0.0=pyhd8ed1ab_0
@@ -248,4 +248,3 @@ dependencies:
     - huggingface-hub==0.20.2
     - safetensors==0.4.1
     - timm==0.9.12
-    

configs/clip.yml

@@ -7,7 +7,7 @@ extraction_total: null # extract a fix number of frames. It is mutually exclusiv
 
 # Extraction Parameters
 device: 'cuda:0'  # device as in `torch`, can be 'cpu'
-on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle']
+on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle', 'save_h5']
 output_path: './output' # where to store results if saved
 tmp_path: './tmp' # folder to store the temporary files used for extraction (frames or aud files)
 keep_tmp_files: false # to keep temp files after feature extraction.

configs/i3d.yml

@@ -8,7 +8,7 @@ extraction_fps: null # For original video fps, leave as "null" (None)
 
 # Extraction Parameters
 device: 'cuda:0'  # device as in `torch`, can be 'cpu'
-on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle']
+on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle', 'save_h5']
 output_path: './output' # where to store results if saved
 tmp_path: './tmp' # folder to store the temporary files used for extraction (frames or aud files)
 keep_tmp_files: false # to keep temp files after feature extraction.

configs/r21d.yml

@@ -7,7 +7,7 @@ extraction_fps: null # For original video fps, leave unspecified "null" (None)
 
 # Extraction Parameters
 device: 'cuda:0'  # device as in `torch`, can be 'cpu'
-on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle']
+on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle', 'save_h5']
 output_path: './output' # where to store results if saved
 tmp_path: './tmp' # folder to store the temporary files used for extraction (frames or aud files)
 keep_tmp_files: false # to keep temp files after feature extraction.

configs/raft.yml

@@ -9,7 +9,7 @@ finetuned_on: 'sintel' # also 'kitti' is supported
 # Extraction Parameters
 device: 'cuda:0'  # device as in `torch`, can be 'cpu'
 batch_size: 1 # increase the extraction speed with batching
-on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle']
+on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle', 'save_h5']
 output_path: './output' # where to store results if saved
 tmp_path: './tmp' # folder to store the temporary files used for extraction (frames or aud files)
 keep_tmp_files: false # to keep temp files after feature extraction.

configs/resnet.yml

@@ -7,7 +7,7 @@ extraction_total: null # extract a fix number of frames. It is mutually exclusiv
 
 # Extraction Parameters
 device: 'cuda:0'  # device as in `torch`, can be 'cpu'
-on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle']
+on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle', 'save_h5']
 output_path: './output' # where to store results if saved
 tmp_path: './tmp' # folder to store the temporary files used for extraction (frames or aud files)
 keep_tmp_files: false # to keep temp files after feature extraction.

configs/s3d.yml

@@ -6,7 +6,7 @@ extraction_fps: 25 # 25 is my best guess. For original video fps, leave unspecif
 
 # Extraction Parameters
 device: 'cuda:0'  # device as in `torch`, can be 'cpu'
-on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle']
+on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle', 'save_h5']
 output_path: './output' # where to store results if saved
 tmp_path: './tmp' # folder to store the temporary files used for extraction (frames or aud files)
 keep_tmp_files: false # to keep temp files after feature extraction.

configs/timm.yml

@@ -7,7 +7,7 @@ extraction_total: null # extract a fix number of frames. It is mutually exclusiv
 
 # Extraction Parameters
 device: 'cuda:0' # device as in `torch`, can be 'cpu'
-on_extraction: 'print' # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle']
+on_extraction: 'print' # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle', 'save_h5']
 output_path: './output' # where to store results if saved
 tmp_path: './tmp' # folder to store the temporary files used for extraction (frames or aud files)
 keep_tmp_files: false # to keep temp files after feature extraction.

configs/vggish.yml

@@ -3,7 +3,7 @@ feature_type: 'vggish'
 
 # Extraction Parameters
 device: 'cuda:0'  # device as in `torch`, can be 'cpu'
-on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle']
+on_extraction: 'print'  # what to do once the features are extracted. Can be ['print', 'save_numpy', 'save_pickle', 'save_h5']
 output_path: './output' # where to store results if saved
 tmp_path: './tmp' # folder to store the temporary files used for extraction (frames or aud files)
 keep_tmp_files: false # to keep temp files after feature extraction.