Merge pull request #105 from adl1995/progress_bar

Add progress bar support for fetching and drawing HiPS tiles

.travis.yml

@@ -27,7 +27,7 @@ env:
         - MAIN_CMD='python setup.py'
         - SETUP_CMD='test'
         - EVENT_TYPE='pull_request push'
-        - CONDA_DEPENDENCIES='healpy scikit-image Pillow reproject matplotlib'
+        - CONDA_DEPENDENCIES='healpy scikit-image Pillow reproject matplotlib tqdm'
         - PIP_DEPENDENCIES=''
         - CONDA_CHANNELS='conda-forge astropy-ci-extras astropy'
         - SETUP_XVFB=True

docs/getting_started.rst

@@ -33,7 +33,10 @@ To draw a sky image from HiPS image tiles with the `hips` package, follow the fo
     hips_survey = 'CDS/P/DSS2/red'
 
 3. Call the `~hips.make_sky_image` function to fetch the HiPS data
-   and draw it, returning an object of `~hips.HipsDrawResult`::
+   and draw it, returning an object of `~hips.HipsDrawResult`.
+   By default a progress bar is shown for fetching and
+   drawing HiPS tiles. For batch processing, this can be
+   turned off by passing a keyword argument: `progress_bar=False`::
 
     from hips import make_sky_image
     result = make_sky_image(geometry, hips_survey, 'fits')

docs/installation.rst

@@ -79,5 +79,6 @@ The ``hips`` package has the following requirements:
 In addition, the following packages are needed for optional functionality:
 
 * `Matplotlib`_ 2.0 or later. Used for plotting in examples.
+* `tqdm`_ 4.15 or later. Used for showing progress bar either on terminal or in Jupyter notebook.
 
 We have some info at :ref:`py3` on why we don't support legacy Python (Python 2).

docs/references.txt

@@ -5,4 +5,5 @@
 .. _Pillow: https://python-pillow.org/
 .. _HiPS paper: https://www.aanda.org/articles/aa/pdf/2015/06/aa26075-15.pdf
 .. _HiPS IVOA recommendation: http://www.ivoa.net/documents/HiPS/
-.. _HiPS at CDS: http://aladin.u-strasbg.fr/hips/
+.. _HiPS at CDS: http://aladin.u-strasbg.fr/hips/
+.. _tqdm: https://pypi.python.org/pypi/tqdm

hips/draw/paint.py

@@ -34,6 +34,8 @@ class HipsPainter:
         Format of HiPS tile
     precise : bool
         Use the precise drawing algorithm
+    progress_bar : bool
+        Show a progress bar for tile fetching and drawing
 
     Examples
     --------
@@ -56,11 +58,13 @@ class HipsPainter:
     (1000, 2000)
     """
 
-    def __init__(self, geometry: Union[dict, WCSGeometry], hips_survey: Union[str, HipsSurveyProperties], tile_format: str, precise: bool = False) -> None:
+    def __init__(self, geometry: Union[dict, WCSGeometry], hips_survey: Union[str, HipsSurveyProperties],
+                 tile_format: str, precise: bool = False, progress_bar: bool = True) -> None:
         self.geometry = WCSGeometry.make(geometry)
         self.hips_survey = HipsSurveyProperties.make(hips_survey)
         self.tile_format = tile_format
         self.precise = precise
+        self.progress_bar = progress_bar
         self._tiles = None
         self.float_image = None
         self._stats: Dict[str, Any] = {}
@@ -107,7 +111,13 @@ def projection(self, tile: HipsTile) -> ProjectiveTransform:
 
     def _fetch_tiles(self) -> Iterator[HipsTile]:
         """Generator function to fetch HiPS tiles from a remote URL."""
-        for healpix_pixel_index in self.tile_indices:
+        if self.progress_bar:
+            from tqdm import tqdm
+            tile_indices = tqdm(self.tile_indices, desc='Fetching tiles')
+        else:
+            tile_indices = self.tile_indices
+
+        for healpix_pixel_index in tile_indices:
             tile_meta = HipsTileMeta(
                 order=self.draw_hips_order,
                 ipix=healpix_pixel_index,
@@ -121,12 +131,6 @@ def _fetch_tiles(self) -> Iterator[HipsTile]:
     @property
     def tiles(self) -> List[HipsTile]:
         """List of `~hips.HipsTile` (cached on multiple access)."""
-        # TODO: add progress bar reporting here???
-        # Do it in a separate pull request
-        # It has to work in the terminal and Jupyter notebook
-        # Users have to be able to turn it off
-        # So you have an option for it.
-        # Maybe if you add it now, make it off by default.
         if self._tiles is None:
             self._tiles = list(self._fetch_tiles())
 
@@ -159,6 +163,7 @@ def run(self) -> np.ndarray:
             self._stats['consumed_memory'] += len(tile.raw_data)
 
 
+
     def make_tile_list(self):
         parent_tiles = self.tiles
 
@@ -189,10 +194,13 @@ def _make_empty_sky_image(self):
     def draw_all_tiles(self):
         """Make an empty sky image and draw all the tiles."""
         image = self._make_empty_sky_image()
+        if self.progress_bar:
+            from tqdm import tqdm
+            tiles = tqdm(self.draw_tiles, desc='Drawing tiles')
+        else:
+            tiles = self.draw_tiles
 
-        # TODO: this is the second place where we should add
-        # progress reporting
-        for tile in self.draw_tiles:
+        for tile in tiles:
             tile_image = self.warp_image(tile)
             # TODO: put better algorithm here instead of summing pixels
             # this can lead to pixels that are painted twice and become to bright

hips/draw/ui.py

@@ -15,7 +15,7 @@
 
 
 def make_sky_image(geometry: Union[dict, WCSGeometry], hips_survey: Union[str, 'HipsSurveyProperties'],
-                   tile_format: str, precise: bool = False) -> 'HipsDrawResult':
+                   tile_format: str, precise: bool = False, progress_bar: bool = True) -> 'HipsDrawResult':
     """Make sky image: fetch tiles and draw.
 
     The example for this can be found on the :ref:`gs` page.
@@ -31,13 +31,15 @@ def make_sky_image(geometry: Union[dict, WCSGeometry], hips_survey: Union[str, '
         (some surveys are available in several formats, so this extra argument is needed)
     precise : bool
         Use the precise drawing algorithm
+    progress_bar : bool
+        Show a progress bar for tile fetching and drawing
 
     Returns
     -------
     result : `~hips.HipsDrawResult`
         Result object
     """
-    painter = HipsPainter(geometry, hips_survey, tile_format, precise)
+    painter = HipsPainter(geometry, hips_survey, tile_format, precise, progress_bar)
     painter.run()
     return HipsDrawResult.from_painter(painter)
 

setup.py

@@ -105,13 +105,16 @@
 extras_require = dict(
     recommended=[
         'matplotlib>=2.0',
+
+        'tqdm>=4.15',
         'reproject>=0.3.1',
     ],
     develop=[
         'matplotlib>=2.0',
         'reproject>=0.3.1',
         'pytest>=3.0',
         'mypy>=0.501',
+        'tqdm>=4.15',
     ],
 )