Anatomography map API specification

Contents

Overview

  • The Anatomography map API returns an image either in still PNG or animated GIF files in response to an HTTP request via a URL.
  • In addition it provides functions to make the map image interactive on the web application.
  • For each request, you can specify the model data, picturing condition, or point on a image to be mapped on the model.
  • The map images can be embedded within and <img> tag's src attribute in a HTML file for browsers, or used as a hyperlink to the image in other application files.
Sample Codes for web API use, 
Map configuration examples in JSON ]

URL parameters

  • Anatomography URL must be of the folwoing form:
http://lifesciencedb.jp/bp3d/API/methods?input_data_string

Methods

  • API provides five different functions (methods) specified by their paths.
  • Output of the functions are images of the maps, or element in the map data.

methods for Image generation (returns image)

  1. API/image: REQUEST; map configuration,// REPLY; image of map
  2. API/animation: REQUEST; map configuration,// REPLY; gif animation map

methods for modify maps on the browser ( Return map data element )

  1. API/map: REQUEST; map configuration and X,Y,Z coordinates on the surface of the model // REPLY; XY coordinates on the image. // This function is used to draw numbers at the foot of pin markers and lines linking pin markers and annotations
  2. API/focus: REQUEST; map configuration // Returnz Zoon value to focus on the parts in the map configuration.
  3. API/pick: REQUEST; map configuration and X,Y coordinates on the map image, // Return; X,Y,Z coordinates and the surface vector of the polygon. used to select segment by mouse action and compute pin-marker coordinates (rotate model by mouse-action on the image is done in javascript in client side)

input data string

  • input data for APi functions have to be in a form of associative arrays of parameter type and parameter value in syntax of URL query string (& = ) or in JSON (Javascript object notation).
  • Input data include map configuration to make image of the map and coordinates of the mouse-click on the image that make the image clickable.
  • Input data consists of 10 categories of about one hundred parameter types.
  • Some categories are common to all method but others are specific to some methods as shown below.


input data to map API
map configuration clickable
Common Window Camera ObjectRotate Light Legend Part Pin Animation Pick
image
animation
focus
pick
map

Types, meanings, and allowed values for input data parameters

  • The following is a list of parameters accepted by map API to define and modify custom maps.
  • The default values as shown will complement the parameter value when URL do not include them.

Common parameters

Parameter type Default value parameter meaning allowed values, range
"Common":{ Array of key value pairs in JSON
"Model": "bp3d" Kit name "bp3d"
"Version": "4.0" Kit version "2.0"|"3.0"|"4.0"|"4.1"
"AnatomogramVersion": "20110318" Configuration syntax version "20110318" at this moment
"ScalarMaximum": 65535 Maximum value for heatmap any integer
"ScalarMinimum": -65535 Minimum value for heatmap any integer smaller than max
"ColorbarFlag": false Insert color progression chart in image false | true
"ScalarColorFlag": false Use backcloth of flagged parts as Choropleth map false | true
"TreeName": "isa" Logical tree for parts aggregation "isa"|"partof"
"DateTime": none Time stamp of configuration "yyyymmddhhmmss"
"CoordinateSystemName": "bp3d" Rendering space "bp3d"
"CopyrightType": "" Copyright insert on the image "large"|"medium"|"small"
"PinDescriptionDrawFlag" false Show notes for pins on the image false | true
"PinIndicationLineDrawFlag" 0 Draw lines between pins and pin note 1; tail, 2; head 0 | 1 | 2
}

Window parameters

Parameter type Default value parameter meaning allowed values, range
"Window":{ Array of key value pairs in JSON
"ImageWidth": 500 Output image width in pixcel integer less than 5000 (1000 for animation)
"ImageHeight": 500 Height of the output image in pixcel integer less than 5000 (1000 for animation)
"BackgroundColor": "FFFFFF" Background color in hexadecimal code "000000" to "FFFFFF"
"BackgroundOpacity": 100 Background opacity(0~100) integer 0 to 100
"GridFlag": FALSE Draw grid pattern on the image false | true
"GridTickInterval": 100 Unit of the grid(mm) non negative integer
"GridColor": "FFFFFF" Grid line color in Hexadecimal code "000000" to "FFFFFF"
}

