Merge pull request #199 from kartverket/docstring_building_update

Docstring building update

generalization/n100/building/building_main.py

@@ -27,6 +27,8 @@
 @timing_decorator
 def main():
     """
+    Building N100 Generalization version 1.0
+
     What:
         MORE DOCSTRING NEEDED: Runs the building generalization logic.
     How:
@@ -37,7 +39,7 @@ def main():
             Simplify building polygons to make them easier to read and fit around other features at a N100 map scale.
 
         calculate_polygon_values:
-            PLACEHOLDER DOCSTRING NEEDS TO BE UPDATED.
+            Adds required fields for building point for symbology and resolves building conflicts: angle, hierarchy, and invisibility.
 
         polygon_propogate_displacement:
             Propagates displacement for building polygons to ensure their alignment with roads is adjusted
@@ -47,7 +49,7 @@ def main():
             PLACEHOLDER DOCSTRING NEEDS TO BE UPDATED.
 
         polygon_to_point:
-            PLACEHOLDER DOCSTRING NEEDS TO BE UPDATED.
+            Merges all points originating from building polygons to a single point feature.
 
         calculate_point_values:
             Adds required fields for building point for symbology and resolves building conflicts: angle, hierarchy, and invisibility.
@@ -68,16 +70,19 @@ def main():
             PLACEHOLDER DOCSTRING NEEDS TO BE UPDATED.
 
         removing_points_and_erasing_polygons_in_water_features:
-            PLACEHOLDER DOCSTRING NEEDS TO BE UPDATED.
+            Fixes geometric conflicts between building polygon/point objects and water-features. Allows for
+            tourist cabins to intersect water-features.
 
         removing_overlapping_polygons_and_points:
-            PLACEHOLDER DOCSTRING NEEDS TO BE UPDATED.
+            Resolves graphic conflicts and overlaps between building features which persist after RBC,
+            prioritizing buildings with higher hierarchy values.
 
         finalizing_buildings:
-            PLACEHOLDER DOCSTRING NEEDS TO BE UPDATED.
+            Separates building points and polygons into their respective features they are going to be delivered as.
 
         data_clean_up:
-            PLACEHOLDER DOCSTRING NEEDS TO BE UPDATED.
+            Deletes all fields for each feature expect the fields which should be kept in the delivered product.
+            Then adds last edited date and finally checks and potentially repairs the geometry of each feature.
     Why:
         MORE DOCSTRING NEEDED: Because we need to processing building information so it is cartographic usable for N100 scale.
     """

generalization/n100/building/calculate_polygon_values.py

@@ -12,15 +12,29 @@
 @timing_decorator
 def main():
     """
-    Summary:
+    What:
         Adds required fields for building point for symbology and resolves building conflicts: angle, hierarchy, and invisibility.
+
+    How:
+        adding_angle_hierarchy_invisibility_fields:
+            Adds angle, hierarchy and invisibility fields and set their corresponding values.
+
+        adding_symbol_val:
+            Adds symbol_val and reclassify NBR values for undefined nbr values
+
+    Why:
+        The angle, hierarchy and invisibility fields are used in future processing, such as polygon_processor and RBC.
     """
 
     adding_angle_hierarchy_invisibility_fields()
     adding_symbol_val()
 
 
 def adding_angle_hierarchy_invisibility_fields():
+    """
+    Adds angle, hierarchy and invisibility fields and set their corresponding values.
+    """
+
     # Adding multiple fields
     print("Adding fields...")
     arcpy.management.AddFields(
@@ -39,13 +53,16 @@ def adding_angle_hierarchy_invisibility_fields():
         expression_type="PYTHON3",
         fields=[
             ["angle", "0"],
-            ["hierarchy", "1"],  # Hierachy 1 so buildings can be moved around
+            ["hierarchy", "1"],  # Hierarchy 1 so buildings can be moved around
             ["invisibility", "0"],
         ],
     )
 
 
 def adding_symbol_val():
