17 April 2011 in android

SkEye now has an API

This post might interest you if you are an Android app developer. I have created an API for SkEye that other applications can use.

There are three functions that are supported by this API:

• searching for any object present in SkEye's database,
• viewing a position specified by RA / Dec,
• details about the position and object viewed in SkEye at the time of quitting

All these APIs use the power of Android's Intent feature to exchange data with SkEye.

The Search function

This can be invoked with the ACTION_SEARCH type of Intent with the target object specified by a path, similar to a website URL. The format used for the path is:

astro_object//category/object_name

Here are a few examples,

astro_object//solarsys/saturn	Identifies Saturn in the Solar system catalog.
astro_object//star/Aldebaran	Identifies a star.
astro_object//messier/m31	Identifies M31 in the Messier Catalog
astro_object//constellation/bootes	Identifies the constellation Bootes

You can also let SkEye search all its catalogs by specifying "any" as the category.

It is pretty simple when you look at the code. Here is an example in which we searh for the planet Jupiter,

public void clickJupiterSkEyeSearch(View v) {
  safeLaunchSkEye("astro_object//solarsys/jupiter");
}

// The following two helper functions will help launch SkEye safely
private void safeLaunchSkEye(String objPath) {
  final Intent skEyeIntent = new Intent(Intent.ACTION_SEARCH);
  final Uri targetUri = new Uri.Builder().path(objPath).build();
  skEyeIntent.setDataAndType(targetUri, "text/astro_object");

  safeLaunchActivity(skEyeIntent, "SkEye v1.2 or higher");
}

private void safeLaunchActivity (Intent i, String hint) {
  if (i.resolveActivity(getPackageManager())!= null) {
    startActivity(i);
  } else {
    Toast.makeText(this, "Please install "+hint, Toast.LENGTH_SHORT).show();
  }
}

The View function

This can be invoked with the ACTION_VIEW type of Intent with the target position specified by extra data in the Intent. The following extra data needs to be present:

RA	(double)	Right Ascension (J2000 epoch / ICRS) in radians
Declination	(double)	Declination (J2000 epoch / ICRS) in radians

Here's some sample code,

public void clickViewRADec(final View v) {
  safeLaunchSkEyeForViewing(6, 30); // View position 6 hours, 30 degrees
}

private void safeLaunchSkEyeForViewing(final double raHours, final double decDegrees) {
  final Intent skEyeIntent = new Intent(Intent.ACTION_VIEW);
  skEyeIntent.setType("text/astro_position");
  skEyeIntent.putExtra("RA", Math.toRadians(ra*15));
  skEyeIntent.putExtra("Declination", Math.toRadians(dec));
  final Uri targetUri = new Uri.Builder().scheme("skeye").build();                                                                   
  skEyeIntent.setDataAndType(targetUri, "text/astro_position");

  safeLaunchActivity(skEyeIntent, "SkEye v5.4 or higher", ACTIVITY_REQUEST_VIEW);
}

Returned data

When SkEye quits it will return the last position that was being viewed. To get this data you will need to launch SkEye with the startActivityForResult function. The Intent that is returned has the following extra data:

RA	(double)	Right Ascension (J2000 epoch / ICRS) in radians
Declination	(double)	Declination (J2000 epoch / ICRS) in radians
centeredObjPresent	(boolean)	If true, then the following data is also present.
centeredObjName	(String)	Name of the object nearest to the center.
centeredObjRa	(double)	RA of centered object in radians.
centeredObjDec	(double)	Declination of centered object in radians.

Sample project

A sample Gradle + Java project with complete source code is available here.

Open API

While designing the API I have tried to keep it open, so that there are no SkEye specific dependencies. The Intent uses the mimetype to find an activity that can handle it. Other planetarium apps are welcome to implement to this API by handling this mimetype. I will be happy to receive feedback and evolve the API further.

Applications using this API

Star Odyssey is a guide book of the brightest stars.

Star Log lets you locate logged objects.

Meteor Shower Calendar can point the origin of a meteor shower.

blog comments powered by Disqus