Chromoscope Developer Documentation

Chromoscope is an accessible, easy tool that anyone can use to explore and understand the sky at multiple wavelengths. It lets you easily move around the sky and fade between wavelengths using a simple user-interface to illustrate the similarities and differences between what is visible at each wavelength.

A standard, modern, web browser is all that you need to use Chromoscope so there is no need to install any extra software, plugins or learn a new interface. Being platform independent means that whether you use Windows, Mac or Linux, it should still be accessible. The code (latest development version) can be downloaded to your own computer or web server and then you can select which wavelength collections you want.

Index

Chromoscope

The first thing you need to do is create a Chromoscope object to show a zoomable, multi-source map.

Parameters

All of these parameters are optional. The defaults are given in brackets.

Usage

$(document).ready(function(){

	// Several ways you could set up Chromoscope

	var chromo = $.chromoscope();

	// Set up the Chromoscope to show Italian and no introductory message
	var chromo = $.chromoscope({lang:'en', showintro:false});

	// Attach to the element with the ID chromoscopeholder2 and in compact mode
	var chromo = $.chromoscope('#chromoscopeholder2',{compact:true});

	// Don't show the introductory message, the "share" link, or the "about" link
	var chromo = $.chromoscope({showintro:false, showshare:false, showabout:false});

	// Start with the view centred on Galactic coordinates 205.5, -17.4, a zoom level of 5 and at a psuedo-wavelength of 2.6
	var chromo = $.chromoscope({l:205.5, b:-17.4, zoom:5, lambda:2.6});

	// Use the specified KML file to add map pins
	var chromo = $.chromoscope({kml:'telescopes.kml'});

}

Adding Wavelength and Annotation Layers

Once Chromoscope is set up and ready we can add the wavelengths and annotation layers we want

Usage

// Attach to document ready
$(document).ready(function(){

	// The spectral bands should be in order they will be displayed in
	chromo.addWavelength({useasdefault:true,key:'v',name:'optical',tiles:'../../DSS2-tiles/',ext:'jpg',title:'optical',attribution:'<a href="http://stdatu.stsci.edu/dss/">DSS2</a>/<a href="http://www.wikisky.org/">Wikisky</a>'});

	// A range limited layer
	chromo.addWavelength({range:{longitude: [-120,80],latitude:[-20,20]},blank:'blank.gif',useasdefault:false,key:'r',name:'radio',tiles:'../../Radio_vsmoothed-tiles/',ext:'jpg',title:'radio',attribution:'<a href="http://lambda.gsfc.nasa.gov/product/foreground/haslam_408.cfm">Haslam et al.</a>'});

	// A layer with different sources of tiles for different zoom levels
	// Here we use Herschel tiles for the level 5 zoom. 'z' defines the default
	chromo.addWavelength({useasdefault:false,key:'f',name:'farir',tiles:{z:'../../IRAS-tiles/',z5:'Herschel-tiles/'},ext:'jpg',title:'farir',attribution:{z:'<a href="http://irsa.ipac.caltech.edu/IRASdocs/iras.html">IRAS</a>/NASA',z5:'ESA/Herschel'}});

	// Add an annotation layer. This uses tiles like the wavelength layers but will be toggled on/off
	chromo.addAnnotationLayer({opacity:0.4,key:'l',name:'labels',tiles:'../../labels-tiles/',ext:'jpg',title:'Labels',attribution:'some Labels from Chris'});

}

Load

Once you've set up the wavelength (and annotation) layers you need to tell Chromoscope that you are ready

Usage

// There are two ways to make your own function happen when Chromoscope loads:

// Method 1: Call load with a callback function

chromo.load(function(){
	alert('Loaded');
});

// Method 2: Bind a load event then call load() later

chromo.bind("load",function(){
	// The 'this' context is the Chromoscope instance
	alert('Loaded '+this.title);
})
...
chromo.load();

Events

As of version 1.4 you can bind your own functions to Chromoscope-specific events. The aim is to make it behave in a way similar to jQuery's bind() function and the this context will be the Chromoscope object.

Usage

// Using a predefined function
chromo.bind(event,myfunction);

// Using an inline function
chromo.bind('zoom',function(){
	alert('Zoomed');
});

// Chaining functions
chromo.bind('zoom',function(){
	alert('Zoomed to '+this.zoom);
}).bind('wcsupdate',function(){
	// Display an alert with the Galactic Coordinates for the edges of the view
	var vr = this.getVisibleRange('G');
	alert('left = '+vr.left+'<br />right = '+vr.right+'<br />top = '+vr.top+'<br />bottom = '+vr.bottom);
});

// Event variables
chromo.bind('zoom',function(ev){
	alert('Zoomed to '+ev.zoom);
}).bind('wcsupdate',function(ev){
	// Display an alert with the Galactic coordinates for the view centre
	alert('l,b = '+ev.position.l+','+ev.position.b);
}).bind('pinopen',function(ev){
	alert('Opened pin '+ev.pin.id);
});

Other functions

Set Language

If you want to load an alternate language you use getLanguage(). The language should be stored in a JSON file of the same name.

Usage

chromo.getLanguage(lang);

// Load the French language file stored in fr.js
chromo.getLanguage('fr');

Define Language

If you want to you can hard-code the entire language translation.

Usage

chromo.changeLanguage(lang)

// Define English (this is the default anyway but should give you hints for writing your own)
chromo.changeLanguage({code:'en',
	name : 'English',
	translator : '',
	lang : 'Change language:',
	version : 'version',
	help : 'Help',
	helpmenu : 'Help',
	helpdesc : 'The Milky Way is shown across the middle. The north pole of the Galaxy is towards the top. Use the mouse to drag the sky around. Want more info? <a href="#" onClick="javascript:chromo_active.showVideoTour();return false;">Watch a quick tour</a> (opens in this window). <span class="keyboard">The keyboard controls are:<ul class="chromo_controlkeys"></ul></span><span class="nokeyboard"><ul class="chromo_controlbuttons"></ul></span> <span class="keyboard">Created by <a href="http://www.strudel.org.uk/">Stuart Lowe</a>, <a href="http://www.astro.cf.ac.uk/pub/Robert.Simpson/index.html">Rob Simpson</a>, and <a href="http://www.astro.cardiff.ac.uk/contactsandpeople/?page=full&id=493">Chris North</a>. You can also <a href="http://blog.chromoscope.net/download/">download it</a> to run locally.</span>',
	about : 'About',
	share : 'Share',
	sharewith : 'Share it with',
	switchtext : 'switch to __WAVELENGTH__ view of the sky',
	search : 'search',
	press : 'Press __KEY__',
	close : 'Close',
	closedesc : 'click to close',
	switchannotation : ' show or hide __ANNOTATION__',
	showhide : 'show or hide all screen furniture (except the credit line)',
	up : 'higher energy (reduce the wavelength)',
	down : 'lower energy (increase the wavelength)',
	zoomin : 'zoom in',
	zoomout : 'zoom out',
	nozoomin : 'Can\'t zoom in any more',
	nozoomout : 'Can\'t zoom out any more',
	url : 'The URL for this view is:',
	intro : 'Ever wanted X-ray specs or super-human vision? Chromoscope lets you explore our Galaxy (the Milky Way) and the distant Universe in <a href="http://blog.chromoscope.net/data/">a range of wavelengths</a> from X-rays to the longest radio waves.',
	gal : 'http://en.wikipedia.org/wiki/Galactic_coordinate_system',
	galcoord : 'Galactic Coordinates',
	eq : 'http://en.wikipedia.org/wiki/Equatorial_coordinate_system',
	eqcoord : 'Equatorial Coordinates',
	gamma : 'Gamma ray',
	xray : 'X-ray',
	optical : 'Visible',
	halpha : 'Hydrogen alpha',
	farir : 'Far-Infrared',
	microwave : 'Microwave',
	radio : 'Radio',
	labels : 'Labels',
	centre : 'Centre map at this point',
	wikisky : 'View in Wikisky',
	wwt : 'View in WorldWideTelescope',
	nearby : 'Objects within 10&prime;',
})

Reset

Reset the map view

Usage

chromo.reset()

Register function to a key

If you'd like to add a command to a key press. It is chainable.

chromo.registerKey(key,function(){
	alert('Pressed');
});


chromo.registerKey('l',function(){
	alert('Pressed l');
	this.changeWavelengthByName('l');
}).registerKey(38,function(){
	alert('Pressed down cursor key');
}).registerKey(['h',63],function(){
	alert('Pressed h or ?');
});

Simulated key press

Sometimes you just want to pretend the user has pressed a key. This function lets you do that.

chromo.simulateKeyPress(key);

chromo.simulateKeyPress('l');

Move Map

Centre the map on the specified Galactic coordinates.

chromo.moveMap(longitude, latitude, zoom);

chromo.moveMap(-67.2, 14.4, 3);

Get Coordinates

Chromoscope will provide the coordinates of the centre of the view. There are two different functions - getCoords() and getCoordinates() - which produce different output. Chromoscope also has some useful coordinate transforms so that it can convert between systems.

// Return a two element structure containing the Galactic l,b {l, b}
var coords = chromo.getCoords();
alert(coords.l+','+coords.b)

// Return a two element structure containing the Galactic l,b [l,b]
coords = chromo.getCoordinates('G');
alert('l='+coords[0]+', b='+coords[1])

// Return a two element structure containing [ra,dec]
coords = chromo.getCoordinates('A');
alert('Ra='+coords[0]+', Dec='+coords[1])

// Return a two element array containing the Galactic l,b from RA/Dec
var galactic = Equatorial2Galactic(ra, dec, epoch);

// Return a two element array containing the Right Ascension and Declination from Galactic Coordinates
var radec = Galactic2Equatorial(l, b, epoch);

Visible Range

Get the coordinate range for the current view as a structure {left, right, top, bottom }. The default output is map x,y coordinates.

var range = chromo.getVisibleRange(coordtype);

// Returns the Galactic coordinates for the view.
var range = chromo.getVisibleRange('G');

// Popup showing the result structure contents { left: l, right: r, top: t, bottom: b }
alert(range.left+' '+range.right+' '+range.top+' '+range.bottom);

Increment Wavelength

Change the wavelength by a value between 0 and 1 where 1 changes a full pseudo-wavelength.

chromo.changeWavelength(delta);

chromo.changeWavelength(0.1);

Zoom

Set the zoom level.

// Zoom in 1 zoom level
chromo.zoomIn();

// Zoom out 1 zoom level
chromo.zoomOut();

chromo.setMagnification(zoom);

chromo.setMagnification(4);

Read KML file

To read a KML file you'll need to use the KML plugin. Due to browser security policies, the KML file will have to be hosted on the same domain.

// Zoom in 1 zoom level
chromo.readKML(kml,overwrite,duration,callback);

// Load the pulsars.kml file
chromo.readKML('pulsars.kml');

Add a map pin

A suitable layer will need to exist for the pin

chromo.addPin({group:0,img:'something.png',title:'Title',desc:'A description', glon:120.0, glat:5.2});


// Adding many pins may get slow so here we don't add the pins to the screen until we've provided them all to Chromoscope.
// We'll allow their IDs to be auto-generated.
group = chromo.addPinGroup({id:'idhere',title:'A title for the group'})
chromo.addPin({group:group,style:style,img:'something.png',title:'Pin 1',desc:'A description',ra:23.56,dec:-5.2},true);
chromo.addPin({group:group,style:style,img:'something.png',title:'Pin 2',desc:'A second',ra:22.01,dec:-15.6},true);
...
chromo.addPin({group:group,style:style,img:'something.png',title:'Pin X',desc:'Final pin',ra:2.64,dec:45.6},true);
// Add a switch to turn the layer on and off
chromo.addPinGroupSwitches(group);
// Update all the pins as we delayed their creation
chromo.updatePins({delay: true})
chromo.wrapPins();

Show balloon

Display the information balloon associated with a particular pin.

pin.showBalloon()

chromo.pins[0].showBalloon()