ObjectNat 2.0.1__tar.gz → 2.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- objectnat-2.2.0/PKG-INFO +232 -0
- objectnat-2.2.0/README.rst +190 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/_api.py +11 -2
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/_config.py +1 -2
- objectnat-2.2.0/objectnat/_version.py +1 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/accessibility/_utils.py +156 -60
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/accessibility/coverage.py +58 -85
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/accessibility/isochrones.py +147 -100
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/accessibility/radius.py +7 -7
- objectnat-2.2.0/objectnat/methods/insolation/__init__.py +1 -0
- objectnat-2.2.0/objectnat/methods/insolation/_sun.py +86 -0
- objectnat-2.2.0/objectnat/methods/insolation/insolation.py +389 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/noise/__init__.py +1 -0
- objectnat-2.2.0/objectnat/methods/noise/noise_grid.py +430 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/noise/noise_reduce.py +54 -77
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/noise/noise_simulation.py +161 -145
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/noise/noise_simulation_simplified.py +24 -47
- objectnat-2.2.0/objectnat/methods/provision/_matrix.py +61 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/provision/provision.py +18 -12
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/provision/provision_calculating.py +30 -151
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/provision/provision_result.py +16 -13
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/utils/geom_utils.py +54 -74
- objectnat-2.2.0/objectnat/methods/utils/raster.py +351 -0
- objectnat-2.2.0/objectnat/methods/utils/scene.py +228 -0
- objectnat-2.2.0/objectnat/methods/visibility/__init__.py +3 -0
- objectnat-2.2.0/objectnat/methods/visibility/_native.py +153 -0
- objectnat-2.2.0/objectnat/methods/visibility/catchment.py +212 -0
- objectnat-2.2.0/objectnat/methods/visibility/isovist.py +176 -0
- objectnat-2.2.0/objectnat/methods/visibility/viewshed.py +341 -0
- objectnat-2.2.0/objectnat/methods/visibility/visibility_analysis.py +272 -0
- objectnat-2.2.0/objectnat/py.typed +0 -0
- objectnat-2.2.0/pyproject.toml +229 -0
- objectnat-2.2.0/rust/Cargo.lock +280 -0
- objectnat-2.2.0/rust/Cargo.toml +25 -0
- objectnat-2.2.0/rust/README.md +28 -0
- objectnat-2.2.0/rust/src/catchment.rs +446 -0
- objectnat-2.2.0/rust/src/insolation.rs +383 -0
- objectnat-2.2.0/rust/src/lib.rs +988 -0
- objectnat-2.2.0/rust/src/noise.rs +973 -0
- objectnat-2.2.0/rust/src/provision.rs +413 -0
- objectnat-2.2.0/rust/src/viewshed.rs +237 -0
- objectnat-2.2.0/rust/src/visibility.rs +887 -0
- objectnat-2.0.1/.gitignore +0 -59
- objectnat-2.0.1/PKG-INFO +0 -203
- objectnat-2.0.1/README.rst +0 -186
- objectnat-2.0.1/objectnat/_version.py +0 -1
- objectnat-2.0.1/objectnat/methods/visibility/__init__.py +0 -1
- objectnat-2.0.1/objectnat/methods/visibility/visibility_analysis.py +0 -437
- objectnat-2.0.1/pyproject.toml +0 -176
- {objectnat-2.0.1 → objectnat-2.2.0}/LICENSE.txt +0 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/__init__.py +0 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/__init__.py +0 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/accessibility/__init__.py +0 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/noise/noise_init_data.py +0 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/provision/__init__.py +0 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/provision/provision_exceptions.py +0 -0
- {objectnat-2.0.1 → objectnat-2.2.0}/objectnat/methods/utils/__init__.py +0 -0
objectnat-2.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ObjectNat
|
|
3
|
+
Version: 2.2.0
|
|
4
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
5
|
+
Classifier: Intended Audience :: Science/Research
|
|
6
|
+
Classifier: Intended Audience :: Developers
|
|
7
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
8
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
9
|
+
Classifier: Operating System :: MacOS
|
|
10
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Classifier: Programming Language :: Rust
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Dist: geopandas>=1.1.0,<2.0.0
|
|
20
|
+
Requires-Dist: iduedu>=2.4.2,<3.0.0
|
|
21
|
+
Requires-Dist: loguru>=0.7.3,<0.8.0
|
|
22
|
+
Requires-Dist: numpy>=2.0.0,<3.0.0 ; python_full_version < '3.14'
|
|
23
|
+
Requires-Dist: numpy>=2.4.0,<3.0.0 ; python_full_version >= '3.14'
|
|
24
|
+
Requires-Dist: pandas>=2.2.0,<4.0.0 ; python_full_version < '3.14'
|
|
25
|
+
Requires-Dist: pandas>=3.0.0,<4.0.0 ; python_full_version >= '3.14'
|
|
26
|
+
Requires-Dist: scipy>=1.16.0,<2.0.0 ; python_full_version < '3.14'
|
|
27
|
+
Requires-Dist: scipy>=1.17.0,<2.0.0 ; python_full_version >= '3.14'
|
|
28
|
+
Requires-Dist: tqdm>=4.66.2,<5.0.0
|
|
29
|
+
License-File: LICENSE.txt
|
|
30
|
+
Summary: ObjectNat is an open-source library for object-level geospatial analysis on city networks, developed by the IDU team.
|
|
31
|
+
Keywords: urban analytics,geospatial,GIS,accessibility,isochrones,service provision,visibility analysis,isovist,noise simulation,street network,GeoPandas
|
|
32
|
+
Author-email: DDonnyy <ddonnyy@itmo.ru>
|
|
33
|
+
License-Expression: BSD-3-Clause
|
|
34
|
+
Requires-Python: >=3.11, <3.15
|
|
35
|
+
Description-Content-Type: text/x-rst; charset=UTF-8
|
|
36
|
+
Project-URL: Changelog, https://github.com/IDUclub/ObjectNat/blob/master/CHANGELOG.md
|
|
37
|
+
Project-URL: Documentation, https://iduclub.github.io/ObjectNat/
|
|
38
|
+
Project-URL: Homepage, https://github.com/IDUclub/ObjectNat
|
|
39
|
+
Project-URL: Issues, https://github.com/IDUclub/ObjectNat/issues
|
|
40
|
+
Project-URL: Repository, https://github.com/IDUclub/ObjectNat
|
|
41
|
+
|
|
42
|
+
ObjectNat
|
|
43
|
+
=========
|
|
44
|
+
|
|
45
|
+
Object-oriented Network Analysis Tools
|
|
46
|
+
--------------------------------------
|
|
47
|
+
|
|
48
|
+
.. |badge-black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
|
|
49
|
+
:target: https://github.com/psf/black
|
|
50
|
+
:alt: Code style: black
|
|
51
|
+
|
|
52
|
+
.. |badge-pypi| image:: https://img.shields.io/pypi/v/objectnat.svg
|
|
53
|
+
:target: https://pypi.org/project/objectnat/
|
|
54
|
+
:alt: PyPI version
|
|
55
|
+
|
|
56
|
+
.. |badge-ci| image:: https://github.com/IDUclub/ObjectNat/actions/workflows/quality.yml/badge.svg
|
|
57
|
+
:target: https://github.com/IDUclub/ObjectNat/actions/workflows/quality.yml
|
|
58
|
+
:alt: Tests and coverage
|
|
59
|
+
|
|
60
|
+
.. |badge-coverage| image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/python-coverage-comment-action-data/badge.svg
|
|
61
|
+
:target: https://github.com/IDUclub/ObjectNat/tree/python-coverage-comment-action-data
|
|
62
|
+
:alt: Coverage
|
|
63
|
+
|
|
64
|
+
.. |badge-license| image:: https://img.shields.io/badge/license-BSD--3--Clause-blue.svg
|
|
65
|
+
:target: https://opensource.org/licenses/BSD-3-Clause
|
|
66
|
+
:alt: License
|
|
67
|
+
|
|
68
|
+
.. |badge-docs| image:: https://img.shields.io/badge/docs-latest-4aa0d5?logo=readthedocs
|
|
69
|
+
:target: https://iduclub.github.io/ObjectNat/
|
|
70
|
+
:alt: Docs
|
|
71
|
+
|
|
72
|
+
|badge-black| |badge-pypi| |badge-ci| |badge-coverage| |badge-license| |badge-docs|
|
|
73
|
+
|
|
74
|
+
`РИДМИ (Russian) <https://github.com/IDUclub/ObjectNat/blob/master/README_RU.rst>`__
|
|
75
|
+
|
|
76
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/master/docs/_static/ONlogo.svg
|
|
77
|
+
:align: center
|
|
78
|
+
:width: 400
|
|
79
|
+
:alt: ObjectNat logo
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
**ObjectNat** is an open-source Python library for spatial analysis of urban objects (buildings, services,
|
|
83
|
+
street observers, noise sources), developed by the IDU team at ITMO University. It computes accessibility,
|
|
84
|
+
coverage and service provision on street graphs from `IduEdu <https://github.com/IDUclub/IduEdu>`__, visibility in
|
|
85
|
+
2D and over building heights, noise levels and insolation. Inputs and outputs are GeoPandas GeoDataFrames; the
|
|
86
|
+
computationally intensive parts run in a compiled Rust extension.
|
|
87
|
+
|
|
88
|
+
`Documentation <https://iduclub.github.io/ObjectNat/>`__ · `Examples <https://iduclub.github.io/ObjectNat/methods/examples/index.html>`__ · `Документация на русском <https://iduclub.github.io/ObjectNat/ru/>`__
|
|
89
|
+
|
|
90
|
+
----
|
|
91
|
+
|
|
92
|
+
Methods
|
|
93
|
+
-------
|
|
94
|
+
|
|
95
|
+
**Isochrones** (`docs <https://iduclub.github.io/ObjectNat/methods/isochrones.html>`__, `example <https://iduclub.github.io/ObjectNat/methods/examples/isochrones.html>`__).
|
|
96
|
+
``get_graph_isochrones`` and ``get_stepped_graph_isochrones`` return the area reachable from origins within a
|
|
97
|
+
travel time (minutes) or network distance (metres) on an ``iduedu.UrbanGraph``, as one polygon per origin or as
|
|
98
|
+
bands of width ``step``. The polygon is built from residual-distance buffers around the reachable nodes, at most
|
|
99
|
+
``off_network_distance`` (150 m) off the streets (``"radius"``), from the buffered reachable streets (``"ways"``) or
|
|
100
|
+
from merged buffers (``"separate"``).
|
|
101
|
+
|
|
102
|
+
**Coverage zones** (`docs <https://iduclub.github.io/ObjectNat/methods/coverage.html>`__, `example <https://iduclub.github.io/ObjectNat/methods/examples/coverage.html>`__).
|
|
103
|
+
``get_graph_coverage`` and ``get_stepped_graph_coverage`` assign every place to the service it reaches at the lowest
|
|
104
|
+
network cost within a budget (search on the reversed graph, Voronoi cells of graph nodes), so zones do not overlap.
|
|
105
|
+
``get_radius_coverage`` is a graph-free variant with a fixed radius.
|
|
106
|
+
|
|
107
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/assets/accessibility_isochrones_stepped_v4.png
|
|
108
|
+
:align: center
|
|
109
|
+
:width: 100%
|
|
110
|
+
:alt: Stepped isochrones with geometry_type ways, radius and separate, bands of 3 minutes
|
|
111
|
+
|
|
112
|
+
**Service provision** (`docs <https://iduclub.github.io/ObjectNat/methods/provision.html>`__, `example <https://iduclub.github.io/ObjectNat/methods/examples/provision.html>`__).
|
|
113
|
+
``get_service_provision`` allocates building demand to services with limited capacity using a gravity-based
|
|
114
|
+
probabilistic model over a dense or pandas-sparse cost matrix and a normative threshold. It returns a
|
|
115
|
+
``ProvisionResult`` with the sparse flow matrix and per-building and per-service metrics (``provision_value`` is the
|
|
116
|
+
share of demand supplied within the threshold); helpers join the metrics to GeoDataFrames, build link lines,
|
|
117
|
+
drop links beyond a shorter threshold and clip the result to an area.
|
|
118
|
+
|
|
119
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/assets/provision_map_links_v4.png
|
|
120
|
+
:align: center
|
|
121
|
+
:width: 100%
|
|
122
|
+
:alt: Provision value of residential buildings and building–school links within and beyond a 10-minute threshold
|
|
123
|
+
|
|
124
|
+
**Visibility** (`docs <https://iduclub.github.io/ObjectNat/methods/visibility.html>`__, examples: `2D <https://iduclub.github.io/ObjectNat/methods/examples/visibility.html>`__,
|
|
125
|
+
`2.5D <https://iduclub.github.io/ObjectNat/methods/examples/viewshed.html>`__). ``get_visibility`` computes the exact visibility polygon (isovist) of
|
|
126
|
+
each observer among obstacles treated as walls of infinite height and, with ``isovist_metrics=True``, area,
|
|
127
|
+
compactness, occlusivity, radial statistics, drift and visible share; ``get_isovist_grid`` maps these metrics over
|
|
128
|
+
an area. ``get_viewshed`` uses building heights and terrain: a grid cell is visible when the line of sight from the
|
|
129
|
+
eye (by default 1.6 m above the ground or a roof) to the cell passes above every wall and the ground.
|
|
130
|
+
``get_visibility_catchment`` and ``get_viewshed_catchment`` count, for every cell, the observers that see it
|
|
131
|
+
(``get_observer_points`` places observers along streets); ``rasterize`` draws the counts as a raster.
|
|
132
|
+
|
|
133
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/assets/viewshed_vs_visibility_v2.png
|
|
134
|
+
:align: center
|
|
135
|
+
:width: 100%
|
|
136
|
+
:alt: 2D visibility polygon, street-level viewshed and roof-level viewshed
|
|
137
|
+
|
|
138
|
+
**Noise** (`docs <https://iduclub.github.io/ObjectNat/methods/noise.html>`__, `example <https://iduclub.github.io/ObjectNat/methods/examples/noise.html>`__). ``simulate_noise_grid``
|
|
139
|
+
computes sound levels on a receiver grid from point, line and polygon sources: direct paths and first-order
|
|
140
|
+
reflections with geometric spreading, air absorption, wall absorption and vegetation attenuation, and diffraction
|
|
141
|
+
around building corners into their shadows, summed as energies. ``simulate_noise`` is a wave-front model for point
|
|
142
|
+
sources with multiple reflections, and ``calculate_simplified_noise_frame`` a fast estimate from visibility masks and
|
|
143
|
+
distance decay. Ground effect is not modelled. Background: `wiki <https://github.com/IDUclub/ObjectNat/wiki/Noise-simulation>`__.
|
|
144
|
+
|
|
145
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/assets/noise_grid_paths_v2.png
|
|
146
|
+
:align: center
|
|
147
|
+
:width: 100%
|
|
148
|
+
:alt: Noise levels on a receiver grid and the levels added by reflections and by diffraction
|
|
149
|
+
|
|
150
|
+
**Insolation** (`docs <https://iduclub.github.io/ObjectNat/methods/insolation.html>`__, `example <https://iduclub.github.io/ObjectNat/methods/examples/insolation.html>`__).
|
|
151
|
+
``get_insolation`` follows the sun (NOAA solar position) through a day or a period and returns, on a ground grid
|
|
152
|
+
among buildings of known height and optional terrain (GeoDataFrame, GeoTIFF or array), the daily hours of direct
|
|
153
|
+
sun, including ground with no direct sun, the hours on the worst day and the longest continuous sunlit period, for
|
|
154
|
+
which insolation norms set a minimum; ``rasterize`` draws them as a raster. ``get_facade_insolation`` computes the same quantities
|
|
155
|
+
for facade points on every floor and checks them against a norm.
|
|
156
|
+
|
|
157
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/assets/insolation_shadows_2026-06-21_v2.gif
|
|
158
|
+
:align: center
|
|
159
|
+
:width: 520
|
|
160
|
+
:alt: Ground shadows of a residential district on 21 June, 15-minute frames
|
|
161
|
+
|
|
162
|
+
**Rasters.** Grid results (insolation and noise receivers, catchment cells, isovist fields from
|
|
163
|
+
``get_isovist_grid``) are converted to rasters with ``rasterize``; a ``Raster`` can be drawn with matplotlib,
|
|
164
|
+
written to a GeoTIFF file or shown on a folium web map with ``explore``.
|
|
165
|
+
|
|
166
|
+
----
|
|
167
|
+
|
|
168
|
+
Installation
|
|
169
|
+
------------
|
|
170
|
+
|
|
171
|
+
::
|
|
172
|
+
|
|
173
|
+
pip install objectnat
|
|
174
|
+
|
|
175
|
+
ObjectNat supports Python 3.11–3.14 on Linux, macOS and Windows and installs IduEdu 2.4.1 or newer within the 2.x
|
|
176
|
+
series. Wheels include the compiled extension ``objectnat._rust``, so ``pip`` needs no compiler. Installing from a
|
|
177
|
+
source checkout (``pip install .``) builds the extension and requires a Rust toolchain
|
|
178
|
+
(`rustup <https://rustup.rs>`__). GeoTIFF terrain requires the optional ``rasterio`` package.
|
|
179
|
+
|
|
180
|
+
----
|
|
181
|
+
|
|
182
|
+
Street graphs from IduEdu
|
|
183
|
+
-------------------------
|
|
184
|
+
|
|
185
|
+
Graph-based methods take an ``iduedu.UrbanGraph`` (nodes and edges as GeoDataFrames, edge weights ``time_min`` and
|
|
186
|
+
``length_meter``) and use IduEdu's Dijkstra routines; ObjectNat does not build graphs itself. IduEdu
|
|
187
|
+
can download a Geofabrik extract and cut the territory out of it, so no Overpass request is needed (cutting
|
|
188
|
+
requires ``pip install "iduedu[pbf]"``)::
|
|
189
|
+
|
|
190
|
+
import iduedu
|
|
191
|
+
from iduedu import get_4326_boundary, get_intermodal_graph
|
|
192
|
+
|
|
193
|
+
with iduedu.use_pbf(osm_id=1114252, region="northwestern-fed-district"):
|
|
194
|
+
boundary = get_4326_boundary(osm_id=1114252)
|
|
195
|
+
graph = get_intermodal_graph(territory=boundary, clip_by_territory=True)
|
|
196
|
+
|
|
197
|
+
Without the ``with`` block the same calls query the Overpass API.
|
|
198
|
+
|
|
199
|
+
----
|
|
200
|
+
|
|
201
|
+
Configuration
|
|
202
|
+
-------------
|
|
203
|
+
|
|
204
|
+
::
|
|
205
|
+
|
|
206
|
+
from objectnat import config
|
|
207
|
+
|
|
208
|
+
config.change_logger_lvl("INFO") # hide debug messages
|
|
209
|
+
config.set_enable_tqdm(False) # disable progress bars
|
|
210
|
+
|
|
211
|
+
----
|
|
212
|
+
|
|
213
|
+
Contacts
|
|
214
|
+
--------
|
|
215
|
+
|
|
216
|
+
- `NCCR <https://actcognitive.org/>`_, National Center for Cognitive Research
|
|
217
|
+
- `IDU <https://idu.itmo.ru/>`_, Institute of Design and Urban Studies
|
|
218
|
+
- `Natalya Chichkova <https://t.me/nancy_nat>`_, project manager
|
|
219
|
+
- `Danila Oleynikov (Donny) <https://t.me/ddonny_dd>`_, lead software engineer
|
|
220
|
+
|
|
221
|
+
Contributions are described in `CONTRIBUTING.md <https://github.com/IDUclub/ObjectNat/blob/master/CONTRIBUTING.md>`__.
|
|
222
|
+
|
|
223
|
+
----
|
|
224
|
+
|
|
225
|
+
Citing ObjectNat
|
|
226
|
+
----------------
|
|
227
|
+
|
|
228
|
+
Citation metadata is kept in
|
|
229
|
+
`CITATION.cff <https://github.com/IDUclub/ObjectNat/blob/master/CITATION.cff>`__; on GitHub,
|
|
230
|
+
**Cite this repository** in the repository sidebar exports it as APA or BibTeX. Publications describing ObjectNat
|
|
231
|
+
will be listed here.
|
|
232
|
+
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
ObjectNat
|
|
2
|
+
=========
|
|
3
|
+
|
|
4
|
+
Object-oriented Network Analysis Tools
|
|
5
|
+
--------------------------------------
|
|
6
|
+
|
|
7
|
+
.. |badge-black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
|
|
8
|
+
:target: https://github.com/psf/black
|
|
9
|
+
:alt: Code style: black
|
|
10
|
+
|
|
11
|
+
.. |badge-pypi| image:: https://img.shields.io/pypi/v/objectnat.svg
|
|
12
|
+
:target: https://pypi.org/project/objectnat/
|
|
13
|
+
:alt: PyPI version
|
|
14
|
+
|
|
15
|
+
.. |badge-ci| image:: https://github.com/IDUclub/ObjectNat/actions/workflows/quality.yml/badge.svg
|
|
16
|
+
:target: https://github.com/IDUclub/ObjectNat/actions/workflows/quality.yml
|
|
17
|
+
:alt: Tests and coverage
|
|
18
|
+
|
|
19
|
+
.. |badge-coverage| image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/python-coverage-comment-action-data/badge.svg
|
|
20
|
+
:target: https://github.com/IDUclub/ObjectNat/tree/python-coverage-comment-action-data
|
|
21
|
+
:alt: Coverage
|
|
22
|
+
|
|
23
|
+
.. |badge-license| image:: https://img.shields.io/badge/license-BSD--3--Clause-blue.svg
|
|
24
|
+
:target: https://opensource.org/licenses/BSD-3-Clause
|
|
25
|
+
:alt: License
|
|
26
|
+
|
|
27
|
+
.. |badge-docs| image:: https://img.shields.io/badge/docs-latest-4aa0d5?logo=readthedocs
|
|
28
|
+
:target: https://iduclub.github.io/ObjectNat/
|
|
29
|
+
:alt: Docs
|
|
30
|
+
|
|
31
|
+
|badge-black| |badge-pypi| |badge-ci| |badge-coverage| |badge-license| |badge-docs|
|
|
32
|
+
|
|
33
|
+
`РИДМИ (Russian) <https://github.com/IDUclub/ObjectNat/blob/master/README_RU.rst>`__
|
|
34
|
+
|
|
35
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/master/docs/_static/ONlogo.svg
|
|
36
|
+
:align: center
|
|
37
|
+
:width: 400
|
|
38
|
+
:alt: ObjectNat logo
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
**ObjectNat** is an open-source Python library for spatial analysis of urban objects (buildings, services,
|
|
42
|
+
street observers, noise sources), developed by the IDU team at ITMO University. It computes accessibility,
|
|
43
|
+
coverage and service provision on street graphs from `IduEdu <https://github.com/IDUclub/IduEdu>`__, visibility in
|
|
44
|
+
2D and over building heights, noise levels and insolation. Inputs and outputs are GeoPandas GeoDataFrames; the
|
|
45
|
+
computationally intensive parts run in a compiled Rust extension.
|
|
46
|
+
|
|
47
|
+
`Documentation <https://iduclub.github.io/ObjectNat/>`__ · `Examples <https://iduclub.github.io/ObjectNat/methods/examples/index.html>`__ · `Документация на русском <https://iduclub.github.io/ObjectNat/ru/>`__
|
|
48
|
+
|
|
49
|
+
----
|
|
50
|
+
|
|
51
|
+
Methods
|
|
52
|
+
-------
|
|
53
|
+
|
|
54
|
+
**Isochrones** (`docs <https://iduclub.github.io/ObjectNat/methods/isochrones.html>`__, `example <https://iduclub.github.io/ObjectNat/methods/examples/isochrones.html>`__).
|
|
55
|
+
``get_graph_isochrones`` and ``get_stepped_graph_isochrones`` return the area reachable from origins within a
|
|
56
|
+
travel time (minutes) or network distance (metres) on an ``iduedu.UrbanGraph``, as one polygon per origin or as
|
|
57
|
+
bands of width ``step``. The polygon is built from residual-distance buffers around the reachable nodes, at most
|
|
58
|
+
``off_network_distance`` (150 m) off the streets (``"radius"``), from the buffered reachable streets (``"ways"``) or
|
|
59
|
+
from merged buffers (``"separate"``).
|
|
60
|
+
|
|
61
|
+
**Coverage zones** (`docs <https://iduclub.github.io/ObjectNat/methods/coverage.html>`__, `example <https://iduclub.github.io/ObjectNat/methods/examples/coverage.html>`__).
|
|
62
|
+
``get_graph_coverage`` and ``get_stepped_graph_coverage`` assign every place to the service it reaches at the lowest
|
|
63
|
+
network cost within a budget (search on the reversed graph, Voronoi cells of graph nodes), so zones do not overlap.
|
|
64
|
+
``get_radius_coverage`` is a graph-free variant with a fixed radius.
|
|
65
|
+
|
|
66
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/assets/accessibility_isochrones_stepped_v4.png
|
|
67
|
+
:align: center
|
|
68
|
+
:width: 100%
|
|
69
|
+
:alt: Stepped isochrones with geometry_type ways, radius and separate, bands of 3 minutes
|
|
70
|
+
|
|
71
|
+
**Service provision** (`docs <https://iduclub.github.io/ObjectNat/methods/provision.html>`__, `example <https://iduclub.github.io/ObjectNat/methods/examples/provision.html>`__).
|
|
72
|
+
``get_service_provision`` allocates building demand to services with limited capacity using a gravity-based
|
|
73
|
+
probabilistic model over a dense or pandas-sparse cost matrix and a normative threshold. It returns a
|
|
74
|
+
``ProvisionResult`` with the sparse flow matrix and per-building and per-service metrics (``provision_value`` is the
|
|
75
|
+
share of demand supplied within the threshold); helpers join the metrics to GeoDataFrames, build link lines,
|
|
76
|
+
drop links beyond a shorter threshold and clip the result to an area.
|
|
77
|
+
|
|
78
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/assets/provision_map_links_v4.png
|
|
79
|
+
:align: center
|
|
80
|
+
:width: 100%
|
|
81
|
+
:alt: Provision value of residential buildings and building–school links within and beyond a 10-minute threshold
|
|
82
|
+
|
|
83
|
+
**Visibility** (`docs <https://iduclub.github.io/ObjectNat/methods/visibility.html>`__, examples: `2D <https://iduclub.github.io/ObjectNat/methods/examples/visibility.html>`__,
|
|
84
|
+
`2.5D <https://iduclub.github.io/ObjectNat/methods/examples/viewshed.html>`__). ``get_visibility`` computes the exact visibility polygon (isovist) of
|
|
85
|
+
each observer among obstacles treated as walls of infinite height and, with ``isovist_metrics=True``, area,
|
|
86
|
+
compactness, occlusivity, radial statistics, drift and visible share; ``get_isovist_grid`` maps these metrics over
|
|
87
|
+
an area. ``get_viewshed`` uses building heights and terrain: a grid cell is visible when the line of sight from the
|
|
88
|
+
eye (by default 1.6 m above the ground or a roof) to the cell passes above every wall and the ground.
|
|
89
|
+
``get_visibility_catchment`` and ``get_viewshed_catchment`` count, for every cell, the observers that see it
|
|
90
|
+
(``get_observer_points`` places observers along streets); ``rasterize`` draws the counts as a raster.
|
|
91
|
+
|
|
92
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/assets/viewshed_vs_visibility_v2.png
|
|
93
|
+
:align: center
|
|
94
|
+
:width: 100%
|
|
95
|
+
:alt: 2D visibility polygon, street-level viewshed and roof-level viewshed
|
|
96
|
+
|
|
97
|
+
**Noise** (`docs <https://iduclub.github.io/ObjectNat/methods/noise.html>`__, `example <https://iduclub.github.io/ObjectNat/methods/examples/noise.html>`__). ``simulate_noise_grid``
|
|
98
|
+
computes sound levels on a receiver grid from point, line and polygon sources: direct paths and first-order
|
|
99
|
+
reflections with geometric spreading, air absorption, wall absorption and vegetation attenuation, and diffraction
|
|
100
|
+
around building corners into their shadows, summed as energies. ``simulate_noise`` is a wave-front model for point
|
|
101
|
+
sources with multiple reflections, and ``calculate_simplified_noise_frame`` a fast estimate from visibility masks and
|
|
102
|
+
distance decay. Ground effect is not modelled. Background: `wiki <https://github.com/IDUclub/ObjectNat/wiki/Noise-simulation>`__.
|
|
103
|
+
|
|
104
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/assets/noise_grid_paths_v2.png
|
|
105
|
+
:align: center
|
|
106
|
+
:width: 100%
|
|
107
|
+
:alt: Noise levels on a receiver grid and the levels added by reflections and by diffraction
|
|
108
|
+
|
|
109
|
+
**Insolation** (`docs <https://iduclub.github.io/ObjectNat/methods/insolation.html>`__, `example <https://iduclub.github.io/ObjectNat/methods/examples/insolation.html>`__).
|
|
110
|
+
``get_insolation`` follows the sun (NOAA solar position) through a day or a period and returns, on a ground grid
|
|
111
|
+
among buildings of known height and optional terrain (GeoDataFrame, GeoTIFF or array), the daily hours of direct
|
|
112
|
+
sun, including ground with no direct sun, the hours on the worst day and the longest continuous sunlit period, for
|
|
113
|
+
which insolation norms set a minimum; ``rasterize`` draws them as a raster. ``get_facade_insolation`` computes the same quantities
|
|
114
|
+
for facade points on every floor and checks them against a norm.
|
|
115
|
+
|
|
116
|
+
.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/assets/insolation_shadows_2026-06-21_v2.gif
|
|
117
|
+
:align: center
|
|
118
|
+
:width: 520
|
|
119
|
+
:alt: Ground shadows of a residential district on 21 June, 15-minute frames
|
|
120
|
+
|
|
121
|
+
**Rasters.** Grid results (insolation and noise receivers, catchment cells, isovist fields from
|
|
122
|
+
``get_isovist_grid``) are converted to rasters with ``rasterize``; a ``Raster`` can be drawn with matplotlib,
|
|
123
|
+
written to a GeoTIFF file or shown on a folium web map with ``explore``.
|
|
124
|
+
|
|
125
|
+
----
|
|
126
|
+
|
|
127
|
+
Installation
|
|
128
|
+
------------
|
|
129
|
+
|
|
130
|
+
::
|
|
131
|
+
|
|
132
|
+
pip install objectnat
|
|
133
|
+
|
|
134
|
+
ObjectNat supports Python 3.11–3.14 on Linux, macOS and Windows and installs IduEdu 2.4.1 or newer within the 2.x
|
|
135
|
+
series. Wheels include the compiled extension ``objectnat._rust``, so ``pip`` needs no compiler. Installing from a
|
|
136
|
+
source checkout (``pip install .``) builds the extension and requires a Rust toolchain
|
|
137
|
+
(`rustup <https://rustup.rs>`__). GeoTIFF terrain requires the optional ``rasterio`` package.
|
|
138
|
+
|
|
139
|
+
----
|
|
140
|
+
|
|
141
|
+
Street graphs from IduEdu
|
|
142
|
+
-------------------------
|
|
143
|
+
|
|
144
|
+
Graph-based methods take an ``iduedu.UrbanGraph`` (nodes and edges as GeoDataFrames, edge weights ``time_min`` and
|
|
145
|
+
``length_meter``) and use IduEdu's Dijkstra routines; ObjectNat does not build graphs itself. IduEdu
|
|
146
|
+
can download a Geofabrik extract and cut the territory out of it, so no Overpass request is needed (cutting
|
|
147
|
+
requires ``pip install "iduedu[pbf]"``)::
|
|
148
|
+
|
|
149
|
+
import iduedu
|
|
150
|
+
from iduedu import get_4326_boundary, get_intermodal_graph
|
|
151
|
+
|
|
152
|
+
with iduedu.use_pbf(osm_id=1114252, region="northwestern-fed-district"):
|
|
153
|
+
boundary = get_4326_boundary(osm_id=1114252)
|
|
154
|
+
graph = get_intermodal_graph(territory=boundary, clip_by_territory=True)
|
|
155
|
+
|
|
156
|
+
Without the ``with`` block the same calls query the Overpass API.
|
|
157
|
+
|
|
158
|
+
----
|
|
159
|
+
|
|
160
|
+
Configuration
|
|
161
|
+
-------------
|
|
162
|
+
|
|
163
|
+
::
|
|
164
|
+
|
|
165
|
+
from objectnat import config
|
|
166
|
+
|
|
167
|
+
config.change_logger_lvl("INFO") # hide debug messages
|
|
168
|
+
config.set_enable_tqdm(False) # disable progress bars
|
|
169
|
+
|
|
170
|
+
----
|
|
171
|
+
|
|
172
|
+
Contacts
|
|
173
|
+
--------
|
|
174
|
+
|
|
175
|
+
- `NCCR <https://actcognitive.org/>`_, National Center for Cognitive Research
|
|
176
|
+
- `IDU <https://idu.itmo.ru/>`_, Institute of Design and Urban Studies
|
|
177
|
+
- `Natalya Chichkova <https://t.me/nancy_nat>`_, project manager
|
|
178
|
+
- `Danila Oleynikov (Donny) <https://t.me/ddonny_dd>`_, lead software engineer
|
|
179
|
+
|
|
180
|
+
Contributions are described in `CONTRIBUTING.md <https://github.com/IDUclub/ObjectNat/blob/master/CONTRIBUTING.md>`__.
|
|
181
|
+
|
|
182
|
+
----
|
|
183
|
+
|
|
184
|
+
Citing ObjectNat
|
|
185
|
+
----------------
|
|
186
|
+
|
|
187
|
+
Citation metadata is kept in
|
|
188
|
+
`CITATION.cff <https://github.com/IDUclub/ObjectNat/blob/master/CITATION.cff>`__; on GitHub,
|
|
189
|
+
**Cite this repository** in the repository sidebar exports it as APA or BibTeX. Publications describing ObjectNat
|
|
190
|
+
will be listed here.
|
|
@@ -7,7 +7,8 @@ from .methods.accessibility import (
|
|
|
7
7
|
get_stepped_graph_coverage,
|
|
8
8
|
get_stepped_graph_isochrones,
|
|
9
9
|
)
|
|
10
|
-
from .methods.
|
|
10
|
+
from .methods.insolation import get_facade_insolation, get_insolation
|
|
11
|
+
from .methods.noise import calculate_simplified_noise_frame, simulate_noise, simulate_noise_grid
|
|
11
12
|
from .methods.provision import (
|
|
12
13
|
ProvisionResult,
|
|
13
14
|
clip_provision,
|
|
@@ -17,4 +18,12 @@ from .methods.provision import (
|
|
|
17
18
|
get_service_provision,
|
|
18
19
|
recalculate_links,
|
|
19
20
|
)
|
|
20
|
-
from .methods.
|
|
21
|
+
from .methods.utils.raster import Raster, rasterize
|
|
22
|
+
from .methods.visibility import (
|
|
23
|
+
get_isovist_grid,
|
|
24
|
+
get_observer_points,
|
|
25
|
+
get_viewshed,
|
|
26
|
+
get_viewshed_catchment,
|
|
27
|
+
get_visibility,
|
|
28
|
+
get_visibility_catchment,
|
|
29
|
+
)
|
|
@@ -6,8 +6,7 @@ from loguru import logger
|
|
|
6
6
|
|
|
7
7
|
class Config:
|
|
8
8
|
"""
|
|
9
|
-
|
|
10
|
-
timeouts, and logging options.
|
|
9
|
+
Global settings of ObjectNat: the logging level and the progress bars.
|
|
11
10
|
|
|
12
11
|
Attributes
|
|
13
12
|
----------
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
VERSION = "2.2.0"
|