+    """
+    Adds symbol_val and reclassify NBR values for undefined nbr values
+    """
     arcpy.AddField_management(
         in_table=Building_N100.simplify_polygons___spatial_join_polygons___n100_building.value,
         field_name="symbol_val",

generalization/n100/building/data_clean_up.py

@@ -15,17 +15,41 @@
 # Main function
 @timing_decorator
 def main():
+    """
+    What:
+        Deletes all fields for each feature expect the fields which should be kept in the delivered product.
+        Then adds last edited date and finally checks and potentially repairs the geometry of each feature.
+    How:
+        keep_necessary_fields:
+            It runs the keep_necessary_fields function for each feature keeping only required fields.
+
+        add_last_edited_date_to_all_feature_classes:
+            Adds a 'last_edited_date' field to specified feature classes and sets it to the current date and time.
+
+        check_and_repair_geometry:
+            Checks and potentially repairs geometry for the final outputs.
+    Why:
+        For each feature there should be no other field present other than the ones which is specified.
+    """
+
     environment_setup.main()
     keep_necessary_fields(
-        Building_N100.BygningsPunkt.value,
-        ["objtype", "byggtyp_nbr", "målemetode", "nøyaktighet", "last_edited_date"],
+        input_layer=Building_N100.BygningsPunkt.value,
+        list_of_fields=[
+            "objtype",
+            "byggtyp_nbr",
+            "målemetode",
+            "nøyaktighet",
+            "last_edited_date",
+        ],
     )
     keep_necessary_fields(
-        Building_N100.Grunnriss.value, ["objtype", "byggtyp_nbr", "last_edited_date"]
+        input_layer=Building_N100.Grunnriss.value,
+        list_of_fields=["objtype", "byggtyp_nbr", "last_edited_date"],
     )
     keep_necessary_fields(
-        Building_N100.TuristHytte.value,
-        [
+        input_layer=Building_N100.TuristHytte.value,
+        list_of_fields=[
             "objtype",
             "byggtyp_nbr",
             "betjeningsgrad",
@@ -38,11 +62,12 @@ def main():
         ],
     )
     keep_necessary_fields(
-        Building_N100.OmrissLinje.value,
-        ["objtype", "målemetode", "nøyaktighet", "last_edited_date"],
+        input_layer=Building_N100.OmrissLinje.value,
+        list_of_fields=["objtype", "målemetode", "nøyaktighet", "last_edited_date"],
     )
     keep_necessary_fields(
-        Building_N100.Piktogram.value, ["byggtyp_nbr", "last_edited_date"]
+        input_layer=Building_N100.Piktogram.value,
+        list_of_fields=["byggtyp_nbr", "last_edited_date"],
     )
 
     check_and_repair_geometry()
@@ -51,10 +76,19 @@ def main():
 
 
 @timing_decorator
-def keep_necessary_fields(input_layer, list_of_fields):
+def keep_necessary_fields(input_layer: str, list_of_fields: list[str]):
     """
-    Summary:
-        Deletes all fields from the input feature class except for a specified set of fields.
+    What:
+        Deletes all fields from the input feature class except for a fields specified in a list.
+
+    How:
+        Retrieves all fields from the input feature. It has a static set of fields always to be kept regardless
+        of parameter input. It then removes all static and provided fields from the list of fields to remove.
+        Then deletes all unspecified fields.
+
+    Args:
+        input_layer (str): The input feature to clean up.
+        list_of_fields (list[str]): The fields to be kept in addition to static fields.
     """
     # Provide the path to your feature class
     feature_class_to_clean_up = input_layer
@@ -89,8 +123,7 @@ def keep_necessary_fields(input_layer, list_of_fields):
 
 def add_last_edited_date_to_all_feature_classes():
     """
-    Summary:
-        Adds a 'last_edited_date' field to specified feature classes and sets it to the current date and time.
+    Adds a 'last_edited_date' field to specified feature classes and sets it to the current date and time.
     """
     all_final_layers = [
         Building_N100.BygningsPunkt.value,
@@ -129,6 +162,9 @@ def add_last_edited_date_to_all_feature_classes():
 
 
 def check_and_repair_geometry():
+    """
+    Checks and potentially repairs geometry for the final outputs.
+    """
     input_features_validation = {
         "building_points": Building_N100.BygningsPunkt.value,
         "building_polygons": Building_N100.Grunnriss.value,

generalization/n100/building/finalizing_buildings.py

@@ -12,6 +12,25 @@
 
 
 def main():
+    """
+    What:
+        Separates building points and polygons into their respective features they are going to be delivered as.
+    How:
+        removing_points_in_and_close_to_urban_areas:
+            Makes sure there are no building points near urban areas, except for hospital, churches and tourist huts.
+
+        selecting_all_tourist_cabins:
+            Selects tourist cabins from building points to be delivered as a separate feature.
+
+        building_polygons_to_line:
+            Converts building polygons to lines, to creat omrisslinje feature.
+
+        selecting_hospital_and_churches_for_pictogram_featureclass:
+            Selects building points categorized as hospitals or churches for inclusion in a pictogram feature.
+
+        assigning_final_file_names:
+            Copies final feature classes to their respective output file locations in the "final_outputs.gdb"
+    """
     environment_setup.main()
     removing_points_in_and_close_to_urban_areas()
     selecting_all_tourist_cabins()
@@ -23,8 +42,7 @@ def main():
 @timing_decorator
 def removing_points_in_and_close_to_urban_areas():
     """
-    Summary:
-        Selects and processes building points based on their proximity to urban areas, keeping those further away and merging specific points.
+    Makes sure there are no building points near urban areas, except for hospital, churches and tourist huts.
     """
     # Defining sql expression to select urban areas
     urban_areas_sql_expr = "objtype = 'Tettbebyggelse' Or objtype = 'Industriområde' Or objtype = 'BymessigBebyggelse'"
@@ -75,8 +93,7 @@ def removing_points_in_and_close_to_urban_areas():
 @timing_decorator
 def selecting_all_tourist_cabins():
     """
-    Summary:
-        Selects building points categorized as tourist cabins and distinguishes them from other building points.
+    Selects tourist cabins from building points to be delivered as a separate feature.
     """
     selecting_tourist_cabins = "byggtyp_nbr = 956"
 
@@ -97,8 +114,7 @@ def selecting_all_tourist_cabins():
 
 def building_polygons_to_line():
     """
-    Summary:
-        Converts building polygons to lines
+    Converts building polygons to lines, to creat omrisslinje feature.
     """
     arcpy.management.PolygonToLine(
         in_features=Building_N100.removing_overlapping_polygons_and_points___polygons_NOT_intersecting_road_buffers___n100_building.value,
@@ -123,8 +139,7 @@ def building_polygons_to_line():
 
 def selecting_hospital_and_churches_for_pictogram_featureclass():
     """
-    Summary:
-        Selects building points categorized as hospitals or churches for inclusion in a pictogram feature class.
+    Selects building points categorized as hospitals or churches for inclusion in a pictogram feature.
     """
     custom_arcpy.select_attribute_and_make_permanent_feature(
         input_layer=Building_N100.finalizing_buildings___all_points_except_tourist_cabins___n100_building.value,
@@ -136,8 +151,7 @@ def selecting_hospital_and_churches_for_pictogram_featureclass():
 @timing_decorator
 def assigning_final_file_names():
     """
-    Summary:
-        Copies final feature classes to their respective output file locations in the "final_outputs.gdb"
+    Copies final feature classes to their respective output file locations in the "final_outputs.gdb".
     """
     arcpy.management.CopyFeatures(
         Building_N100.finalizing_buildings___tourist_cabins___n100_building.value,

generalization/n100/building/polygon_to_point.py

@@ -15,15 +15,23 @@
 @timing_decorator
 def main():
     """
-    This function creates points from small polygons lost during aggregation, and merges
-    them together with collapsed points from the tools simplify building and simplify polygon.
+    What:
+        Merges all points originating from building polygons to a single point feature.
+    How:
+        building_polygons_to_points:
+            First does a spatial join on all collapsed points from simplify_polygons. Then merges all points from building polygons
+            to a single point feature.
     """
     environment_setup.main()
     building_polygons_to_points()
 
 
 @timing_decorator
 def building_polygons_to_points():
+    """
+    First does a spatial join on all collapsed points from simplify_polygons. Then merges all points from building polygons
+    to a single point feature.
+    """
     # List of building points which will be spatially joined with building polygons
     input_points = [
         f"{Building_N100.simplify_polygons___simplify_polygon___n100_building.value}_Pnt",