Skip to content

titan.gdal_utils

Utility functions to make it easier to work with gdal in python.

ProgressBar

Bases: tqdm

Source code in titan/gdal_utils.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class ProgressBar(tqdm):
    def __init__(
        self,
        desc: str = "GDAL",
        unit: str = "%",
        total: int = 100,
        bar_format: str = "{l_bar}{bar:25}{r_bar}{bar:-25b}",
        **kwargs,
    ) -> object:
        """Extension of tqdm progress bars for tracking `gdal` progress via callbacks.

        This class is used in conjunction with the `utils.gdal_callback()` function.

        Args:
            desc: progress bar label.
            unit: unit of progress reported by the callback.
            total: total number of iterations to report.
            bar_format: string format for the progress bar.
            **kwargs: any other keyword argument passsed to a tqdm() object.

        Returns:
            self: a `tqdm` progress bar object.
        """
        super().__init__(desc=desc, unit=unit, total=total, bar_format=bar_format, **kwargs)

    def update_to(self, current, total=100):
        self.total = total
        self.update(current - self.n)

__init__(desc='GDAL', unit='%', total=100, bar_format='{l_bar}{bar:25}{r_bar}{bar:-25b}', **kwargs)

Extension of tqdm progress bars for tracking gdal progress via callbacks.

This class is used in conjunction with the utils.gdal_callback() function.

Parameters:

Name Type Description Default
desc str

progress bar label.

 'GDAL'
unit str

unit of progress reported by the callback.

 '%'
total int

total number of iterations to report.

 100
bar_format str

string format for the progress bar.

 '{l_bar}{bar:25}{r_bar}{bar:-25b}'
**kwargs

any other keyword argument passsed to a tqdm() object.

 {}

Returns:

Name Type Description
self object

a tqdm progress bar object.
Source code in titan/gdal_utils.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def __init__(
    self,
    desc: str = "GDAL",
    unit: str = "%",
    total: int = 100,
    bar_format: str = "{l_bar}{bar:25}{r_bar}{bar:-25b}",
    **kwargs,
) -> object:
    """Extension of tqdm progress bars for tracking `gdal` progress via callbacks.

    This class is used in conjunction with the `utils.gdal_callback()` function.

    Args:
        desc: progress bar label.
        unit: unit of progress reported by the callback.
        total: total number of iterations to report.
        bar_format: string format for the progress bar.
        **kwargs: any other keyword argument passsed to a tqdm() object.

    Returns:
        self: a `tqdm` progress bar object.
    """
    super().__init__(desc=desc, unit=unit, total=total, bar_format=bar_format, **kwargs)

Callback(complete, message, progress_bar)

A callback to pass to functions like gdal.Warp() in order to track progress.

Parameters:

Name Type Description Default
complete float

the 0.0-1.0 percent complete reported by gdal's C++ callback.

 required
message str

status message reported by gdal's C++ callback.

 required
progress_bar object

a gdal_utils.ProgressBar() tqdm tracker.

 required

Returns:

Type Description
None

None. Updates the progress_bar object.
Source code in titan/gdal_utils.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
def Callback(complete: float, message: str, progress_bar: object) -> None:
    """A callback to pass to functions like gdal.Warp() in order to track progress.

    Args:
        complete: the 0.0-1.0 percent complete reported by gdal's C++ callback.
        message: status message reported by gdal's C++ callback.
        progress_bar: a gdal_utils.ProgressBar() tqdm tracker.

    Returns:
        None. Updates the `progress_bar` object.
    """
    pct = int(complete * 100)
    progress_bar.update_to(pct, 100)

get_creation_options(file_path)

Reads gdal-format creation options from a raster dataset.

Parameters:

Name Type Description Default
file_path str

the input file to check.

 required

Returns:

Type Description
dict

a dictionary of raster file creation options.
Source code in titan/gdal_utils.py 
154
155
156
157
158
159
160
161
162
163
164
165
166
167
def get_creation_options(file_path: str) -> dict:
    """Reads gdal-format creation options from a raster dataset.

    Args:
        file_path: the input file to check.

    Returns:
        a dictionary of raster file creation options.
    """
    ref = gdal.Open(file_path, gdal.GA_ReadOnly)
    creation_options = ref.GetMetadata("IMAGE_STRUCTURE")
    ref = None

    return creation_options

