Skip to content

Commit

Permalink
ttools: add XML documentation strings for ShapeForms
Browse files Browse the repository at this point in the history
  • Loading branch information
@mbtaylor @mmpcn
mbtaylor authored and mmpcn committed Nov 27, 2014
1 parent 9b3c3f8 commit b9012b7
Show file tree
Hide file tree
Showing 6 changed files with 114 additions and 7 deletions.
7 changes: 6 additions & 1 deletion ttools/src/main/uk/ac/starlink/ttools/plot2/geom/TimePlotType.java
View file
Expand Up @@ -3,6 +3,7 @@
import uk.ac.starlink.ttools.gui.ResourceIcon;
import uk.ac.starlink.ttools.plot2.DataGeom;
import uk.ac.starlink.ttools.plot2.PlotType;
import uk.ac.starlink.ttools.plot2.PlotUtil;
import uk.ac.starlink.ttools.plot2.Plotter;
import uk.ac.starlink.ttools.plot2.SurfaceFactory;
import uk.ac.starlink.ttools.plot2.config.StyleKeys;
Expand Down Expand Up @@ -41,8 +42,12 @@ public DataGeom[] getPointDataGeoms() {
}

public Plotter[] getPlotters() {
String descrip = PlotUtil.concatLines( new String[] {
"<p>Plots symmetric or asymmetric error bars in the Y direction.",
"</p>",
} );
MultiPointForm errorForm =
new MultiPointForm( "Error", ResourceIcon.FORM_ERROR1,
new MultiPointForm( "Error", ResourceIcon.FORM_ERROR1, descrip,
CartesianErrorCoordSet
.createSingleAxisErrorCoordSet( 2, 1, "Y" ),
false, StyleKeys.ERROR_SHAPE_1D );
Expand Down
20 changes: 19 additions & 1 deletion ttools/src/main/uk/ac/starlink/ttools/plot2/layer/MarkForm.java
View file
Expand Up @@ -17,6 +17,7 @@
import uk.ac.starlink.ttools.plot2.DataGeom;
import uk.ac.starlink.ttools.plot2.Glyph;
import uk.ac.starlink.ttools.plot2.Pixer;
import uk.ac.starlink.ttools.plot2.PlotUtil;
import uk.ac.starlink.ttools.plot2.PointCloud;
import uk.ac.starlink.ttools.plot2.SubCloud;
import uk.ac.starlink.ttools.plot2.Surface;
Expand Down Expand Up @@ -78,6 +79,14 @@ public Icon getFormIcon() {
return icon_;
}

public String getFormDescription() {
return PlotUtil.concatLines( new String[] {
"<p>Plots a marker of fixed size and shape",
"at each position.",
"</p>",
} );
}

public Coord[] getExtraCoords() {
return new Coord[ 0 ];
}
Expand Down Expand Up @@ -121,9 +130,18 @@ public Outliner createOutliner( ConfigMap config ) {
};
}
else {
return new MarkForm( npos, "Marks",
return new MarkForm( npos, "Mark" + npos,
npos == 2 ? ResourceIcon.FORM_MARKS2
: ResourceIcon.FORM_MARKS3 ) {
public String getFormDescription() {
return PlotUtil.concatLines( new String[] {
"<p>Plots " + npos + "similar markers",
"of fixed size and shape",
"representing " + npos + " separate positions",
"from the same input table row.",
"</p>",
} );
}
public ConfigKey[] getConfigKeys() {
return new ConfigKey[] {
StyleKeys.MARK_SHAPE,
Expand Down
50 changes: 46 additions & 4 deletions ttools/src/main/uk/ac/starlink/ttools/plot2/layer/MultiPointForm.java
View file
Expand Up @@ -20,6 +20,7 @@
import uk.ac.starlink.ttools.plot2.DataGeom;
import uk.ac.starlink.ttools.plot2.Glyph;
import uk.ac.starlink.ttools.plot2.Pixer;
import uk.ac.starlink.ttools.plot2.PlotUtil;
import uk.ac.starlink.ttools.plot2.Surface;
import uk.ac.starlink.ttools.plot2.config.ConfigKey;
import uk.ac.starlink.ttools.plot2.config.ConfigMap;
Expand Down Expand Up @@ -51,6 +52,7 @@ public class MultiPointForm implements ShapeForm {

private final String name_;
private final Icon icon_;
private final String description_;
private final MultiPointCoordSet extraCoordSet_;
private final boolean canScale_;
private final MultiPointConfigKey rendererKey_;
Expand All @@ -60,6 +62,7 @@ public class MultiPointForm implements ShapeForm {
*
* @param name shapeform name
* @param icon shapeform icon
* @param description XML description
* @param extraCoordSet defines the extra positional coordinates
* used to plot multipoint shapes
* @param canScale true if a configuration option to scale the shapes
Expand All @@ -69,11 +72,12 @@ public class MultiPointForm implements ShapeForm {
* must be expecting data corresponding to the
* <code>extraCoordSet</code> parameter
*/
public MultiPointForm( String name, Icon icon,
public MultiPointForm( String name, Icon icon, String description,
MultiPointCoordSet extraCoordSet, boolean canScale,
MultiPointConfigKey rendererKey ) {
name_ = name;
icon_ = icon;
description_ = description;
extraCoordSet_ = extraCoordSet;
canScale_ = canScale;
rendererKey_ = rendererKey;
Expand All @@ -91,6 +95,10 @@ public Icon getFormIcon() {
return icon_;
}

public String getFormDescription() {
return description_;
}

public Coord[] getExtraCoords() {
return extraCoordSet_.getCoords();
}
Expand Down Expand Up @@ -127,8 +135,28 @@ public Outliner createOutliner( ConfigMap config ) {
public static MultiPointForm
createVectorForm( MultiPointCoordSet extraCoordSet,
boolean canScale ) {
String descrip = PlotUtil.concatLines( new String[] {
"<p>Plots directed lines from the data position",
"given delta values for the coordinates.",
"The plotted markers are typically little arrows,",
"but there are other options.",
"</p>",
"<p>In some cases such delta values may be",
"the actual magnitude required for the plot,",
"but often the vector data represents a value",
"which has a different magnitude or is in different units",
"to the positional data.",
"As a convenience for this case, the plotter can optionally",
"scale the magnitudes of all the vectors",
"to make them a sensible size,",
"so by default the largest ones are a few tens of pixels long.",
"This auto-scaling is in operation by default,",
"but it can be turned off or adjusted with the scaling and",
"auto-scaling options.",
"</p>",
} );
return new MultiPointForm( "Vector", ResourceIcon.FORM_VECTOR,
extraCoordSet, canScale,
descrip, extraCoordSet, canScale,
StyleKeys.VECTOR_SHAPE );
}

Expand All @@ -145,8 +173,14 @@ public Outliner createOutliner( ConfigMap config ) {
public static MultiPointForm
createEllipseForm( MultiPointCoordSet extraCoordSet,
boolean canScale ) {
String descrip = PlotUtil.concatLines( new String[] {
"<p>Plots an ellipse (or rectangle or other similar figure)",
"defined by two principal radii and",
"an optional rotation angle.",
"</p>",
} );
return new MultiPointForm( "Ellipse", ResourceIcon.FORM_ELLIPSE,
extraCoordSet, canScale,
descrip, extraCoordSet, canScale,
StyleKeys.ELLIPSE_SHAPE );
}

Expand All @@ -160,7 +194,15 @@ public Outliner createOutliner( ConfigMap config ) {
public static MultiPointForm
createErrorForm( MultiPointCoordSet extraCoordSet,
MultiPointConfigKey rendererKey ) {
return new MultiPointForm( "Error", ResourceIcon.FORM_ERROR,
String descrip = PlotUtil.concatLines( new String[] {
"<p>Plots symmetric or asymmetric error bars in some or",
"all of the plot dimensions.",
"The shape of the error \"bars\" is quite configurable,",
"including (for 2-d and 3-d errors)",
"ellipses, rectangles etc aligned with the axes.",
"</p>",
} );
return new MultiPointForm( "Error", ResourceIcon.FORM_ERROR, descrip,
extraCoordSet, false, rendererKey );
}

Expand Down
11 changes: 10 additions & 1 deletion ttools/src/main/uk/ac/starlink/ttools/plot2/layer/PairLinkForm.java
View file
Expand Up @@ -13,6 +13,7 @@
import uk.ac.starlink.ttools.plot2.AuxScale;
import uk.ac.starlink.ttools.plot2.DataGeom;
import uk.ac.starlink.ttools.plot2.Glyph;
import uk.ac.starlink.ttools.plot2.PlotUtil;
import uk.ac.starlink.ttools.plot2.Surface;
import uk.ac.starlink.ttools.plot2.config.ConfigKey;
import uk.ac.starlink.ttools.plot2.config.ConfigMap;
Expand Down Expand Up @@ -41,13 +42,21 @@ private PairLinkForm() {
}

public String getFormName() {
return "Link";
return "Link2";
}

public Icon getFormIcon() {
return ResourceIcon.FORM_LINK2;
}

public String getFormDescription() {
return PlotUtil.concatLines( new String[] {
"<p>Plots a line linking two positions from the same",
"input table row.",
"</p>",
} );
}

public int getPositionCount() {
return 2;
}
Expand Down
8 changes: 8 additions & 0 deletions ttools/src/main/uk/ac/starlink/ttools/plot2/layer/ShapeForm.java
View file
Expand Up @@ -18,6 +18,14 @@
*/
public interface ShapeForm extends ModePlotter.Form {

/**
* Returns a description of this mode as an XML string.
* The return value should be one or more &lt;p&gt; elements.
*
* @return XML description of form
*/
String getFormDescription();

/**
* Returns the number of data positions per tuple used by this form.
*
Expand Down
25 changes: 25 additions & 0 deletions ttools/src/main/uk/ac/starlink/ttools/plot2/layer/SizeForm.java
View file
Expand Up @@ -85,6 +85,31 @@ public Icon getFormIcon() {
return ResourceIcon.FORM_SIZE;
}

public String getFormDescription() {
return PlotUtil.concatLines( new String[] {
"<p>Plots a marker of fixed shape but variable size",
"at each postion.",
"The size is determined by an additional input data value.",
"</p>",
"<p>The marker size is scaled according to the values",
"of the data.",
"The data range in the visible part of the plot is determined,",
"the maximum value is assigned to the maximum marker size,",
"and the size of each marker is determined as",
"(data value)/(max data value).",
"Currently data values of zero always correspond to",
"marker size of zero, negative data values are not represented,",
"and the mapping is linear.",
"Other options may be introduced in future.",
"</p>",
"<p>Note the scaling to size is in terms of screen dimensions",
"(pixels).",
"For sizes that correspond to actual data values,",
"Error plotting may be more appropriate.",
"</p>",
} );
}

public Coord[] getExtraCoords() {
return new Coord[] {
SIZE_COORD,
Expand Down

0 comments on commit b9012b7

Please sign in to comment.