Skip to content

Commit

Permalink
ttools: add metadata for time-related config keys
Browse files Browse the repository at this point in the history 
Added full config key metadata for all the keys used in TimePlotType.
Add new task TimePlot2Task.
  • Loading branch information
@mbtaylor @mmpcn
mbtaylor authored and mmpcn committed Nov 27, 2014
1 parent 0d390d5 commit db1bd65
Show file tree
Hide file tree
Showing 5 changed files with 191 additions and 48 deletions.
18 changes: 18 additions & 0 deletions ttools/src/main/uk/ac/starlink/ttools/plot2/config/TimeConfigKey.java
View file
Expand Up @@ -15,13 +15,31 @@
*/
public class TimeConfigKey extends ConfigKey<Double> {

/** XML &lt;p&gt; element describing the text input format. */
public static final String FORMAT_XML =
ConfigMeta.concatLines( new String[] {
"<p>The value may be set with a string that can be interpreted as",
"a decimal year",
"(e.g. \"<code>2007.521</code>\")",
"or an ISO-8601 string",
"(e.g. \"<code>2007-07-10T03:57:36</code>\",",
"\"<code>2007-07-10T03</code>\"",
"or \"<code>2007-07-10</code>\").",
"Note however that the numeric value of this configuration item",
"if accessed programmatically is seconds since 1 Jan 1970.",
"</p>",
} );

/**
* Constructs a key with no default value.
*
* @param meta metadata
*/
public TimeConfigKey( ConfigMeta meta ) {
this( meta, Double.NaN );
if ( meta.getStringUsage() == null ) {
meta.setStringUsage( "<year-or-iso8601>" );
}
}

/**
Expand Down
40 changes: 33 additions & 7 deletions ttools/src/main/uk/ac/starlink/ttools/plot2/geom/TimeFormat.java
View file
Expand Up @@ -35,6 +35,7 @@
public abstract class TimeFormat {

private final String name_;
private final String description_;

/** Time format for ISO-8601 dates. */
public static final TimeFormat ISO8601;
Expand All @@ -53,15 +54,16 @@ public abstract class TimeFormat {
private static final TimeFormat[] KNOWN_FORMATS = new TimeFormat[] {
ISO8601 = new Iso8601TimeFormat( 'T', TimeZone.getTimeZone( "UTC" ),
Locale.UK ),
DECIMAL_YEAR = decimalYear_ = new NumericTimeFormat( "Year" ) {
DECIMAL_YEAR = decimalYear_ =
new NumericTimeFormat( "Year", "Decimal year" ) {
public double fromUnixSeconds( double unixSec ) {
return unixSecondsToDecimalYear( unixSec );
}
public double toUnixSeconds( double value ) {
return decimalYearToUnixSeconds( value );
}
},
MJD = new NumericTimeFormat( "MJD" ) {
MJD = new NumericTimeFormat( "MJD", "Modified Julian Date" ) {
public double fromUnixSeconds( double unixSec ) {
return Times
.decYearToMjd( unixSecondsToDecimalYear( unixSec ) );
Expand All @@ -70,7 +72,9 @@ public double toUnixSeconds( double value ) {
return decimalYearToUnixSeconds( Times.mjdToDecYear( value ) );
}
},
UNIX_SECONDS = new NumericTimeFormat( "Unix" ) {
UNIX_SECONDS = new NumericTimeFormat( "Unix",
"Seconds since midnight"
+ " of 1 Jan 1970" ) {
public double fromUnixSeconds( double unixSec ) {
return unixSec;
}
Expand All @@ -84,9 +88,11 @@ public double toUnixSeconds( double value ) {
* Constructor.
*
* @param name format name
* @param description short description
*/
protected TimeFormat( String name ) {
protected TimeFormat( String name, String description ) {
name_ = name;
description_ = description;
}

/**
Expand All @@ -105,6 +111,24 @@ protected TimeFormat( String name ) {
*/
public abstract Ticker getTicker();

/**
* Returns the name of this format.
*
* @return format name
*/
public String getFormatName() {
return name_;
}

/**
* Returns a short description of this format.
*
* @return format description
*/
public String getFormatDescription() {
return description_;
}

@Override
public String toString() {
return name_;
Expand Down Expand Up @@ -183,9 +207,10 @@ private static abstract class NumericTimeFormat extends TimeFormat {
* Constructor.
*
* @param name format name
* @param description format description
*/
protected NumericTimeFormat( String name ) {
super( name );
protected NumericTimeFormat( String name, String description ) {
super( name, description );
ticker_ = new BasicTicker( false ) {
public Rule createRule( double dlo, double dhi,
double approxMajorCount, int adjust ) {
Expand Down Expand Up @@ -284,7 +309,8 @@ private static class Iso8601TimeFormat extends TimeFormat {
* @param locale calendar locale
*/
Iso8601TimeFormat( char dateSep, TimeZone tz, Locale locale ) {
super( "ISO-8601" );
super( "ISO-8601",
"ISO 8601 date, of the form yyyy-mm-ddThh:mm:ss.s" );
levelSet_ = new DateLevelSet( dateSep, tz, locale );
ticker_ = new Iso8601Ticker( levelSet_ );
}
Expand Down
62 changes: 33 additions & 29 deletions ttools/src/main/uk/ac/starlink/ttools/plot2/geom/TimeNavigator.java
View file
Expand Up @@ -33,9 +33,7 @@ public class TimeNavigator implements Navigator<TimeAspect> {

/** Config key to select which axes zoom will operate on. */
public static final ConfigKey<boolean[]> NAVAXES_KEY =
new AxisCombinationConfigKey( new ConfigMeta( "navaxes",
"Pan/Zoom Axes" ),
true, false );
createNavAxesKey();

/**
* Constructor.
Expand Down Expand Up @@ -193,32 +191,38 @@ public static TimeNavigator createNavigator( ConfigMap config ) {
}

/**
* ConfigKey for selecting a combination (0, 1 or 2) of the axes
* of a time plot.
* Returns a config key for selecting which axes of a time plot
* will be pan/zoomable.
*
* @return config key
*/
private static class AxisCombinationConfigKey extends CombinationConfigKey {

/**
* Constructor.
*
* @param metadata
* @param tDflt true to include time axis by default
* @param yDflt true to include Y axis by default
*/
AxisCombinationConfigKey( ConfigMeta meta,
boolean tDflt, boolean yDflt) {
super( meta, new boolean[] { tDflt, yDflt },
new String[] { "Time", "Y" }, null );
}

/**
* Allow X as an alias for T
*/
@Override
public int optCharToIndex( char c ) throws ConfigException {
return Character.toLowerCase( c ) == 'x'
? 0
: super.optCharToIndex( c );
}
private static CombinationConfigKey createNavAxesKey() {
ConfigMeta meta = new ConfigMeta( "navaxes", "Pan/Zoom Axes" );
meta.setStringUsage( "t|y|ty" );
meta.setShortDescription( "Axes affected by pan/zoom" );
meta.setXmlDescription( new String[] {
"<p>Determines the axes which are affected by",
"the interactive navigation actions (pan and zoom).",
"The default is <code>t</code>",
"which means that the various mouse gestures",
"will provide panning and zooming in the Time direction only.",
"However, if it is set to <code>ty</code>",
"mouse actions will affect both the horizontal and vertical",
"axes.",
"</p>",
} );

/* Allow X as an alias for T. */
CombinationConfigKey key =
new CombinationConfigKey( meta, new boolean[] { true, false },
new String[] { "Time", "Y" }, null ) {
@Override
public int optCharToIndex( char c ) throws ConfigException {
return Character.toLowerCase( c ) == 'x'
? 0
: super.optCharToIndex( c );
}
};
return key;
}
}
104 changes: 92 additions & 12 deletions ttools/src/main/uk/ac/starlink/ttools/plot2/geom/TimeSurfaceFactory.java
View file
Expand Up @@ -34,15 +34,37 @@ public class TimeSurfaceFactory

/** Config key for time axis lower bound, before subranging. */
public static final ConfigKey<Double> TMIN_KEY =
new TimeConfigKey( new ConfigMeta( "tmin", "Time Minimum" ) );
new TimeConfigKey(
new ConfigMeta( "tmin", "Time Minimum" )
.setShortDescription( "Lower limit on time axis" )
.setXmlDescription( new String[] {
"<p>Minimum value of the time coordinate plotted.",
"This sets the value before any subranging is applied.",
"If not supplied, the value is determined from the plotted",
"data.",
"</p>",
TimeConfigKey.FORMAT_XML,
} )
);

/** Config key for time axis upper bound, before subranging. */
public static final ConfigKey<Double> TMAX_KEY =
new TimeConfigKey( new ConfigMeta( "tmax", "Time Maximum" ) );
new TimeConfigKey(
new ConfigMeta( "tmax", "Time Maximum" )
.setShortDescription( "Upper limit on time axis" )
.setXmlDescription( new String[] {
"<p>Maximum value of the time coordinate plotted.",
"This sets the value before any subranging is applied.",
"If not supplied, the value is determined from the plotted",
"data.",
"</p>",
TimeConfigKey.FORMAT_XML,
} )
);

/** Config key for time axis subrange. */
public static final ConfigKey<Subrange> TSUBRANGE_KEY =
new SubrangeConfigKey( new ConfigMeta( "tsub", "Time Subrange" ) );
new SubrangeConfigKey( SubrangeConfigKey.createAxisMeta( "Time" ) );

/** Config key for Y axis lower bound, before subranging. */
public static final ConfigKey<Double> YMIN_KEY =
Expand All @@ -66,32 +88,45 @@ public class TimeSurfaceFactory

/** Config key for time axis text label. */
public static final ConfigKey<String> TLABEL_KEY =
new StringConfigKey( new ConfigMeta( "timelabel", "Time Label" ),
null );
new StringConfigKey(
new ConfigMeta( "tlabel", "Time Label" )
.setStringUsage( "<text>" )
.setShortDescription( "Label for Time axis" )
.setXmlDescription( new String[] {
"<p>Gives a label to be used for annotating the Time axis.",
"If not supplied no label will be drawn.",
"</p>",
} )
, null );

/** Config key for Y axis text label.*/
public static final ConfigKey<String> YLABEL_KEY =
PlaneSurfaceFactory.YLABEL_KEY;

/** Config key to determine if grid lines are drawn. */
public static final ConfigKey<Boolean> GRID_KEY =
new BooleanConfigKey( new ConfigMeta( "grid", "Draw Grid" ), false );
new BooleanConfigKey(
new ConfigMeta( "grid", "Draw Grid" )
.setShortDescription( "Draw grid lines?" )
.setXmlDescription( new String[] {
"<p>If true, grid lines are drawn on the plot",
"at positions determined by the major tick marks.",
"If false, they are absent.",
"</p>",
} )
, false );

/** Config key to control tick mark crowding on time axis. */
public static final ConfigKey<Double> TCROWD_KEY =
StyleKeys.createCrowdKey( new ConfigMeta( "tcrowd",
"Time Tick Crowding" ) );
PlaneSurfaceFactory.createAxisCrowdKey( "Time" );

/** Config key to control tick mark crowding on Y axis. */
public static final ConfigKey<Double> YCROWD_KEY =
PlaneSurfaceFactory.YCROWD_KEY;

/** Config key to control time value formatting. */
public static final ConfigKey<TimeFormat> TFORMAT_KEY =
new OptionConfigKey<TimeFormat>( new ConfigMeta( "tformat",
"Time Format" ),
TimeFormat.class,
TimeFormat.getKnownFormats() );
createTimeFormatKey();

public Surface createSurface( Rectangle plotBounds, Profile profile,
TimeAspect aspect ) {
Expand Down Expand Up @@ -205,6 +240,51 @@ private static TimeAspect createUnrangedAspect( Profile profile,
: new TimeAspect( tlimits, ylimits );
}

/**
* Returns a config key used to select time display format.
*
* @return config key
*/
private static ConfigKey<TimeFormat> createTimeFormatKey() {
TimeFormat[] formats = TimeFormat.getKnownFormats();
StringBuffer sbuf = new StringBuffer();
double unixSec = 1331613420;
double secPrecision = 60 * 60 * 4;
for ( TimeFormat format : Arrays.asList( formats ) ) {
sbuf.append( "<li>" )
.append( "<code>" )
.append( format.getFormatName() )
.append( "</code>" )
.append( ": " )
.append( format.getFormatDescription() )
.append( " (e.g. \"" )
.append( format.formatTime( unixSec, secPrecision ) )
.append( "\")" )
.append( "</li>" )
.append( "\n" );
}
ConfigMeta meta = new ConfigMeta( "tformat", "Time Format" );
meta.setShortDescription( "Time display format" );
meta.setXmlDescription( new String[] {
"<p>Selects the way in which time values are represented",
"when using them to label the time axis.",
"</p>",
"<p>Available options are",
"<ul>",
sbuf.toString(),
"</ul>",
"</p>",
} );
OptionConfigKey<TimeFormat> key =
new OptionConfigKey( meta, TimeFormat.class, formats ) {
public String valueToString( TimeFormat format ) {
return format.getFormatName();
}
};
key.setOptionUsage();
return key;
}

/**
* Profile class which defines fixed configuration items for a TimeSurface.
* Instances of this class are usually obtained from the
Expand Down
15 changes: 15 additions & 0 deletions ttools/src/main/uk/ac/starlink/ttools/plot2/task/TimePlot2Task.java
View file
@@ -0,0 +1,15 @@
package uk.ac.starlink.ttools.plot2.task;

import uk.ac.starlink.ttools.plot2.geom.TimePlotType;

/**
* Task for time plots.
*
* @author Mark Taylor
* @since 11 Sep 2014
*/
public class TimePlot2Task extends TypedPlot2Task {
public TimePlot2Task() {
super( TimePlotType.getInstance() );
}
}

0 comments on commit db1bd65

Please sign in to comment.