Map/Style documentation
jericks
I finally got the documentation monkey off my back. I just commited
map/style documentation to the learning and examples sections of the
web site. I only did Groovy examples. As always I am open to
feedback.
Jared
Justin Deoliveira
--
You received this message because you are subscribed to the GeoScript mailing list.
To post to this group, send email to geos...@googlegroups.com
To unsubscribe from this group, send email to geoscript+...@googlegroups.com
Visit this group at http://groups.google.com/group/geoscript or see http://geoscript.org
--
Justin Deoliveira
Tim Schaub
I just tossed in the JavaScript map examples in the learning section.
http://github.com/tschaub/geoscript.org/commit/dda1e708394d3ace92783c0ecc185e7b481b2fe8
I agree with Justin that we should better define the purpose of the
narrative docs (as compared to API docs). Perhaps we can come up with a
nice outline. The purpose of examples & learning pages are a bit cloudy
in my mind right now.
I also wonder if we should discuss a bit more the Map API. I think we
came to a good place with Style (and Rule & symbolizers are pretty easy).
Perhaps we don't need better alignment, but in the JS implementation, a
map is a simple collection of layers. As with the other GeoScript
collections (workspace, layer, schema), it's got add and (soon) remove
methods.
The map render method takes (among other things) width, height, and
projection. Perhaps it's pedantic, but size feels more like a rendering
option to me (rather than a map property). Projection and bounds are
derived from the first layer added if not provided to render.
Anyway, if we don't want perfect alignment on the API, then I think the
example narrative shouldn't be specific with regard to property and
method names (these can be in the API docs). If the examples are goal
oriented, then the narrative can set up the goal and the code can
demonstrate the syntax.
I'll put more code into the examples as time allows, but wanted to hear
a bit more discussion first.
Tim
Jared Erickson
David Winslow
The render method should have good defaults (width = 400, imageType=png, ect...) and I couldn't figure out a good way to do this in Groovy without named parameters and default values(I have Python/Scala envy here), so I moved all parameters out of render (except the OutputStream or File).
class Map {
private val defaults = immutable.Map("width" -> "300", "height" -> 300)
def render(providedParams: collection.Map[String, String]) = {
val params = defaults ++ providedParams
... do stuff with params here
}
}
David Winslow
new LineSymbolizer(strokeColor:"red", strokeWidth:3)
new LineSymbolizer(color:"red", width:"3")
var styles = collection.mutable.Buffer[Style]()
styles +=
Stroke(color="#000000", width=3)
styles +=
Stroke(color="#333333", width=5, linecap="round", z=0) and
Stroke(color="#6699FF", width=3, linecap="round", z=1)
styles +=
Stroke(color="#000000", width=3) when ("type='local-road'")
styles +=
Stroke(color="#000000", width=3) when (ScaleBetween(1.8e9, 3.6e9))
Tim Schaub
> Hey guys, I've been looking over the style API docs, and I have a small
> suggestion.
>
> Right now a Style is a container of Rules which are containers of
> Symbolizers. I think it would be more convenient and "scripty" to make
> Symbolizers themselves styles which can be composed with other styles if
> you want multiple styles, or annotated with restrictions if desired.
What is the layer property called in this case? I assume styles.
> Also, I think it would be a big win to drop the "stroke" prefix from
> LineSymbolizer properties (and "fill" from PolygonSymbolizer, etc.) For
> example, calls like
>
> new LineSymbolizer(strokeColor:"red", strokeWidth:3)
>
> would go to
>
> new LineSymbolizer(color:"red", width:"3")
>
For clarification, you are proposing "color" mean "strokeColor" for
LineSymbolizer and "fillColor" for PolygonSymbolizer? Then we still
have "strokeColor" for PolygonSymbolizer. And both "strokeColor" and
"fillColor" for PointSymbolizer.
I'm somewhat partial to the consistency we currently have (but for me,
scripting is not about typing fewer characters).
>
> Here's what a Scala style API implementing both ideas might look like
> (based on the Groovy examples from the site sources, in order):
>
> var styles = collection.mutable.Buffer[Style]()
>
> styles +=
>
> Stroke(color="#000000", width=3)
>
> styles +=
>
> Stroke(color="#333333", width=5, linecap="round", z=0) and
>
> Stroke(color="#6699FF", width=3, linecap="round", z=1)
>
> styles +=
>
> Stroke(color="#000000", width=3) when ("type='local-road'")
>
> styles +=
>
> Stroke(color="#000000", width=3) when (ScaleBetween(1.8e9, 3.6e9))
>
This is what I currently write (ommitting cap for brevity):
layer.style = [{
symbolizers: [{strokeColor: "#000000", strokeWidth: 3}]
}, {
symbolizers: [
{strokeColor: "#333333", strokeWidth: 5, zIndex: 0},
{strokeColor: "#6699FF", strokeWidth: 3, zIndex: 1}
]
}, {
symbolizers: [{strokeColor: "#000000", strokeWidth: 3}],
filter: "type='local-road'"
}, {
symbolizers: [{strokeColor: "#000000", strokeWidth: 3}],
minScaleDenominator: 1.8e9,
maxScaleDenominator: 3.6e9
}];
With your proposal, I think this is what I'd write:
layer.style = [
new Stroke({color: "#000000", width: 3}),
new Stroke({color: "#333333", width: 5, zIndex: 0})
.and({color: "#6699FF", width: 3, zIndex: 1}),
new Stroke({color: "#000000", width: 3})
.where("type='local-road'"),
new Stroke({color: "#000000", width: 3})
.range({min: 1.8e9, max: 3.6e9})
];
I like it. This does bring up some questions for me though.
var foo =
new Stroke({color: "fuchsia", width: 10, zIndex: 0})
.and({color: "navy", width: 5, zIndex: 1});
assert(foo instanceof Stroke);
assert(foo.color === "no idea");
Tim
David Winslow
On 10/15/10 7:47 AM, David Winslow wrote:What is the layer property called in this case? I assume styles.
Hey guys, I've been looking over the style API docs, and I have a small
suggestion.
Right now a Style is a container of Rules which are containers of
Symbolizers. I think it would be more convenient and "scripty" to make
Symbolizers themselves styles which can be composed with other styles if
you want multiple styles, or annotated with restrictions if desired.
For clarification, you are proposing "color" mean "strokeColor" for LineSymbolizer and "fillColor" for PolygonSymbolizer? Then we still have "strokeColor" for PolygonSymbolizer. And both "strokeColor" and "fillColor" for PointSymbolizer.
Also, I think it would be a big win to drop the "stroke" prefix from
LineSymbolizer properties (and "fill" from PolygonSymbolizer, etc.) For
example, calls like
new LineSymbolizer(strokeColor:"red", strokeWidth:3)
would go to
new LineSymbolizer(color:"red", width:"3")
Fill(color:blue) and Stroke(color: red)
Fill(fillcolor: blue, strokecolor:red)
I like it. This does bring up some questions for me though.
var foo =
new Stroke({color: "fuchsia", width: 10, zIndex: 0})
.and({color: "navy", width: 5, zIndex: 1});
assert(foo instanceof Stroke);
assert(foo.color === "no idea");
Tim Schaub
I consistently read Stroke as LineSymbolizer somehow in your previous
email. Seeing that you are indeed talking about creating separate
stroke and fill constructors, I agree the name "color" makes sense.
>
> With your proposal, I think this is what I'd write:
>
> layer.style = [
>
> new Stroke({color: "#000000", width: 3}),
>
> new Stroke({color: "#333333", width: 5, zIndex: 0})
> .and({color: "#6699FF", width: 3, zIndex: 1}),
>
> new Stroke({color: "#000000", width: 3})
> .where("type='local-road'"),
>
> new Stroke({color: "#000000", width: 3})
> .range({min: 1.8e9, max: 3.6e9})
>
> ];
>
>
Indeed what I was thinking I was typing above was LineSymbolizer (or
some shorthand for it) instead of Stroke.
> This looks right to me, assuming that layer.style has a setter which
> automatically composes styles. Otherwise, I'd expect a
> org.geoscript.style.compose() call in there somewhere.
>
> I like it. This does bring up some questions for me though.
>
> var foo =
> new Stroke({color: "fuchsia", width: 10, zIndex: 0})
> .and({color: "navy", width: 5, zIndex: 1});
>
> assert(foo instanceof Stroke);
>
>
> I would expect this assertion to fail, as the result of a
> *.and* operation would be a CompositeStyle or something instead of a Stroke.
>
> assert(foo.color === "no idea");
>
>
> Similarly, CompositeStyles don't have a color of their own; instead,
> they /contain/ styles which /might/ contain colors (or might themselves
> be composites of other styles.)
>
Ok, CompositeStyle is new. It would probably help to list the
constructors you are suggesting.
(I like the way this is going.)
Tim
>
> Tim
>
>
> Here "and" is a Style method which composes two styles, and
> "when" is a
> Style method which adds a constraint. ("when" might be
> overloaded to
> accept Strings (interpreted as CQL) and ScaleBetween's or something,
> specifics are up for debate).
>
> --
> David Winslow
> OpenGeo - http://opengeo.org/
>
> On Fri, Oct 15, 2010 at 12:39 PM, David Winslow
> <cdwi...@gmail.com <mailto:cdwi...@gmail.com>
> <mailto:cdwi...@gmail.com <mailto:cdwi...@gmail.com>>> wrote:
>
> On Wed, Oct 13, 2010 at 5:10 AM, Jared Erickson
> <jared.e...@gmail.com <mailto:jared.e...@gmail.com>
> <mailto:jared.e...@gmail.com
> <mailto:geos...@googlegroups.com>
> To unsubscribe from this group, send email to
> geoscript+...@googlegroups.com
> <mailto:geoscript%2Bunsu...@googlegroups.com>
> Visit this group at http://groups.google.com/group/geoscript or see
> http://geoscript.org
>
>
> --
> You received this message because you are subscribed to the
> GeoScript mailing list.
> To post to this group, send email to geos...@googlegroups.com
> <mailto:geos...@googlegroups.com>
> To unsubscribe from this group, send email to
> geoscript+...@googlegroups.com
> <mailto:geoscript%2Bunsu...@googlegroups.com>
David Winslow
- LineSymbolizer's are dumb, Stroke's are where it's at.
- PolygonSymbolizer's are dumb, Fill's are where it's at. Fill's only do Fill stuff, no stroking. Use composites (see below) if you want to fill and outline stuff.
- Strokes and Fills are complete styles on their own, suitable for attaching to a layer and mapmaking.
- Every style has an "and" method which takes another style (simple or composite) and composes the two styles, SLD-painter's-model-wise. This produces a new style whose type is an implementation detail.
- Every style has a "when" or "where" or "range" method which takes constraints on data or scale and produces a new style which does the same thing, but only when those constraints are met.
- This code might work (composites themselves have when's and and's):
- ((Stroke("blue") when ("type='river'")) and (Stroke("orange",z=-1) when ("contamination='nuclear'")) when (ScaleAbove(1.8e7))
David Winslow
- Style - Styles can be attached to Layers and passed to a Viewport to draw spatial data on maps.
- where(Filter): Style - Produce a new Style which restricts its drawing to a subset of features based on their attributes. Only features which are accepted by the Filter will be drawn. There is an implicit conversion from String to Filter which interprets the String as an ECQL expression.
- aboveScale(Double): Style - Produce a new Style which only draws features when the Map's scale denominator is above the provided value.
- belowScale(Double): Style - Produce a new Style which only draws features when the Map's scale denominator is below the provided value.
- and(Style): Style - Create a new Style whose effect is approximately the same as rendering this Style, followed by the Style passed as an argument. The difference lies in the handling of zIndex properties (see SimpleStyle below). zIndex is only respected within an And'ed style.
- underlying: org.geotools.styling.Style - A GeoTools Style instance corresponding to this Style.
- Paint - A Paint provides the actual pixels to use when actualizing a Stroke or Fill. End-users will likely be more interested in the concrete implementations Color, Symbol, and Graphic. There is an implicit conversion from String to Filter which interprets the String as a CSS/SVG color name, or else as a hexadecimal RGB color specification.
- SimpleStyle - A Style which is "flat;" forming the leaves in the tree produced by and'ing Styles together. This (abstract) class is mostly an implementation detail, end-users will likely be more interested in the concrete implementations Stroke, Fill, Label, Symbol, and Graphic.
- filter: Option[Filter] - If there are attribute constraints on this Style, this property will be a Some[Filter] containing those constraints. Otherwise, it is None.
- minScale: Option[Double] - If there is a minimum scale denominator constraint on this Style, this property will be a Some[Double] containing the minimum allowable scale value. Otherwise, it is None.
- maxScale: Option[Double] - If there is a maximum scale denominator constraint on this Style, this property will be a Some[Double] containing the maximum allowable scale value. Otherwise, it is None.
- symbolizers: Seq[org.geotools.styling.Symbolizer] - This property produces a collection of the GeoTools symbolizers which this Style contributes to the rendering.
- zIndex: Double - This property is used to sort styles before rendering; higher values are rendered later using the painter's model ("on top" of Styles with lower-valued z-indices).
- (also inherits all Style methods)
- CompositeStyle - A Style which combines other Styles such that they can be treated as a single Style. If SimpleStyles are leaves in a tree, CompositeStyles are the internal nodes. This class is mostly an implementation detail, end-users are encouraged to use Style#and instead of instantiating CompositeStyles directly.
- flatten: Seq[SimpleStyle] - A Seq containing all the SimpleStyles in this CompositeStyle in the order they were added.
- (also inherits all Style methods)
- Fill(fill: Paint, opacity: Expression, zIndex: Double) - A Style which fills in polygons. (Multi)LineStrings will be coerced into Polygons by adding a segment between the first and last vertices, and then filled in. Point geometries are not drawn.
- Stroke(stroke: Paint, width: Expression, opacity: Expression, linecap: Expression, linejoin: Expression, dashoffset: Expression, dasharray: Seq[Float], zIndex: Double, mode: Stroke.Mode) - A Style which strokes lines and polygon edges. Point geometries are not drawn.
- Label(text: Expression, geometry: Expression) - A Style which annotates the map with text, possibly derived from a property of the data. (Note: zIndex has no effect on Label's; the text is always rendered on top of any other map elements.)
- Symbol(shape: Expression, fill: Fill, stroke: Stroke, size: Expression, rotation: Expression, opacity: Expression, zIndex: Double) - A Symbol can be used as Paint in Fill's or Stroke's, or as a Style which draws the described Symbol as a point marker. For Line and Polygon geometries a marker will be placed at an appropriate but unspecified point within the geometry.
- Graphic(url: String, size: Expression, rotation: Expression, zIndex: Double) - A Graphic can be used as Paint in Fill's or Stroke's, or as a Style which draws an image from a file or http URL as a point marker. The URL may contain embedded CQL expressions. For Line and Polygon geometries a marker will be placed at an appropriate but unspecified point within the geometry.
Tim Schaub
I look forward to finding time to implement this and see how it feels.
I'm tempted to use Brush instead of Paint. And I think below you mean
that Fill and Stroke are constructed with "color" (instead of "fill"
and "stroke"). And the implicit conversion is from String to Paint
(or Brush). Not meaning to nitpick, but these were things that
confused me on first read, so I'm just clarifying.
Tim Schaub
up - given a layer with multiple geometry types, you can no longer
stroke the lines and the polygons differently, right?
David Winslow
Fill(color=Graphic("pattern.png"))
(Stroke("blue") when "geometryType(the_geom) = 'Polygon'") and
(Stroke("red") when "geometryType(the_geom) = 'Line'")
Tim Schaub
> I named the paint properties for Fill and Stroke, fill and stroke
> respectively. This is because
>>
>> Fill(color=Graphic("pattern.png"))
Yeah, I hit send too soon. Makes sense.
>
> sounds a bit awkward to me.
> I don't feel strongly about Brush vs. Paint. I suppose Brush has been
> popularized by Photoshop and its ilk, so we can go with that.
> The note about implicit conversions from String to Filter should have said
> String to Paint. Guess it's time to move those docs over to version
> control. (I may have been thinking about how Color should really be
> constructed with an Expression...)
> As for multiple geometry types - is that how things are handled now? I was
> under the impression that a LineSymbolizer and a PolygonSymbolizer with no
> Fill's were 100% equivalent (ie, in your style with a LineSymbolizer and a
> PolygonSymbolizer, lines and polygons would both get filled once and stroked
> twice). On the other hand, there is a CQL function for identifying the type
> of a geometry, so you could do something like:
I see that GeoTools is pretty liberal in how it applies a
PolygonSymbolizer. The spec reads that it "is used draw a polygon (or
other area-type geometries)." This would lead me to believe that you
could use a PolygonSymbolizer and LineSymbolizer to stroke geometries
differently depending on their type.
In any case, I'd be tempted to add a property to Stroke that specified
whether it applied to polygons, lines, or both (default). The CQL
below is clever, but it makes round-tripping SLD a bit more awkward
(not to mention writing CQL to capture the different geometry type
names - in GML at least - that all represent polygons).
Thanks for the responses.
David Winslow
On Sat, Oct 16, 2010 at 5:10 PM, David Winslow <cdwi...@gmail.com> wrote:Yeah, I hit send too soon. Makes sense.
> I named the paint properties for Fill and Stroke, fill and stroke
> respectively. This is because
>>
>> Fill(color=Graphic("pattern.png"))
I see that GeoTools is pretty liberal in how it applies a
>
> sounds a bit awkward to me.
> I don't feel strongly about Brush vs. Paint. I suppose Brush has been
> popularized by Photoshop and its ilk, so we can go with that.
> The note about implicit conversions from String to Filter should have said
> String to Paint. Guess it's time to move those docs over to version
> control. (I may have been thinking about how Color should really be
> constructed with an Expression...)
> As for multiple geometry types - is that how things are handled now? I was
> under the impression that a LineSymbolizer and a PolygonSymbolizer with no
> Fill's were 100% equivalent (ie, in your style with a LineSymbolizer and a
> PolygonSymbolizer, lines and polygons would both get filled once and stroked
> twice). On the other hand, there is a CQL function for identifying the type
> of a geometry, so you could do something like:
PolygonSymbolizer. The spec reads that it "is used draw a polygon (or
other area-type geometries)." This would lead me to believe that you
could use a PolygonSymbolizer and LineSymbolizer to stroke geometries
differently depending on their type.
In any case, I'd be tempted to add a property to Stroke that specified
whether it applied to polygons, lines, or both (default). The CQL
below is clever, but it makes round-tripping SLD a bit more awkward
(not to mention writing CQL to capture the different geometry type
names - in GML at least - that all represent polygons).