From 7d5e87b8bed68322614499659301b8feadb10292 Mon Sep 17 00:00:00 2001 From: Saijin-Naib <19295950+Saijin-Naib@users.noreply.github.com> Date: Fri, 30 Jul 2021 17:08:46 -0400 Subject: [PATCH 1/6] Update build-overviews.rst This contains the core of what I'd like to add for each argument going forward. --- source/arguments_edit/build-overviews.rst | 54 ++++++++++++++++++++++- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/source/arguments_edit/build-overviews.rst b/source/arguments_edit/build-overviews.rst index 28585a73f..173b9d8af 100644 --- a/source/arguments_edit/build-overviews.rst +++ b/source/arguments_edit/build-overviews.rst @@ -1,2 +1,52 @@ -Overviews are an optimization that reduce the time it takes to -open GeoTIFF files, for the tradeoff of a larger filesize. \ No newline at end of file +---- + +| Parameter Type: ``Boolean`` +| Parameter Domain: +| True: --build-overviews +| False: `null` + +---- + +======== ======== +Resource Impact +======== ======== +CPU ░▓░ +GPU ░░░ +HDD ░▓░ +RAM ░▓░ +Time ░▓░ +======== ======== + +---- + +What Are Overviews? +------------------- +Overviews (sometimes referred to as pyramids) are an optimization that reduce the time it takes to render GeoTIFF files; Larger file-size is the tradeoff for this increased rendering performance. + +Overviews are lower-resoultion copies of the raster data (Power of two factor [128x128, 256x256, etc]) that are stored either internally or externally in a sidecar. + +In the case of OpenDroneMap, the Overviews will always be internal. + +When are Overviews appropriate? +------------------------------- +One would likely want to use Overviews for nearly every instance, with some few (relatively rare) exceptions. + + * Small File Size is paramount + * Reading software does not support internal Overviews + +Why would one use Overviews? +---------------------------- +Overviews speed preview of the raster data by allowing the program rendering the raster to choose the closest size pyramid to match the resolution of the display extent that it is being rendered into, potentially saving a significant amount of time retrieving the full-size raster, buffering it, and then downscaling it for display. + +In the case of WebODM, Overviews are used to create dynamic tiles for rapid display and navigation of the 2D web map. + +Example Images +-------------- + +True: --build-overviews +^^^^^^^^^^^^^^^^^^^^^^^ +.. image:: https://user-images.githubusercontent.com/19295950/127073339-6b2a0a4f-6ede-4dc1-8da4-5bc9646de304.png + +False: `null` +^^^^^^^^^^^^^ +.. image:: https://user-images.githubusercontent.com/19295950/127074349-a3f84c4c-d05c-4bf1-bd7c-790781ad0fe3.png From 4cb60a54eff6455b5efce8145bec5a7841c36cd6 Mon Sep 17 00:00:00 2001 From: Saijin-Naib <19295950+Saijin-Naib@users.noreply.github.com> Date: Fri, 30 Jul 2021 17:23:12 -0400 Subject: [PATCH 2/6] Small syntax update Switching from image to figure to take advantage of alt-text, captions, etc. --- source/arguments_edit/build-overviews.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/source/arguments_edit/build-overviews.rst b/source/arguments_edit/build-overviews.rst index 173b9d8af..33796f029 100644 --- a/source/arguments_edit/build-overviews.rst +++ b/source/arguments_edit/build-overviews.rst @@ -45,8 +45,14 @@ Example Images True: --build-overviews ^^^^^^^^^^^^^^^^^^^^^^^ -.. image:: https://user-images.githubusercontent.com/19295950/127073339-6b2a0a4f-6ede-4dc1-8da4-5bc9646de304.png +.. figure:: https://user-images.githubusercontent.com/19295950/127073339-6b2a0a4f-6ede-4dc1-8da4-5bc9646de304.png + :alt: QGIS displaying the generated Overviews + + The Layer Properties panel demonstrates that this OpenDroneMap-generated GeoTIFF has internal Overviews. False: `null` ^^^^^^^^^^^^^ -.. image:: https://user-images.githubusercontent.com/19295950/127074349-a3f84c4c-d05c-4bf1-bd7c-790781ad0fe3.png +.. figure:: https://user-images.githubusercontent.com/19295950/127074349-a3f84c4c-d05c-4bf1-bd7c-790781ad0fe3.png + :alt: QGIS displaying the file is lacking Overviews + + The Layer Properties panel demonstrates that this OpenDroneMap-generated GeoTIFF lacks internal Overviews. From 3291f0d8c6f8a96b0f3166ee4f94c574177f086c Mon Sep 17 00:00:00 2001 From: Saijin-Naib <19295950+Saijin-Naib@users.noreply.github.com> Date: Sat, 31 Jul 2021 01:59:53 -0400 Subject: [PATCH 3/6] Minor formatting update Small tweaks to ensure that things don't get ligatured. I have not found a way to colorize the symbol blocks yet. --- source/arguments_edit/build-overviews.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/source/arguments_edit/build-overviews.rst b/source/arguments_edit/build-overviews.rst index 33796f029..e59ee70c6 100644 --- a/source/arguments_edit/build-overviews.rst +++ b/source/arguments_edit/build-overviews.rst @@ -1,9 +1,10 @@ ---- -| Parameter Type: ``Boolean`` +| Parameter Type: +| **Boolean** | Parameter Domain: -| True: --build-overviews -| False: `null` +| True: ``--build-overviews`` +| False: ``null`` ---- @@ -43,14 +44,14 @@ In the case of WebODM, Overviews are used to create dynamic tiles for rapid disp Example Images -------------- -True: --build-overviews +True: ``--build-overviews`` ^^^^^^^^^^^^^^^^^^^^^^^ .. figure:: https://user-images.githubusercontent.com/19295950/127073339-6b2a0a4f-6ede-4dc1-8da4-5bc9646de304.png :alt: QGIS displaying the generated Overviews The Layer Properties panel demonstrates that this OpenDroneMap-generated GeoTIFF has internal Overviews. -False: `null` +False: ``null`` ^^^^^^^^^^^^^ .. figure:: https://user-images.githubusercontent.com/19295950/127074349-a3f84c4c-d05c-4bf1-bd7c-790781ad0fe3.png :alt: QGIS displaying the file is lacking Overviews From 7412eb1a4b003f369d167b8d515f939745c3e896 Mon Sep 17 00:00:00 2001 From: Piero Toffanin Date: Sat, 31 Jul 2021 09:52:05 -0400 Subject: [PATCH 4/6] Fix warnings --- source/arguments_edit/build-overviews.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/arguments_edit/build-overviews.rst b/source/arguments_edit/build-overviews.rst index e59ee70c6..b4c51963f 100644 --- a/source/arguments_edit/build-overviews.rst +++ b/source/arguments_edit/build-overviews.rst @@ -1,5 +1,3 @@ ----- - | Parameter Type: | **Boolean** | Parameter Domain: @@ -45,14 +43,14 @@ Example Images -------------- True: ``--build-overviews`` -^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. figure:: https://user-images.githubusercontent.com/19295950/127073339-6b2a0a4f-6ede-4dc1-8da4-5bc9646de304.png :alt: QGIS displaying the generated Overviews The Layer Properties panel demonstrates that this OpenDroneMap-generated GeoTIFF has internal Overviews. False: ``null`` -^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^ .. figure:: https://user-images.githubusercontent.com/19295950/127074349-a3f84c4c-d05c-4bf1-bd7c-790781ad0fe3.png :alt: QGIS displaying the file is lacking Overviews From 15b9d366416864a77fea9428356b2e5e9845b243 Mon Sep 17 00:00:00 2001 From: Saijin-Naib <19295950+Saijin-Naib@users.noreply.github.com> Date: Sat, 31 Jul 2021 20:48:01 -0400 Subject: [PATCH 5/6] Possible compromise? Possible compromise for now? I still like the idea of a graphical representation as that works best for me at a quick glance, but I definitely agree with the issues noted above in regards to readability of the impact glyphs in different fontsets, as well as the possibility of issues with regards to translation across different langauges, which a text legend absolutely aids. I think I might need to create custom "roles" to colorize the graph, and/or investigate other glyphs entirely which may hopefully render much nicer. --- source/arguments_edit/build-overviews.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/arguments_edit/build-overviews.rst b/source/arguments_edit/build-overviews.rst index b4c51963f..025d665b6 100644 --- a/source/arguments_edit/build-overviews.rst +++ b/source/arguments_edit/build-overviews.rst @@ -9,11 +9,11 @@ ======== ======== Resource Impact ======== ======== -CPU ░▓░ -GPU ░░░ -HDD ░▓░ -RAM ░▓░ -Time ░▓░ +CPU ░▓░ | Medium +GPU ░░░ | None +HDD ░▓░ | Medium +RAM ░▓░ | Medium +Time ░▓░ | Medium ======== ======== ---- From 508792e0b1ffcc4e318213476f49684e1dac1c8f Mon Sep 17 00:00:00 2001 From: Saijin-Naib <19295950+Saijin-Naib@users.noreply.github.com> Date: Sat, 31 Jul 2021 21:10:17 -0400 Subject: [PATCH 6/6] Potential new style Wife suggested empty/filled circles like a linear LED display. I think this reads nicely, and hopefully, once I figure out color roles, will be even stronger of a quick visual indicator. --- source/arguments_edit/build-overviews.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/arguments_edit/build-overviews.rst b/source/arguments_edit/build-overviews.rst index 025d665b6..bbaf86a3a 100644 --- a/source/arguments_edit/build-overviews.rst +++ b/source/arguments_edit/build-overviews.rst @@ -9,11 +9,11 @@ ======== ======== Resource Impact ======== ======== -CPU ░▓░ | Medium -GPU ░░░ | None -HDD ░▓░ | Medium -RAM ░▓░ | Medium -Time ░▓░ | Medium +CPU ●●○ | Medium +GPU ○○○ | None +HDD ●●○ | Medium +RAM ●●○ | Medium +Time ●●○ | Medium ======== ======== ----