Differences

This shows you the differences between two versions of the page.

--- userguide:thinknode [2015/06/22 20:29] – [SOBP Dose Calculation] dbottomley
+++ userguide:thinknode [2015/07/02 15:42] (current) – removed dpatenaude
@@ Line 1: / Line 1: @@
-====== thinknode™ Examples ======
-These examples provide a starting point for issuing http connections and requests to the dosimetry app on the thinknode™ framework. They are provided as is, and are written in python and c++. Any further dependencies are listed along with the provided scripts.
-====== C++ ======
-A simple C++ project that handles posting immutable objects and calculation requests to thinknode™ framework. The //main()// function toggles on which task to perform. Below are the defined functions of the project as well as a link to download the file in its entirety.
-Dependencies:
-  * [[http://curl.haxx.se/libcurl/c/example.html|libcurl]]
-  * [[https://github.com/open-source-parsers/jsoncpp|jsoncpp]]
-===thinknode.cpp===
-  * {{:userguide:thinknode.cpp|}}
-<code cpp>
-// Copyright (c) 2015 .decimal, Inc. All rights reserved.
-// Desc:     Worker to perform tasks on thinknode framework
-#include "stdafx.h"
-#include <stdio.h>
-#include <string.h>
-#include <iostream>
-#include <fstream>
-#include <sstream>
-#include <json/json.h>
-#define CURL_STATICLIB
-#include <curl/curl.h>
-using namespace std;
-// API configuration
-string basic_user = "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456";    // Base64 encoded username:password
-string api_url = "https://api.thinknode.com/v1.0";         // thinknode url
-string app_name = "Dosimetry";                             // app name
-string app_version = "1.0.0";                              // app version
-// Curl get request call back
-static size_t WriteCallback(void *contents, size_t size, size_t nmemb, void *userp)
-...
-// Select a specific json tag into string
-string get_json_value(string json, string id, int num = 0)
-...
-// Curllib get http request
-string do_curl_get(string auth, string url)
-...
-// Curllib post http request
-string do_curl_post(string auth, string json, string url)
-...
-// Handles http request to get the user ID from the basic_user
-string get_user_token()
-...
-// Handles http request for realm id
-string get_realm_id(string token)
-...
-// Handles http request for context id
-string get_context_id(std::map<string, string> config)
-...
-// API Authentication
-std::map<string, string> authenticate()
-...
-// Grab and post the specified calc request
-void post_calc_request()
-...
-// Grab and post sepcified object to the ISS
-void post_immutable_object()
-...
-int main(void)
-...
-</code>
-===== C++: Immutable Storage =====
-The below example is a function in the [[userguide:thinknode#thinknode.cpp|thinknode.cpp]] class to post an immutable object to the dosimetry app on the thinknode™ framework. This example can be used for any immutable storage post using any datatype by replacing the json iss file.
-Dependencies:
-  * {{:userguide:aperture_creation_params.json|compute_aperture_creation_params.json}}
-<code cpp>
-void post_immutable_object()
-{
-    // Immutable info
-    string path = "C:\\";                                    // Path of folder json file is located in
-    string sjon_iss_file = "aperture_creation_params.json";  // local json object file
-    string obj_name = "aperture_creation_params";            // app named_type
-    std::map<string, string> iam = authenticate();
-    // Read local immutable json file
-    std::ifstream json_file((path + sjon_iss_file).c_str());
-    string str((std::istreambuf_iterator<char>(json_file)), std::istreambuf_iterator<char>());
-    // Post object
-    std::cout << "Posting Object to ISS..." << std::endl;
-    string authentication_string = "Authorization : Bearer " + iam["user_token"];
-    string res = do_curl_post(
-        authentication_string,
-        str,
-        api_url + "/iss/named/" + app_name + "/" + obj_name + "/?context=" + iam["context_id"]);
-    std::cout << "Immuntable ID: " << res << std::endl;
-}
-</code>
-**Returns:**
-  - The ID (in json) of the object stored in Immutable Storage.
-===== C++: Calculation Request =====
-The below example is a function in the [[userguide:thinknode#thinknode.cpp|thinknode.cpp]] class to post a calculation request to dosimetry. This example can be used for any calculation request using any datatype by replacing the calculation request json file. This request will post a calculation request, check the status using long polling with a specified timeout, and return the calculation result.
-Dependencies:
-  * {{:userguide:compute_aperture.json|compute_aperture.json}}
-<code cpp>
-void post_calc_request()
-{
-    // Request info
-    string path = "C:\\";                            // Path of folder json file is located in
-    string sjon_iss_file = "compute_aperture.json";  // local json calc request
-    std::map<string, string> iam = authenticate();
-    std::ifstream json_file((path + sjon_iss_file).c_str());
-    string str((std::istreambuf_iterator<char>(json_file)), std::istreambuf_iterator<char>());
-    string authentication_string = "Authorization : Bearer " + iam["user_token"];
-    // Get calculation id
-    std::cout << "Sending Calculation..." << std::endl;
-    string calculation_id = get_json_value(
-        do_curl_post(authentication_string,
-        str, api_url + "/calc/?context=" + iam["context_id"]),
-        "id");
-    // Get calculation Status - using long polling
-    std::cout << "Checking Calculation Status..." << std::endl;
-    string calculation_status = get_json_value(
-        do_curl_get(authentication_string,
-        api_url + "/calc/" + calculation_id + "/status/?status=completed&progress=1&timeout=5"),
-        "type");
-    if (calculation_status.find("failed") != string::npos)
-    {
-        std::cout << "Server Responded: " << calculation_status << std::endl;
-        return;
-    }
-    // Get calculation Result
-    std::cout << "Fetching Calculation Result..." << std::endl;
-    string calculation_result = do_curl_get(
-        authentication_string,
-        api_url + "/calc/" + calculation_id + "/result/?context=" + iam["context_id"]);
-    std::cout << "Calculation Result: " << calculation_result << std::endl;
-}
-</code>
-**Returns:**
-  - The calculation result (in json) of the API function called.
-====== Python ======
-The provided python scripts and libraries are meant to be a foundation and starting point for using the astroid Dosimetry app on the thinknode™ framework. The provided scripts outline the basic usage of using ISS to store objects, constructing, and making calculation requests to the calculation provider. The below sections detail the basic usage for each script.
-**Download:** The python astroid_script_library can be downloaded from the [[https://github.com/dotdecimal/astroid-script-library|.decimal GitHub repository]].
-====thinknode.cfg====
-Configuration file for connecting to the Dosimetry app on the thinknode™ framework. This file is required by all scripts in the python astroid_script_library to authenticate and use the Dosimetry app.
-  * //basic_user// being a base64 encoded username and password. Refer to the [[http://www.docs.thinknode.com|thinknode documentation]] for more information.
-  * //api_url// being the connection string to the thinknode™ framework.
-  * //app_name// being the current app name (e.g. dosimetry).
-  * //app_version// being the current version of dosimetry existing on the thinknode™ framework being used.
-<code json thinknode.cfg>
-{
-    "basic_user": "<Base64 encoded username:password>",
-    "api_url": "https://api.thinknode.com/v1.0",
-    "app_name": "dosimetry",
-    "app_version": "1.0.0.0"
-}
-</code>
-===== Python: Immutable Storage =====
-==== Post Generic ISS Object ====
-The //post_iss_object_generic.py// is a basic python script that provides an example to post any dosimetry type as an immutable object to the dosimetry app on the thinknode™ framework. This example can be used for any immutable storage post using any datatype by replacing the json iss file. The current example posts the aperture_creation_params.json as
-Dependencies:
-  * thinknode.cfg
-  * .decimal Python libraries
-  * compute_aperture_creation_params.json (or any other prebuilt json file of a dosimetry object as described in the [[http://docs.dosimetry.dotdecimal.com|Dosimetry Manifest Guide]])
-<code python post_iss_object_generic.py>
-# Copyright (c) 2015 .decimal, Inc. All rights reserved.
-# Desc:     Post an immutable json object to the thinknode framework
-from lib import thinknode_worker as thinknode
-from lib import decimal_logging as dl
-import requests
-import json
-iss_dir = "iss_files"
-json_iss_file = "aperture_creation_params.json"
-obj_name = "aperture_creation_params"
-# Get IAM ids
-iam = thinknode.authenticate(thinknode.read_config('thinknode.cfg'))
-# App object to post to iss
-with open(iss_dir + '/' + json_iss_file) as data_file:
-    json_data = json.load(data_file)
-# Post immutable object to ISS
-res = thinknode.post_immutable(iam, json_data, obj_name)
-dl.data("Immutable id: ", res.text)
-</code>
-**Returns:**
-  - The ID (in json) of the object stored in Immutable Storage.
-===== Python: Calculation Request =====
-==== Generic Calc Request ====
-The //post_calc_request_generic.py// is a basic example to post a calculation request to dosimetry. This example can be used for any calculation request using any datatype by replacing the calculation request json file. This request will post a calculation request, check the status using long polling with a specified timeout, and return the calculation result.
-Dependencies:
-  * thinknode.cfg
-  * .decimal Python libraries
-  * compute_aperture.json (or any other prebuilt json file of a dosimetry object as described in the [[http://docs.dosimetry.dotdecimal.com|Dosimetry Manifest Guide]])
-<code python post_calc_request_generic.py>
-# Copyright (c) 2015 .decimal, Inc. All rights reserved.
-# Desc:     Post a json calculation request to the thinknode framework
-from lib import thinknode_worker as thinknode
-from lib import decimal_logging as dl
-import requests
-import json
-request_dir = "request_files"
-json_calc_file = "compute_aperture.json"
-# Get IAM ids
-iam = thinknode.authenticate(thinknode.read_config('thinknode.cfg'))
-# App calculation request
-with open(request_dir + '/' + json_calc_file) as data_file:
-    json_data = json.load(data_file)
-# Send calc request and wait for answer
-res = thinknode.do_calculation(iam, json_data, True)
-dl.data("Calculation Result: ", res.text)
-</code>
-**Returns:**
-  - The calculation result (in json) of the API function called.
-==== SOBP Dose Calculation ====
-The //post_calc_request_sobp_dose.py// and //post_calc_request_sobp_dose_with_shifter.py// are basic examples to create and call an sobp dose calculation function request to the dosimetry app on the thinknode™ framework.
-The //post_calc_request_sobp_dose.py// example creates the entire calculation request inline using thinknode structure, array, and function requests. The entire dose calculation request is performed using one thinknode calculation provider call. While this structure of a request is a little more complicated to setup and perform, it removes the need to post to ISS or perform ancillary calculations separately.
-The //post_calc_request_sobp_dose_with_shifter.py// adds in a complication of a degrader to the sobp calculation. This example performs two separate calculation requests. The first request creates the proton degrader_geometry and the second performs actual dose calculation request using the previously made degrader. The entire example could be condensed into a single more complicated thinknode calculation structure, eliminating the need to perform two separate requests, but it can also be simpler to perform some calculations separately as shown.
-=== Example ===
-Below is an abbreviated version of the //post_calc_request_sobp_dose.py// file. The abbreviated sections are denoted as "...".
-  * The //dosimetry_types// (dt) module that is imported is a class library of all the dosimetry data types as described in the [[http://docs.dosimetry.dotdecimal.com|Dosimetry Manifest Guide]]. This library provides easier manual construction of the dosimetry data types.
-  * The //thinknode_worker// (thinknode) module that is imported is a library that provides worker functions for performing and building the authentication, iss, and calculation requests to the thinknode framework.
-  * The //decimal_logger// (dl) module that is imported is a library that provides prettified log output. Includes optional file logging, timestamps, message coloring (when run through command windows).
-Refer to the [[userguide:thinknode##pythondecimal_libraries|decimal Libraries]] section for more information on the provided decimal libraries.
-<code python>
-import json
-from lib import thinknode_worker as thinknode
-from lib import decimal_logging as dl
-from lib import dosimetry_types as dt
-# Get IAM ids
-iam = thinknode.authenticate(thinknode.read_config('thinknode.cfg'))
-def make_grid(corner, size, spacing):
-...
-def make_water_phantom(corner, size, spacing):
-...
-def make_dose_points(pointCount):
-...
-def get_example_sobp_machine(id):
-...
-def make_layers(sad, range, mod):
-...
-def make_target():
-    return \
-        thinknode.function("dosimetry", "make_cube",
-            [
-                thinknode.value([-32, -20, -30]),
-                thinknode.value([16, -10, 30])
-            ])
-def make_view():
-    mv = dt.multiple_source_view()
-    ds = {}
-    ds['corner'] = [-100, -100]
-    ds['size'] = [200, 200]
-    mv.display_surface = ds
-    mv.center = [0, 0, 0]
-    mv.direction = [0, 1, 0]
-    mv.distance = [2270, 2270]
-    mv.up = [0, 0, 1]
-    return mv.out()
-def compute_aperture():
-    ap_params = dt.aperture_creation_params()
-    # ap_params.targets.append(thinknode.reference("55802bcf49400020000c")) # Use existing ISS target
-    ap_params.targets.append(make_target())
-    ap_params.target_margin = 20.0
-    ap_params.view = make_view()
-    ap_params.mill_radius = 0.0
-    ap_params.downstream_edge = 250.5
-    # Make aperture_creation_params
-    args = {}
-    args["targets"] = thinknode.array_named_type("dosimetry", "triangle_mesh", ap_params.targets)
-    args["target_margin"] = thinknode.value(ap_params.target_margin)
-    args["view"] = thinknode.value(ap_params.view)
-    args["mill_radius"] = thinknode.value(ap_params.mill_radius)
-    args["organs"] = thinknode.value(ap_params.organs)
-    args["half_planes"] = thinknode.value(ap_params.half_planes)
-    args["corner_planes"] = thinknode.value(ap_params.corner_planes)
-    args["centerlines"] = thinknode.value(ap_params.centerlines)
-    args["overrides"] = thinknode.value(ap_params.overrides)
-    args["downstream_edge"] = thinknode.value(ap_params.downstream_edge)
-    return \
-        thinknode.function("dosimetry", "compute_aperture",
-            [
-                thinknode.structure_named_type("dosimetry", "aperture_creation_params", args)
-            ])
-beam_geometry = \
-...
-# Call compute_sobp_pb_dose2
-dose_calc = \
-    thinknode.function("dosimetry", "compute_sobp_pb_dose2",
-        [
-            make_water_phantom([-100, -100, -100], [200, 200, 200], [2, 2, 2]), #stopping_power_image
-            thinknode.value(make_dose_points(181)), # dose_points
-            beam_geometry, #beam_geometry
-            make_grid([-75, -75], [150, 150], [2, 2]), # bixel_grid
-            make_layers(2270.0, 152.0, 38.0),
-            compute_aperture(), # aperture based on targets
-            thinknode.value([proton_degr]) # degraders
-        ])
-# Perform calculation
-res = thinknode.do_calculation(iam, dose_calc, id)
-dl.data("Calculation Result: ", res.text)
-</code>
-===== Python: decimal Libraries =====
-==== decimal_logging ====
-==== dosimetry_types ====
-==== thinknode_worker ====
-The //thinknode_worker// module is the main work horse for communication with the dosimetry app and thinknode. The module will handle authentication, posting objects to ISS, creating most of the common calculation request structures, and posting the calculation request.
-Refer to the [[https://github.com/dotdecimal/astroid-script-library|.decimal GitHub repository]] for the complete module. Below are a few of the more common thinknode http worker and their intended usages:
-<code python>
-# Authenticate with thinknode and store necessary ids
-#   param config: connection settings (url and unique basic user authentication)
-def authenticate(config):
-# Send calculation request to thinknode api
-#   param config: connection settings (url, user token, and ids for context and realm)
-#   param json_data: calculation request in json format
-#   param return_data: True = returns calculation result; False = returns calculation id
-def do_calculation(config, json_data, return_data=True):
-# Post immutable object to ISS
-#   param config: connection settings (url, user token, and ids for context and realm)
-#   param json_data: immutable object in json format
-#   param obj_name: object name of app to post to
-def post_immutable(config, json_data, obj_name):
-# Post immutable object to ISS
-#   param config: connection settings (url, user token, and ids for context and realm)
-#   param obj_id: thinknode iss reference id for object to get
-def get_immutable(config, obj_id):
-</code>
-====== Node.js ======
-The following section contains examples using node.js and (if applicable) the specified modules. These examples are for a high level approach to encoding and decoding the blob data that is part of the Dosimetry App calculation request.
-**Base64 Blob Format**
-The blob returned by a calculation request is formatted as such:
-<code cpp>
-// value_type enum definitions
-// Nil = 0;
-// Boolean = 1;
-// Number = 2;
-// String = 3;
-// Blob = 4;
-// List = 5;
-// Record = 6;
-// For value_types nil, boolean, number, string
-// <uint32 value_type enum (4 bytes)><data>
-// For value_types blob, list, record
-// <uint31 value_type enum (4 bytes)><size of each data (8 bytes)><data>
-</code>
-===== Node: Decrypt Base64 Blob Data =====
-The following example shows , using node.js, how to decode the base64 encoded data returned by a calculation request.
-<code javascript>
-// The below base64string is a blob array with the values [ -25, -25, 25, -25, 25, 25, -25, 25 ]
-var b64string = "CF2Hl0z_eJxjYWBgcGBABpYH0GgHHHwMcQDM7AYN";
-// The below base64string is a number set to the value 25.1
-//var b64string = "NztmHgz_eJxjYmBgmDUTCCQtHQATFwOT";
-var buf = new Buffer(b64string, 'base64');
-var zlib = require('zlib');
-function read_base_255_number(buf, offset) {
-    var n = 0;
-    var s = 0;
-    while (offset < buf.length) {
-        var digit = buf[offset];
-        var value = buf.readUInt8(offset);
-        offset++;
-        s++;
-        if (digit.toString(16) === 'ff') {
-            break;
-        }
-        n = n * 255;
-        n += value;
-    }
-    return [s, n];
-}
-var size = read_base_255_number(buf, 4);
-zlib.unzip(buf.slice(4 + size[0]), function (err, data) {
-    if (err) {
-        throw err
-    }
-    var value_type = data.readUInt32LE(0);
-    // Number
-    if (value_type === 2) {
-        console.log("DOUBLE", data.readDoubleLE(4));
-    }
-    // Blob
-    else if (value_type === 4) {
-        // Read size here
-        var values = [];
-        for (var i = 12; i < data.length; i+=8) {
-            values.push(data.readDoubleLE(i));
-        }
-        console.log(values); // Outputs: [ -25, -25, 25, -25, 25, 25, -25, 25 ]
-    }
-});
-</code>
-{{page>userguide:approval&nofooter}}