easyidp 2.0.0__tar.gz

easyidp-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 UTokyo-FieldPhenomics-Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

easyidp-2.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.1
+Name: easyidp
+Version: 2.0.0
+Summary: A handy tool for dealing with region of interest (ROI) on the image reconstruction (Metashape & Pix4D) outputs, mainly in agriculture applications
+Home-page: https://github.com/UTokyo-FieldPhenomics-Lab/EasyIDP
+Author: Haozhou Wang
+Author-email: howcanoewang@gmail.com
+Project-URL: Documentation, https://easyidp.readthedocs.io/en/latest/
+Project-URL: Source, https://github.com/UTokyo-FieldPhenomics-Lab/EasyIDP
+Project-URL: Tracker, https://github.com/UTokyo-FieldPhenomics-Lab/EasyIDP/issues
+Project-URL: forum, https://github.com/UTokyo-FieldPhenomics-Lab/EasyIDP/discussions
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.7, <4
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.18.1
+Requires-Dist: matplotlib>=3.2.2
+Requires-Dist: scikit-image>=0.19.2
+Requires-Dist: tabulate>=0.8.9
+Requires-Dist: tqdm>=4.64.0
+Requires-Dist: pyproj>=3.4.0
+Requires-Dist: tifffile>=2020.09.03
+Requires-Dist: imagecodecs>=2021.11.20
+Requires-Dist: shapely~=1.8.0
+Requires-Dist: lazrs>=0.1.1
+Requires-Dist: laspy>=2.1.2
+Requires-Dist: plyfile==0.7.2
+Requires-Dist: pyshp==2.1.3
+Requires-Dist: geojson>=3.1.0
+Requires-Dist: gdown>=4.7.3
+Provides-Extra: docs
+Requires-Dist: sphinx==5.3.0; extra == "docs"
+Requires-Dist: sphinx-intl==2.0.1; extra == "docs"
+Requires-Dist: sphinx-inline-tabs==2022.1.2b11; extra == "docs"
+Requires-Dist: furo==2022.12.7; extra == "docs"
+Requires-Dist: nbsphinx==0.8.11; extra == "docs"
+Requires-Dist: sphinx-gallery==0.10.1; extra == "docs"
+Requires-Dist: ipython==8.10.0; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7.1.2; extra == "test"
+Provides-Extra: build
+Requires-Dist: packaging>=20.0; extra == "build"
+Requires-Dist: wheel; extra == "build"
+Requires-Dist: numpy>=1.19; extra == "build"
+Requires-Dist: build; extra == "build"
+
+<div align="center">
+
+<p>
+   <!-- <a align="left" href="https://ultralytics.com/yolov5" target="_blank"> -->
+   <img width="850" src="https://github.com/UTokyo-FieldPhenomics-Lab/EasyIDP/raw/v2.0/docs/_static/images/header_v2.0.png"></a>
+</p>
+
+<p align="center">
+  <img alt="GitHub Actions Badge" src="https://github.com/UTokyo-FieldPhenomics-Lab/EasyIDP/actions/workflows/pytest.yml/badge.svg?style=plastic">
+  <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/easyidp?style=plastic">
+  <img alt="GitHub" src="https://img.shields.io/github/license/UTokyo-FieldPhenomics-Lab/EasyIDP?style=plastic">
+  <img alt="GitHub top language" src="https://img.shields.io/github/languages/top/UTokyo-FieldPhenomics-Lab/EasyIDP?style=plastic">
+  <img alt="GitHub Downloads" src="https://img.shields.io/github/downloads/UTokyo-FieldPhenomics-Lab/EasyIDP/total?label=github%20downloads&style=plastic">
+  <img alt="GitHub Downloads" src="https://img.shields.io/pypi/dm/easyidp?color=%233775A9&label=pypi%20downloads&style=plastic">
+</p>
+
+</div>
+
+EasyIDP (Easy Intermediate Data Processor), A handy tool for dealing with region of interest (ROI) on the image reconstruction (Metashape & Pix4D) outputs, mainly in agriculture applications. It provides the following functions: 
+
+1. Backward Projection ROI to original images (`Backward Projector`).
+2. Crop ROI on GeoTiff Maps (DOM & DSM) and Point Cloud (`ROI Cropper`).
+3. Save cropped results to corresponding files (`ROI Saver`).
+
+This project tried to use packges based on pure-python, instead of installing some heavy packages (Open3D, OpenCV) and hard to install packages (GDAL dependices) for one or two individual functions. This may cause efficiency loss and differences in coding habit.
+
+<p align="center">
+  <img alt="GitHub Downloads" height="400px" src="https://api.star-history.com/svg?repos=UTokyo-FieldPhenomics-Lab/EasyIDP&type=Date">
+</p>
+
+## <div align="center">Documentation</div>
+
+Please check [Official Documents](https://easyidp.readthedocs.io/en/latest/) ( [中文](https://easyidp.readthedocs.io/zh_CN/latest/) | [日本語(翻訳募集)](https://easyidp.readthedocs.io/ja/latest/) ) for full documentations. And please also use the [Github Discussion](https://github.com/UTokyo-FieldPhenomics-Lab/EasyIDP/discussions) when you meet any problems.
+
+## <div align="center">References</div>
+
+Please cite this paper if this project helps you：
+
+```latex
+@Article{wang_easyidp_2021,
+AUTHOR = {Wang, Haozhou and Duan, Yulin and Shi, Yun and Kato, Yoichiro and Ninomiya, Seish and Guo, Wei},
+TITLE = {EasyIDP: A Python Package for Intermediate Data Processing in UAV-Based Plant Phenotyping},
+JOURNAL = {Remote Sensing},
+VOLUME = {13},
+YEAR = {2021},
+NUMBER = {13},
+ARTICLE-NUMBER = {2622},
+URL = {https://www.mdpi.com/2072-4292/13/13/2622},
+ISSN = {2072-4292},
+DOI = {10.3390/rs13132622}
+}
+```
+
+We also thanks the benefits from the following open source projects:
+
+* package main (**for users**)
+  * numpy: [https://numpy.org/](https://numpy.org/)
+  * matplotlib:[https://matplotlib.org/](https://matplotlib.org/)
+  * scikit-image: [https://github.com/scikit-image/scikit-image](https://github.com/scikit-image/scikit-image)
+  * pyproj: [https://github.com/pyproj4/pyproj](https://github.com/pyproj4/pyproj)
+  * tifffile: [https://github.com/cgohlke/tifffile](https://github.com/cgohlke/tifffile)
+  * imagecodecs: [https://github.com/cgohlke/imagecodecs](https://github.com/cgohlke/imagecodecs)
+  * shapely: [https://github.com/shapely/shapely](https://github.com/shapely/shapely)
+  * laspy/lasrs/lasio: [https://github.com/laspy/laspy](https://github.com/laspy/laspy)
+  * geojson: [https://github.com/jazzband/geojson](https://github.com/jazzband/geojson)
+  * plyfile: [https://github.com/dranjan/python-plyfile](https://github.com/dranjan/python-plyfile)
+  * pyshp: [https://github.com/GeospatialPython/pyshp](https://github.com/GeospatialPython/pyshp)
+  * tabulate: [https://github.com/astanin/python-tabulate](https://github.com/astanin/python-tabulate)
+  * tqdm: [https://github.com/tqdm/tqdm](https://github.com/tqdm/tqdm)
+  * gdown: [https://github.com/wkentaro/gdown](https://github.com/wkentaro/gdown)
+* package documentation (**for developers**)
+  * sphinx: [https://github.com/sphinx-doc/sphinx](https://github.com/sphinx-doc/sphinx)
+  * nbsphinx: [https://github.com/spatialaudio/nbsphinx](https://github.com/spatialaudio/nbsphinx)
+  * sphinx-gallery: [https://github.com/sphinx-gallery/sphinx-gallery](https://github.com/sphinx-gallery/sphinx-gallery)
+  * sphinx-inline-tabs: [https://github.com/pradyunsg/sphinx-inline-tabs](https://github.com/pradyunsg/sphinx-inline-tabs)
+  * sphinx-intl: [https://github.com/sphinx-doc/sphinx-intl](https://github.com/sphinx-doc/sphinx-intl)
+  * sphinx-rtc-theme: [https://github.com/readthedocs/sphinx_rtd_theme](https://github.com/readthedocs/sphinx_rtd_theme)
+  * furo: [https://github.com/pradyunsg/furo](https://github.com/pradyunsg/furo)
+* package testing and releasing (**for developers**)
+  * pytest: [https://github.com/pytest-dev/pytest](https://github.com/pytest-dev/pytest)
+  * packaging: [https://github.com/pypa/packaging](https://github.com/pypa/packaging)
+  * wheel: [https://github.com/pypa/wheel](https://github.com/pypa/wheel)
+
+This project was partially funded by:
+
+* the JST AIP Acceleration Research “Studies of CPS platform to raise big-data-driven AI agriculture”; 
+* the SICORP Program JPMJSC16H2; 
+* CREST Programs JPMJCR16O2 and JPMJCR16O1; 
+* the International Science & Technology Innovation Program of Chinese Academy of Agricultural Sciences (CAASTIP); 
+* the National Natural Science Foundation of China U19A2061.

easyidp-2.0.0/README.md

@@ -0,0 +1,90 @@
+<div align="center">
+
+<p>
+   <!-- <a align="left" href="https://ultralytics.com/yolov5" target="_blank"> -->
+   <img width="850" src="https://github.com/UTokyo-FieldPhenomics-Lab/EasyIDP/raw/v2.0/docs/_static/images/header_v2.0.png"></a>
+</p>
+
+<p align="center">
+  <img alt="GitHub Actions Badge" src="https://github.com/UTokyo-FieldPhenomics-Lab/EasyIDP/actions/workflows/pytest.yml/badge.svg?style=plastic">
+  <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/easyidp?style=plastic">
+  <img alt="GitHub" src="https://img.shields.io/github/license/UTokyo-FieldPhenomics-Lab/EasyIDP?style=plastic">
+  <img alt="GitHub top language" src="https://img.shields.io/github/languages/top/UTokyo-FieldPhenomics-Lab/EasyIDP?style=plastic">
+  <img alt="GitHub Downloads" src="https://img.shields.io/github/downloads/UTokyo-FieldPhenomics-Lab/EasyIDP/total?label=github%20downloads&style=plastic">
+  <img alt="GitHub Downloads" src="https://img.shields.io/pypi/dm/easyidp?color=%233775A9&label=pypi%20downloads&style=plastic">
+</p>
+
+</div>
+
+EasyIDP (Easy Intermediate Data Processor), A handy tool for dealing with region of interest (ROI) on the image reconstruction (Metashape & Pix4D) outputs, mainly in agriculture applications. It provides the following functions: 
+
+1. Backward Projection ROI to original images (`Backward Projector`).
+2. Crop ROI on GeoTiff Maps (DOM & DSM) and Point Cloud (`ROI Cropper`).
+3. Save cropped results to corresponding files (`ROI Saver`).
+
+This project tried to use packges based on pure-python, instead of installing some heavy packages (Open3D, OpenCV) and hard to install packages (GDAL dependices) for one or two individual functions. This may cause efficiency loss and differences in coding habit.
+
+<p align="center">
+  <img alt="GitHub Downloads" height="400px" src="https://api.star-history.com/svg?repos=UTokyo-FieldPhenomics-Lab/EasyIDP&type=Date">
+</p>
+
+## <div align="center">Documentation</div>
+
+Please check [Official Documents](https://easyidp.readthedocs.io/en/latest/) ( [中文](https://easyidp.readthedocs.io/zh_CN/latest/) | [日本語(翻訳募集)](https://easyidp.readthedocs.io/ja/latest/) ) for full documentations. And please also use the [Github Discussion](https://github.com/UTokyo-FieldPhenomics-Lab/EasyIDP/discussions) when you meet any problems.
+
+## <div align="center">References</div>
+
+Please cite this paper if this project helps you：
+
+```latex
+@Article{wang_easyidp_2021,
+AUTHOR = {Wang, Haozhou and Duan, Yulin and Shi, Yun and Kato, Yoichiro and Ninomiya, Seish and Guo, Wei},
+TITLE = {EasyIDP: A Python Package for Intermediate Data Processing in UAV-Based Plant Phenotyping},
+JOURNAL = {Remote Sensing},
+VOLUME = {13},
+YEAR = {2021},
+NUMBER = {13},
+ARTICLE-NUMBER = {2622},
+URL = {https://www.mdpi.com/2072-4292/13/13/2622},
+ISSN = {2072-4292},
+DOI = {10.3390/rs13132622}
+}
+```
+
+We also thanks the benefits from the following open source projects:
+
+* package main (**for users**)
+  * numpy: [https://numpy.org/](https://numpy.org/)
+  * matplotlib:[https://matplotlib.org/](https://matplotlib.org/)
+  * scikit-image: [https://github.com/scikit-image/scikit-image](https://github.com/scikit-image/scikit-image)
+  * pyproj: [https://github.com/pyproj4/pyproj](https://github.com/pyproj4/pyproj)
+  * tifffile: [https://github.com/cgohlke/tifffile](https://github.com/cgohlke/tifffile)
+  * imagecodecs: [https://github.com/cgohlke/imagecodecs](https://github.com/cgohlke/imagecodecs)
+  * shapely: [https://github.com/shapely/shapely](https://github.com/shapely/shapely)
+  * laspy/lasrs/lasio: [https://github.com/laspy/laspy](https://github.com/laspy/laspy)
+  * geojson: [https://github.com/jazzband/geojson](https://github.com/jazzband/geojson)
+  * plyfile: [https://github.com/dranjan/python-plyfile](https://github.com/dranjan/python-plyfile)
+  * pyshp: [https://github.com/GeospatialPython/pyshp](https://github.com/GeospatialPython/pyshp)
+  * tabulate: [https://github.com/astanin/python-tabulate](https://github.com/astanin/python-tabulate)
+  * tqdm: [https://github.com/tqdm/tqdm](https://github.com/tqdm/tqdm)
+  * gdown: [https://github.com/wkentaro/gdown](https://github.com/wkentaro/gdown)
+* package documentation (**for developers**)
+  * sphinx: [https://github.com/sphinx-doc/sphinx](https://github.com/sphinx-doc/sphinx)
+  * nbsphinx: [https://github.com/spatialaudio/nbsphinx](https://github.com/spatialaudio/nbsphinx)
+  * sphinx-gallery: [https://github.com/sphinx-gallery/sphinx-gallery](https://github.com/sphinx-gallery/sphinx-gallery)
+  * sphinx-inline-tabs: [https://github.com/pradyunsg/sphinx-inline-tabs](https://github.com/pradyunsg/sphinx-inline-tabs)
+  * sphinx-intl: [https://github.com/sphinx-doc/sphinx-intl](https://github.com/sphinx-doc/sphinx-intl)
+  * sphinx-rtc-theme: [https://github.com/readthedocs/sphinx_rtd_theme](https://github.com/readthedocs/sphinx_rtd_theme)
+  * furo: [https://github.com/pradyunsg/furo](https://github.com/pradyunsg/furo)
+* package testing and releasing (**for developers**)
+  * pytest: [https://github.com/pytest-dev/pytest](https://github.com/pytest-dev/pytest)
+  * packaging: [https://github.com/pypa/packaging](https://github.com/pypa/packaging)
+  * wheel: [https://github.com/pypa/wheel](https://github.com/pypa/wheel)
+
+This project was partially funded by:
+
+* the JST AIP Acceleration Research “Studies of CPS platform to raise big-data-driven AI agriculture”; 
+* the SICORP Program JPMJSC16H2; 
+* CREST Programs JPMJCR16O2 and JPMJCR16O1; 
+* the International Science & Technology Innovation Program of Chinese Academy of Agricultural Sciences (CAASTIP); 
+* the National Natural Science Foundation of China U19A2061.

easyidp-2.0.0/easyidp/__init__.py

@@ -0,0 +1,241 @@
+__version__ = "2.0.0"
+
+import os
+import warnings
+import numpy as np
+from pathlib import Path
+
+from copy import deepcopy
+
+##############
+# dict tools #
+##############
+
+class Container(dict):
+    """Self designed dictionary class to fetch items by id or label
+
+    Caution
+    -------
+    This object can not be saved by ``pickle``, it will cause problem when loading [1]_ 
+
+    References
+    ----------
+    .. [1] https://stackoverflow.com/questions/4014621/a-python-class-that-acts-like-dict
+    """
+    def __init__(self, suffix=''):
+        super().__init__()
+        self.id_item = {}   # {0: item1, 1: item2}
+        self.item_label = {}  #{"N1W1": 0, "N1W2": 1}, just index it position
+        self._suffix = str(suffix)
+
+    def __setitem__(self, key, item):
+        if isinstance(key, int):
+            # default method to set values
+            # Container[0] = A, while A.label = "N1W1"
+
+            if key < len(self.item_label):
+                if 'label' in dir(item):  # has item.label
+                    # delete old label
+                    # e.g. {'empty 0': 0, 'empty 1': 1}
+                    #       0 -> IMG_0001;
+                    #      {'empty 0': 0, 'empty 1': 1, 'IMG_0001': 0}
+                    old_key = self.id_item[key].label
+                    del self.item_label[old_key]
+                    
+                    # add new label
+                    self.item_label[item.label] = key
+                # change the value of one item
+                self.id_item[key] = item
+
+            elif key == len(self.item_label):
+                # add a new item
+                self.id_item[key] = item
+                if 'label' in dir(item): 
+                    # sometimes two items has the same label
+                    if item.label in self.item_label.keys():
+                        raise KeyError(f"The given item's label [{item.label}] already exists -> {self.item_label.keys()}")
+                    else:
+                        self.item_label[item.label] = key
+                else:
+                    self.item_label[key] = key
+            else:
+                raise IndexError(f"Index [{key}] out of range (0, {len(self.item_label)})")
+
+        elif isinstance(key, str):
+            # advanced method to change items
+            # Container["N1W1"] = B, here assuemt B.label already == "N1W1"
+
+            # item already exists
+            if key in self.item_label.keys():   
+                idx = self.item_label[key]
+                self.id_item[idx] = item
+            else:  # add new item
+                idx = len(self.id_item)
+                self.id_item[idx] = item
+                if 'label' in dir(item):  # has item.label
+                    self.item_label[item.label] = idx
+                else:  # act as common dictionary
+                    self.item_label[key] = idx
+        else:
+            raise KeyError(f"Key should be 'int', 'str', not {key}")
+
+    def __getitem__(self, key):
+        if isinstance(key, int):  # index by photo order
+            if key < len(self.item_label):
+                return self.id_item[key]
+            else:
+                raise IndexError(f"Index [{key}] out of range (0, {len(self.item_label)})")
+        elif isinstance(key, str):  # index by photo name
+            if key in self.item_label.keys():
+                return self.id_item[self.item_label[key]]
+            elif self._suffix in key and os.path.splitext(key)[0] in self.item_label.keys():
+                return self.id_item[self.item_label[os.path.splitext(key)[0]]]
+            else:
+                raise KeyError(f"Can not find key [{key}]")
+        elif isinstance(key, slice):
+            idx_list = list(self.id_item.keys())[key]
+
+            out = self.copy()
+            out.id_item = {k:v for k, v in self.id_item.items() if k in idx_list}
+            out.item_label = {k:v for k, v in self.item_label.items() if v in idx_list}
+            
+            return out
+        else:
+            raise KeyError(f"Key should be 'int', 'str', 'slice', not {key}")
+
+    def __repr__(self) -> str:
+        return self._btf_print()
+
+    def __str__(self) -> str:
+        return self._btf_print()
+
+    def _btf_print(self):
+        title = f'easyidp.{self.__class__.__name__}'
+        key_list = list(self.item_label.keys())
+        num = len(key_list)
+        out_str = f'<{title}> with {num} items\n'
+
+        # limit the numpy print out
+        default_np_thresh = np.get_printoptions()['threshold']
+        default_np_suppress = np.get_printoptions()['suppress']
+        np.set_printoptions(threshold=4, suppress=True)
+        if num == 0:
+            out_str = "<Empty easyidp.Container object>"
+        elif num > 5:
+            for i, k in enumerate(key_list[:2]):
+                out_str += f"[{i}]\t{k}\n"
+                out_str += repr(self.id_item[self.item_label[k]])
+                out_str += '\n'
+            out_str += '...\n'
+            for i, k in enumerate(key_list[-2:]):
+                out_str += f"[{num-2+i}]\t{k}\n"
+                out_str += repr(self.id_item[self.item_label[k]])
+                out_str += '\n'
+        else:
+            for i, k in enumerate(key_list):
+                out_str += f"[{i}]\t{k}\n"
+                out_str += repr(self.id_item[self.item_label[k]])
+                out_str += '\n'
+        np.set_printoptions(threshold=default_np_thresh, suppress=default_np_suppress)
+
+        out_str = out_str[:-1]
+        return out_str
+
+    def __len__(self):
+        return len(self.id_item)
+
+    def __delitem__(self, key):
+        if isinstance(key, int):
+            k = key
+            del self.item_label[self.id_item[key]]
+            del self.id_item[key]
+        elif isinstance(key, str):
+            k = self.item_label[key]
+            del self.id_item[self.item_label[key]]
+            del self.item_label[key]
+        else:
+            raise KeyError(f"Key should be 'int', 'str', 'slice', not {key}")
+
+        # update the id
+        # a[5] = a.pop(1)
+        # https://stackoverflow.com/questions/4406501/change-the-name-of-a-key-in-dictionary
+        id_item_keys = list(self.id_item.keys())
+        for idx in id_item_keys:
+            # e,g. k = 3, idx in [0, 1, 2, 4, 5]
+            if idx > k:
+                self.id_item[idx-1] = self.id_item.pop(idx)
+
+                # e.g. {"N1W1": 0, "N1W2": 1},
+                label = _find_key(self.item_label, idx)
+                self.item_label[label] = idx - 1
+
+    def __iter__(self):
+        return iter(self.id_item.values())
+
+    def keys(self):
+        return self.item_label.keys()
+
+    def values(self):
+        return self.id_item.values()
+
+    def items(self):
+        out_dict = {}
+        for k, idx in self.item_label.items():
+            out_dict[k] = self.id_item[idx]
+        return out_dict.items()
+
+    def copy(self):
+        return deepcopy(self)
+
+
+def _find_key(mydict, value):
+    """a simple function to using dict value to find key
+    e.g. 
+    >>> mydict = {"a": 233, "b": 456}
+    >>> _find_key(mydict, 233)
+    "a"
+    """
+    key_idx = list(mydict.values()).index(value)
+    return list(mydict.keys())[key_idx]
+
+
+##############
+# path tools #
+##############
+
+def get_full_path(short_path):
+    if isinstance(short_path, str):
+        return Path(short_path)
+    elif isinstance(short_path, Path):
+        return short_path
+    else:
+        return None
+
+def parse_relative_path(root_path, relative_path):
+    # for metashape frame.zip path use only
+    if r"../../" in relative_path:
+        frame_path = os.path.dirname(os.path.abspath(root_path))
+        merge = os.path.join(frame_path, relative_path)
+        return os.path.abspath(merge)
+    else:
+        warnings.warn(f"Seems it is an absolute path [{relative_path}]")
+        return relative_path
+    
+###############
+# import APIs #
+###############
+
+from . import (
+    visualize, 
+    cvtools,
+    geotools,
+    shp, 
+    jsonfile, 
+    data, 
+)
+from .reconstruct import ProjectPool
+from .pointcloud import PointCloud
+from .geotiff import GeoTiff
+from .pix4d import Pix4D
+from .metashape import Metashape
+from .roi import ROI