Skip to content

annotation

Jump to bottom
Jason Guan-Shuo Mai edited this page Dec 20, 2018 · 9 revisions

資料編輯 WF 4

版本紀錄 WF 4.1.3.4, WF 4.16

目前設計是針對檔案，由於每個檔案可能有 1N 個 tokens，故每個 revisions 也可能有 1N 個 tokens。

  • endpoint /annotation-revision/query
  • post data
{
  "query": {
    "_id": "11053ee0ec864feca68e7bf8932dd23e" // url_md5 = _id from WF 4.2 /media/annotation/query
  },
  "sort": {
    "revisions.created": 1
  }
}
  • response
{
  "results": [
    {
      "_id": "11053ee0ec864feca68e7bf8932dd23e",
      "revisions": [
        {
          "modifiedBy": {
            "_id": "OrcID_0000-0002-7446-3249",
            "name": "Thomas Yu"
          },
          "created": 1542014474.531,
          "tokens": [
            { // 可直接用於 restore 的資料單元
              "data": [ 
                {
                  "key": "species",
                  "label": "物種",
                  "value": "山羌",
                  "data_error_flag": false,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "sex",
                  "label": "性別",
                  "value": "NA",
                  "data_error_flag": true,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "lifeStage",
                  "label": "年齡",
                  "value": "NA",
                  "data_error_flag": true,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "id",
                  "label": "id",
                  "value": "NA",
                  "data_error_flag": false,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "category",
                  "label": "category",
                  "value": "NA",
                  "data_error_flag": false,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "sciName",
                  "label": "sciName",
                  "value": "Muntiacus reevesi micrurus",
                  "data_error_flag": false,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "behavior",
                  "label": "behavior",
                  "value": "NA",
                  "data_error_flag": false,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                }
              ],
              "summary": { // 用於介面顯示的 revision 摘要
                "species": "山羌",
                "sex": "NA",
                "lifeStage": "NA",
                "id": "NA",
                "category": "NA",
                "sciName": "Muntiacus reevesi micrurus",
                "behavior": "NA"
              }
            },
            { // 同張照片的第 2 筆 record
              "data": [ 
                {
                  "key": "species",
                  "label": "物種",
                  "value": "山羌",
                  "data_error_flag": false,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "sex",
                  "label": "性別",
                  "value": "NA",
                  "data_error_flag": true,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "lifeStage",
                  "label": "年齡",
                  "value": "non-adult",
                  "data_error_flag": true,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "id",
                  "label": "id",
                  "value": "NA",
                  "data_error_flag": false,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "category",
                  "label": "category",
                  "value": "NA",
                  "data_error_flag": false,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "sciName",
                  "label": "sciName",
                  "value": "Muntiacus reevesi micrurus",
                  "data_error_flag": false,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                },
                {
                  "key": "behavior",
                  "label": "behavior",
                  "value": "NA",
                  "data_error_flag": false,
                  "last_validated_timestamp": 1542014471.053,
                  "unit": "",
                  "context": "camera-trap"
                }
              ],
              "summary": { // 同照片第二筆資料用於介面顯示的摘要
                "species": "山羌",
                "sex": "NA",
                "lifeStage": "non-adult",
                "id": "NA",
                "category": "NA",
                "sciName": "Muntiacus reevesi micrurus",
                "behavior": "NA"
              }
            }
          ]
        }
      ],
      "url_md5": "11053ee0ec864feca68e7bf8932dd23e"
    }
  ]
}

版本紀錄 還原成此版本 WF 4.16.2

  • endpoint /annotation-revision/restore
  • post data
{
  "url_md5": "11053ee0ec864feca68e7bf8932dd23e",
  "revision_tokens": [ // 選定要還原的 revision 下的 tokens 直接搬過來，其餘後端處理
    {
      "data": [ 
        {
          "key": "species",
          "label": "物種",
          "value": "山羌",
          "data_error_flag": false,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "sex",
          "label": "性別",
          "value": "NA",
          "data_error_flag": true,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "lifeStage",
          "label": "年齡",
          "value": "NA",
          "data_error_flag": true,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "id",
          "label": "id",
          "value": "NA",
          "data_error_flag": false,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "category",
          "label": "category",
          "value": "NA",
          "data_error_flag": false,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "sciName",
          "label": "sciName",
          "value": "Muntiacus reevesi micrurus",
          "data_error_flag": false,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "behavior",
          "label": "behavior",
          "value": "NA",
          "data_error_flag": false,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        }
      ],
      "summary": {
        "species": "山羌",
        "sex": "NA",
        "lifeStage": "NA",
        "id": "NA",
        "category": "NA",
        "sciName": "Muntiacus reevesi micrurus",
        "behavior": "NA"
      }
    },
    {
      "data": [ 
        {
          "key": "species",
          "label": "物種",
          "value": "山羌",
          "data_error_flag": false,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "sex",
          "label": "性別",
          "value": "NA",
          "data_error_flag": true,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "lifeStage",
          "label": "年齡",
          "value": "non-adult",
          "data_error_flag": true,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "id",
          "label": "id",
          "value": "NA",
          "data_error_flag": false,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "category",
          "label": "category",
          "value": "NA",
          "data_error_flag": false,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "sciName",
          "label": "sciName",
          "value": "Muntiacus reevesi micrurus",
          "data_error_flag": false,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        },
        {
          "key": "behavior",
          "label": "behavior",
          "value": "NA",
          "data_error_flag": false,
          "last_validated_timestamp": 1542014471.053,
          "unit": "",
          "context": "camera-trap"
        }
      ],
      "summary": {
        "species": "山羌",
        "sex": "NA",
        "lifeStage": "non-adult",
        "id": "NA",
        "category": "NA",
        "sciName": "Muntiacus reevesi micrurus",
        "behavior": "NA"
      }
    }
  ]
}
  • response default mongodb response