Camera parameters

Parameter type Default value parameter meaning allowed values, range
"Camera":{ Array of key value pairs in JSON
"CameraMode": "front" camera mode, either movable or fixed "camera"|"front"|"back"|"left"|"right"|"top"|"bottom"
"CameraX": 0 camera X-coordinate, when mode=camera Double precision
"CameraY": 0 camera Y-coordinate, when mode=camera Double precision
"CameraZ": 0 camera Z-coordinate, when mode=camera Double precision
"TargetX": 0 Camera direction X coordinate of target point Double precision
"TargetY": 0 Camera direction Y coordinate of target point Double precision
"TargetZ": 0 Camera direction Z coordinate of target point Double precision
"CameraUpVectorX": 0 Camera up vector X (upside of camera device) Double precision (usually unit vector)
"CameraUpVectorY": 0 Camera up vector Y Double precision (usually unit vector)
"CameraUpVectorZ": 0 Camera up vector Z Double precision (usually unit vector)
"Zoom": 0 Arbitrary zooming power 0 to 19.8
"AddLatitudeDegree": 0 Rotate latitudinary 0 to 360
"AddLongitudeDegree": 0 Rotate longitudinary 0 to 360
}

Object rotation parameters

Parameter type Default value parameter meaning allowed values, range
"ObjectRotate":{ parameters for object rotation Array of key value pairs in JSON
"RotateDegree": 0 Angle of rotation in degree Double precision
"RotateCenterX": 0 center for rotation X Double precision
"RotateCenterY": 0 center for rotation Y Double precision
"RotateCenterZ": 0 center for rotation Z Double precision
"RotateAxisVectorX": 0 axis vector for rotation X Double precision
"RotateAxisVectorY": 0 axis vector for rotation Y Double precision
"RotateAxisVectorZ": 1 axis vector for rotation Z Double precision
}

Part parameters

Parameter type Default value parameter meaning allowed values, range
"Part":[ repeat for all parts with comma separation
{ Array of key value pairs in JSON
"PartID": "" concept ID for body parts in FMA
"PartName": "" common concept names (effective when no ID specified)
"PartColor": "FFFFFF" hexadecimal color code
"PartScalar": 0 Data value mapped to the Part
"ScalarColorFlag" false Use surface as a part of Choropleth map true | false
"PartOpacity": 1 Opacity of the surface 1=opaque actual number 0 to 1
"PartRepresentation": "surface" object representation "surface"|"wireframe"|"point"
"UseForBoudingBoxFlag": true included in bounding box for zoom true | false
"PartDeleteFlag": false Do not shown this part true | false
}
]

Legend parameters

Parameter type Default value parameter meaning allowed values, range
"Legend":{ Array of key value pairs in JSON
"DrawLegendFlag": false Draw note on the image true | false
"LegendPosition": "UL" location of note (only upper left is supported) "UL"
"LegendColor": "FFFFFF" Color of note in hexadecimal code 000000 to FFFFF
"LegendTitle": "" title of note within URL allowance 2083 altogether
"Legend": "" content of note within URL allowance 2083 altogether
"LegendAuthor": "" author of note within URL allowance 2083 altogether
}

Pin parameters