get_data_type_name(data_type_int)

Cross-references a data type integer to it's corresponding string ID.

When reading a dataset with ref = gdal.Open(), you can get the data type of a file with ref.GetRasterBand(1).DataType. These are opaque gdal integer references. This function returns the name of the data type.

Parameters:

Name Type Description Default
data_type_int int

a gdal.GDT_* integer reference.

 required

Returns:

Name Type Description
data_type_name str

the corresponding gdal data type string.
Source code in titan/gdal_utils.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def get_data_type_name(data_type_int: int) -> str:
    """Cross-references a data type integer to it's corresponding string ID.

    When reading a dataset with `ref = gdal.Open()`, you can get the data type of a
        file with `ref.GetRasterBand(1).DataType`. These are opaque gdal integer
        references. This function returns the name of the data type.

    Args:
        data_type_int: a gdal.GDT_* integer reference.

    Returns:
        data_type_name: the corresponding gdal data type string.
    """
    data_type_name = gdal.GetDataTypeName(data_type_int)

    return data_type_name

get_data_type_number(data_type_name)

Cross-references a data type string to it's gdal.GDT_* number.

In functions like gdal.Warp(), gdal requires data types be passed according to their internal data type integer format. These are represented as variables like gdal.GDT_Float32 (which is 6). This function returns the appropriate integer type based on passing a data type string (e.g. "Float32").

Parameters:

Name Type Description Default
data_type_name str

a data type string. available options from list_data_type_names()

 required

Returns:

Name Type Description
data_type_int int

the corresponding gdal data type integer.
Source code in titan/gdal_utils.py 
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def get_data_type_number(data_type_name: str) -> int:
    """Cross-references a data type string to it's `gdal.GDT_*` number.

    In functions like `gdal.Warp()`, gdal requires data types be passed according to
        their internal data type integer format. These are represented as variables
        like `gdal.GDT_Float32` (which is `6`). This function returns the appropriate
        integer type based on passing a data type string (e.g. "Float32").

    Args:
        data_type_name: a data type string. available options from list_data_type_names()

    Returns:
        data_type_int: the corresponding gdal data type integer.
    """
    available_types = list_data_type_names()
    assert data_type_name in available_types, f"Invalid data type. Options are: {', '.join(available_types)}"

    data_type_int = gdal.GetDataTypeByName(data_type_name)

    return data_type_int

list_data_type_names()

Returns a list of available GDAL data types by name.

Returns:

Name Type Description
data_types list

list of gdal data type names.
Source code in titan/gdal_utils.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def list_data_type_names() -> list:
    """Returns a list of available GDAL data types by name.

    Returns:
        data_types: list of gdal data type names.
    """
    data_types = []
    for code in range(20):
        try:
            data_types.append(gdal.GetDataTypeName(code))
        except ValueError:
            continue
    data_types.sort()

    return data_types

list_driver_names()

Returns a list of available GDAL drivers by name.

Returns:

Name Type Description
drivers list

list of gdal driver formats.
Source code in titan/gdal_utils.py 
52
53
54
55
56
57
58
59
60
61
def list_driver_names() -> list:
    """Returns a list of available GDAL drivers by name.

    Returns:
        drivers: list of gdal driver formats.
    """
    drivers = [gdal.GetDriver(i).GetDescription() for i in range(gdal.GetDriverCount())]
    drivers.sort()

    return drivers

list_resampling_names()

Returns a list of avaialble resampling options.

Returns:

Name Type Description
resampling list

list of gdal resampling options.
Source code in titan/gdal_utils.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def list_resampling_names() -> list:
    """Returns a list of avaialble resampling options.

    Returns:
        resampling: list of gdal resampling options.
    """
    # set options based on the installed version
    major, minor, sub = gdal.__version__.split(".")

    resampling = [
        "near",
        "bilinear",
        "cubic",
        "cubicspline",
        "lanczos",
        "average",
        "mode",
        "max",
        "min",
        "med",
        "q1",
        "q3",
    ]

    if int(major) >= 3 and int(minor) >= 1:
        resampling.append("sum")

    if int(major) >= 3 and int(minor) >= 3:
        resampling.append("rms")

    return resampling