錯誤提示 WF 4.17

一次取得所有樣區是否有錯誤
  • method GET
  • endpoint /project/{id}/multimedia-annotation-error-sites
  • response
{
  "results": [
    {
      "site": "新竹",
      "subSite": "南庄30林班",
      "errorCount": 142
    },
    {
      "site": "臺東處",
      "subSite": "NULL",
      "errorCount": 2127
    },
    {
      "site": "苗栗",
      "subSite": "南庄鄉田美村",
      "errorCount": 735
    }
  ]
}
提供相機錯誤數量
  • method GET
  • endpoint /project/{id}/multimedia-annotation-error-cameras?site=&subSite=
  • response
{
  "results": [
    {
      "site": "苗栗",
      "subSite": "南庄鄉田美村",
      "cameraLocation": "HC20B",
      "errorCount": 255
    },
    {
      "site": "苗栗",
      "subSite": "南庄鄉田美村",
      "cameraLocation": "HC20A",
      "errorCount": 480
    }
  ]
}

資料篩選 WF 4.2

fullCameraLocationMd5 optional, 拿掉此值會得到所有相機位置資料 date_time_corrected_timestamp optional

  • endpoint /media/annotation/query
  • post data
{
  "query": {
    "projectId": "d8064aa7-9643-44fb-bed9-1f23a690f968", // 測試計畫1的 projectId,
    "site": "苗栗",
    "fullCameraLocationMd5": {
      "$in": [fullCameraLocationMd5_1, ...]
    },
    "date_time_corrected_timestamp": {
      "$gte": 4.2.1.c 選取的起始時間timestamp, optional
      "$lte": 4.2.1.c 選取的結束時間timestamp, optional
    }
  },
  "projection": {
    "projectId": true,
    "projectTitle": true,
    "site": true,
    "subSite": true,
    "cameraLocation": true,
    "fullCameraLocationMd5": true,
    "tokens.data.key": true,
    "tokens.data.label": true,
    "tokens.data.value": true,
    "corrected_date_time": true,
    "date_time_corrected_timestamp": true,
    "url": true,
    "low_quality_url": true,
    "imageUrlPrefix": true
  },
  "limit": 1000, // 視前端效能調整數字, WF 4.6.1.a
  "skip": 0 (for page 1, 1000 for page 2, ... etc.)
}
  • response

limit 與 skip 限制的是回傳的 results 數，單位是多媒體標註文件 media annotation(以下簡稱annotation)。 annotation 下會有 tokens，每個 token 是表格資料裡的一個 row。 tokens.data 的每個物件即額外欄位

表格資料欄位與對應的回傳資料：

date_time_corrected_timestamp 便於計算連續照片是否為連拍用

不允許內容更動的欄位 -- 樣區：$site + ["-" + subSite] -- 相機位置：$cameraLocation -- 檔名：base name of $url -- 時間：$corrected_date_time 允許內容更動的欄位 -- tokens.data

Required: -- 物種: data.key == species 其他要顯示的部分(含要顯示的欄位與順序)，請參考計畫啟用的自訂欄位 project.dataFieldEnabled -- 性別: data.key == sex -- 年齡: data.key == lifeStage -- 角況: data.key == antler -- 備註: data.key == remarks 除了以上必要欄位與啟用的自訂欄位，剩下的都「不要顯示」在編輯表單

