diff --git a/docs/docs/API.md b/docs/docs/API.md index 50b1181..2d2be1f 100644 --- a/docs/docs/API.md +++ b/docs/docs/API.md @@ -107,3 +107,48 @@ with MemoryFile() as mem_dst: client = boto3_session.client("s3") client.upload_fileobj(mem_dst, "my-bucket", "my-key") ``` + +3. Output Progress to Alternative Text Buffer + +Use Case: You may want to run your translation tasks in the background and keep +track of progress. To do so you can utilize an alternative text buffer and another +thread. By outputting the progress to a seperate text buffer you can then track +the translation progress without blocking the program. +```python +from rio_cogeo.cogeo import cog_translate +from rio_cogeo.profiles import cog_profiles + +config = { + "GDAL_NUM_THREADS": "ALL_CPUS", + "GDAL_TIFF_INTERNAL_MASK": True, + "GDAL_TIFF_OVR_BLOCKSIZE": "128", +} + + +with open("logfile.txt", "w+") as buffer: + + # Progress output buffer must be interactive + buffer.isatty = lambda: True + + cog_translate( + "example-input.tif", + "example-output.tif", + cog_profiles.get("deflate"), + config=config, + in_memory=False, + nodata=0, + quiet=False, + progress_out=buffer, + ) +``` + +Below is a snippet of code that allows you to grab the percentage complete a +translation is using the text buffer. + +```python +import re + +def getPercentage(buffer:str) -> float: + return int(re.findall("\d*%", buffer)[-1].replace("%", "")) / 100 +``` + diff --git a/rio_cogeo/cogeo.py b/rio_cogeo/cogeo.py index 5465cdf..670a10f 100644 --- a/rio_cogeo/cogeo.py +++ b/rio_cogeo/cogeo.py @@ -6,7 +6,7 @@ import tempfile import warnings from contextlib import ExitStack, contextmanager -from typing import Any, Dict, List, Literal, Optional, Sequence, Tuple, Union +from typing import Any, Dict, List, Literal, Optional, Sequence, TextIO, Tuple, Union import click import morecantile @@ -93,6 +93,7 @@ def cog_translate( # noqa: C901 forward_band_tags: bool = False, forward_ns_tags: bool = False, quiet: bool = False, + progress_out: Optional[TextIO] = None, temporary_compression: str = "DEFLATE", colormap: Optional[Dict] = None, additional_cog_metadata: Optional[Dict] = None, @@ -155,6 +156,8 @@ def cog_translate( # noqa: C901 Forward namespaces tags to output dataset. quiet: bool, optional (default: False) Mask processing steps. + progress_out: TextIO, optional + Output progress steps to alternative text buffer. Quiet must be False. temporary_compression: str, optional Compression used for the intermediate file, default is deflate. colormap: dict, optional @@ -302,6 +305,9 @@ def cog_translate( # noqa: C901 click.echo("Reading input: {}".format(source), err=True) fout = ctx.enter_context(open(os.devnull, "w")) if quiet else sys.stderr + if quiet is False and progress_out: + fout = progress_out + with click.progressbar(wind, file=fout, show_percent=True) as windows: # type: ignore for _, w in windows: matrix = vrt_dst.read(window=w, indexes=indexes)