Sun Apr 17 2011

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.

Tue Dec 28 2010

Introducing SkEye

SkEye is a Planetarium for Android. It is similar to Google Sky Map, but designed to work with telescopes. It lets you use your phone as a PUSHTO guide without needing any other equipment.

There is now a dedicated website for SkEye and related apps.