Access modifiers for feature extraction methods

README.md

@@ -1,5 +1,5 @@
 <div align="center">
- 
+
 ![piq_logo](https://user-images.githubusercontent.com/15848838/95228385-ed106500-0807-11eb-8584-d3fdbdd47ac7.jpeg)
 
 [![License][license-shield]][license-url]
@@ -16,18 +16,20 @@
 <!-- ABOUT THE PROJECT -->
 
 Collection of measures and metrics for image quality assessment.
-- Unified interface, which easy to use and extend.
+- Unified interface, which is easy to use and extend.
 - Written on pure PyTorch with bare minima of additional dependencies.
+- Extensive user input validation. You code will not crash in the middle of the training.
 - Fast (GPU computations available) and reliable.
 - Most metrics can be backpropagated for model optimization.
-- Supports python 3.6-3.8
+- Supports python 3.6-3.8.
 
 
 <!-- GETTING STARTED -->
-### Getting started  
+### Getting started
 
-First group of metrics takes image or images as input, e.g PSNR, SSIM, BRISQUE. 
-We have functional interface, which returns metric value and class interface, which allows to use any metric as a loss.
+The first group of metrics takes image or images as input, e.g., PSNR, SSIM, BRISQUE.
+We have a functional interface, which returns a metric value, and a class interface, which allows us to use any metric 
+as a loss function.
 
 ```python
 import torch
@@ -43,22 +45,24 @@ output: torch.Tensor = loss(prediction, target)
 output.backward()
 ```
 
-Second group takes a list of image features e.g. IS, FID, KID.
-Image features can be extracted by some feature extractor network separetely, or by using `_compute_feats` method of a class. Note, that `_compute_feats` consumes a dataloader of predefined format.
+The second group takes a list of image features, e.g., IS, FID, KID.
+Image features can be extracted by some feature extractor network separately or by using the `compute_feats` method of a
+class.   
+**Important note**: `compute_feats` consumes a data loader of a predefined format.
 
 ```python
 import torch
-from  torch.utils.data import DataLoader
+from torch.utils.data import DataLoader
 from piq import FID
 
 first_dl, second_dl = DataLoader(), DataLoader()
-fid_metric = FID() 
-first_feats = fid_metric._compute_feats(first_dl)
-second_feats = fid_metric._compute_feats(second_dl)
+fid_metric = FID()
+first_feats = fid_metric.compute_feats(first_dl)
+second_feats = fid_metric.compute_feats(second_dl)
 fid: torch.Tensor = fid_metric(first_feats, second_feats)
 ```
 
-If you already have image features, use class interface for score computation:
+If you already have image features, use the class interface for score computation:
 
 ```python
 import torch
@@ -75,45 +79,45 @@ For a full list of examples, see [image metrics](examples/image_metrics.py) and
 <!-- IMAGE METRICS -->
 ### Image metrics
 
- 1. [Blind/Referenceless Image Spatial Quality Evaluator (BRISQUE)](https://live.ece.utexas.edu/publications/2012/TIP%20BRISQUE.pdf)
- 2. [Content score](https://openaccess.thecvf.com/content_cvpr_2016/html/Gatys_Image_Style_Transfer_CVPR_2016_paper.html)
- 3. [Deep Image Structure and Texture Similarity measure (DISTS)](https://arxiv.org/abs/2004.07728)
- 4. [Feature Similarity Index Measure (FSIM)](https://www4.comp.polyu.edu.hk/~cslzhang/IQA/TIP_IQA_FSIM.pdf)
- 5. [Gradient Magnitude Similarity Deviation (GMSD)](https://arxiv.org/pdf/1308.3052.pdf)
- 6. [Haar Wavelet-Based Perceptual Similarity Index (HaarPSI)](http://www.math.uni-bremen.de/cda/HaarPSI/publications/HaarPSI_preprint_v4.pdf)
- 7. [Learned Perceptual Image Patch Similarity measure (LPIPS)](https://arxiv.org/abs/1801.03924) 
- 8. [Mean Deviation Similarity Index (MDSI)](https://ieeexplore.ieee.org/abstract/document/7556976/)
- 9. [Multi-Scale Structural Similarity (MS-SSIM)](https://ieeexplore.ieee.org/document/1292216)
- 10. [Multi-Scale Gradient Magnitude Similarity Deviation (MS-GMSD)](http://www.cse.ust.hk/~psander/docs/gradsim.pdf)
- 11. [Peak Signal-to-Noise Ratio (PSNR)](https://en.wikipedia.org/wiki/Peak_signal-to-noise_ratio)
- 12. [Perceptual Image-Error Assessment through Pairwise Preference (PieAPP)](https://arxiv.org/abs/1806.02067)
- 13. [Structural Similarity (SSIM)](https://ece.uwaterloo.ca/~z70wang/publications/ssim.pdf)
- 14. [Style score](https://openaccess.thecvf.com/content_cvpr_2016/html/Gatys_Image_Style_Transfer_CVPR_2016_paper.html)
- 15. [Total Variation (TV)](https://en.wikipedia.org/wiki/Total_variation)
- 16. [Visual Information Fidelity (VIF)](https://live.ece.utexas.edu/research/Quality/VIF.htm)
- 17. [Visual Saliency-induced Index (VSI)](https://ieeexplore.ieee.org/document/6873260) 
+1. [Blind/Referenceless Image Spatial Quality Evaluator (BRISQUE)](https://live.ece.utexas.edu/publications/2012/TIP%20BRISQUE.pdf)
+2. [Content score](https://openaccess.thecvf.com/content_cvpr_2016/html/Gatys_Image_Style_Transfer_CVPR_2016_paper.html)
+3. [Deep Image Structure and Texture Similarity measure (DISTS)](https://arxiv.org/abs/2004.07728)
+4. [Feature Similarity Index Measure (FSIM)](https://www4.comp.polyu.edu.hk/~cslzhang/IQA/TIP_IQA_FSIM.pdf)
+5. [Gradient Magnitude Similarity Deviation (GMSD)](https://arxiv.org/pdf/1308.3052.pdf)
+6. [Haar Wavelet-Based Perceptual Similarity Index (HaarPSI)](http://www.math.uni-bremen.de/cda/HaarPSI/publications/HaarPSI_preprint_v4.pdf)
+7. [Learned Perceptual Image Patch Similarity measure (LPIPS)](https://arxiv.org/abs/1801.03924)
+8. [Mean Deviation Similarity Index (MDSI)](https://ieeexplore.ieee.org/abstract/document/7556976/)
+9. [Multi-Scale Structural Similarity (MS-SSIM)](https://ieeexplore.ieee.org/document/1292216)
+10. [Multi-Scale Gradient Magnitude Similarity Deviation (MS-GMSD)](http://www.cse.ust.hk/~psander/docs/gradsim.pdf)
+11. [Peak Signal-to-Noise Ratio (PSNR)](https://en.wikipedia.org/wiki/Peak_signal-to-noise_ratio)
+12. [Perceptual Image-Error Assessment through Pairwise Preference (PieAPP)](https://arxiv.org/abs/1806.02067)
+13. [Structural Similarity (SSIM)](https://ece.uwaterloo.ca/~z70wang/publications/ssim.pdf)
+14. [Style score](https://openaccess.thecvf.com/content_cvpr_2016/html/Gatys_Image_Style_Transfer_CVPR_2016_paper.html)
+15. [Total Variation (TV)](https://en.wikipedia.org/wiki/Total_variation)
+16. [Visual Information Fidelity (VIF)](https://live.ece.utexas.edu/research/Quality/VIF.htm)
+17. [Visual Saliency-induced Index (VSI)](https://ieeexplore.ieee.org/document/6873260)
 
 <!-- FEATURE METRICS -->
 ### Feature metrics
 1. [Frechet Inception Distance(FID)](https://arxiv.org/abs/1706.08500)
 2. [Geometry Score (GS)](https://arxiv.org/abs/1802.02664)
 3. [Inception Score(IS)](https://arxiv.org/abs/1606.03498)
 4. [Kernel Inception Distance(KID)](https://arxiv.org/abs/1801.01401)
-5. [Multi-Scale Intrinsic Distance (MSID)](https://arxiv.org/abs/1905.11141) 
+5. [Multi-Scale Intrinsic Distance (MSID)](https://arxiv.org/abs/1905.11141)
 
 ### Overview
 
 *PyTorch Image Quality* (former [PhotoSynthesis.Metrics](https://pypi.org/project/photosynthesis-metrics/0.4.0/)) helps you to concentrate on your experiments without the boilerplate code.
-The library contains a set of measures and metrics that is constantly getting extended. 
+The library contains a set of measures and metrics that is continually getting extended.
 For measures/metrics that can be used as loss functions, corresponding PyTorch modules are implemented.
- 
+
 
 #### Installation
 
 `$ pip install piq`
 
-`$ conda install piq -c photosynthesis-team -c conda-forge -c pytorch`
- 
+`$ conda install piq -c photosynthesis-team -c conda-forge -c PyTorch`
+
 If you want to use the latest features straight from the master, clone the repo:
 ```sh
 $ git clone https://github.com/photosynthesis-team/piq.git
@@ -122,7 +126,7 @@ $ git clone https://github.com/photosynthesis-team/piq.git
 <!-- ROADMAP -->
 #### Roadmap
 
-See the [open issues](https://github.com/photosynthesis-team/piq/issues) for a list of proposed 
+See the [open issues](https://github.com/photosynthesis-team/piq/issues) for a list of proposed
 features and known issues.
 
 
@@ -133,10 +137,10 @@ features and known issues.
 <!-- CONTRIBUTING -->
 #### Contributing
 
-We appreciate all contributions. If you plan to: 
-- contribute back bug-fixes, please do so without any further discussion
+We appreciate all your contributions. If you plan to:
+- contribute back bug-fixes; please do so without any further discussion
 - close one of [open issues](https://github.com/photosynthesis-team/piq/issues), please do so if no one has been assigned to it
-- contribute new features, utility functions or extensions, please first open an issue and discuss the feature with us
+- contribute new features, utility functions, or extensions; please first open an issue and discuss the feature with us
 
 Please see the [contribution guide](CONTRIBUTING.md) for more information.
 
@@ -146,12 +150,6 @@ Please see the [contribution guide](CONTRIBUTING.md) for more information.
 
 **Sergey Kastryulin** - [@snk4tr](https://github.com/snk4tr) - `snk4tr@gmail.com`
 
-Project Link: [https://github.com/photosynthesis-team/piq](https://github.com/photosynthesis-team/piq)  
-PhotoSynthesis Team: [https://github.com/photosynthesis-team](https://github.com/photosynthesis-team)
-
-Other projects by PhotoSynthesis Team:  
-* [PhotoSynthesis.Models](https://github.com/photosynthesis-team/photosynthesis.models)
-
 <!-- ACKNOWLEDGEMENTS -->
 #### Acknowledgements
 
@@ -178,4 +176,4 @@ Other projects by PhotoSynthesis Team:
 [reliability-rating-badge]: https://sonarcloud.io/api/project_badges/measure?project=photosynthesis-team_photosynthesis.metrics&metric=reliability_rating
 [reliability-rating-url]:https://sonarcloud.io/dashboard?id=photosynthesis-team_photosynthesis.metrics
 [codecov-shield]:https://codecov.io/gh/photosynthesis-team/piq/branch/master/graph/badge.svg
-[codecov-url]:https://codecov.io/gh/photosynthesis-team/piq
+[codecov-url]:https://codecov.io/gh/photosynthesis-team/piq

examples/feature_metrics.py

@@ -16,8 +16,8 @@ def main():
     fid: torch.Tensor = piq.FID()(prediction_features, target_features)
     print(f"FID: {fid:0.4f}")
 
-    # If image features are not available, extract them using _compute_feats of FID class.
-    # Please note that _compute_feats consumes a data loader of predefined format.
+    # If image features are not available, extract them using compute_feats of FID class.
+    # Please note that compute_feats consumes a data loader of predefined format.
 
     # Use GS class to compute Geometry Score from image features, pre-extracted from some feature extractor network.
     # Computation is heavily CPU dependent, adjust num_workers parameter according to your system configuration.

piq/base.py

@@ -18,7 +18,7 @@ def forward(self, predicted_features: torch.Tensor, target_features: torch.Tenso
         return self.compute_metric(predicted_features, target_features)
 
     @torch.no_grad()
-    def _compute_feats(
+    def compute_feats(
             self,
             loader: torch.utils.data.DataLoader,
             feature_extractor: torch.nn.Module = None,

tests/test_fid.py

@@ -66,7 +66,7 @@ def test_compute_feats(device: str) -> None:
     )
     fid = FID()
     model = InceptionV3()
-    fid._compute_feats(loader, model, device=device)
+    fid.compute_feats(loader, model, device=device)
 
 
 @pytest.mark.parametrize("input_range,normalize_input,expectation",
@@ -86,4 +86,4 @@ def test_inception_input_range(input_range, normalize_input, expectation) -> Non
         )
         fid = FID()
         model = InceptionV3(normalize_input=normalize_input)
-        fid._compute_feats(loader, model, device='cpu')
+        fid.compute_feats(loader, model, device='cpu')

tests/test_msid.py

@@ -106,7 +106,7 @@ def test_compute_feats_cpu() -> None:
         )
         metric = MSID()
         model = InceptionV3()
-        metric._compute_feats(loader, model, device='cpu')
+        metric.compute_feats(loader, model, device='cpu')
     except Exception as e:
         pytest.fail(f"Unexpected error occurred: {e}")
 
@@ -122,6 +122,6 @@ def test_compute_feats_cuda() -> None:
         )
         metric = MSID()
         model = InceptionV3()
-        metric._compute_feats(loader, model, device='cuda')
+        metric.compute_feats(loader, model, device='cuda')
     except Exception as e:
         pytest.fail(f"Unexpected error occurred: {e}")