Растры¶

Обзор¶

Несколько методов вычисляют значения на регулярной сетке квадратных ячеек и возвращают сетку в виде точек:

Функция	Точки возвращаются при	Столбцы и значение в ячейке
`objectnat.get_insolation()`	всегда	`sun_hours`, `min_sun_hours`, `max_continuous_hours`: прямое солнце в приёмнике, часов в сутки
`objectnat.simulate_noise_grid()`	`output="receivers"` или `"both"`	`noise_level`: уровень звука в приёмнике, дБ
`objectnat.get_visibility_catchment()`, `objectnat.get_viewshed_catchment()`	всегда	`count`: число наблюдателей, которые видят ячейку (`weight`: сумма их весов)
`objectnat.get_isovist_grid()`	всегда	метрики изовисты наблюдателя, стоящего в ячейке: `visible_share` (доля круга обзора), `compactness`, `occlusivity` (м), `drift` (м), …

Для шума output="receivers" не строит полосы уровней, это быстрее, когда нужны только значения.

objectnat.rasterize() превращает один столбец таких точек в objectnat.Raster: двумерный массив с аффинным преобразованием и системой координат. Растр показывает непрерывную величину по ячейкам, без границ классов полигонов зон, и его можно нарисовать в matplotlib, записать в файл GeoTIFF или показать на веб-карте folium.

Метод¶

Методы на сетке записывают свою сетку в attrs возвращаемых точек: локальную метрическую систему координат расчёта (зону UTM), размер ячейки и положение центра одной ячейки. objectnat.rasterize() перепроецирует точки в эту систему координат, относит каждую точку к её ячейке и заполняет ячейки без точек (здания, ячейки ниже target_noise_db, ячейки, которые никто не видит) значением NaN. Растр точно воспроизводит расчётную сетку, в какой бы системе координат ни были возвращены точки, в том числе после фильтрации строк. Точкам без такой записи, например прочитанным из файла, нужен cell_size; тогда они размещаются в собственной проекции или в оценённой зоне UTM.

objectnat.Raster — кортеж (values, transform, crs). В values первой идёт северная строка; transform содержит аффинные коэффициенты (a, b, c, d, e, f) в порядке rasterio и GDAL. В том же формате задаются аргументы terrain, поэтому растр можно передать обратно как рельеф.

plot(ax, **imshow_kwargs) рисует растр через imshow в его системе координат. Другие слои на тех же осях нужно перепроецировать в raster.crs.
to_geotiff(path) записывает GeoTIFF float32 (нужен rasterio).
to_folium(cmap=..., vmin=..., vmax=..., opacity=...) возвращает folium.raster_layers.ImageOverlay. Веб-карты рисуют изображения в проекции Web Mercator, поэтому сетка пересчитывается на сетку Меркатора примерно с тем же числом ячеек (по ближайшей ячейке) и раскрашивается палитрой matplotlib; ячейки без значения прозрачны. Слой можно добавить на любую карту folium, в том числе на карты GeoDataFrame.explore() (нужны folium и matplotlib).
explore(m=None, cmap=..., vmin=..., vmax=..., name=...) делает то же на новой карте (или на m) и добавляет цветовую шкалу, как GeoDataFrame.explore().

from objectnat import get_insolation, rasterize

receivers = get_insolation(buildings, "2026-03-21", area=area)
sun = rasterize(receivers, "sun_hours")

image = sun.plot(cmap="inferno", vmin=0, vmax=14)          # matplotlib
sun.to_geotiff("sun_hours_2026-03-21.tif")                 # GIS
sun.explore(cmap="inferno", vmin=0, vmax=14, name="sun hours")   # web map with a colour bar
m = buildings.explore(color="grey")                               # or on top of another map
sun.explore(m, cmap="inferno", vmin=0, vmax=14, name="sun hours")

objectnat.rasterize(points, column, *, cell_size=None)[исходный код]¶

Превращает точки сетки со значениями в Raster, по одной ячейке на точку.

Точки сетки — это то, что возвращают методы на сетке: приёмники get_insolation() и simulate_noise_grid() (output="receivers" или "both"), ячейки get_visibility_catchment() и get_viewshed_catchment() и точки get_isovist_grid(). Их attrs записывают сетку (систему координат, размер ячейки, положение), поэтому растр точно воспроизводит её в локальной метрической системе координат расчёта, в какой бы системе координат ни были возвращены точки, в том числе после фильтрации строк.

Точкам без такой записи (например, прочитанным из файла) нужен cell_size; тогда они размещаются в собственной системе координат, если она проецированная, или в оценённой зоне UTM, а центром ячейки служит первая точка.

Параметры:

points (GeoDataFrame) – GeoDataFrame точек на регулярной сетке.
column (str) – Числовой (или логический) столбец, значения которого записываются в ячейки.
cell_size (float | None) – Сторона ячейки в метрах, для точек без attrs сетки.

Тип результата:

Raster

Результат:

Raster, покрывающий точки; ячейки без точки — NaN.

