/**
* Find the best match for a single JPEG2000 image and either
* output a link to the image, or display the image directly.
*
* @return void
*/
public function getJP2Image()
{
include_once HV_ROOT_DIR . '/../src/Database/ImgIndex.php';
$imgIndex = new Database_ImgIndex();
// Optional parameters
$defaults = array('jpip' => false, 'json' => false);
$options = array_replace($defaults, $this->_options);
// If image id is set, use it
if (isset($this->_params['id'])) {
$filepath = HV_JP2_DIR . $imgIndex->getDataFilePathFromId($this->_params['id']);
} else {
// Filepath to JP2 Image
$filepath = HV_JP2_DIR . $imgIndex->getDataFilePath($this->_params['date'], $this->_params['sourceId']);
}
// Output results
if ($options['jpip']) {
if ($options['json']) {
header('Content-type: application/json;charset=UTF-8');
echo json_encode(array('uri' => $this->_getJPIPURL($filepath)));
} else {
echo $this->_getJPIPURL($filepath);
}
} else {
$this->_displayJP2($filepath);
}
}
protected function _parseSourceIds($sourceIds)
{
$sourceIds = trim($sourceIds, ' []');
$sourceIdArray = explode(',', $sourceIds);
if (count($sourceIdArray) > 0 && $sourceIdArray[0] != '') {
include_once HV_ROOT_DIR . '/../src/Database/ImgIndex.php';
$imgIndex = new Database_ImgIndex();
foreach ($sourceIdArray as $i => $sourceId) {
$info = $imgIndex->getDatasourceInformationFromSourceId($sourceId);
$imageLayersArray[$i] = array('uiLabels' => $info['uiLabels']);
}
} else {
throw new Exception("Parameter 'sourceIds' must contain one or more data source identifiers.", 23);
}
return $imageLayersArray;
}
function output_html($api_version)
{
require_once HV_ROOT_DIR . '/../src/Database/DbConnection.php';
require_once HV_ROOT_DIR . '/../src/Database/ImgIndex.php';
require_once HV_ROOT_DIR . '/../src/Helper/ErrorHandler.php';
import_xml($api_version, $api_xml_path, $xml);
?>
<!DOCTYPE html>
<html class="no-js">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Helioviewer API Documentation</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width">
<link rel="stylesheet" href="<?php
echo HV_WEB_ROOT_URL;
?>
/docs/css/bootstrap.min.css">
<style>
body {
padding-top: 50px;
padding-bottom: 20px;
}
</style>
<link rel="stylesheet" href="<?php
echo HV_WEB_ROOT_URL;
?>
/docs/css/bootstrap-theme.min.css">
<link rel="stylesheet" href="<?php
echo HV_WEB_ROOT_URL;
?>
/docs/css/helioviewer_api.css">
<link rel="stylesheet" href="<?php
echo HV_WEB_ROOT_URL . '/docs/' . $api_version . '/version_specific.css';
?>
">
<script src="<?php
echo HV_WEB_ROOT_URL;
?>
/docs/js/vendor/modernizr-2.6.2-respond-1.1.0.min.js"></script>
</head>
<body>
<div class="navbar navbar-inverse navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="#">Heliviewer API <?php
echo $api_version;
?>
</a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class=""><a href="#about">About</a></li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Browse API <b class="caret"></b></a>
<ul class="dropdown-menu">
<li class="dropdown-header">By Category:</li>
<li><a href="#JPEG2000">JPEG2000</a></li>
<li><a href="#Movies">Movies</a></li>
<li><a href="#Screenshots">Screenshots</a></li>
<li><a href="#SolarFeaturesandEvents">Solar Features and Events</a></li>
<li><a href="#YouTube" onclick="javascript:navigate(this);">YouTube</a></li>
<li><a href="#OfficialClients">Official Clients</a></li>
<li><a href="#WebSite">Web Site</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Appendix <b class="caret"></b></a>
<ul class="dropdown-menu">
<li class="dropdown-header">More about:</li>
<li><a href="#appendix_datasources">Data Sources</a></li>
<li><a href="#appendix_coordinates">Coordinates</a></li>
</ul>
</li>
</ul>
</div><!--/.navbar-collapse -->
</div>
</div>
<!-- Main jumbotron for a primary marketing message or call to action -->
<a name="about" class="anchor"></a>
<div class="jumbotron">
<div class="container">
<h1>API Documentation</h1>
<p class="description"><a href="<?php
echo HV_CLIENT_URL;
?>
">The Helioviewer Project</a> maintains a set of
Public APIs with the goal of improving access to solar and
heliospheric datasets to scientists, educators, developers, and the
general public. Read below for descriptions of each API endpoint and
examples of usage.</p>
<p class="description">Browse APIs by category using the menu above,
or consult the <a href="#appendix">Appendix</a> for more about the
available datasources and working with coordinates.</p>
<p class="description">For easy access to API responses within your code, check out the open-source libraries available at <a href="http://unirest.io/" target="_blank" rel="nofollow">Unirest.io</a>. Libraries are provided for integration with <a href="http://unirest.io/python.html" target="_blank" rel="nofollow">Python</a>, <a href="http://unirest.io/php.html" target="_blank" rel="nofollow">PHP</a>, <a href="http://unirest.io/java.html" target="_blank" rel="nofollow">Java</a>, <a href="http://unirest.io/ruby.html" target="_blank" rel="nofollow">Ruby</a>, <a href="http://unirest.io/objective-c.html" target="_blank" rel="nofollow">Objective-C</a>, <a href="http://unirest.io/nodejs.html" target="_blank" rel="nofollow">Node.js</a>, <a href="http://unirest.io/net.html" target="_blank" rel="nofollow">.NET</a>, and <a href="http://unirest.io/windows-eight.html" target="_blank" rel="nofollow">Windows 8</a> code bases.</p>
<p style="margin-top: 1.5em;"><a class="btn btn-primary btn-lg" href="http://unirest.io/" rel="nofollow" target="_blank">Unirest.io API Libraries ➚</a></p>
</div>
</div>
<?php
renderGroup('JPEG2000', $xml);
renderGroup('Movies', $xml);
renderGroup('Screenshots', $xml);
renderGroup('Solar Features and Events', $xml);
renderGroup('YouTube', $xml);
renderGroup('Official Clients', $xml);
renderGroup('Web Site', $xml);
?>
<a name="appendix" class="anchor"></a>
<div class="container">
<h1>Appendix</h1>
<p class="description">The appendices below provide further context for Helioviewer API usage.</p>
</div>
<div class="container">
<a name="appendix_datasources" class="anchor"></a>
<h2 class="appendix">Data Sources</h2>
<p class="description">Listed below are all valid image data sources hosted by the Helioviewer Project. Reference a particular datasource in your API requests by its '<span class="param">sourceId</span>' parameter shown in the following tables.</p>
<?php
function recursiveGroup($obj, &$out_arr = array())
{
foreach ($obj as $key => $val) {
if (!array_key_exists('sourceId', $val)) {
recursiveGroup($val, $out_arr);
} else {
$groupBy = $val['uiLabels'][0]['name'];
$sourceId = $val['sourceId'];
$current_arr = array();
$current_arr['sourceId'] = $val['sourceId'];
$current_arr['nickname'] = $val['nickname'];
$current_arr['uiLabels'] = $val['uiLabels'];
$out_arr[$groupBy][] = $current_arr;
continue;
}
}
}
$imgIndex = new Database_ImgIndex();
recursiveGroup($imgIndex->getDataSources(false), $groupedSources);
foreach ($groupedSources as $group => $obj) {
?>
<a name="datasource_<?php
echo strtolower($group);
?>
" class="anchor"></a>
<h3><?php
echo $group;
?>
</h3>
<table style="width: 100%;">
<tr style="border: 1px solid #999; background-color: #eee;">
<th style="padding: 2px 6px; text-align:center;">Source ID</th>
<th style="padding: 2px 6px;">Description</th>
<?php
// Grab datasource hierarchy information from first element
foreach ($obj[0]['uiLabels'] as $hierarchy) {
echo ' <th>' . $hierarchy['label'] . '</th>';
}
?>
</tr>
<?php
foreach ($obj as $sourceId => $source) {
?>
<tr>
<td class="sourceId param"><?php
echo $source['sourceId'];
?>
</td>
<td ><?php
echo $source['nickname'];
?>
</td>
<?php
foreach ($source['uiLabels'] as $hierarchy) {
echo ' <td>' . $hierarchy['name'] . '</td>';
}
?>
</tr>
<?php
}
?>
</table>
<br />
<?php
}
?>
</div>
<div class="container">
<a name="appendix_coordinates" class="anchor"></a>
<h2 class="appendix">Coordinates</h2>
<p class="description">The APIs for creating custom movies ('<a class="endpoint" href="#queueMovie">queueMovie</a>') and screenshot images ('<a class="endpoint" href="#takeScreenshot">takeScreenshot</a>') require that you specify a rectangular region-of-interest (ROI). The ROI defines the field-of-view of the video or image in terms of a zoom level and the location and size of the region.</p>
<p class="description">The region-of-interest may be defined in either of two ways. Both methods require an '<span class="param">imageScale</span>' expressed in arc-seconds per pixel, and atleast one pair of X- and Y-coordinates (expressed as arc-seconds from the center of the solar disk).</p>
<p class="description">The first method defines the ROI based on a pair parameters specifying the X- and Y-coordinates for the top-left ('<span class="param">x1</span>','<span class="param">y1</span>') and bottom-right ('<span class="param">x2</span>','<span class="param">y2</span>') corners of rectangle.</p>
<p class="description" style="text-align:center;">
<img src="<?php
echo HV_WEB_ROOT_URL;
?>
/resources/images/Helioviewer_ROI_Arcseconds_Overview.png" />
</p>
<p class="description">An alternative method defines the ROI in terms of the X- and Y-coordinates of the center of the region ('<span class="param">x0</span>','<span class="param">y0</span>'), coupled with the total width and height of the rectangle in pixels. Use this method if the pixel dimensions of the output are important to you. The APIs handle the translation between arc-seconds and pixels based on the value of '<span class="param">imageScale</span>' that you have specified. </p>
<p class="description" style="text-align:center;">
<img src="<?php
echo HV_WEB_ROOT_URL;
?>
/resources/images/Helioviewer_ROI_Pixels_Overview.png" />
</p>
<p class="description">Smaller values of '<span class="param">imageScale</span>' will produce results that appear "zoomed-in" to show more detail.</p>
<p class="description">Below is a listing of the native image scales by datasource:</p>
<div class="description">
<table style="margin: 0 auto; margin-bottom:2em; width:80%;">
<tr style="border: 1px solid #999; background-color: #eee;">
<th style="padding: 2px 6px;">Datasource</th>
<th style="padding: 2px 6px; text-align:center;">Dimensions (pixels)</th>
<th style="padding: 2px 6px;">Image Scale (arc-seconds/pixel)</th>
</tr>
<tr>
<td>PROBA2 SWAP</td>
<td class="param" style="text-align:center;">1024 x 1024</td>
<td class="param"> 3.162</td>
</tr>
<tr>
<td>SDO AIA</td>
<td class="param" style="text-align:center;">4096 x 4096</td>
<td class="param"> 0.6</td>
</tr>
<tr>
<td>SDO HMI</td>
<td class="param" style="text-align:center;">4096 x 4096</td>
<td class="param"> 0.6</td>
</tr>
<tr>
<td>SOHO EIT</td>
<td class="param" style="text-align:center;">1024 x 1024</td>
<td class="param"> 2.63</td>
</tr>
<tr>
<td>SOHO LASCO C2</td>
<td class="param" style="text-align:center;">1024 x 1024</td>
<td class="param">11.9</td>
</tr>
<tr>
<td>SOHO LASCO C3</td>
<td class="param" style="text-align:center;">1024 x 1024</td>
<td class="param">56.0</td>
</tr>
<tr>
<td>SOHO MDI</td>
<td class="param" style="text-align:center;">1024 x 1024</td>
<td class="param"> 1.986</td>
</tr>
<tr>
<td>STEREO SECCHI EUVI</td>
<td class="param" style="text-align:center;">2048 x 2048</td>
<td class="param"> 1.588</td>
</tr>
<tr>
<td>STEREO SECCHI COR1</td>
<td class="param" style="text-align:center;">512 x 512</td>
<td class="param">15.0</td>
</tr>
<tr>
<td>STEREO SECCHI COR2</td>
<td class="param" style="text-align:center;">2048 x 2048</td>
<td class="param">14.7</td>
</tr>
<tr>
<td>Yohkoh SXT</td>
<td class="param" style="text-align:center;">1024 x 1024</td>
<td class="param"> 2.46</td>
</tr>
</table>
</div>
<p class="description">You are not limited to creating screenshots and movies at a datasource's native resolution. Each image layer will be scaled to match the imageScale you have requested.</p>
</div>
<?php
footer($api_version, $api_xml_path);
?>
</body>
</html>
<?php
}
/**
* Return list of JP2 files to use for JPX generation selected by Mid Points
*
* @return array List of filepaths of images to use during JPX generation
* as well as a list of the times for each image in the
* series.
*/
private function _queryJPXImageFramesMidPoint()
{
include_once HV_ROOT_DIR . '/../src/Helper/DateTimeConversions.php';
include_once HV_ROOT_DIR . '/../src/Database/ImgIndex.php';
$imgIndex = new Database_ImgIndex();
// Parse List of dates and convert them to Unix Timestaps
$startTimesArray = explode(',', $this->_startTime);
$endTimesArray = explode(',', $this->_endTime);
if (count($startTimesArray) < 1 || count($endTimesArray) < 1) {
throw new Exception('At least one Start and End date need to be specified. Please use timestamps separated with commas.', 61);
}
if (count($startTimesArray) != count($endTimesArray)) {
throw new Exception('Number of Start dates doesn\'t match the number of End dates. Please use equal amount of Start and End dates.', 61);
}
$images = array();
$dates = array();
foreach ($startTimesArray as $k => $start) {
$end = $endTimesArray[$k];
$middle = round(($start + $end) / 2);
$results = $imgIndex->getDataMidPoint($start, $end, $middle, $this->_sourceId);
if ($results && isset($results['id'])) {
$filepath = HV_JP2_DIR . $results['filepath'] . '/' . $results['filename'];
array_push($images, $filepath);
array_push($dates, strtotime($results['date']));
} else {
array_push($images, null);
array_push($dates, null);
}
}
return array($images, $dates);
}
}
/**
* getStatusIcon
*
* @var unknown_type
*/
function getStatusIcon($level)
{
$levels = array(1 => "green", 2 => "yellow", 3 => "orange", 4 => "red", 5 => "gray");
$icon = "<img class='status-icon' src='icons/status_icon_%s.png' alt='%s status icon' />";
return sprintf($icon, $levels[$level], $levels[$level]);
}
$config = new Config("../../settings/Config.ini");
// Current time
$now = time();
$imgIndex = new Database_ImgIndex();
// Get a list of the datasources grouped by instrument
$instruments = $imgIndex->getDataSourcesByInstrument();
$tableRow = "<tr class='%s'><td>%s</td><td>%s</td><td>%s</td><td align='center'>%s</td></tr>";
// Create table of datasource statuses
foreach ($instruments as $name => $datasources) {
$oldest = array("level" => 0, "datetime" => new DateTime(), "icon" => null);
$maxElapsed = 0;
$oldestDate = null;
$subTableHTML = "";
// Create table row for a single datasource
foreach ($datasources as $ds) {
// Determine status icon to use
$date = $imgIndex->getNewestData($ds['id']);
$elapsed = $now - strtotime($date);
$level = computeStatusLevel($elapsed, $name);
/**
* Returns status information (i.e. time of most recent available data)
* based on either observatory, instrument, detector or measurement.
*
* There are two types of queries that can be made:
*
* (1) instrument
*
* If key is set to instrument, then the time of the data source associated
* with that instrument that is lagging the furthest behind is returned.
*
* (2) nickname
*
* If the key is set to nickname, then the most recent image times
* are returned for all datasources, sorted by instrument.
*/
public function getStatus()
{
// Connect to database
include_once HV_ROOT_DIR . '/../src/Database/ImgIndex.php';
include_once HV_ROOT_DIR . '/../src/Helper/DateTimeConversions.php';
$imgIndex = new Database_ImgIndex();
// Default to instrument-level status information
if (!isset($this->_options['key'])) {
$this->_options['key'] = 'instrument';
}
$statuses = array();
// Case 1: instrument
$instruments = $imgIndex->getDataSourcesByInstrument();
// Date format
$format = 'Y-m-d H:i:s';
// Current time
$now = new DateTime();
// Iterate through instruments
foreach ($instruments as $inst => $dataSources) {
$oldest = new DateTime('2035-01-01');
// Keep track of which datasource is the furthest behind
foreach ($dataSources as $dataSource) {
// Get date string for most recent image
$dateStr = $imgIndex->getNewestData($dataSource['id']);
// Skip data source if no images are found
if (is_null($dateStr)) {
continue;
}
// Convert to DateTime
$date = DateTime::createFromFormat($format, $dateStr);
// Store if older
if ($date < $oldest) {
$oldest = $date;
}
}
// Get elapsed time
$delta = $now->getTimestamp() - $oldest->getTimestamp();
// Add to result array
if ($delta > 0) {
$statuses[$inst] = array('time' => toISOString($oldest), 'level' => $this->_computeStatusLevel($delta, $inst), 'secondsBehind' => $delta);
}
}
// Get a list of the datasources grouped by instrument
$this->_printJSON(json_encode($statuses));
}
