classification train

Author: sshuair

docs/Makefile

@@ -33,7 +33,8 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.mathjax'
+    'sphinx.ext.mathjax',
+    'recommonmark'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -44,6 +45,10 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
 # -- Options for HTML output -------------------------------------------------
 

docs/README.md

@@ -1,20 +1,15 @@
-Core Conceptions
-================
+# Core Conceptions
+
 Because TorchSat is based on PyTorch, 
 you'd better have some deep learning and PyTorch knowledge to use and modify this project.
 
 Here are some core conceptions you should know.
 
-1. All input image data, Whether it is PNG, JPEG or GeoTIFF, will be converted to NumPy_ ndarray, 
-and the ndarray dimension is ``[height, width]`` (single channel image) or ``[height, width, channels]`` (multi-channel image).
+1. All input image data, Whether it is PNG, JPEG or GeoTIFF, will be converted to [NumPy](https://numpy.org/) ndarray, 
+and the ndarray dimension is `[height, width]` (single channel image) or `[height, width, channels]` (multi-channel image).
 
-2. After the data is read into NumPy_ ndarray, there are only three data types, `np.uint8`, `np.uint16`, `np.float`. 
+2. After the data is read into [NumPy](https://en.wikipedia.org/wiki/Normalized_difference_vegetation_index) ndarray, there are only three data types, `np.uint8`, `np.uint16`, `np.float`. 
 These three data types are chosen because, in satellite imagery, 
     - The most common image stored in JPEG or PNG (such as the Google Map Satellite Image) is mostly `8-bit (np.uint8)` data;
     - And the `16-bit (np.uint16)` is mostly the original data type of remote sensing satellite imagery, which is also very common; 
     - The third type `float (np.float)` is considered, because sometimes, we will use remote sensing index (such as NDVI_) as features to participate in training. For this data we suppose all input data values range from 0 to 1.
-
-
-
-.. _NumPy: https://numpy.org/
-.. _NDVI: https://en.wikipedia.org/wiki/Normalized_difference_vegetation_index

docs/make.bat

@@ -22,10 +22,10 @@ TorchSat is an open-source deep learning framework for satellite imagery analysi
    :maxdepth: 2
    :caption: Contents:
 
-   installation.rst
-   core-conception.rst
+   installation.md
+   core-conception.md
    quickstart.rst
-   tutorials.rst
+   tutorials/image_classification.md
    api/api.rst
 
 

docs/requirements.txt

@@ -1,54 +1,44 @@
-Installation
-=============
-Deepndencies
-------------
+# Installation
+## Deepndencies
 
-TorchSat is based on `PyTorch`_, so you should install the PyTorch
+TorchSat is based on [PyTorch](https://pytorch.org/), so you should install the PyTorch
 first. And if you want to use the GPU version, you should install CUDA.
 
 Python package dependencies(seee also requirements.txt): pytorch,
 torchvision, numpy, pillow, tifffile, six, scipy, opencv
 
-   Note: TorchSat only suport `Python 3`_. We recommend version after
+>Note: TorchSat only suport [Python 3](https://www.python.org/). We recommend version after
    Python 3.5(including python 3.5), but wo have not tested any version
    below Python 3.5
 
-Install
+## Install
 -------
 
-Install from PyPI or Anconda
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Install from PyPI
 
 -  PyPI: ``pip3 install torchsat``
--  Anconda: `` ``
 
-Install from source
-~~~~~~~~~~~~~~~~~~~
+### Install from source
 
 -  Install the latest version
 
-.. code:: bash
+```
 
     git clone https://github.com/sshuair/torchsat.git
     cd torchsat
     python3 setup.py install
+```
 
 -  Install the stable version
 
-   1. Visit the `release`_ page and download the version you want.
+   1. Visit the [release](https://github.com/sshuair/torchsat/releases) page and download the version you want.
    2. Decompress the zip or tar file.
    3. Enter the torchsat directory and run this command
       ``python3 setup.py install``.
 
-For data preparation
---------------------
 
-[wip]
-
-
-Docker
-------
-You can pull the docker image from `Docker Hub`_ if you want use TorchSat in docker.
+### Docker
+You can pull the docker image from [Docker Hub](https://hub.docker.com/r/sshuair/torchsat) if you want use TorchSat in docker.
 
 1. pull image 
     - cpu: `docker pull sshuair/torchsat:cpu-latest` 
@@ -61,9 +51,3 @@ You can pull the docker image from `Docker Hub`_ if you want use TorchSat in doc
 
 This way you can easily use the TorchSat in docker container.
 
-
-
-.. _PyTorch: https://pytorch.org/
-.. _Python 3: https://www.python.org/
-.. _release: https://github.com/sshuair/torchsat/releases
-.. _Docker Hub: https://hub.docker.com/r/sshuair/torchsat

docs/source/_static/img/turotial/classification_patch.png

@@ -0,0 +1,25 @@
+
+1. clip vector error
+- description
+```
+/usr/local/lib/python3.6/site-packages/geopandas/base.py:76: UserWarning: Cannot generate spatial index: Missing package `rtree`.
+  warn("Cannot generate spatial index: Missing package `rtree`.")
+Traceback (most recent call last):
+  File "script.py", line 17, in <module>
+    res_union = gpd.overlay(df1, df2, how='union')
+  File "/usr/local/lib/python3.6/site-packages/geopandas/tools/overlay.py", line 371, in overlay
+    result = _overlay_union(df1, df2)
+  File "/usr/local/lib/python3.6/site-packages/geopandas/tools/overlay.py", line 298, in _overlay_union
+    dfinter = _overlay_intersection(df1, df2)
+  File "/usr/local/lib/python3.6/site-packages/geopandas/tools/overlay.py", line 212, in _overlay_intersection
+    sidx = bbox.apply(lambda x: list(spatial_index.intersection(x)))
+  File "/usr/local/lib/python3.6/site-packages/pandas/core/series.py", line 3194, in apply
+    mapped = lib.map_infer(values, f, convert=convert_dtype)
+  File "pandas/_libs/src/inference.pyx", line 1472, in pandas._libs.lib.map_infer
+  File "/usr/local/lib/python3.6/site-packages/geopandas/tools/overlay.py", line 212, in <lambda>
+    sidx = bbox.apply(lambda x: list(spatial_index.intersection(x)))
+AttributeError: 'NoneType' object has no attribute 'intersection'
+```
+
+- solution: you should install the rtree
+for macos: brew install spatialindex && pip3 install rtree

docs/source/api/api.rst

@@ -0,0 +1,72 @@
+# Image Classification
+
+This is classification turtorial for satellite image. We will use sentinal-2 TCI data as an example. It cover from training data prepare, train the model, and predict the new files.
+
+## Prepare Trainning Data
+Suppose we got a scene of sentinel-2 satellite TCI image data. You can download from [esa scihub](https://scihub.copernicus.eu/dhus/#/home). I has got the secene id `T51RTQ_20200513T023551_TCI` and convert the JPEG2000 to GeoTIFF.
+
+1. patch the large 10980x10980 pixel image to 128x128 pixel image
+
+```
+
+    ➜ cd  tests/classification/      
+    ➜ ts make-mask-cls --filepath T51RTQ_20200513T023551_TCI.tif --width 128 --height 128 --outpath ./patched
+    processing 1/1 file T51RTQ_20200513T023551_TCI.tif ...
+    14%|███████████████▉                                                              | 12/85 [00:07<00:45,  1.60it/s]
+```
+You should get the following data:
+
+![](../_static/img/turotial/classification_patch.png)
+
+2. **labeling the train data and test data**  
+
+You can split the data into tran data and test data as below. And then labeling those patched image into four classes: `water`, `residential`, `farmland`, `forest`. Reorganize the catalog of these small images according to different categories and split them to train and validation dataset.
+```
+        .
+        ├── train
+        │    ├── water
+        │    │   ├── T51RTQ_20200513T023551_TCI_1_29.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_2_29.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_8_14.tif
+        │    │   └── ...
+        │    ├── frameland
+        │    │   ├── T51RTQ_20200513T023551_TCI_3_2.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_3_77.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_11_1.tif
+        │    │   └── ...
+        │    ├── residential
+        │    │   ├── T51RTQ_20200513T023551_TCI_0_29.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_1_37.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_4_36.tif
+        │    │   └── ...
+        │    ├── forest
+        │    │   ├── T51RTQ_20200513T023551_TCI_7_21.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_22_45.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_41_29.tif
+        │    │   └── ...
+        ├── validation
+        │    ├── water
+        │    │   ├── T51RTQ_20200513T023551_TCI_5_32.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_5_12.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_4_32.tif
+        │    │   └── ...
+        │    ├── frameland
+        │    │   ├── T51RTQ_20200513T023551_TCI_9_2.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_6_76.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_2_5.tif
+        │    │   └── ...
+        │    ├── residential
+        │    │   ├── T51RTQ_20200513T023551_TCI_8_29.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_3_37.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_2_36.tif
+        │    │   └── ...
+        │    ├── forest
+        │    │   ├── T51RTQ_20200513T023551_TCI_8_12.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_31_5.tif
+        │    │   ├── T51RTQ_20200513T023551_TCI_29_29.tif
+        │    │   └── ...
+```
+
+## Train the model
+
+test