Sample Codes for web API use

Your script may receive map image file by sending request with map configuration to anatomography API.

Contents

Calling map API from perl scripts

In the following sections, we show example Perl scripts that generate an output file (image or animation) in the same directory as the scrpt when executed.

  • The name of the script is example.pl
  • The result files are result.png or result.gif
  • Create and execute the example.pl in your linux environment will results in a generation of result.xxx in the same directory.
  • By opening result.xxx, you can see the anatomogram image or animation you specified by the script.
  • NOTE: Example use a library "libwww-perl HTTP" for communication with API with perl. If your environment do not have one, install "libwww-perl HTTP" from CPAN.

example.pl

Script files named example.pl is a concatenation of four segments.

  1. Seg1: Direct the message to anatomography mapAPI  : common to all scripts.
  2. Seg2: Store JSON object (map configuration) to pass : map configuration in JSON format, determins the image content.
  3. Seg3: Generate request messge by specifying a method of the API and configuration having a form of JSON object: common to all scripts except for the method name, image? or animation?
  4. Seg4: Send Request and Receive the API response and save it as a file: common to all scripts


Seg1

  • This segment is stable. Just copy and paste in your script
#!/usr/bin/env perl
use strict;
use LWP::UserAgent;
my $serverURL = "http://lifesciencedb.jp/bp3d/API/";

Seg2

$json = <<JSON;
{
        "Common":{
                "Version":"4.0",
                "TreeName":"partof"
        },
        "Part":[
                {
                        "PartName":"human body", # Some common names are allowed (list), better be FMA_ID in the list (list)
                        "PartColor":"F0D2A0",  #Hexadecimal color code
                        "PartOpacity":0.1
                },
                {
                        "PartName":"skeletal system",
                        "PartColor":"FFFFFF"
                },
                {
                        "PartName":"heart",
                        "PartColor":"FF0000"
                }
        ]
}
JSON

Seg3 for still image

  • This segment specify a subroutine process which makes a message directed of a method of API with query parameter of JSON object ($json)
  • In this example a method is "image?"
sub getImage () {                                # Define subroutine name
        my $json = shift;
        my $userAgent = LWP::UserAgent->new;
        my $request = HTTP::Request->new('GET', $serverURL."image?".$json);  # Specify which method of API you use by this subroutine
        my $response = $userAgent->request($request);
        return $response->content;
}

Seg3 for rotating animation in GIF

sub getAnimation () {
	my $json = shift;
	my $userAgent = LWP::UserAgent->new;
	my $request = HTTP::Request->new('GET', $serverURL."animation?".$json);
	my $response = $userAgent->request($request);
	return $response->content;
}

Seg4 for still image

  • Stable except for the " subroutine name in Seg3 " and "result file name" .

open OUT, ">result.png";  # The name of result file
binmode(OUT);
print OUT  &getImage($json);  # The name of subroutine you choose
close OUT;

Seg4 for animation GIF

open OUT, ">gifanimation.gif";
binmode(OUT);
print OUT  &getAnimation($json);	# 作成したJSONを利用して描画リクエスト
close OUT;

result.png

By executing the file example.pl "', you will have the "'result.png"' as below.

WS000035.JPG

Making anatomical address encoder

  • By using API/pick function, you can make a platform which turns people into human GPS for a body.
  • A click on a manikin image on this platform is coded as pin URL for that position on a 3D manikin as below.
  • Pin URL is exchangable, mappable, and contains FMA_ID.
http://lifesciencedb.jp/bp3d/API/animation?
{"Part":[{"PartID":"FMA16586"}],"Common":{"Version":"4.1","TreeName":"partof"},"Pin":[{"PinY":-69,"PinUpVectorX":0,"PinArrowVectorY":17,"PinDescription":"","PinCoordinateSystemName":"bp3d",
"PinArrowVectorX":-11,"PinUpVectorZ":1,"PinUpVectorY":0,"PinZ":911,"PinX":-98,"PinPartID":"FMA16586","PinArrowVectorZ":-5}]}
  • This example anatomical address encoder [1], serves as a template for your own task platform. I

API/pick function

  • ADDRESS: http://lifesciencedb.jp/bp3d/API/pick
  • REQUEST content; map configuration and X,Y coordinates on the map image,
  • RESPONCE content; 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)

Constracting JSON object for API/pick request

  • JSON object for /pick has two components: map configuration($config) and "picked" coordinates on the map image ($pick).
  • $pick should be an additional key value pair in JSON object passed to API.

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
}

A process to put a pin on the map

  1. User's browser visualize the map of $config
  2. User picks a position on a image of $config.
  3. Your script receive X,Y coordinates from the browser.
  4. Your script put the information in the form of JSON ($pick).
  5. Your script pass JSON($config,$pick) to API/pick
  6. Your script receive the pin coordinate
  7. Your script put the pin coordinate into JSON $pin
  8. Your script construct JSON ($config,$pin)
  9. Your script request JSON ($config,$pin) to API/image

Processing response returned from API/pick

  • The response from API/pick looks like this:
{
 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
  }
 }
}