Parameter type Default value parameter meaning allowed values, range
"Pin":[ repeat for all pins with comma separation
{ associative array of parameter type and value
"PinID": "" marker-pin serial ID in the map any string of character
"PinX": 0 Pin X coordinate Double
"PinY": 0 Pin Y coordinate Double
"PinZ": 0 Pin Z coordinate Double
"PinArrowVectorX": 0 pin vector direction X element Double precision (usually unit vector)
"PinArrowVectorY": 0 pin vector direction Y element Double precision (usually unit vector)
"PinArrowVectorZ": 0 pin vector direction Z element Double precision (usually unit vector)
"PinUpVectorX": 0 Pin Up vector X element Double precision (usually unit vector)
"PinUpVectorY": 0 Pin Up vector Y element Double precision (usually unit vector)
"PinUpVectorZ": 1 Pin Up vector Z element Double precision (usually unit vector)
"PinScreenX": 0 X coordinate on the pin image integer up to image width
"PinScreenY": 0 Y coordinate on thepin image integer up to image height
"PinDescriptionDrawFlag": false Show note for each pin in image true | false
"PinDescriptionColor": "FFFFFF" Color of the note in Hexadecimal 000000 to FFFFFF
"PinColor": "FFFFFF" Color of the marker pin in Hexadecimal 000000 to FFFFFF
"PinShape": "CONE" template of the marker-pin "CONE"|"PIN_LONG"
"PinSize": 10 size of the marker-pin Double precision
"PinCoordinateSystemName": "bp3d" coordinate system of the marker-pin "bp3d"
"PinPartID" "" smallest part marked by pin in ID used in reply of pick
"PinPartName" "" smallest part marked by pin in name used in reply of pick
"PinDescription" "" annotation on a marker-pin text within URL allowance 2083 altogether
}
]

Pick parameters

Parameter type Default value parameter meaning allowed values, range
"Pick":{ Array of key value pairs in JSON
"MaxNumberOfPicks": 20 penetrate object surface by this number integer 1 to 20
"ScreenPosX": 0 X-coordinate on a image in pixcel up to image width
"ScreenPosY": 0 Y-coordinate on a image in pixcel up to image height
}

Light parameters

Parameter type Default value parameter meaning allowed values, range
"Light":{ Array of key value pairs in JSON
"LightPosX": 0 X-coordinate of light source Double precision
"LightPosY": 0 Y-coordinate of light source Double precision
"LightPosZ": 0 Z-coordinate of light source Double precision
"LightAddDistance": 0 move light away from target by this mm Double precision
"LightAddLatitude": 0 turn light in lattitude by this degree Double precision 0 to 360
"LightAddLongitude": 0 turn light in longitude by this degree Double precision 0 to 360
"LightIsAuto": true light source colocalize with camera true | false
"LightIsParallel": true pararelle light (true) or point light (false) true | false
"LightIsSpec": true Grossy object surface (true) or matt (false) true | false
}

Animation parameters

Parameter type Default value parameter meaning allowed values, range
"Animation":{ Array of key value pairs in JSON
"Mode": "camera" camera go around or object rotate "camera" | "object"
"IsLatitude": false camera go around lattitude direction or longitude direction true | false
"CenterX": 0 object rotation center X Double precision
"CenterY": 0 object rotation center Y Double precision
"CenterZ": 0 object rotation center Z Double precision
"AxisVectorX": 0 object rotation axis vector X Double precision
"AxisVectorY": 0 object rotation axis vector Y Double precision
"AxisVectorZ": 1 object rotation axis vector Z Double precision
"DivideNumber": 60 number of animation framed for 1 rotation natural number
"DelayTime": 10 frame migration time in miliseconds natural number
"ExpNumOfColors": 8 number of colors 2 powered by N 1 to 8
"QuantizeMode": 1 quantize mode in GIF color (0: normal, 1: total) 0|1
}

Reply data from map API

image

  • When map URL is requested by "GET" image data in PNG format will returned.
  • When requested by "POST", to browser older than IE8 will receive the same as GET.
  • Otherwise reply is in JSON formatted data as below
 {
  "data":"image/png;base64,base64 encoded data"
 }

animation

  • Reply animated gif file

focus

  • Returns following data in JSON
{
 Camera:{
  CameraX:nnn,
  CameraY:nnn,
  CameraZ:nnn,
  TargetX:nnn,
  TargetY:nnn,
  TargetZ:nnn,
  CameraUpVectorX:nnn,
  CameraUpVectorY:nnn,
  CameraUpVectorZ:nnn,
  Zoom:nnn
 }
}

