SkyShare for apps

Someone photographs the evening sky and wants to know what the bright dot beside the Moon is. SkyShare reads the photo and answers with names placed on the picture. It runs on the Sky Map today, and you can put it in your own app. It is free on npm with our mark.

What it does

Give SkyShare a photo of the night sky. It reads when and where the photo was taken, works out where the Moon, the planets and the bright stars stood at that moment, finds them in the picture, and returns each name with its position in pixels.

You can take those positions and draw your own labels. Or let SkyShare draw them: a finished image with the names on it, or the names alone on a clear layer to place over the photo.

To see it, open the Sky Map on a phone, tap the camera button, and choose a photo with the Moon or a bright planet in it.

How well it works today

We ran it on 22 of our own photos of the Moon, planets and bright stars, taken with one iPhone on 11 dates, at dusk and at night. In 6 of them the names were placed with no help, and we checked those six by eye. In the other 16, SkyShare asks the person to tap one or two objects it names, and the labels line up from those taps.

Of the 16 that needed a tap, 8 had other lights in the frame that could not be told from sky objects, 6 had two objects that fit the sky more than one way, and 2 could not be matched at all.

Every one of these files still carried its time and place. A photo chosen through a phone's photo picker often arrives without its place, and then the person has to set it. We have not tested photos from Android phones yet. We report the count as we find it, and we will update it here as the test set grows.

What you get

A JavaScript package, @cyclecalcs/skyshare on npm. It takes a photo file and returns the names, their positions and a confidence grade. It is the code the Sky Map runs, and it runs in the browser.
A label layer. The names in a small italic face, with a thin pointer for faint stars, as an image or as a clear overlay in story, portrait or square shape.
The sky as data. GET /v2/sky-targets returns the Sun, the Moon, the planets and thirty named stars for a time and place, if you would rather draw everything yourself.

Try it

npm install @cyclecalcs/skyshare

import { labelPhoto, renderCard } from '@cyclecalcs/skyshare';

const result = await labelPhoto(file);   // a File from <input type="file">
if (result.ok) {
  console.log(result.inFrame);           // the names in the picture
  const card = renderCard(result.image, result, { shape: 'story' });
  document.body.append(card.canvas);
} else {
  console.log(result.reason, result.missing);   // most photos today: ask for a place, a time or a tap
}

The package README covers the rest: passing a place when the photo has none, and lining up the names from a tap on the Moon or a planet when the photo alone is not enough.

Two ways to use it

With our mark, free. Every labeled image people see, save or share must carry a small CycleCalcs mark, even when you draw the names yourself. Your own logo can sit beside it, and your colors and typeface are free to use. Use it in your app, on your site or on your own servers.

Under your own brand, by agreement. No mark of ours, or your brand in its place.

Offering the package, or a wrapper around it, as a kit for other developers, or running it as an API for other companies' apps, is also by agreement. The full terms are in its LICENSE.

Where it stands

No app uses it yet. If your app handles photos of the sky, such as a camera app, a stargazing app, a telescope companion or a travel journal, we would like to hear what you need.

Talk to us

Write to info@cyclecalcs.com and tell us what your app does, or ask about using it under your own brand. We will reply.

Build guides

Looking for something to build this weekend? These five guides run as written.