ObjectNat 1.3.3__py3-none-any.whl

objectnat/methods/visibility/visibility_analysis.py

@@ -0,0 +1,485 @@
+import math
+from multiprocessing import cpu_count
+
+import geopandas as gpd
+import numpy as np
+import pandas as pd
+from shapely import LineString, MultiPolygon, Point, Polygon
+from shapely.ops import unary_union
+from tqdm.contrib.concurrent import process_map
+
+from objectnat import config
+from objectnat.methods.utils.geom_utils import (
+    combine_geometry,
+    explode_linestring,
+    get_point_from_a_thorough_b,
+    point_side_of_line,
+    polygons_to_multilinestring,
+)
+from objectnat.methods.utils.math_utils import min_max_normalization
+
+logger = config.logger
+
+
+def _ensure_crs(point_from, obstacles):
+    if isinstance(point_from, gpd.GeoDataFrame):
+        if point_from.empty:
+            raise ValueError("GeoDataFrame 'point_from' is empty.")
+        return_gdf = True
+        original_crs = point_from.crs
+        local_crs = point_from.estimate_utm_crs()
+        point_from = point_from.to_crs(local_crs)
+        if len(point_from) > 1:
+            logger.warning(
+                "This method processes only a single point. "
+                f"The GeoDataFrame contains {len(point_from)} points – "
+                "only the first geometry will be used for visibility calculation."
+            )
+        point_geom = point_from.iloc[0].geometry
+        if len(obstacles) > 0:
+            obstacles = obstacles.to_crs(local_crs)
+
+    else:
+        return_gdf = False
+
+        if len(obstacles) > 0:
+            original_crs = obstacles.crs
+            local_crs = obstacles.estimate_utm_crs()
+            obstacles = obstacles.to_crs(local_crs)
+            point_geom = gpd.GeoDataFrame(geometry=[point_from], crs=original_crs).to_crs(local_crs).iloc[0].geometry
+        else:
+            original_crs = 4326
+            logger.warning("No information about CRS was found, accepting everything in 4326")
+            point_gdf = gpd.GeoDataFrame(geometry=[point_from], crs=original_crs)
+            local_crs = point_gdf.estimate_utm_crs()
+
+            point_gdf = point_gdf.to_crs(local_crs)
+            point_geom = point_gdf.geometry.iloc[0]
+
+    return point_geom, obstacles, original_crs, local_crs, return_gdf
+
+
+def get_visibility_accurate(
+    point_from: Point | gpd.GeoDataFrame, obstacles: gpd.GeoDataFrame, view_distance, return_max_view_dist=False
+) -> Polygon | gpd.GeoDataFrame | tuple[Polygon | gpd.GeoDataFrame, float]:
+    """
+    Function to get accurate visibility from a given point to buildings within a given distance.
+
+    Args:
+        point_from (Point | gpd.GeoDataFrame):
+            The point or GeoDataFrame with 1 point from which the line of sight is drawn.
+            If Point is provided it should be in the same crs as obstacles.
+        obstacles (gpd.GeoDataFrame):
+            A GeoDataFrame containing the geometry of the obstacles.
+        view_distance (float):
+            The distance of view from the point.
+        return_max_view_dist (bool):
+            If True, the max view distance is returned with view polygon in tuple.
+
+    Returns:
+        (Polygon | gpd.GeoDataFrame | tuple[Polygon | gpd.GeoDataFrame, float]):
+            A polygon representing the area of visibility from the given point or polygon with max view distance.
+            if point_from was a GeoDataFrame, return GeoDataFrame with one feature, else Polygon.
+
+    Notes:
+        If a quick result is important, consider using the `get_visibility()` function instead.
+        However, please note that `get_visibility()` may provide less accurate results.
+    """
+
+    def find_furthest_point(point_from, view_polygon):
+        try:
+            res = round(max(Point(coords).distance(point_from) for coords in view_polygon.exterior.coords), 1)
+        except Exception as e:
+            print(view_polygon)
+            raise e
+        return res
+
+    point_geom, obstacles, original_crs, local_crs, return_gdf = _ensure_crs(point_from, obstacles)
+
+    if len(obstacles) > 0 and obstacles.contains(point_geom).any():
+        return gpd.GeoDataFrame() if return_gdf else Point()
+
+    point_buffer = point_geom.buffer(view_distance, resolution=32)
+
+    if len(obstacles) == 0:
+        full_vision_gdf = gpd.GeoDataFrame(geometry=[point_buffer], crs=local_crs).to_crs(original_crs)
+        return full_vision_gdf if return_gdf else full_vision_gdf.iloc[0].geometry
+
+    obstacles.reset_index(inplace=True, drop=True)
+
+    allowed_geom_types = ["MultiPolygon", "Polygon", "LineString", "MultiLineString"]
+
+    obstacles = obstacles[obstacles.geom_type.isin(allowed_geom_types)]
+    s = obstacles.intersects(point_buffer)
+    obstacles_in_buffer = obstacles.loc[s[s].index].geometry
+
+    buildings_lines_in_buffer = gpd.GeoSeries(
+        pd.Series(
+            obstacles_in_buffer.apply(polygons_to_multilinestring).explode(index_parts=False).apply(explode_linestring)
+        ).explode()
+    )
+
+    buildings_lines_in_buffer = buildings_lines_in_buffer.loc[buildings_lines_in_buffer.intersects(point_buffer)]
+
+    buildings_in_buffer_points = gpd.GeoSeries(
+        [Point(line.coords[0]) for line in buildings_lines_in_buffer.geometry]
+        + [Point(line.coords[-1]) for line in buildings_lines_in_buffer.geometry]
+    )
+
+    max_dist = max(view_distance, buildings_in_buffer_points.distance(point_geom).max())
+    polygons = []
+    buildings_lines_in_buffer = gpd.GeoDataFrame(geometry=buildings_lines_in_buffer, crs=obstacles.crs).reset_index()
+    logger.debug("Calculation vis polygon")
+    while not buildings_lines_in_buffer.empty:
+        gdf_sindex = buildings_lines_in_buffer.sindex
+        # TODO check if 2 walls are nearest and use the widest angle between points
+        nearest_wall_sind = gdf_sindex.nearest(point_geom, return_all=False, max_distance=max_dist)
+        nearest_wall = buildings_lines_in_buffer.loc[nearest_wall_sind[1]].iloc[0]
+        wall_points = [Point(coords) for coords in nearest_wall.geometry.coords]
+
+        # Calculate angles and sort by angle
+        points_with_angle = sorted(
+            [(pt, math.atan2(pt.y - point_geom.y, pt.x - point_geom.x)) for pt in wall_points], key=lambda x: x[1]
+        )
+        delta_angle = 2 * math.pi + points_with_angle[0][1] - points_with_angle[-1][1]
+        if round(delta_angle, 10) == round(math.pi, 10):
+            wall_b_centroid = obstacles_in_buffer.loc[nearest_wall["index"]].centroid
+            p1 = get_point_from_a_thorough_b(point_geom, points_with_angle[0][0], max_dist)
+            p2 = get_point_from_a_thorough_b(point_geom, points_with_angle[1][0], max_dist)
+            polygon = LineString([p1, p2])
+            polygon = polygon.buffer(
+                distance=max_dist * point_side_of_line(polygon, wall_b_centroid), single_sided=True
+            )
+        else:
+            if delta_angle > math.pi:
+                delta_angle = 2 * math.pi - delta_angle
+            a = math.sqrt((max_dist**2) * (1 + (math.tan(delta_angle / 2) ** 2)))
+            p1 = get_point_from_a_thorough_b(point_geom, points_with_angle[0][0], a)
+            p2 = get_point_from_a_thorough_b(point_geom, points_with_angle[-1][0], a)
+            polygon = Polygon([points_with_angle[0][0], p1, p2, points_with_angle[1][0]])
+
+        polygons.append(polygon)
+        buildings_lines_in_buffer.drop(nearest_wall_sind[1], inplace=True)
+
+        if not polygon.is_valid or polygon.area < 1:
+            buildings_lines_in_buffer.reset_index(drop=True, inplace=True)
+            continue
+
+        lines_to_kick = buildings_lines_in_buffer.within(polygon)
+        buildings_lines_in_buffer = buildings_lines_in_buffer.loc[~lines_to_kick]
+        buildings_lines_in_buffer.reset_index(drop=True, inplace=True)
+    logger.debug("Done calculating!")
+    res = point_buffer.difference(unary_union(polygons + obstacles_in_buffer.to_list()))
+
+    if isinstance(res, MultiPolygon):
+        res = list(res.geoms)
+        for polygon in res:
+            if polygon.intersects(point_geom):
+                res = polygon
+                break
+
+    result_gdf = gpd.GeoDataFrame(geometry=[res], crs=local_crs).to_crs(original_crs)
+    if return_gdf:
+        return result_gdf
+    res = result_gdf.to_crs(original_crs).iloc[0].geometry
+    if return_max_view_dist:
+        return res, find_furthest_point(point_geom, res)
+    return res
+
+
+def get_visibility(
+    point_from: Point | gpd.GeoDataFrame, obstacles: gpd.GeoDataFrame, view_distance: float, resolution: int = 32
+) -> Polygon | gpd.GeoDataFrame:
+    """
+    Function to get a quick estimate of visibility from a given point to buildings within a given distance.
+
+    Args:
+        point_from (Point | gpd.GeoDataFrame):
+            The point or GeoDataFrame with 1 point from which the line of sight is drawn.
+            If Point is provided it should be in the same crs as obstacles.
+        obstacles (gpd.GeoDataFrame):
+            A GeoDataFrame containing the geometry of the buildings.
+        view_distance (float):
+            The distance of view from the point.
+        resolution (int) :
+            Buffer resolution for more accuracy (may give result slower)
+
+    Returns:
+        (Polygon | gpd.GeoDataFrame):
+            A polygon representing the area of visibility from the given point.
+            if point_from was a GeoDataFrame, return GeoDataFrame with one feature, else Polygon.
+
+    Notes:
+        This function provides a quicker but less accurate result compared to `get_visibility_accurate()`.
+        If accuracy is important, consider using `get_visibility_accurate()` instead.
+    """
+
+    obstacles = obstacles.copy()
+
+    point_geom, obstacles, original_crs, local_crs, return_gdf = _ensure_crs(point_from, obstacles)
+    print(return_gdf)
+    if len(obstacles) > 0 and obstacles.contains(point_geom).any():
+        return Polygon()
+
+    point_buffer = point_geom.buffer(view_distance, resolution=resolution)
+
+    if len(obstacles) == 0:
+        full_vision_gdf = gpd.GeoDataFrame(geometry=[point_buffer], crs=local_crs).to_crs(original_crs)
+        return full_vision_gdf if return_gdf else full_vision_gdf.iloc[0].geometry
+
+    s = obstacles.intersects(point_buffer)
+    buildings_in_buffer = obstacles.loc[s[s].index].reset_index(drop=True)
+    buffer_exterior_ = list(point_buffer.exterior.coords)
+    line_geometry = [LineString([point_geom, ext]) for ext in buffer_exterior_]
+    buffer_lines_gdf = gpd.GeoDataFrame(geometry=line_geometry)
+    united_buildings = buildings_in_buffer.union_all()
+    if united_buildings:
+        splited_lines = buffer_lines_gdf["geometry"].apply(lambda x: x.difference(united_buildings))
+    else:
+        splited_lines = buffer_lines_gdf["geometry"]
+
+    splited_lines_gdf = gpd.GeoDataFrame(geometry=splited_lines).explode(index_parts=True)
+    splited_lines_list = []
+
+    for _, v in splited_lines_gdf.groupby(level=0):
+        splited_lines_list.append(v.iloc[0]["geometry"].coords[-1])
+    circuit = Polygon(splited_lines_list)
+    if united_buildings:
+        circuit = circuit.difference(united_buildings)
+
+    result_gdf = gpd.GeoDataFrame(geometry=[circuit], crs=local_crs).to_crs(original_crs)
+    return result_gdf if return_gdf else result_gdf.iloc[0].geometry
+
+
+def get_visibilities_from_points(
+    points: gpd.GeoDataFrame,
+    obstacles: gpd.GeoDataFrame,
+    view_distance: int,
+    sectors_n=None,
+    max_workers: int = cpu_count(),
+) -> list[Polygon]:
+    """
+    Calculate visibility polygons from a set of points considering obstacles within a specified view distance.
+
+    Args:
+        points (gpd.GeoDataFrame):
+            GeoDataFrame containing the points from which visibility is calculated.
+        obstacles (gpd.GeoDataFrame):
+            GeoDataFrame containing the obstacles that block visibility.
+        view_distance (int):
+            The maximum distance from each point within which visibility is calculated.
+        sectors_n (int, optional):
+            Number of sectors to divide the view into for more detailed visibility calculations. Defaults to None.
+        max_workers (int, optional):
+            Maximum workers in multiproccesing, multipocessing.cpu_count() by default.
+
+    Returns:
+        (list[Polygon]):
+            A list of visibility polygons for each input point.
+
+    Notes:
+        This function uses `get_visibility_accurate()` in multiprocessing way.
+
+    """
+    if points.crs != obstacles.crs:
+        raise ValueError(f"CRS mismatch, points crs:{points.crs} != obstacles crs:{obstacles.crs}")
+    if points.crs.is_geographic:
+        logger.warning("Points crs is geographic, it may produce invalid results")
+    # remove points inside polygons
+    joined = gpd.sjoin(points, obstacles, how="left", predicate="intersects")
+    points = joined[joined.index_right.isnull()]
+
+    # remove unused obstacles
+    points_view = points.geometry.buffer(view_distance).union_all()
+    s = obstacles.intersects(points_view)
+    buildings_in_buffer = obstacles.loc[s[s].index].reset_index(drop=True)
+
+    buildings_in_buffer.geometry = buildings_in_buffer.geometry.apply(
+        lambda geom: MultiPolygon([geom]) if isinstance(geom, Polygon) else geom
+    )
+    args = [(point, buildings_in_buffer, view_distance, sectors_n) for point in points.geometry]
+    all_visions = process_map(
+        _multiprocess_get_vis,
+        args,
+        chunksize=5,
+        desc="Calculating Visibility Catchment Area from each Point, it might take a while for a "
+        "big amount of points",
+        max_workers=max_workers,
+    )
+
+    # could return sectorized visions if sectors_n is set
+    return all_visions
+
+
+def calculate_visibility_catchment_area(
+    points: gpd.GeoDataFrame, obstacles: gpd.GeoDataFrame, view_distance: int | float, max_workers: int = cpu_count()
+) -> gpd.GeoDataFrame:  # pragma: no cover
+    """
+    Calculate visibility catchment areas for a large urban area based on given points and obstacles.
+    This function is designed to work with at least 1000 points spaced 10-20 meters apart for optimal results.
+    Points can be generated using a road graph.
+
+    Args:
+        points (gpd.GeoDataFrame): GeoDataFrame containing the points from which visibility is calculated.
+        obstacles (gpd.GeoDataFrame): GeoDataFrame containing the obstacles that block visibility.
+        view_distance (int | float): The maximum distance from each point within which visibility is calculated.
+        max_workers (int): Maximum workers in multiproccesing, multipocessing.cpu_count() by default.
+
+    Returns:
+        (gpd.GeoDataFrame): GeoDataFrame containing the calculated visibility catchment areas.
+    """
+
+    def filter_geoms(x):
+        if x.geom_type == "GeometryCollection":
+            return MultiPolygon([y for y in x.geoms if y.geom_type in ["Polygon", "MultiPolygon"]])
+        return x
+
+    def calc_group_factor(x):
+        return np.mean(x.new_ratio) * x.count_n
+
+    def unary_union_groups(x):
+        return unary_union(MultiPolygon(list(x["geometry"])).buffer(0))
+
+    raise NotImplementedError("This method is temporarily unsupported.")
+
+    local_crs = obstacles.estimate_utm_crs()
+    obstacles = obstacles.to_crs(local_crs)
+    points = points.to_crs(local_crs)
+
+    sectors_n = 12
+    logger.info("Calculating Visibility Catchment Area from each point")
+    all_visions_sectorized = get_visibilities_from_points(points, obstacles, view_distance, sectors_n, max_workers)
+    all_visions_sectorized = gpd.GeoDataFrame(
+        geometry=[item for sublist in all_visions_sectorized for item in sublist], crs=local_crs
+    )
+    logger.info("Calculating non-vision part...")
+    all_visions_unary = all_visions_sectorized.union_all()
+    convex = all_visions_unary.convex_hull
+    dif = convex.difference(all_visions_unary)
+
+    del convex, all_visions_unary
+
+    buf_area = (math.pi * view_distance**2) / sectors_n
+    all_visions_sectorized["ratio"] = all_visions_sectorized.area / buf_area
+    all_visions_sectorized["ratio"] = min_max_normalization(
+        all_visions_sectorized["ratio"].values, new_min=1, new_max=10
+    )
+    groups = all_visions_sectorized.sample(frac=1).groupby(all_visions_sectorized.index // 6000)
+    groups = [group for _, group in groups]
+
+    del all_visions_sectorized
+
+    groups_result = process_map(
+        _process_group,
+        groups,
+        desc="Counting intersections in each group...",
+        max_workers=max_workers,
+    )
+    logger.info("Calculating all groups intersection...")
+    all_in = combine_geometry(gpd.GeoDataFrame(data=pd.concat(groups_result), geometry="geometry", crs=local_crs))
+
+    del groups_result
+
+    all_in["count_n"] = all_in["index_right"].apply(len)
+
+    logger.info("Calculating intersection's parameters")
+    # all_in["factor"] = all_in.parallel_apply(calc_group_factor, axis=1) # TODO replace pandarallel methods
+    threshold = all_in["factor"].quantile(0.3)
+    all_in = all_in[all_in["factor"] > threshold]
+
+    all_in["factor_normalized"] = np.round(
+        min_max_normalization(np.sqrt(all_in["factor"].values), new_min=1, new_max=5)
+    ).astype(int)
+    logger.info("Calculating normalized groups geometry...")
+    all_in = (
+        all_in.groupby("factor_normalized").parallel_apply(unary_union_groups).reset_index()
+    )  # TODO replace pandarallel methods
+    all_in = gpd.GeoDataFrame(data=all_in.rename(columns={0: "geometry"}), geometry="geometry", crs=32636)
+
+    all_in = all_in.explode(index_parts=True).reset_index(drop=True)
+    all_in["area"] = all_in.area
+    threshold = all_in["area"].quantile(0.9)
+    all_in = all_in[all_in["area"] > threshold]
+    all_in = all_in.groupby("factor_normalized").apply(unary_union_groups).reset_index()
+    all_in = gpd.GeoDataFrame(data=all_in.rename(columns={0: "geometry"}), geometry="geometry", crs=32636)
+
+    all_in.geometry = all_in.geometry.buffer(20).buffer(-20).difference(dif)
+
+    all_in.sort_values(by="factor_normalized", ascending=False, inplace=True)
+    all_in.reset_index(drop=True, inplace=True)
+    logger.info("Smoothing normalized groups geometry...")
+    for ind, row in all_in.iloc[:-1].iterrows():
+        for ind2 in range(ind + 1, len(all_in)):
+            current_geometry = all_in.at[ind2, "geometry"]
+            all_in.at[ind2, "geometry"] = current_geometry.difference(row.geometry)
+            all_in["geometry"] = all_in["geometry"].apply(filter_geoms)
+
+    all_in = all_in.explode(index_parts=True)
+    logger.info("Done!")
+    return all_in
+
+
+def _multiprocess_get_vis(args):  # pragma: no cover
+    point, buildings, view_distance, sectors_n = args
+    result = get_visibility_accurate(point, buildings, view_distance)
+
+    if sectors_n is not None:
+        sectors = []
+
+        cx, cy = point.x, point.y
+
+        angle_increment = 2 * math.pi / sectors_n
+        view_distance = math.sqrt((view_distance**2) * (1 + (math.tan(angle_increment / 2) ** 2)))
+        for i in range(sectors_n):
+            angle1 = i * angle_increment
+            angle2 = (i + 1) * angle_increment
+
+            x1, y1 = cx + view_distance * math.cos(angle1), cy + view_distance * math.sin(angle1)
+            x2, y2 = cx + view_distance * math.cos(angle2), cy + view_distance * math.sin(angle2)
+
+            sector_triangle = Polygon([point, (x1, y1), (x2, y2)])
+            sector = result.intersection(sector_triangle)
+
+            if not sector.is_empty:
+                sectors.append(sector)
+        result = sectors
+    return result
+
+
+def _process_group(group):  # pragma: no cover
+    geom = group
+    combined_geometry = combine_geometry(geom)
+    combined_geometry.drop(columns=["index", "index_right"], inplace=True)
+    combined_geometry["count_n"] = combined_geometry["ratio"].apply(len)
+    combined_geometry["new_ratio"] = combined_geometry.apply(
+        lambda x: np.power(np.prod(x.ratio), 1 / x.count_n) * x.count_n, axis=1
+    )
+
+    threshold = combined_geometry["new_ratio"].quantile(0.25)
+    combined_geometry = combined_geometry[combined_geometry["new_ratio"] > threshold]
+
+    combined_geometry["new_ratio_normalized"] = min_max_normalization(
+        combined_geometry["new_ratio"].values, new_min=1, new_max=10
+    )
+
+    combined_geometry["new_ratio_normalized"] = np.round(combined_geometry["new_ratio_normalized"]).astype(int)
+
+    result_union = (
+        combined_geometry.groupby("new_ratio_normalized")
+        .agg({"geometry": lambda x: unary_union(MultiPolygon(list(x)).buffer(0))})
+        .reset_index(drop=True)
+    )
+    result_union.set_geometry("geometry", inplace=True)
+    result_union.set_crs(geom.crs, inplace=True)
+
+    result_union = result_union.explode("geometry", index_parts=False).reset_index(drop=True)
+
+    representative_points = combined_geometry.copy()
+    representative_points["geometry"] = representative_points["geometry"].representative_point()
+
+    joined = gpd.sjoin(result_union, representative_points, how="inner", predicate="contains").reset_index()
+    joined = joined.groupby("index").agg({"geometry": "first", "new_ratio": lambda x: np.mean(list(x))})
+
+    joined.set_geometry("geometry", inplace=True)
+    joined.set_crs(geom.crs, inplace=True)
+    return joined

objectnat-1.3.3.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: ObjectNat
+Version: 1.3.3
+Summary: ObjectNat is an open-source library created for geospatial analysis created by IDU team
+License: BSD-3-Clause
+License-File: LICENSE.txt
+Author: DDonnyy
+Author-email: 63115678+DDonnyy@users.noreply.github.com
+Requires-Python: >=3.11,<3.13
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: geopandas (>=1.0.1,<2.0.0)
+Requires-Dist: loguru (>=0.7.3,<0.8.0)
+Requires-Dist: networkx (>=3.4.2,<4.0.0)
+Requires-Dist: numpy (>=2.1.3,<3.0.0)
+Requires-Dist: pandas (>=2.2.0,<3.0.0)
+Requires-Dist: scikit-learn (>=1.4.0,<2.0.0)
+Requires-Dist: tqdm (>=4.66.2,<5.0.0)
+Description-Content-Type: text/x-rst
+
+ObjectNat
+=========
+
+Object-oriented Network Analysis Tools
+--------------------------------------
+
+.. |badge-black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+   :alt: Code style: black
+
+.. |badge-pypi| image:: https://img.shields.io/pypi/v/objectnat.svg
+   :target: https://pypi.org/project/objectnat/
+   :alt: PyPI version
+
+.. |badge-ci| image:: https://github.com/IDUclub/ObjectNat/actions/workflows/ci_pipeline.yml/badge.svg
+   :target: https://github.com/IDUclub/ObjectNat/actions/workflows/ci_pipeline.yml
+   :alt: CI
+
+.. |badge-codecov| image:: https://codecov.io/gh/DDonnyy/ObjectNat/graph/badge.svg?token=K6JFSJ02GU
+   :target: https://codecov.io/gh/DDonnyy/ObjectNat
+   :alt: Coverage
+
+.. |badge-license| image:: https://img.shields.io/badge/license-BSD--3--Clause-blue.svg
+   :target: https://opensource.org/licenses/BSD-3-Clause
+   :alt: License
+
+.. |badge-docs| image:: https://img.shields.io/badge/docs-latest-4aa0d5?logo=readthedocs
+   :target: https://iduclub.github.io/ObjectNat/
+   :alt: Docs
+
+|badge-black| |badge-pypi| |badge-ci| |badge-codecov| |badge-license| |badge-docs|
+
+`РИДМИ (Russian) <https://github.com/IDUclub/ObjectNat/blob/master/README_RU.rst>`__
+
+.. image:: https://raw.githubusercontent.com/IDUclub/ObjectNat/master/docs/_static/ONlogo.svg
+   :align: center
+   :width: 400
+   :alt: ObjectNat logo
+
+
+**ObjectNat** is an open-source library developed by the **IDU** team
+for spatial and network analysis in urban studies.
+The library provides tools for analyzing **accessibility**, **visibility**,
+**noise propagation**, and **service provision**.
+----
+
+Key Features
+------------
+
+Each feature includes a **Jupyter Notebook example** and **full documentation**.
+
+1. **Isochrones and Transport Accessibility**  
+
+   Isochrones represent areas reachable from an origin point within a specified time along a transport network.
+   This feature allows the analysis of transport accessibility using pedestrian, road,
+   public transport, or multimodal graphs.
+
+   The library supports several methods for building isochrones:
+
+   - **Basic isochrones**: display a single zone reachable within a specified time.
+   - **Step isochrones**: divide the accessibility area into time intervals (e.g., 3, 5, 10 minutes).
+
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/isochrones.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/isochrones.html>`__
+
+2. **Graph Coverage Zones from Points**
+
+   A function for generating **coverage areas** from a set of origin points using a transport network.
+   It computes the area reachable from each point by **travel time** or **distance**,
+   then builds polygons using **Voronoi diagrams** and clips them by a given boundary if specified.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/coverage.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/coverage.html>`__
+
+3. **Service Provision Analysis**  
+
+   A function to evaluate how well residential buildings and their populations are provided
+   with services (e.g., schools, clinics) that have limited **capacity**
+   and a defined **accessibility threshold** (in minutes or meters).
+   The function models the **balance between supply and demand**,
+   assessing how well services meet the needs of nearby buildings within an acceptable time.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/provision.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/provision.html>`__
+
+4. **Visibility Analysis**  
+
+   A function for evaluating visibility from a given point or set of points to nearby buildings within a given radius.
+   It is used to assess visual accessibility in urban environments.
+   A module is also implemented for computing **visibility coverage zones**
+   using a dense observer grid (recommended ~1000 points with a 10–20 m spacing).
+   Points can be generated along the transport network and distributed across its edges.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/visibility.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/visibility.html>`__
+
+5. **Noise Simulation & Noise Frame**
+
+   Simulation of noise propagation from sources, taking into account **obstacles**, **vegetation**,
+   and **environmental factors**.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/noise.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/noise.html>`__
+   🧠 `Detailed theory <https://github.com/DDonnyy/ObjectNat/wiki/Noise-simulation>`__
+
+6. **Point Clusterization**  
+
+   A function for constructing **cluster polygons** based on a set of points using:
+
+   - Minimum **distance** between points.
+   - Minimum **number of points** in a cluster.
+
+   The function can also compute the **ratio of service types** in each cluster
+   for spatial analysis of service composition.
+
+   📘 `Example <https://iduclub.github.io/ObjectNat/methods/examples/clustering.html>`__
+   🔗 `Documentation <https://iduclub.github.io/ObjectNat/methods/clustering.html>`__
+
+----
+
+City Graphs via *IduEdu*
+------------------------
+
+For optimal performance, **ObjectNat** is recommended to be used with graphs
+created by the `IduEdu <https://github.com/IDUclub/IduEdu>`_ library.
+
+**IduEdu** is an open-source Python library designed for building and processing
+complex urban networks based on OpenStreetMap data.
+
+
+**IduEdu** can be installed via ``pip``::
+
+    pip install IduEdu
+
+Example usage::
+
+    from iduedu import get_4326_boundary, get_intermodal_graph
+
+    poly = get_4326_boundary(osm_id=1114252)
+    G_intermodal = get_intermodal_graph(territory=poly, clip_by_territory=True)
+
+----
+
+Installation
+------------
+
+**ObjectNat** can be installed via ``pip``::
+
+    pip install ObjectNat
+
+----
+
+Configuration
+-------------
+
+You can adjust logging and progress bar output using the config module::
+
+    from objectnat import config
+
+    config.change_logger_lvl("INFO")   # mute debug logs
+    config.set_enable_tqdm(False)      # disable tqdm progress bars
+
+----
+
+Contacts
+--------
+
+- `NCCR <https://actcognitive.org/>`_ — National Center for Cognitive Research  
+- `IDU <https://idu.itmo.ru/>`_ — Institute of Design and Urban Studies  
+- `Natalya Chichkova <https://t.me/nancy_nat>`_ — Project Manager  
+- `Danila Oleynikov (Donny) <https://t.me/ddonny_dd>`_ — Lead Software Engineer
+
+----
+
+Publications
+------------
+
+Coming soon.
+