pick

  • Returns following data in JSON
{
 Pin:[
  {
   PinX:nnn,
   PinY:nnn,
   PinZ:nnn,
   PinArrowVectorX:nnn,
   PinArrowVectorY:nnn,
   PinArrowVectorZ:nnn,
   PinUpVectorX:nnn,
   PinUpVectorY:nnn,
   PinUpVectorZ:nnn,
   PinPartID:"xxx",
   PinCoordinateSystemName:"xxx"
  },
  ...
  {
   Repeat the above for all pins
  }
 }
}

map

  • Returns data in JSON
{
 Map:[
  {
   PinX:nnn,
   PinY:nnn,
   PinZ:nnn,
   PinScreenX:nnn,
   PinScreenY:nnn
  },
  ...
  {
   Repeat as above for all pins
  }
 }
}

Japanese version

一般的な設定項目

"Common": {
 "Model":"bp3d",			モデル(文字列)
 "Version":"4.0",			バージョン(文字列/"2.0"、"3.0"、"4.0"。未指定の場合最新バージョンとなります)
 "AnatomogramVersion":"20110318",	アナトモグラムのバージョン(文字列)
 "ScalarMaximum":65535,			Scalar最大値(整数)
 "ScalarMinimum":-65535,		Scalar最小値(整数)
 "ColorbarFlag":false,			カラーバーの描画フラグ(Boolean)
 "ScalarColorFlag":false,		Valueを利用した臓器描画フラグ(Boolean)
 "TreeName":"isa",			利用するTree名(文字列/"isa"、"partof"のいずれかを指定します)
 "DateTime":"",				描画時刻(文字列、yyyymmddhhmmss)
 "CoordinateSystemName":"bp3d",		描画座標系(文字列)
 "CopyrightType":"",			コピーライト画像サイズ(文字列/未指定、large、medium、small)
 "PinDescriptionDrawFlag":false,	true:description表示、false:description非表示(Boolean)
 "PinIndicationLineDrawFlag":0		ピンからPin Descriptionへの線描画指定(整数/0:描画なし、1:ピン先端から描画、2:ピン終端から描画)
}
ウィンドウ項目

ウィンドウ(描画画像全体)に関する項目

"Window": {
 "ImageWidth":500,			画像幅px数(整数)
 "ImageHeight":500,			画像高さpx数(正数)
 "BackgroundColor":"FFFFFF",		背景色RGB(文字列、16進数6桁)
 "BackgroundOpacity":100,		背景の不透明度(整数、0~100)
 "GridFlag":false,			Gridの描画有無(Boolean)
 "GridTickInterval":100,		Gridの描画単位(整数、mm指定)
 "GridColor":"FFFFFF"			Gridの描画色RGB(文字列、16進数6桁)
}
カメラ項目

カメラ(視点)に関する項目

"Camera": {
 "CameraMode":"front",			カメラ位置のモード(文字列、camera、front、back、left、right、top、bottom)
 "CameraX":0,				カメラのX座標(Double)
 "CameraY":0,				カメラのY座標(Double)
 "CameraZ":0,				カメラのZ座標(Double)
 "TargetX":0,				中心点のX座標(Double)
 "TargetY":0,				中心点のY座標(Double)
 "TargetZ":0,				中心点のZ座標(Double)
 "CameraUpVectorX":0,			カメラの上方ベクトルのX要素(Double)
 "CameraUpVectorY":0,			カメラの上方ベクトルのY要素(Double)
 "CameraUpVectorZ":0,			カメラの上方ベクトルのZ要素(Double)
 "Zoom":0,				ズーム値(Double、0~19.8)
 "AddLatitudeDegree":0,			緯度方向への追加回転角度(Double、0~360度)
 "AddLongitudeDegree":0			経度方向への追加回転角度(Double、0~360度)
}
オブジェクトの回転項目

オブジェクト(パーツ群)の回転に関する項目

