欢迎查阅EasyIDP官方文档¶

EasyIDP(中间数据处理助手)是一个处理三维重建(Metashape和Pix4D)产品上兴趣区域(ROI)的软件包(主要是农业应用)，提供如下的功能：

把ROI逆投影回原始图片上
在正射地图(DOM)、高程图(DSM)和点云上把ROI切出来
把切块后的结果保存为对应文件格式

其他语言

这是一个多语言文档，你可以通过这里或左下角切换语言

English

中文

日本語(翻訳募集)

备注

EasyIDP中使用(水平轴, 垂直轴, 维度/深度)顺序作为坐标顺序。当坐标为地理信息坐标时，对应(经度，纬度，海拔/高度)。

举些栗子¶

举些栗子

快速开始¶

可以通过PyPi来安装：

pip install easyidp

备注

如果你在pypi版本中遇到了Bug，请考虑使用最新版的源码。使用教程可以参考这个链接：使用源码.

然后在你的python环境中导入包：

import easyidp as idp

小心

在执行下面的示例代码前，请确保基本理解了Metashape或Pix4D的图像三维重建的工作流程，并且知道如何导出地图(DOM和DSM的tiff文件格式)和点云(ply文件格式)。并且知道一些基本的GIS矢量文件(shp)的格式与制作方法。

1. 读取ROI¶

roi = idp.ROI("xxxx.shp")  # lon and lat 2D info

# get z values from DSM
roi.get_z_from_dsm("xxxx_dsm.tiff")  # add height 3D info

二维的ROI可以用来切正射地图、高程图和点云(参考 2. 切ROI )。三维点ROI可以用来逆投影回原始图片上(参考 4. 逆投影 )。

小心

强烈推荐保证shapefile文件和geotiff文件的地理坐标系(CRS)一致，EasyIDP内置的转换算法可能会有一定的精度损失。

推荐使用UTM地理坐标系(WGS 84 / UTM grid system)，该坐标系的XY轴单位是米，方便后续计算且经过开发者的验证。
也支持传统的经纬度坐标系，如EPSG4326。但是当你需要计算距离的场景下不推荐使用因为它的单位是度。
特定国家内部的特殊坐标系，如北京54(BJZ54), 2000国家大地坐标系(CGCS2000), 日本測地系2011(JDG2011)等，没有经过测试且难以保证可用性。如果遇到任何问题，建议使用GIS软件先转换成UTM坐标系。

可接受的ROI类型仅为多边形类型(网格是一种多边形的特殊形式)，并且每个多边形ROI的尺寸应该可以被完整的包含进单张原始照片(推荐最佳大小约为原始图片的1/4)

ROI types — 第四个可能太大了，没法被涵盖进单张照片里，推荐使用更小的多边形。¶

2. 切ROI¶

读取正射地图和高程图文件

dom = idp.GeoTiff("xxx_dom.tif")
dsm = idp.GeoTiff("xxx_dsm.tif")

读取点云文件

ply = idp.PointCloud("xxx_pcd.ply")

把兴趣区域(ROI)切出来：

dom_parts = roi.crop(dom)
dsm_parts = roi.crop(dsm)
pcd_parts = roi.crop(ply)

如果你想在切的时候，顺便保存切块的结果：

dom_parts = roi.crop(dom, save_folder="./crop_dom")
dsm_parts = roi.crop(dsm, save_folder="./crop_dsm")
pcd_parts = roi.crop(ply, save_folder="./crop_pcd")

3. 读取重建项目¶

可以单独添加一块重建的样地或者使用批处理添加。

Metashape

Metashape项目本身支持使用不同的块(chunk)来实现在一个项目中(*.psx)创建不同的重建样地，所以需要使用 chunk_id 来指定处理哪一个样地。

ms = idp.Metashape("xxxx.psx", chunk_id=0)

小心

尽管这边只给了 xxxx.psx 项目文件参数，但其实Metashape自动生成的 xxxx.files 同名文件夹更加重要。请把他们两个放在同一个路径下。

Pix4D

目前，EasyIDP尚不支持从元信息中获取原始图片的文件夹路径，所以如果需要进行逆投影，请手动指定 raw_img_folder 原始图片文件夹的路径

p4d = idp.Pix4D(project_path="xxxx.p4d",
                raw_img_folder="path/to/folders/with/raw/photos/",
                # optional, in case you changed the pix4d project folder
                param_folder="path/to/pix4d/parameter/folders")

