Набор растровых инструментов

Зависимости:

• numpy
• gdal

Установка:

При наличии gdal и numpy развёрнутый из git код может сразу локально использоваться

Для установки при помощи pip:

pip install git+https://github.com/oldbay/raster_tools

Для установки в gentoo linux представлен:

ebuild сценарий raster-tools-999.ebuild

Для создания пакета для debian linux представлен:

debian сценарий

Инструментарий представлен:

До версии 0.3 в raster_tools был включён растровый калькулятор. Начиная с версии 0.4 растровый калькулятор вынесен в отдельный проект raster_calc (https://github.com/oldbay/raster_calc)

Классы:

• raster2array - преобразования растра в массив(базовый класс).
• array2raster - преобразования вычисленного массива в растр.
• raster2transform - трансформация моноканального растра: изменение размеренности массива, географическая привязка
• raster2calc - растровых вычислений в режиме итерации (для экономии памяти)
• raster2multiarray - создания стандарного словаря для мультирастра с возможностью его обработки в OpenCV
• multiraster2transform - трансформация мультиканального растра: изменение размеренности массива, географическая привязка
• raster2multiraster - преобразования одноканальных растров в мультиканальный
• multiarray2multiraster - преобразования стандарного словаря мультирастра в мультиканальный растр.
• repair2reload - исправления "перевёрнутых растров"

применение:

Class raster2array

Класс преобразования георастра в numpy массив и операций с данным массивом. Данный класс является базовым и наследуется array2raster и raster2transform, а raster2calc и raster2multiarray обрабатывают некоторые методы raster2array через декоратор.

Аргументы принимаемые классом при инициализации:

1. (fname) - имя файла
2. (band) - канал (band) многослойного георастра (по умолчанию = 1)

Переменные по умолчанию установленне для класса:

• stdict_div = (False/Int делитель растра) - устанавливает возможность возврата растра итерационно сегментами по делителю
• codage = (тип numpy массива) - устанавливает тип numpy массива возвращаемого методами класса (numpy.float64 по умолчанию).
• scale = использование шкалы для распеделения точек растра False(default) - не использовать, True - использовать стандартную, list или tuple - использовать свою шкалу (min, max)
• nodata = установить занвчение "нет данных" для растра, по умолчанию None - берётся значение nodata из загружаемого растра.

Некоторые методы array2raster возвращают геоданные в виде стандартного словаря следующего формата:

{
    "array": numpy.array(),
    "shape": (gdal.dataset.RasterYSize()=rows, gdal.dataset.RasterXSize()=cols)=np.ndarray.shape,
    "transform": gdal.dataset.GetGeoTransform(),
    "projection": gdal.dataset.GetProjection(),
}

Данный словарь можно передавать классу array2raster для преобразования в георастр.

Примеры работы с методами raster2array:

from raster_tools import raster2array

# загрузка файла георастра в объект класса(выбран band №1, он же по умолчанию):
band_number = 1
filename = "georaster.tif"
raster = raster2array(filename, band_number)

# получение екстента растра в указанной проекции:
raster.get_raster_extent()# вернёт экстент в текущей проекции, в виде списка координат полигона
raster.get_raster_extent(4326,"json")# экстент в EPSG:4326, в формате geojson

# получение площади растра(или пикселя) в пересчёте c geodetic distance на сфероиде WGS84
raster.get_wgs84_area()# вернёт площадь в квадратных метрах всего экстента растра
raster.get_wgs84_area(pixel=True)# вернёт площадь пикселя в квадратных метрах

# выгрузка всего numpy массива или "стандартного словаря" из георастра:
array = raster.array() # вывод метода в формате numpy массива
array = raster.get_std_dict() # вывод метода в формате "стандартного словаря"

# выгрузка части массива numpy или "стандартного словаря" георастра ограниченного по индексу:
x_index = 10 # индекс исходной точки массива по оси Х
y_index = 10 # индекс исходной точки массива по оси Y
x_axis = 100 # количество значений в срезе массива по оси X
y_axis = 200 # количество значений в срезе массива по оси Y
array = raster.array(x_index, y_index, x_axis, y_axis) # вывод метода в формате numpy массива
array = raster.get_std_dict(x_index, y_index, x_axis, y_axis) # вывод метода в формате "стандартного словаря"

# преобразование географических координат георастра в значения индекса numpy массива:
# (координаты вводятся в корректных значениях для проекции текущего георастра)
x = 295932.856017917
y = 7137808.56469495
x_index, y_index = raster.get_coord_index(x, y) # вывод метода в формате кортежа

# преобразование индекса numpy массива в географические координаты данного георастра:
# (координаты вводятся в корректных значениях для проекции текущего георастра)
x_index = 100
y_index = 100
x, y = raster.get_index_coord(x_index, y_index) # вывод метода в формате кортежа

# возврат значения яркости пикселя георастра по координатам:
x = 295932.856017917
y = 7137808.56469495
pixel = raster.get_pixel_value(x, y) # вывод метода в формате float

# вырезать из георастра прямоугольный numpy массив ограниченный координатами:
# (коодинаты вводятся либо отдельными кортежами (x1, y1), (x2, y2), .. (xn, yn),
# либо списком кортежей [(x1, y1), (x2, y2), .. (xn, yn)] )
coords = [
            (295932.856017917, 7137808.56469495),
            (295932.856017917, 7137808.43615462),
            (295932.727479474, 7137808.43615462)
         ]
cut_area = raster.cut_area(coords) # вывод метода в формате "стандартного словаря"

# обрезать прямоугольный numpy массив георастра по геометрии полигона(нов) векторного слоя:
shpfile = ogr.Open("vector.shp")
layer = shpfile.GetLayerByIndex(0)
cut_area = raster.cut_shp_layer(layer) # вывод метода в формате "стандартного словаря"

# обрезать прямоугольный numpy массив георастра по геометрии полигона(нов) shp файла:
# примечание - если проекция shape файла отличается от растра, то лучше указать её отдельно (желательно в формате EPSG кода)
# иначе перепроецирование геометрии по проекции из prj файла может быть некорректным
shpfile = "vector.shp"
layer_index = 0 # указать номер слоя или 0 по умолчанию
cut_area = raster.cut_shp_file(shpfile, layer_index, 4326) # вывод метода в формате "стандартного словаря"

# обрезать прямоугольный numpy массив георастра на основании геометрии полигона в одном из форматов(wkt, geojson, gml, wkb):
# Привечание 1: передачу нескольких полигонов нужно производить в списке, один - можно строкой
# Примечание 2: если проекция геометрий отличается от проекции растра, её необходимо указать третим параметром cut_ogr_geometry
geom = "POLYGON((295932.856017917 7137808.56469495, .. ,295932.856017917 7137808.56469495))"
format_geom = "wkt" # по умочанию wkt - возврат postgis функции ST_AsText()
cut_area = raster.cut_ogr_geometry(geom, format_geom) # вывод метода в формате "стандартного словаря"

# проверка растра на "валидность" - нормальную ориентацию numpy массива в пространстве:
#(верх - север, низ -юг, право - восток, лева - запад)
validate = raster.is_valid() # вывод метода в формате списка из 2-х логических значений:
                             # [<True/False - по оси х>, <True/False - по оси y>]

# валидизация(ремонт) растра на основании вывода метода is_valid
valid_output = raster.repair() # вывод метода в формате "стандартного словаря"

# Прочие методы:
raster.np_array_load() # загрузка всего numpy массива растра в экземпляр класса (ускорение работы некоторых методов + загрузка памяти)
raster.np_array_clean() # очистка экземпляра класса от массива (освобождение памяти)

Class array2raster(raster2array)

Класс преобразования numpy массива или "стандартного словаря" ,сформированного некоторыми методами raster2array, в георастр. Данный класс наследуется от raster2array.

аргументы принимаемые классом при инициализации:

1. (raster) - объект экземпляра класса raster2array или None (если вторым аргументом класс принимает "стандартный словарь")
2. (array) - numpy массив (если первый аргумент объект экземпляра класса raster2array) или "стандартный словарь"
3. (fname) - имя файла георастра или False (по умолчанию - тогда растр создастся в памяти)
4. (band) - номер канала band (по умолчанию 1)

Переменные по умолчанию установленне для класса:

• drvname = драйвер георастра (доступны GTiff и MEM - по умолчанию False это GTiff для файла и MEM для памяти)
• overviews = создание пирамид, значения: None(без пирамид - поумолчанию), True - стандартные пирамиды ("NEAREST", [2,4,8,16,32,64]), tuple или list - задать свои значения ("<тип>", [<список значений>])

Примеры использования array2raster:

# загрузка файла георастра в объект класса raster2array:
inputname = "inraster.tif"
raster = raster2array(inputname)


# 1-й метод передачи аргументов классу array2raster
# (применяется для записи растра после трансформирующих методов raster2array)

# преобразование исходного георастра(валидизация в качестве примера):
valid_output = raster.repair()

# сохранение получившегося в результате валидизации "стандартного словаря" в георастер
outputname = "valid.tif"
raster = raster2array(None, valid_output, outputname)

# 2-й метод передачи аргументов классу array2raster
# (применяется в растровых калькуляторах - без трансформации исходного растра)

# получение numpy массива загруженного георастра
np_array = raster.array()

# преобразование масива (обнуление значений меньших или равных 10)
import numpy as np
np_array = np.where(np_array>10, np_array, 0)

# сохранение получившегося в результате валидизации "стандартного словаря" в георастер
outputname = "calc.tif"
raster = raster2array(raster, np_array, outputname)

Class raster2transform(raster2array)

Класс трансформации моноканального растра: изменение размеренности массива, географическая привязка. Данный класс наследуется от raster2array.

аргументы принимаемые классом при инициализации:

1. (_input) - стандартный словарь/имя растрового файла/объект класса raster2array и его субклассы
2. (_rows) - количество строк нового массива
3. (_cols) - количество колонок нового массива
4. (_proj) - None без перепроецирования или проекция для перепроецирования (формат Wkt или EPSG).

Переменные по умолчанию установленне для класса:

• warp_resampling = метод перепроецирования растров, по умолчанию: gdal.GRA_NearestNeighbour (как у утилиты gdal_warp)
• warp_error_threshold = значание ошибки перепроецирования, по умолчанию: 0.125 (как у утилиты gdal_warp)
• drvname = драйвер георастра (доступны GTiff и MEM - по умолчанию False это GTiff для файла и MEM для памяти)
• overviews = создание пирамид, значения: None(без пирамид - поумолчанию), True - стандартные пирамиды ("NEAREST", [2,4,8,16,32,64]), tuple или list - задать свои значения ("<тип>", [<список значений>])

Примеры использования raster2transform:

from raster_tools import raster2array, raster2transform
from matplotlib import pyplot as plt

in_raster = "input.tif"
out_raster = "output.tif"

_in = in_raster

# трансформация массва растра в shape(455, 314)
_in = raster2transform(_in, 455, 314)
_in.transform()

# Привязка и перепривязка растра

# привязка георастра по координатами:
# (коодинаты вводятся либо отдельными кортежами (x1, y1), (x2, y2), .. (xn, yn),
# либо списком кортежей [(x1, y1), (x2, y2), .. (xn, yn)] )
coords = [
            (295932.856017917, 7137808.56469495),
            (295932.856017917, 7137808.43615462),
            (295932.727479474, 7137808.43615462)
         ]
_in.transform(*coords) # вывод метода в формате "стандартного словаря"

# привязка георастра по геометрии полигона(нов) векторного слоя:
shpfile = ogr.Open("vector.shp")
layer = shpfile.GetLayerByIndex(0)
_in.transform_shp_layer(layer) # вывод метода в формате "стандартного словаря"

# привязка георастра по геометрии полигона(нов) shp файла:
# примечание - если проекция shape файла отличается от растра, то лучше указать её отдельно (желательно в формате EPSG кода)
# иначе перепроецирование геометрии по проекции из prj файла может быть некорректным
shpfile = "vector.shp"
layer_index = 0 # указать номер слоя или 0 по умолчанию
_in.transform_shp_file(shpfile, layer_index, 4326) # вывод метода в формате "стандартного словаря"

# привязка георастра на основании геометрии полигона в одном из форматов(wkt, geojson, gml, wkb):
# Привечание 1: передачу нескольких полигонов нужно производить в списке, один - можно строкой
# Примечание 2: если проекция геометрий отличается от проекции растра, её необходимо указать третим параметром transform_ogr_geometry
geom = "POLYGON((295932.856017917 7137808.56469495, .. ,295932.856017917 7137808.56469495))"
format_geom = "wkt" # по умочанию wkt - возврат postgis функции ST_AsText()
_in.transform_ogr_geometry(geom, format_geom) # вывод метода в формате "стандартного словаря"


# сохранение трансформированного растра
_in.save(out_raster)

Пример изменения размерности массива растра в "examples/resize.py"

Class raster2calc

Класс растровых вычислений в режиме итерации (для экономии памяти). Данный класс через декораторы использует методы raster2array.

аргументы принимаемые классом при инициализации:

1. (div) - значение делителя вычисляемых растров во вертикали и горизонтали (по усолчанию 100)

Примеры использования raster2calc:

from raster_tools import raster2array, array2raster, raster2calc

"""
Загрузка каналов мультирастра в объекты raster2array
можно загружать стандартый словарь или по имени растрового файла.
Загруженные растры должны иметь одинаковую размерность массива.
"""
in_file = "multi.tif"
red = raster2array(in_file, 1)
green = raster2array(in_file, 2)
blue = raster2array(in_file, 3)

"""
Создание формулы итерационного вычисления через lambda
переменные объявленные в lambda должны быть переданы в любой из методов:
get_std_dict(по умолчанию), cut_area, cut_shp_layer, cut_shp_file, cut_ogr_geometry
класса raster2calc
"""
calc_func = lambda r,g,b: (r - b) * r

# инициализация объекта со значением делителя = 50
calc = raster2calc(50)

# запуск процесса итерационных вычислений для функции calc_func в методе get_std_dict
out = calc.get_std_dict(
        calc_func,
        r=red,
        g=green,
        b=blue
    )

# сохранение растра
out_file = "calc.tif"
array2raster(None, out, "calc.tif")

Пример итерациооного вычисления вегететивного индекса TGI в "examples/calc_iter.py"

Class raster2multiarray

Класс создания стандарного словаря для мультирастра с возможностью его обработки в OpenCV. Данный класс через декораторы использует методы raster2array.

аргументы принимаемые классом при инициализации:

1. (_fname) - имя мультиканального растра для загрузки. 1. (*args) - спсок каналов(band) в порядке очерёдности их записи в стандартный словарь мультирастра (по умолчанию порядок каналов сохраняется как мультирастре)

Переменные по умолчанию установленне для класса:

• multi_type = (None/"cv") - None по умолчанию, cv - формат вывада массива мультиканального растра в формате opencv
• codage = (тип numpy массива) - устанавливает тип numpy массива возвращаемого методами класса (numpy.float64 по умолчанию).
• scale = использование шкалы для распеделения точек растра False(default) - не использовать, True - использовать стандартную, list или tuple - использовать свою шкалу (min, max)
• nodata = установить занвчение "нет данных" для растра, по умолчанию None - берётся значение nodata из загружаемого растра.

Примеры использования raster2multiarray:

from raster_tools import raster2multiarray, multiarray2multiraster

img_in = 'multi.tif'
img_out = 'out.tif'

# сохранения мультиканального растра в страндартную библиотеку в послндовательности каналов 2,3,1
img = raster2multiarray(img_in, 3, 2, 1)
# установить вывод массива в формате opencv
img.array_type = "cv"
# установить тип массива np.uint8 (чаще всего используемый для работы метовод opencv)
img.codage = np.uint8
# вывод стандартного ловаря мультирастра через метод get_std_dict
# также возможен вывод через методы: cut_area, cut_shp_layer, cut_shp_file, cut_ogr_geometry
img = img.get_std_dict()

Пример сохранения мультиканальго растра в стандартный словарь с изменённой последовательностью каналов в "examples/multiarray.py"

Class multiraster2transform(raster2multiarray)

Класс трансформации мультиканального растра: изменение размеренности массива, географическая привязка. Данный класс наследуется от raster2multiarray.

аргументы принимаемые классом при инициализации:

1. (_input) - стандартный словарь/имя растрового файла/объект класса raster2array и его субклассы
2. (_rows) - количество строк нового массива
3. (_cols) - количество колонок нового массива
4. (_proj) - None без перепроецирования или проекция для перепроецирования (формат Wkt или EPSG).

Переменные по умолчанию установленне для класса:

• warp_resampling = метод перепроецирования растров, по умолчанию: gdal.GRA_NearestNeighbour (как у утилиты gdal_warp)
• warp_error_threshold = значание ошибки перепроецирования, по умолчанию: 0.125 (как у утилиты gdal_warp)
• drvname = драйвер георастра (доступны GTiff и MEM - по умолчанию False это GTiff для файла и MEM для памяти)
• overviews = создание пирамид, значения: None(без пирамид - поумолчанию), True - стандартные пирамиды ("NEAREST", [2,4,8,16,32,64]), tuple или list - задать свои значения ("<тип>", [<список значений>])

Примеры использования multiraster2transform аналогичны raster2transform, но для многокалаьных рвстров

Class raster2multiraster

Класс преобразования одноканальных растров в мультиканальный.

аргументы принимаемые классом при инициализации:

1. (*args) - спсок объектов array2raster или raster2array в очерёдности включения их в каналы мультирастра
2. (*args[-1]) - при указаеии в качестве последнего аргумента типа драйвера в формате str он будет использоваться, иначе GTiff

Переменные по умолчанию установленне для класса:

• drvname = драйвер георастра (доступны GTiff и MEM - по умолчанию False это GTiff для файла и MEM для памяти)
• overviews = создание пирамид, значения: None(без пирамид - поумолчанию), True - стандартные пирамиды ("NEAREST", [2,4,8,16,32,64]), tuple или list - задать свои значения ("<тип>", [<список значений>])

Примеры использования raster2multiraster в "examples/cut2multi.py"

Class multiarray2multiraster

Класс преобразования стандарного словаря мультирастра в мультиканальный растр.

аргументы принимаемые классом при инициализации:

1. (_fname) - имя сохраняемого файла мультирастра
2. (_mdict) - стандартный словарь мультирастра как вывод методов класса raster2multiarray

Переменные по умолчанию установленне для класса:

• drvname = драйвер георастра (доступны GTiff и MEM - по умолчанию False это GTiff для файла и MEM для памяти)
• overviews = создание пирамид, значения: None(без пирамид - поумолчанию), True - стандартные пирамиды ("NEAREST", [2,4,8,16,32,64]), tuple или list - задать свои значения ("<тип>", [<список значений>])

Пример сохранеия стандартоного словаря в мультиканальный растр в "examples/multiarray.py"

Class repair2reload

Класс исправления "перевёрнутых растров" и/или перезапись исходного растра

аргументы принимаемые классом при инициализации:

1. (in_name) - имя файла георастра для "ремонта"
2. (out_name) - имя файла георастра для сохранения результата (по умолчанию None - результат будет сохранён в исходный файл)
3. (drv) - типа драйвера (по умолчанию GTiff)

Примеры использования repair2reload в "examples/valid.py"