"ObjectRotate": {
 "RotateDegree":0,			オブジェクトの回転角度(Double、0~360度)
 "RotateCenterX":0,			オブジェクトの回転中心X座標(Double)
 "RotateCenterY":0,			オブジェクトの回転中心X座標(Double)
 "RotateCenterZ":0,			オブジェクトの回転中心X座標(Double)
 "RotateAxisVectorX":0,			オブジェクトの回転軸ベクトルX要素(Double)
 "RotateAxisVectorY":0,			オブジェクトの回転軸ベクトルY要素(Double)
 "RotateAxisVectorZ":0			オブジェクトの回転軸ベクトルZ要素(Double)
}
パーツ項目

パーツ(臓器)に関する項目。複数が前提のため、要素が1つの場合でも配列として記載する必要があります。

"Part": [
 {
  "PartID":"",				臓器ID(文字列、名称より優先されます)
  "PartName":"",			臓器名(文字列)
  "PartColor":"FFFFFF",			臓器色RGB(文字列、16進数6桁)
  "PartScalar":0.0,			臓器スカラー値(Double)
  "ScalarColorFlag":false,		臓器をスカラー値で描画するフラグ(Boolean)
  "PartOpacity":1,			臓器不透明度(Double、0~1)
  "PartRepresentation":"surface",	臓器描画方法(文字列、surface、wireframe、point)
  "UseForBoundingBoxFlag":true,		臓器をBoundingBoxに含めるか否かのフラグ(Boolean、Focus時にはBoudingBoxに含まれる臓器群が収まるように拡大率が返されます)
  "PartDeleteFlag":false		臓器の削除フラグ(Boolean)
 }
]
Legend項目

描画画像のLegendに関する項目

"Legend": {
 "DrawLegendFlag":false,		Legendの描画有無フラグ(Boolean)
 "LegendPosition":"UL",			Legendの描画位置(文字列、ULのみ)
 "LegendColor":"FFFFFF",		Legendの描画色RGB(文字列、16進数6桁)
 "LegendTitle":"",			Legendのタイトル(文字列)
 "Legend":"",				Legend(文字列)
 "LegendAuthor":""			Legend Author(文字列)
}
Pin項目

Pinに関する項目。複数が前提のため、要素が1つの場合であっても配列として記載する必要があります。

"Pin": [
 {
  "PinID":"",				PinID(文字列)
  "PinX":0,				Pinの3次元空間上X座標(Double)
  "PinY":0,				Pinの3次元空間上Y座標(Double)
  "PinZ":0,				Pinの3次元空間上Z座標(Double)
  "PinArrowVectorX":0,			PinベクトルのX要素(Double)
  "PinArrowVectorY":0,			PinベクトルのY要素(Double)
  "PinArrowVectorZ":0,			PinベクトルのZ要素(Double)
  "PinUpVectorX":0,			Pinの上方ベクトルのX要素(Double)
  "PinUpVectorY":0,			Pinの上方ベクトルのY要素(Double)
  "PinUpVectorZ":0,			Pinの上方ベクトルのZ要素(Double)
  "PinScreenX":0,			Pinの画像上のX座標(Double)
  "PinScreenY":0,			Pinの画像上のY座標(Double)
  "PinDescriptionDrawFlag":false,	PinのDescription描画フラグ(Boolean)
  "PinDescriptionColor":"FFFFFF",	PinのDescription描画色RGB(文字列、16進数6桁)
  "PinColor":"FFFFFF",			Pinの描画色RGB(文字列、16進数6桁)
  "PinShape":"",			Pin形状(文字列、16進数6桁)
  "PinSize":10.0,			Pinサイズ(Double)
  "PinCoordinateSystemName":"bp3d",	Pin作成時の座標系(文字列)
  "PinPartID":"",			Pinが打たれているパーツのID(文字列)
  "PinPartName":"",			Pinが打たれているパーツの名称(文字列)
  "PinDescription":""			PinのDescription(文字列)
 }
]
Pick項目

Pickに関する項目

"Pick": {
 "MaxNumberOfPicks":20,			ピックする最大数(整数)
 "ScreenPosX":0,			画像上のピック座標X(整数)
 "ScreenPosY":0				画像上のピック座標Y(整数)
}
Light項目

