# DocuGIS 介接說明

<!-- 標籤 -->
###### tags: `使用導引`, `介接`, `文件狀態：停止更新`

<!-- 內文編輯更新資訊，若有更動此份文件內容，請務必更新此項資訊 -->
> [name=林農堯]
> [time=Jan, 2019]

<!-- 摘要 -->
:::success

<!-- 當前負責人使用高亮標示，新接替維護人員請加在第一個 -->
- **建立者**：林農堯
- **維護者**：林農堯

:::

<!-- 筆記正文開始 -->

## Outline
- DocuGIS的介接本文件有兩個主要的說明如下
1. 如何在DocuGIS上呈現空間資料
2. 空間資料如何呈現原文本資料
## 如何在DocuGIS上呈現空間資料
- DocuSky上的工具或軟體可以產生符合格式的JSON檔案或CSV檔案，讓DocuGIS呈現空間分布。共有三種方式，分別在以下說明：
### 一、使用JSON檔案，在\[文本圖層\]中上傳
- JSON檔格的格式說明：
- 整個是一個物件的陣列，每個物件必需有wkt屬性。wkt為Well-known text。
- 以下是wkt的例子
- 
- wkt的值必須為WGS84經緯度十進位，例如：經度121.5；緯度23.5。以wkt表示即為：
- **POINT (121.5 23.5)**
- 如何將TGAZ或哈佛的ID轉成WGS84坐標，可以參考[此文件](http://docusky.digital.ntu.edu.tw/DocuSky/DocuTools/DocuGIS/api/hvdID.html)。
- id屬性最好有，可以按其排序。其它屬性則可以自由加入。以下為2筆資料的例子。

    {
        { "id": "1", "name": "Taiwan", "wkt": "POINT (121.5 23.5)" },
        { "id": "2", "name": "Taipei", "wkt": "POINT (121.6 23.3)" },
    }

- 之後可透過\[文本圖層\]裡，上載單份JSON資料檔的功能上傳。
- 
### 二、使用URL傳JSON檔名
1. JSON儲存在DocuSky上
- 在工具內產生上述之符合格式的JSON檔後，將此JSON的內容使用`docuskyManageDataFileListSimpleUI`，將其放置在DocuSky上。簡單的範例如下：

    var docuSkyFileObj = docuslyManageDataDileListSimpleUI;
    var transporter = docuSkyFileObj.jsonTransporter;
    
    transporter.catagory = 'gis';
    transporter.datapath = 'web';
    transporter.filename = fn + ".json";
    transporter.storeJson( jsonObj, function() {
        alert('OK');
    });

- 注意category值為gis；datapath值為web(之後會擴充調整)，檔案名稱需要urlecode。之後產生以下的Link。使用者按下此Link後即可到DocuGIS中觀察此地圖。
- `http://docusky.digital.ntu.edu.tw/DocuSky/DocuTools/DocuGIS/index.html?u=jsonfilename&y=400`
- <span style="color: red">Jsonfilename不需副檔名 .json</span>
2. JSON儲存在遠端的網站上
- 產生JSON檔案後放在可透過http或https公開存取的網站上，使用以參數u指定urlencode的JSON完整網址，JSON檔案需要檔名及副檔名。如下例子：
- `https://docusky.digital.ntu.edu.tw/DocuSky/docutools/DocuGIS/index.html?u=https://docusky.digital.ntu.edu.tw/DocuSky/docutools/docugis/20180605-045438_DrugsBook0913_%E6%9C%AC%E8%8D%89%E7%B6%93%E9%9B%86%E6%B3%A82-4%E5%8D%B7_249_style-%E2%96%B2-3366FF-FFFFFF-6.json`
- u為JSON檔案的檔名；y為文本的西元年份，可以不用給值。DocuGIS即可以呈現其內容。不過此時為預設的地圖地點樣式，若需要指定樣式可以在主檔名的最後加上樣式的說明，再儲存在DocuSky上再用url方式呈現。
- -77_Liexianzhuan0409_列仙傳_35_<span style="color: red">style-⬟-FF4500-FFFFFF-7</span>.json
- 以上紅色的部分就是樣式的文字說明
| \_style | \_style表示樣式的開始，之後的值用”-”相連 |
|---------------|-----------------------------------------|
| ⬟ | 圖示的樣式。目前可以使用的圖樣： ⬤、◎、◉、▣、▇、▲、△、▼、▽、★、✪、✦、✱、⊛、♥、◆、◈、◊、⬟、✿、♝、♚、☻、⚑、☗、♣、☺、👍 |
| FF4500 | 圖示的色彩值，使用RGB 16進位值表示 |
| FFFFFF | 圖示外框輪廓值 |
| 7 | 圖示大小 |
- 透過在JSON主檔名後指定的上述Style，就會在DocuGIS上呈現有樣式的地圖：
- 

### 三、使用CSV上傳資料
- 在文本圖層中有[Upload CSV]可以使用
- 
- 可以直接貼上CSV或由EXCEL貼上TSV 的值。重要經緯度的坐標欄位需要用x,y命名。(x為經度；y為緯度)
- 
## 空間資料如何呈現原文本資料
- DocuGIS由JSON檔案中的藍色的部分取得資料庫及文獻集的名稱 ，即以底線(\_)隔開的第2與第3的位置。
- -77_<span style="color: blue">Liexianzhuan0409_列仙傳</span>_35_style-⬟-FF4500-FFFFFF-7.json
- DocuGIS還需要知道文件的ID，即檔案名稱。
- 在MarkusConverter中，記得要將<span style="color: blue">Passage轉換成個別的獨立文件</span>選取
- 
- 如此DocuGIS就會在id上產生Link，可以點選顯示該Passage的全文。
-