lavadip

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/saturnIdentifies Saturn in the Solar system catalog.
astro_object//star/AldebaranIdentifies a star.
astro_object//messier/m31Identifies M31 in the Messier Catalog
astro_object//constellation/bootesIdentifies 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 ra, final double dec) {
  final Intent skEyeIntent = new Intent(Intent.ACTION_VIEW);
  skEyeIntent.setType("text/astro_position");
  skEyeIntent.putExtra("RA", Math.toRadians(ra*15)); // where ra is in hours
  skEyeIntent.putExtra("Declination", Math.toRadians(dec)); // where dec is in degrees

  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 Eclipse project with complete source code is available for download 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

The handy Meteor Shower Calendar can point the origin of a meteor shower using this API!

A new app called Star Odyssey is a guide book of the brightest stars and it helps you locate them in the Sky using this API!

blog comments powered by Disqus