光源に関する項目

"Light": {
 "LightPosX":0,				光源位置座標X(Double)
 "LightPosY":0,				光源位置座標Y(Double)
 "LightPosZ":0,				光源位置座標Z(Double)
 "LightAddDistance":0,			光源位置が動的の場合、光源位置のターゲットとの距離を指定ポイント分移動します。(Double)
 "LightAddLatitude":0,			光源位置が動的の場合、光源位置を緯度方向に指定度数移動します。(Double)
 "LightAddLongitude":0,			光源位置が動的の場合、光源位置を経度方向に指定度数移動します。(Double)
 "LightIsAuto":true,			trueの場合光源位置が動的に変化(カメラと同一位置)します。(Boolean)
 "LightIsParallel":true,		true:並行光源、false:点光源になります。(Boolean)
 "LightIsSpec":false			true:反射効果有り、false:反射効果無し、になります。(Boolean)
}
Animation項目

アニメーションGIFに関する項目

"Animation": {
 "Mode":"camera",			回転モードを指定します。(文字列、camera:中心点を中心に緯度または経度方向にカメラを回します。object:回転中心を通り軸ベクトルを回転軸としてオブジェクトを回します。)
 "IsLatitude":false,			カメラ回転モードにおける回転方向を指定します。(Boolean、true:緯度方向の回転、false:経度方向の回転)
 "CenterX":0,				オブジェクト回転モードの回転中心X座標。(Double)
 "CenterY":0,				オブジェクト回転モードの回転中心Y座標。(Double)
 "CenterZ":0,				オブジェクト回転モードの回転中心Z座標。(Double)
 "AxisVectorX":0,			オブジェクト回転モードの回転軸ベクトルX要素。(Double)
 "AxisVectorY":0,			オブジェクト回転モードの回転軸ベクトルY要素。(Double)
 "AxisVectorZ":0,			オブジェクト回転モードの回転軸ベクトルZ要素。(Double)
 "DivideNumber":60,			1回転の分割フレーム数。(整数)
 "DelayTime":10,			1フレームの表示時間ミリ秒。(整数)
 "ExpNumOfColors":8,			カラーマップのべき乗数。(整数、1:2色~8:256色)
 "QuantizeMode":1			gifカラーの量子化モード(0:ノーマル、1:トータル)
}
レスポンス

レスポンス内容(JSON)

各メソッドの返すレスポンスは下記のようになっています。

image

GETリクエストの場合
 画像データ(image/png)を返します。

POSTリクエストの場合
 IE8以前:画像データ(image/png)を返します。
 上記以外:下記形式のJSONデータを返します。
  {
   "data":"image/png;base64,base64エンコードデータ"
  }
animation

 画像データ(image/gif)を返します。
focus

 下記形式のJSONオブジェクトを返します。
 {
  Camera:{
   CameraX:nnn,
   CameraY:nnn,
   CameraZ:nnn,
   TargetX:nnn,
   TargetY:nnn,
   TargetZ:nnn,
   CameraUpVectorX:nnn,
   CameraUpVectorY:nnn,
   CameraUpVectorZ:nnn,
   Zoom:nnn
  }
 }
pick

 下記形式のJSONオブジェクトを返します。
 {
  Pin:[
   {
    PinX:nnn,
    PinY:nnn,
    PinZ:nnn,
    PinArrowVectorX:nnn,
    PinArrowVectorY:nnn,
    PinArrowVectorZ:nnn,
    PinUpVectorX:nnn,
    PinUpVectorY:nnn,
    PinUpVectorZ:nnn,
    PinPartID:"xxx",
    PinCoordinateSystemName:"xxx"
   },
   ・・・
   {
    同上形式のPin情報
   }
  }
 }
map

 下記形式のJSONオブジェクトを返します。
 {
  Map:[
   {
    PinX:nnn,
    PinY:nnn,
    PinZ:nnn,
    PinScreenX:nnn,
    PinScreenY:nnn
   },
   ・・・
   {
    同上形式のPin情報
   }
  }
 }