{
  "results": [
    ...,
    {
      "_id": "11053ee0ec864feca68e7bf8932dd23e",
      "tokens": [
        {
          "data": [
            {
              "key": "species",
              "value": "山羌",
              "label": "物種"
            },
            {
              "key": "sex",
              "value": "NA",
              "label": "性別"
            },
            {
              "key": "lifeStage",
              "value": "NA",
              "label": "年齡"
            },
            {
              "key": "id",
              "value": "NA",
              "label": "id"
            },
            {
              "key": "category",
              "value": "NA",
              "label": "category"
            },
            {
              "key": "sciName",
              "value": "Muntiacus reevesi micrurus",
              "label": "sciName"
            },
            {
              "key": "behavior",
              "value": "NA",
              "label": "behavior"
            }
          ]
        },
        {
          "data": [
            {
              "key": "species",
              "value": "山羌",
              "label": "物種"
            },
            {
              "key": "sex",
              "value": "NA",
              "label": "性別"
            },
            {
              "key": "lifeStage",
              "value": "non-adult",
              "label": "年齡"
            },
            {
              "key": "id",
              "value": "NA",
              "label": "id"
            },
            {
              "key": "category",
              "value": "NA",
              "label": "category"
            },
            {
              "key": "sciName",
              "value": "Muntiacus reevesi micrurus",
              "label": "sciName"
            },
            {
              "key": "behavior",
              "value": "NA",
              "label": "behavior"
            }
          ]
        }
      ],
      "url": "images/orig/測試計畫1/苗栗/南庄鄉田美村/HC20A/IMG_0064_1486661309.jpg",
      "url_md5": "11053ee0ec864feca68e7bf8932dd23e",
      "projectId": "d8064aa7-9643-44fb-bed9-1f23a690f968",
      "projectTitle": "測試計畫1",
      "site": "苗栗",
      "subSite": "南庄鄉田美村",
      "cameraLocation": "HC20A",
      "fullCameraLocationMd5": "e6d9c06937a24d9db8ac9a431b89aa17",
      "corrected_date_time": "2017-02-09 17:28:29",
      "low_quality_url": "some low quality image url",
      "imageUrlPrefix": "https://....."
    }
    ...
  ]
}

相機位置資料是否上鎖 WF 4.2.1.b

查詢相機位置資料已上鎖/上鎖者是誰

  • endpoint /camera-location/data-lock/locked
  • post data
{
  "projectId": "d8064aa7-9643-44fb-bed9-1f23a690f968", // required projectId
  "site": "苗栗", // optional 樣區名稱
  "subSite": "南庄30林班", // optional 子樣區名稱
  "fullCameraLocationMd5": null, // optional 相機位置 ID
}
  • response
{
  "ret": [
    {
      "cameraLocationDataLock": {
        "fullCameraLocationMd5": "e6d9c06937a24d9db8ac9a431b89aa17",
        "projectId": "d8064aa7-9643-44fb-bed9-1f23a690f968",
        "projectTitle": "測試計畫1",
        "locked": true,
        "locked_by": {
          "user_id": "OrcID_0000-0002-7446-3249",
          "name": "Thomas Yu",
          "email": "XXXX@XXXX.XXX"
        },
        "locked_on": 0,
        "site": "苗栗",
        "subSite": "南庄鄉田美村",
        "cameraLocation": "HC20A"
      }
    },
    {
      "cameraLocationDataLock": {
        "fullCameraLocationMd5": "8c0223d81f4958ddc3a776e0c7337e4c",
        "projectId": "d8064aa7-9643-44fb-bed9-1f23a690f968",
        "projectTitle": "測試計畫1",
        "locked": true,
        "locked_by": {
          "user_id": "OrcID_0000-0002-7446-3249",
          "name": "Thomas Yu",
          "email": "XXXX@XXXX.XXX"
        },
        "locked_on": 0,
        "site": "苗栗",
        "subSite": "南庄鄉田美村",
        "cameraLocation": "HC20B"
      }
    },
    {
      "cameraLocationDataLock": {
        "fullCameraLocationMd5": "4d3d38693056909db46c564531a63e8c",
        "projectId": "d8064aa7-9643-44fb-bed9-1f23a690f968",
        "projectTitle": "測試計畫1",
        "locked": true,
        "locked_by": {
          "user_id": "OrcID_0000-0002-7446-3249",
          "name": "Thomas Yu",
          "email": "XXXX@XXXX.XXX"
        },
        "locked_on": 0,
        "site": "新竹",
        "subSite": "南庄30林班",
        "cameraLocation": "HC21A"
      }
    }
  ]
}

編輯模式, 鎖相機位置 WF 4.3.2

fullCameraLocationMd5：相機地點 id projectId：計畫名稱，除了當雙保險，還用來限制本操作的權限

後端機制會在 bulk-replace 批次更新相機位置上鎖狀態前，檢查相機位置是否已被其他人鎖定。欲鎖定的多個相機位置中，只要有一個已被他人鎖定，整個鎖定流程都會失敗

  • endpoint /camera-location/data-lock/bulk-replace
  • post data