小心

尽管这边只给了 xxxx.p4d 项目文件参数，但其实Pix4D自动生成的 xxxx 同名文件夹更重要。请把他们两个放在同一个路径下，并且不推荐调整该文件夹内部的文件。

4. 逆投影¶

img_dict = roi.back2raw(chunk1)

然后检查运算结果：

# find the raw image name list
>>> img_dict.keys()
dict_keys(['DJI_0177', 'DJI_0178', 'DJI_0179', 'DJI_0180', ... ]

# the roi pixel coordinate on that image
>>> img_dict['DJI_0177']
array([[ 779,  902],
       [1043,  846],
       [1099, 1110],
       [ 834, 1166],
       [ 779,  902]])

保存反投影的图片结果：

Metashape

img_dict = roi.back2raw(ms, save_folder="folder/to/put/results/")

Pix4D

img_dict = roi.back2raw(p4d, save_folder="folder/to/put/results/")

5. 正投影¶

This function support bring results and image itself from corresponding raw images to geotiff.

小心

The following features have not been supported.

请使用下面的代码来把原始图正投影到正射影像DOM上（ raw forward dom 缩减为 raw4dom ）

该特性尚未支持

imarray_dict = roi.raw4dom(ms)

这是一个包含使用每个ROI的编号作为键值的图片字典，把原始图上对应部位的图片投影到正射影像DOM上。

>>> geotif = imarray_dict['roi_111']
>>> geotif
<class 'easyidp.geotiff.GeoTiff'>

也可以把原始图上检测到的结果正投影到正射影像上，多边形顶点会使用地理坐标。在做这件事之前，请先准备检测的结果（通过深度学习的检测或分割得到的，顶点为像素坐标）

result_on_raw = idp.roi.load_results_on_raw_img(r"C:/path/to/detected/results/folder/IMG_2345.txt")

然后使用下面的函数把两个都进行正投影：

>>> imarray_dict, coord_dict = roi.raw4dom(ms, result_on_raw)
>>> coord_dict['roi_111']
{0: array([[139.54052962,  35.73475194],
           ...,
           [139.54052962,  35.73475194]]),
 ...,
 1: array([[139.54053488,  35.73473289],
           ...,
           [139.54053488,  35.73473289]]),

保存单个ROI为单个GeoTiff文件

>>> geotif = imarray_dict['roi_111']
>>> geotif.save(r"/file/path/to/save/geotif_roi_111.tif")

批量保存每个ROI为单个GeoTiff文件

>>> imarray_dict = roi.raw4dom(ms, save_folder="/path/to/save/folder")

参考资料¶

发表论文¶

如果您的研究受益于该项目，请引用我们的论文：

@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}
}

第三方库¶

我们也感谢下面所有开源工程对本项目的贡献：

核心库(面向用户)
- numpy: https://numpy.org/
- matplotlib: https://matplotlib.org/
- scikit-image: https://github.com/scikit-image/scikit-image
- pyproj: https://github.com/pyproj4/pyproj
- tifffile: https://github.com/cgohlke/tifffile
- imagecodecs: https://github.com/cgohlke/imagecodecs
- shapely: https://github.com/shapely/shapely
- laspy/lasrs/lasio: https://github.com/laspy/laspy
- geojson: https://github.com/jazzband/geojson
- plyfile: https://github.com/dranjan/python-plyfile
- pyshp: https://github.com/GeospatialPython/pyshp
- tabulate: https://github.com/astanin/python-tabulate
- tqdm: https://github.com/tqdm/tqdm
- gdown: https://github.com/wkentaro/gdown
文档工具(面向开发者)
- sphinx: https://github.com/sphinx-doc/sphinx
- nbsphinx: https://github.com/spatialaudio/nbsphinx
- sphinx-gallery: https://github.com/sphinx-gallery/sphinx-gallery
- sphinx-inline-tabs: https://github.com/pradyunsg/sphinx-inline-tabs
- sphinx-intl: https://github.com/sphinx-doc/sphinx-intl
- sphinx-rtc-theme: https://github.com/readthedocs/sphinx_rtd_theme
- furo: https://github.com/pradyunsg/furo
测试与发布工具(面向开发者)
- pytest: https://github.com/pytest-dev/pytest
- packaging: https://github.com/pypa/packaging
- wheel: https://github.com/pypa/wheel

资金来源¶

该项目的部分资金来自于：

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);
国家自然科学基金U19A2061