Примеры

>>> receivers = get_insolation(buildings, "2026-03-21")
>>> raster = rasterize(receivers, "sun_hours")
>>> raster.plot(cmap="inferno", vmin=0, vmax=14)
>>> raster.explore(cmap="inferno", vmin=0, vmax=14, name="sun hours")
>>> raster.to_geotiff("sun_hours.tif")

class objectnat.Raster(values, transform, crs)[исходный код]¶

Значения на ориентированной на север сетке квадратных ячеек, как их возвращает rasterize().

Это кортеж (values, transform, crs), который принимают аргументы terrain, поэтому его можно передать обратно как рельеф, записать через rasterio или нарисовать в matplotlib.

Параметры:

values (ndarray)
transform (tuple)
crs (Any)

values¶: Массив float (rows, cols); строка 0 — северный край, NaN отмечает ячейки без значения.

transform¶: Аффинные коэффициенты (a, b, c, d, e, f), как в rasterio и GDAL: верхний левый угол ячейки (row, col) — x = c + a * col, y = f + e * row (b = d = 0, e = -a).

crs¶: Проецированная система координат сетки (метры).

property cell_size: float¶: Сторона ячейки в метрах.

property bounds: tuple[float, float, float, float]¶: (minx, miny, maxx, maxy) сетки.

property extent: tuple[float, float, float, float]¶: (left, right, bottom, top), аргумент extent функции matplotlib.pyplot.imshow.

plot(ax=None, **kwargs)[исходный код]¶

Рисует растр через ax.imshow в системе координат сетки (ячейки без значения остаются прозрачными).

Именованные аргументы передаются в imshow (cmap, vmin, vmax, alpha, …). Слои на тех же осях должны быть в crs, например buildings.to_crs(raster.crs).plot(ax=ax). Нужен matplotlib.

Результат:: AxesImage, например для fig.colorbar.

to_geotiff(path, *, nodata=nan)[исходный код]¶

Записывает однополосный GeoTIFF float32; ячейки без значения получают nodata. Нужен rasterio.

Тип результата:: None
Параметры:: nodata (float)

to_folium(*, cmap='viridis', vmin=None, vmax=None, opacity=0.75, name=None, **kwargs)[исходный код]¶

Раскрашивает растр и возвращает его как folium.raster_layers.ImageOverlay для веб-карты.

Веб-карты показывают изображения в проекции Web Mercator, поэтому перед раскраской сетка пересчитывается (по ближайшей ячейке) на сетку Меркатора примерно с тем же числом ячеек; после этого слой совпадает с подложкой. Добавьте его через .add_to(m), например на карту из GeoDataFrame.explore(). Нужны folium и matplotlib.

Параметры:

cmap – Палитра matplotlib или её имя.
vmin (float | None) – Пределы цветовой шкалы (по умолчанию минимум и максимум значений).
vmax (float | None) – Пределы цветовой шкалы (по умолчанию минимум и максимум значений).
opacity (float) – Непрозрачность слоя, 0-1. Ячейки без значения прозрачны.
name (str | None) – Имя слоя в folium.LayerControl.
**kwargs – Передаются в ImageOverlay.

explore(m=None, *, cmap='viridis', vmin=None, vmax=None, opacity=0.75, name=None, legend=True, caption=None, tiles=None, **kwargs)[исходный код]¶

Показывает растр на интерактивной карте folium, как GeoDataFrame.explore().

Параметры:

m – Существующая folium.Map, на которую добавляется слой, например buildings.explore(); если None — новая карта с центром на растре.
cmap – Как в to_folium().
vmin (float | None) – Как в to_folium().
vmax (float | None) – Как в to_folium().
opacity (float) – Как в to_folium().
name (str | None) – Как в to_folium().
legend (bool) – Добавить цветовую шкалу.
caption (str | None) – Подпись цветовой шкалы (по умолчанию name).
tiles – Подложка новой карты: название или URL, как в folium.Map, либо folium.TileLayer. По умолчанию светло-серая карта (Esri World Light Gray Canvas), тайлы которой заканчиваются на масштабе 16 и дальше растягиваются.
**kwargs – Передаются в folium.Map при создании новой карты.

Результат:

folium.Map. Нужны folium и matplotlib.

Ограничения¶

Разрешение растра равно разрешению расчётной сетки; для более подробного растра нужен меньший grid_step или cell_size в самом расчёте.
to_folium встраивает изображение в карту как PNG, поэтому очень большие растры дают большие HTML-файлы; для больших территорий запишите GeoTIFF и публикуйте его тайлами.
Точки без attrs сетки должны лежать на регулярной сетке с заданным cell_size.

Примеры в ноутбуках¶

Инсоляция: часы солнца на земле и на фасадах (часы солнца в виде растров и на веб-карте), Моделирование шума (уровни в приёмниках), Видимость 2D: полигоны видимости, метрики изовист и охват (поле изовист, растр охвата 2D) и Видимость 2.5D: области видимости и их охват (растр охвата 2.5D).