[
  {
    "fullCameraLocationMd5": "4d3d38693056909db46c564531a63e8c", // 相機位置 id
    "projectId": "d8064aa7-9643-44fb-bed9-1f23a690f968", // 計畫名稱
    "locked": false, // 上鎖 true / 解鎖 false
  },
  {
    // 更多相機位置
  },
  ...
]
  • response default db response

編輯模式, 儲存按鈕 WF 4.3.2.c

更新 WF 4.2 response 的資料 annotation > tokens[] > data[] 使用者上傳的資料有可能包含不在 WF 3.2 允許的欄位，需要將之保留，因此要用特定的 update 寫法。

  • endpoint /media/annotation/bulk-update
  • post data 根據 WF 4.2 回傳的資料（要注意 array items 的順序）修改現有的 tokens.data
[
  {
    "_id": "11053ee0ec864feca68e7bf8932dd23e", // annotation 中的 _id 或 url_md5 (兩個值相同)
    "projectId": "d8064aa7-9643-44fb-bed9-1f23a690f968", // annotation 中的 projectId
    "fullCameraLocationMd5": "e6d9c06937a24d9db8ac9a431b89aa17", // annotation 中的 fullCameraLocationMd5
    "$set": {
      "tokens.0.data.2.value": "Adult", // 設定annotation下的第1個token的第3項資料值
      "tokens.1.data.1.value": "F" // 設定annotation下的第2個token的第2項資料
    }
  },
  {
    // 更新另一個 annotation 資料
  },
  ...
]

編輯模式 操作相關

複製一列並貼上 by 增加一組 tokens, WF 4.10.2, WF 4.10.3

下拉物種清單（與其他有固定選項的欄位） WF 4.5, WF 4.9

取得特定計畫要顯示的所有欄位 WF 4.1.3

含必要欄位 (species)、已啟用的自訂欄位 (dataFieldEnabled) 與欄位允許內容資訊

  • endpoint /project/data-fields

  • post data

{
  "projectId": "d8064aa7-9643-44fb-bed9-1f23a690f968" // 測試計畫1的projectId
}
  • response
{
  "ret": [
    {
      "_id": null,
      "speciesList": [ // 必填欄位，label:物種, key:species
        "山羌",
        "水鹿",
        "鼬獾",
        "定時測試",
        "工作照",
        "空拍"
      ],
      "dailyTestTime": [ // 每日拍攝測試照的時間, 24 時制
        {
          "since": 1539593959,
          "time": "12:00:00"
        }
      ],
      "fieldDetails": [ // 其他啟用欄位
        {
          "_id": "lifeStage",
          "key": "lifeStage",
          "label": "年齡",
          "description": "string",
          "widget_type": "select", // 如果是 select, 則會需要 options
          "widget_select_options": [
            "Young",
            "Adult",
            "Unknown"
          ],
          "created": 1541401451.944,
          "modified": 1541401451.944,
          "widget_date_format": null
        },
        {
          "_id": "sex",
          "key": "sex",
          "label": "性別",
          "description": "string",
          "widget_type": "select",
          "widget_select_options": [
            "M",
            "F",
            "Unknown"
          ],
          "created": 1541401451.944,
          "modified": 1541401451.944,
          "widget_date_format": null
        },
        {
          "_id": "antler",
          "key": "antler",
          "label": "角況",
          "description": "string",
          "widget_type": "select",
          "widget_select_options": [
            "TBD",
            "Unknown"
          ],
          "created": 1541401451.944,
          "modified": 1541401451.944,
          "widget_date_format": null
        },
        {
          "_id": "remarks",
          "key": "remarks",
          "label": "備註",
          "description": "其他相關內容",
          "widget_type": "text", // 文字欄位，不做任何內容檢查
          "created": 1541401451.944,
          "modified": 1541401451.944,
          "widget_select_options": null,
          "widget_date_format": null
        }
      ]
    }
  ]
}

整份文件更新 (可以先不管這邊)

bulk-update 方法需要特定的 spec for access control _id： update 的對象 projectId：權限管控並保護資料一致性，不會真的用在資料更新上 fullCameraLocationMd5：同 project $set：裡面若有設定 project 與 fullCameraLocationMd5，後端會為了維護一致性將之清除

  • endpoint /media/annotaion/bulk-update
  • post data
[{
  "_id": $url_md5,
  "projectId": $projectId,
  "fullCameraLocationMd5": $fullCameraLocationMd5,
  "$set": {
    "tokens": [
      {
        "data": [
          {
            "label": "物種",
            "key": "species",
            "value": "鼬獾",
            "unit": "",
            "data_error_flag": false|true,
            "last_validated_timestamp": now(),
            "context": "camera-trap"
          },
          {
            // 其他 data
          },
          ...
        ],
        "species_shortcut": "鼬獾",
        ... // 其他屬性維持不變
      },
      {
        // 其他 tokens
      },
      ...
    ]
  }
}]

命名

API documentation

V1

Legacy docs

Clone this wiki locally