add docs for read_geojson

Also fix other docs contents
UTokyo-FieldPhenomics-Lab · Jan 9, 2024 · 148b1ec · 148b1ec
1 parent 60c0986
commit 148b1ec
Show file tree

Hide file tree

Showing 6 changed files with 134 additions and 81 deletions.
diff --git a/docs/python_api/manualdoc/easyidp.roi.ROI.rst b/docs/python_api/manualdoc/easyidp.roi.ROI.rst
@@ -23,6 +23,7 @@
       ~ROI.open
       ~ROI.read_labelme_json
       ~ROI.read_shp
+      ~ROI.read_geojson
 
    .. rubric:: Attributes
 

diff --git a/easyidp/jsonfile.py b/easyidp/jsonfile.py
@@ -97,67 +97,95 @@ def read_geojson(geojson_path, name_field=None, include_title=False, return_proj
 
     Returns
     -------
-    dict
+    dict, 
+        the dictionary with read numpy polygon coordinates
+
         .. code-block:: python
 
-            {
-                'crs': pyproj.CRS, 
-                'geometry': [ 
-                    {'coordiante': [[[...]]], 'type': '...'}, 
-                    ... 
-                ], 
-                'property': [ 
-                    {key1: v1, key2: v2},
-                    ... 
-                ]
-            }
+            {'id1': np.array([[x1,y1],[x2,y2],...]),
+             'id2': np.array([[x1,y1],[x2,y2],...]),...}
+    pyproj.CRS, optional
+        once set return_proj=True
     
     Example
     -------
+
+    The example geojons file has the following columns:
+
+    .. code-block:: text
+
+         [0] FID    [1] 試験区    [2] ID    [3] 除草剤    [4] plotName    [5] lineNum
+        ---------  ------------  --------  ------------  --------------  -------------
+           65       SubBlk 2b       0           有          Enrei-10           1
+           97       SubBlk 2b       0           有          Enrei-20           1
+           147      SubBlk 2b       0           有        Nakasenri-10         1
+           ...         ...         ...         ...            ...             ...
+           259        SB 0a         0                    Tachinagaha-10        3
+            4         SB 0a         0                    Fukuyutaka-10         3
+            1       SubBlk 2a       0           無          Enrei-20           1
+
     Data prepare:
 
     .. code-block:: python
 
         >>> import easyidp as idp
         >>> test_data = idp.data.TestData()
+        >>> data_path = test_data.json.geojson_soy
 
-    Use this function:
+    Use this function to read geojson:
 
     .. code-block:: python
 
-        >>> out = idp.jsonfile.read_json(test_data.json.geojson_soy)
-        >>> out
-        {'crs': <Projected CRS: EPSG:6677>
-            Name: JGD2011 / Japan Plane Rectangular CS IX
-            Axis Info [cartesian]:
-            - X[north]: Northing (metre)
-            - Y[east]: Easting (metre)
-            Area of Use:
-            - name: Japan - onshore - Honshu - Tokyo-to.
-            - bounds: (138.4, 29.31, 141.11, 37.98)
-            Coordinate Operation:
-            - name: Japan Plane Rectangular CS zone IX
-            - method: Transverse Mercator
-            Datum: Japanese Geodetic Datum 2011
-            - Ellipsoid: GRS 1980
-            - Prime Meridian: Greenwich,
-         'geometry': [
-            { 
-                "coordinates": [[[-26384.952573, -28870.678514], ..., [-26384.952573, -28870.678514]]], 
-                "type": "Polygon" 
-            },
-            ...
-         ],
-         'property': [
-            {'FID': 65,
-             '試験区': 'SubBlk 2b',
-             'ID': 0,
-             '除草剤': '有',
-             'plotName': 'Enrei-10',
-             'lineNum': 1},
-            ...
-         ]
-        }
+        >>> out = idp.jsonfile.read_geojson(data_path)
+        >>> out['196']  
+        array([[-26403.247163, -28847.161464],
+               [-26404.137868, -28843.261904],
+               [-26404.820258, -28843.417749],
+               [-26403.929552, -28847.317309],
+               [-26403.247163, -28847.161464]])
+
+    .. caution::
+
+        The ``196`` in previous code is the row 196, not the ``FID``=196. 
+        To use the FID as result key, Please use ``name_field`` introduced below
+               
+    If want use other attributes as result keys, for example, the first column ``FID`` as the key:
+
+    .. code-block:: python
+
+        >>> out = idp.jsonfile.read_geojson(data_path, name_field="FID")
+        >>> # or
+        >>> out = idp.jsonfile.read_geojson(data_path, name_field="0")
+        >>> out['196']
+        array([[-26391.733164, -28862.99536 ],
+               [-26392.623851, -28859.09578 ],
+               [-26393.306263, -28859.25163 ],
+               [-26392.415575, -28863.15121 ],
+               [-26391.733164, -28862.99536 ]])
+
+    You can also combine multiple columns as the key values, by passing a list to ``name_field``:
+
+    .. code-block:: python
+
+        >>> out = idp.jsonfile.read_geojson(data_path, name_field=["FID", "plotName"])
+        >>> # or
+        >>> out = idp.jsonfile.read_geojson(data_path, name_field=[0, 4])
+        >>> out.keys()
+        dict_keys(['65_Enrei-10', '97_Enrei-20', '147_Nakasenri-10', ... ])
+
+    And you can also add column_names to id by ``include_title=True`` :
+
+    .. code-block:: python
+
+        >>> out = idp.jsonfile.read_geojson(data_path, name_field=["FID", "plotName"], include_title=True)
+        >>> # or
+        >>> out = idp.jsonfile.read_geojson(data_path, name_field=[0, 4], include_title=True)
+        >>> out.keys()
+         dict_keys(['FID_65_plotName_Enrei-10', 'FID_97_plotName_Enrei-20', ... ])
+
+    See also
+    --------
+    easyidp.jsonfile.show_geojson_fields, easyidp.shp.read_shp
 
     """
     geo_dict = {}
@@ -276,19 +304,15 @@ def show_geojson_fields(geojson_path):
         >>> test_data = idp.data.TestData()
 
         >>> idp.jsonfile.show_geojson_fields(test_data.json.geojson_soy)
-                          Properties of /Users/hwang/Library/Application                   
-             Support/easyidp.data/data_for_tests/json_test/2023_soybean_field.geojson      
-        ────────────────────────────────────────────────────────────────────────────────── 
-         [-1]   [0] FID   [1] 試験区   [2] ID   [3] 除草剤    [4] plotName    [5] lineNum  
-        ────────────────────────────────────────────────────────────────────────────────── 
-            0     65      SubBlk 2b      0          有          Enrei-10           1       
-            1     97      SubBlk 2b      0          有          Enrei-20           1       
-            2     147     SubBlk 2b      0          有        Nakasenri-10         1       
-          ...     ...        ...        ...        ...            ...             ...      
-          257     259       SB 0a        0                   Tachinagaha-10        3       
-          258      4        SB 0a        0                   Fukuyutaka-10         3       
-          259      1      SubBlk 2a      0          無          Enrei-20           1       
-        ──────────────────────────────────────────────────────────────────────────────────
+         [0] FID    [1] 試験区    [2] ID    [3] 除草剤    [4] plotName    [5] lineNum
+        ---------  ------------  --------  ------------  --------------  -------------
+           65       SubBlk 2b       0           有          Enrei-10           1
+           97       SubBlk 2b       0           有          Enrei-20           1
+           147      SubBlk 2b       0           有        Nakasenri-10         1
+           ...         ...         ...         ...            ...             ...
+           259        SB 0a         0                    Tachinagaha-10        3
+            4         SB 0a         0                    Fukuyutaka-10         3
+            1       SubBlk 2a       0           無          Enrei-20           1
     
     See also
     --------

diff --git a/easyidp/metashape.py b/easyidp/metashape.py
@@ -106,9 +106,9 @@ def __init__(self, project_path=None, chunk_id=None, raw_img_folder=None, check_
         self.meta = self.meta
         #: whether this project is activated, (often for Metashape), ``<class 'bool'>``
         self.enabled = self.enabled
-        #: the container for all sensors in this project (camera model), ``<class 'easyidp.Container'>``
+        #: the container for all sensors in this project (camera model), ``<class 'easyidp.Container'>``, a dict-like object consisted by :py:class:`Sensor <easyidp.reconstruct.Sensor>`
         self.sensors = self.sensors
-        #: the container for all photos used in this project (images), ``<class 'easyidp.Container'>``
+        #: the container for all photos used in this project (images), ``<class 'easyidp.Container'>``, a dict-like object consisted by :py:class:`Photo <easyidp.reconstruct.Photo>`
         self.photos = self.photos
 
         self.open_project(project_path, chunk_id)
@@ -389,12 +389,7 @@ def change_photo_folder(self, raw_img_folder, check_img_existance=True):
                 e.g. {'path/to/flight1/': 'new/path/to/flight1', }
         check_img_existance : bool
             Ignore the missing photos when set to False, suitable for testing project with just a few images, to avoid the FileNotFoundError
-
-        Returns
-        -------
-        _type_
-            _description_
-
+            
         """
         if isinstance(raw_img_folder, Path):
             raw_img_folder = str(raw_img_folder)

diff --git a/easyidp/reconstruct.py b/easyidp/reconstruct.py
@@ -57,9 +57,9 @@ def __init__(self):
         #: whether this project is activated, (often for Metashape), ``<class 'bool'>``
         self.enabled = True
 
-        #: the container for all sensors in this project (camera model), ``<class 'easyidp.Container'>``
+        #: the container for all sensors in this project (camera model), ``<class 'easyidp.Container'>``, a dict-like object consisted by :py:class:`Sensor <easyidp.reconstruct.Sensor>`
         self.sensors = idp.Container()
-        #: the container for all photos used in this project (images), ``<class 'easyidp.Container'>``
+        #: the container for all photos used in this project (images), ``<class 'easyidp.Container'>``, a dict-like object consisted by :py:class:`Photo <easyidp.reconstruct.Photo>`
         self.photos = idp.Container()
 
         #: the world crs for geocentric coordiante, ``<class 'pyproj.crs.crs.CRS'>``
@@ -178,7 +178,7 @@ def __init__(self):
         #: focal length, unit in mm, ``<class 'float'>``
         self.focal_length = 0.0  # in mm
 
-        #: sensor calibration information, :class:`easyidp.reconstruct.Calibration`
+        #: sensor calibration information, :py:class:`easyidp.Calibration <easyidp.reconstruct.Calibration>`
         self.calibration = Calibration(self)
 
     def in_img_boundary(self, polygon_hv, ignore=None, log=False):
@@ -299,7 +299,7 @@ def __init__(self, sensor=None):
 
         #: the id of the camera model (sonsor), ``<class 'int'>``
         self.sensor_id = 0
-        #: the object of the camera model (sensor), :class:`easyidp.reconstruct.Sensor`
+        #: the object of the camera model (sensor), :class:`easyidp.Sensor <easyidp.reconstruct.Sensor>`
         self.sensor = sensor
 
         #: whether this image is used in the 3D reconstruction,  ``<class 'bool'>``
@@ -356,7 +356,7 @@ def __init__(self, sensor=None):
         self.software = "metashape"
         #: the calibration type, same as the sensor.type, in [frame, fisheye, spherical, rpc], by default 'frame'
         self.type = "frame"
-        #: the object of the camera model (sensor), :class:`easyidp.reconstruct.Sensor`
+        #: the object of the camera model (sensor), :py:class:`Sensor <easyidp.reconstruct.Sensor>`
         self.sensor = sensor
 
         #: focal length, unit is pixel, for pix4d project, convert mm to pixel. ``<class 'float'>``

diff --git a/easyidp/roi.py b/easyidp/roi.py
@@ -32,7 +32,7 @@ def __init__(self, target_path=None, **kwargs):
 
             >>> roi = idp.ROI(test_data.shp.lotus_shp, name_field=0)
             [shp][proj] Use projection [WGS 84] for loaded shapefile [lotus_plots.shp]
-            Read shapefile [lotus_plots.shp]: 100%|██████████████| 112/112 [00:00<00:00, 2559.70it/s]
+            Read shapefile [lotus_plots.shp]: 100%|███████████| 112/112 [00:00<00:00, 2559.70it/s]
 
             >>> roi
             <easyidp.ROI> with 112 items
@@ -172,7 +172,7 @@ def read_shp(self, shp_path, shp_proj=None, name_field=None, include_title=False
 
             >>> roi.read_shp(test_data.shp.lotus_shp, name_field=0)
             [shp][proj] Use projection [WGS 84] for loaded shapefile [lotus_plots.shp]
-            Read shapefile [lotus_plots.shp]: 100%|██████████████| 112/112 [00:00<00:00, 2559.70it/s]
+            Read shapefile [lotus_plots.shp]: 100%|███████████| 112/112 [00:00<00:00, 2559.70it/s]
             >>> roi
             <easyidp.ROI> with 112 items
             [0]     N1W1
@@ -299,15 +299,44 @@ def read_geojson(self, geojson_path, name_field=None, include_title=False):
 
         .. code-block:: python
 
-            >>> roi.read_shp(test_data.shp.lotus_shp, name_field=0)
-            [shp][proj] Use projection [WGS 84] for loaded shapefile [lotus_plots.shp]
-            Read shapefile [lotus_plots.shp]: 100%|██████████████| 112/112 [00:00<00:00, 2559.70it/s]
+            >>> roi.read_geojson(test_data.json.geojson_soy, name_field="FID")
+            Read geojson [2023_soybean_field.geojson]: 100%|███████████| 260/260         [00:00<00:00, 218234.75it/s]
+        
             >>> roi
-
+            <easyidp.ROI> with 260 items
+            [0]	65
+            array([[-26384.952573, -28870.678514],
+                   [-26384.269447, -28870.522501],
+                   [-26385.160022, -28866.622912],
+                   [-26385.843163, -28866.778928],
+                   [-26384.952573, -28870.678514]])
+            [1]	97
+            array([[-26386.065868, -28865.804036],
+                   [-26385.382668, -28865.648006],
+                   [-26386.273244, -28861.748416],
+                   [-26386.956458, -28861.90445 ],
+                   [-26386.065868, -28865.804036]])
+            ...
+            [258]	4
+            array([[-26404.447166, -28860.770249],
+                   [-26405.337854, -28856.870669],
+                   [-26406.020223, -28857.026509],
+                   [-26405.129644, -28860.926114],
+                   [-26404.447166, -28860.770249]])
+            [259]	1
+            array([[-26393.693576, -28844.979604],
+                   [-26394.58426 , -28841.08004 ],
+                   [-26395.26665 , -28841.235885],
+                   [-26394.375966, -28845.135449],
+                   [-26393.693576, -28844.979604]])
+        
+        Notes
+        -----
+        For more details of these parameters, please refer to :func:`easyidp.jsonfile.read_geojson`
 
         See also
         --------
-        easyidp.jsonfile.read_geojson, easyidp.jsonfile.show_geojson_fields
+        easyidp.jsonfile.show_geojson_fields
         """
         pass
 

diff --git a/easyidp/shp.py b/easyidp/shp.py
@@ -217,7 +217,7 @@ def read_shp(shp_path, shp_proj=None, name_field=None, include_title=False, enco
         >>> # or 
         >>> out = idp.shp.read_shp(data_path, name_field=1, encoding='gbk')
         [shp][proj] Use projection [WGS 84] for loaded shapefile [complex_shp_review.shp]
-        [shp] read shp [complex_shp_review.shp]: 100%|███████████████████████████████████████| 323/323 [00:02<00:00, 143.13it/s] 
+        [shp] read shp [complex_shp_review.shp]: 100%|███████████| 323/323 [00:02<00:00, 143.13it/s] 
         >>> out['23010...0000'] 
         array([[ 45.83319255, 126.84383445],
                [ 45.83222256, 126.84212197],
@@ -233,7 +233,7 @@ def read_shp(shp_path, shp_proj=None, name_field=None, include_title=False, enco
         >>> # or
         >>> out = idp.shp.read_shp(data_path, name_field=[2, 1], include_title=True, encoding='gbk') 
         [shp][proj] Use projection [WGS 84] for loaded shapefile [complex_shp_review.shp]
-        [shp] read shp [complex_shp_review.shp]: 100%|███████████████████████████████████████| 323/323 [00:02<00:00, 143.13it/s] 
+        [shp] read shp [complex_shp_review.shp]: 100%|███████████| 323/323 [00:02<00:00, 143.13it/s] 
         >>> out.keys()
         dict_keys(['小麦_23010...0000', '蔬菜_23010...0012', '玉米_23010...0014', ... ])
 
@@ -245,6 +245,10 @@ def read_shp(shp_path, shp_proj=None, name_field=None, include_title=False, enco
         >>> out.keys()
         dict_keys(['CROPTYPE_小麦_MASSIFID_23010...0000', 'CROPTYPE_蔬菜_MASSIFID_23010...0012', ... ])
 
+    See also
+    --------
+    easyidp.jsonfile.read_geojson
+
     """
     #####################################
     # check projection coordinate first #