Switch on writing of VRTs by default

CHANGELOG.md

@@ -9,6 +9,7 @@ _When adding new entries to the changelog, please include issue/PR numbers where
 - Prevented committing local changes to linked datasets. [#953](https://github.com/koordinates/kart/pull/953)
 - Fixes a bug where even datasets marked as `--no-checkout` are checked out when the working copy is first created. [#954](https://github.com/koordinates/kart/pull/954)
 - Fixes a bug where minor changes to auxiliary metadata (.aux.xml) files that Kart is supposed to ignore were preventing branch changes. [#957](https://github.com/koordinates/kart/pull/957)
+- Enables VRT creation by default during raster dataset checkout. [#956](https://github.com/koordinates/kart/pull/956)
 
 ## 0.15.0
 

docs/pages/raster_datasets.rst

@@ -58,4 +58,4 @@ For technical reasons, raster tiles are stored within the repository using `Git
 
 VRT files
 ~~~~~~~~~
-Setting an environment variable ``KART_RASTER_VRTS=1`` when creating the Kart working copy or checking out a commit will cause Kart to create a `VRT <vrt_>`_ (Virtual Raster) file for each raster dataset. This single file comprises a mosaic of all the tiles in the working copy that belong to that dataset, so that if you load this file in your tile-editing software, you have effectively loaded the entire dataset. The individual tiles are referenced by the VRT, rather than the data from each tile being duplicated in the VRT. Creation of VRTs is still experimental but should become the default in a future version of Kart.
+When creating the working copy or checking out a commit, Kart will create a `VRT <vrt_>`_ (Virtual Raster) file for each raster dataset. This single file comprises a mosaic of all the tiles in the working copy that belong to that dataset, so that if you load this file in your tile-editing software, you have effectively loaded the entire dataset. The individual tiles are referenced by the VRT, rather than the data from each tile being duplicated in the VRT. To turn off the automatic creation of VRTs, set environment variable ``KART_RASTER_VRTS`` to ``0``.

kart/cli_util.py

@@ -424,3 +424,19 @@ def forward_context_to_command(ctx, command):
     subctx = command.make_context(command.name, ctx.unparsed_args)
     subctx.obj = ctx.obj
     subctx.forward(command)
+
+
+def get_bool_from_env(env_var_name, default=False):
+    """
+    Checks what the user has requested in terms of environment variables in the form:
+    SOME_FEATURE=YES or OTHER_FEATURE=0
+    - 0, N, NO, FALSE and OFF are falsey (case insensitive)
+    - every other string is truthy
+    - if the variable is unset, the default is returned.
+    """
+    env_var_val = os.environ.get(env_var_name)
+    if env_var_val is None:
+        return default
+    if env_var_val.upper() in ("0", "N", "NO", "FALSE", "OFF"):
+        return False
+    return True

kart/raster/mosaic_util.py

@@ -32,4 +32,9 @@ def write_vrt_for_directory(directory_path):
     del vrt
 
     vrt_text = vrt_path.read_text()
+    vrt_text = vrt_text.replace(
+        "</VRTDataset>",
+        '  <OverviewList resampling="average">2 4 8</OverviewList>\n</VRTDataset>',
+    )
+
     vrt_path.write_text(KART_VRT_HEADING + vrt_text)

kart/raster/v1.py

@@ -1,7 +1,7 @@
 import functools
-import os
 import re
 
+from kart.cli_util import get_bool_from_env
 from kart.core import all_blobs_in_tree
 from kart.diff_structs import DeltaDiff, Delta
 from kart.key_filters import FeatureKeyFilter
@@ -80,7 +80,7 @@ def convert_tile_to_format(cls, source_path, dest_path, target_format):
     def write_mosaic_for_directory(cls, directory_path):
         from kart.raster.mosaic_util import write_vrt_for_directory
 
-        if os.environ.get("KART_RASTER_VRTS"):
+        if get_bool_from_env("KART_RASTER_VRTS", default=True):
             write_vrt_for_directory(directory_path)
 
     @classmethod

tests/raster/test_workingcopy.py

@@ -731,8 +731,6 @@ def test_working_copy_conflicting_extension(cli_runner, data_archive):
 
 
 def test_working_copy_vrt(cli_runner, data_archive, monkeypatch):
-    monkeypatch.setenv("KART_RASTER_VRTS", "1")
-
     with data_archive("raster/elevation.tgz") as repo_path:
         vrt_path = repo_path / "elevation" / "elevation.vrt"
 
@@ -758,6 +756,8 @@ def test_working_copy_vrt(cli_runner, data_archive, monkeypatch):
 
 
 def test_working_copy_vrt_disabled(cli_runner, data_archive, monkeypatch):
+    monkeypatch.setenv("KART_RASTER_VRTS", "0")
+
     with data_archive("raster/elevation.tgz") as repo_path:
         shutil.rmtree(repo_path / "elevation")