📄 ogr_feature_style.html
字号:
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"><HTML><HEAD> <TITLE>OGR - Feature Style Specification</TITLE></HEAD><BODY BGCOLOR="#FFFFFF"><CENTER><H1>OGR - Feature Style Specification</H1></CENTER><CENTER> <H2>DRAFT V0.010 - 2006/09/23</H2></CENTER><HR WIDTH=50%><H2>REVISION HISTORY</H2><UL><LI><B>Version 0.010 - 2006-09-23- Andrey Kiselev</B><BR> Added label styles 'w', 'st', 'h', 'm:h', 'm:a', 'p:{10,11,12}'<LI><B>Version 0.009 - 2005-03-11- Frank Warmerdam</B><BR> Remove reference to OGRWin, move into ogr distribution<LI><B>Version 0.008 - 2001-03-21- Frank Warmerdam</B><BR> Fix minor typos (h:12pt instead of s:12pt in examples)<LI><B>Version 0.008 - 2000-07-15 - Stephane Villeneuve</B><BR> Remove style table in Layer. Add forecolor and backcolor to brush.<LI><B>Version 0.007 - 2000-06-22 - Daniel Morissette</B><BR> Fixed typo and added offset param for PEN.<LI><B>Version 0.006 - 2000-06-20 - Daniel Morissette</B><BR> Added the OGR-Win idea and made small changes here and there.<LI><B>Version 0.005 - 2000-06-12 - Daniel Morissette</B><BR> Allow passing of comma-delimited list of names in PEN's "id" parameter.<BR> Defined system-independent pen style names.<LI><B>Version 0.004 - 2000-06-09 - Stephane Villeneuve</B><BR> Added PEN cap and join parameters<BR> More clearly defined the API<LI><B>Version 0.003 - 2000-02-15 - Daniel Morissette</B><BR> First kind-of-complete version.<P></UL><HR WIDTH=50%><H2>1. Overview</H2>This document defines the way feature style information (i.e. colors, linewidth, symbols, etc.) should be handled at the various levels in OGR.<H2>1.1 Style is a property of Feature object</H2>Conceptually, the feature style should be seen as a property of a feature.Even though some systems would store style information in a special attribute,in OGR it is more consistent to see the style as a property just the sameway the geometry of a feature is also a property.<P>This does not prevent us from storing the style information in an attributewhen writing to some formats that have no provision for styles (e.g. E00).But then at the time such a dataset is opened through OGR, the name ofthe attribute that contains style information should either be specifiedin some metadata, or be specified by the user.<P>Also, in the SFCOM interface, the style information will be stored inan attribute just like the geometry is. Later in this document, we willdefine a kind of "WKT" format to be used when storing style informationin text form.<H2>1.2 Feature Styles can be stored at 2 levels</H2>The style defines the way a feature should be drawn, but it is very commonto have several features that share the same style. In those cases, insteadof duplicating the style information on each feature, we will provide amore efficient way to share style information.<P>There are actually 2 levels at which style information can be found:<UL><LI><B>At the dataset level</B>:</LI><UL><LI>A dataset can have a default style that applies to all features.</LI><LI>It can also have a table of pre-defined styles that can then be referredto by the layers or by the individual features.</LI><BR>The mechanism for that is defined further down in this document.</UL><LI><B>At the feature level (in the OGRFeature)</B>:</LI><UL><LI>By default, a feature inherits the style information from the dataset.</LI><LI>A feature can (and should in most cases) be linked to a style in the dataset's table of styles. This can save lots of storage spacewhen the same styles are reused often.</LI><LI>Finally, a feature can have its own complete style definition.</LI></UL></UL>It should be possible to have style information stored at one or more ofthe various levels while working on a given dataset. The level(s) wherethe style is actually stored will depend on the most efficient approachfor the format we are dealing with.<P>However, all that stuff should be transparent to the OGR client thatdoes not want to worry about the details and a single call to a methodsuch as OGRFeature::GetStyleString() should hide all the magic and alwaysreturn the right information.<H2>1.3 Drawing Tools</H2>We define a small set of drawing tools that are used to build style definitions:<UL><LI><B>PEN</B>: For linear styles</LI><LI><B>BRUSH</B>: For filling areas</LI><LI><B>SYMBOL</B>: Point symbols</LI><LI><B>LABEL</B>: For annotations</LI></UL>Each drawing tool can take a number of parameters, all optional. The stylesyntax is built in a way that a system that cannot support all possibleparameters can safely skip and ignore the parameters it does not support.This will also make it easy to extend the specification in the future withoutbreaking existing code or applications.<P>A style can use a single tool, or use a combination of one or more tools.By combining the use of several tools in a style, one can build virtuallyany type of graphical representation. For instance, the SYMBOL tool canbe used to place spaced symbols along a line. Also, the LABEL tool canbe used to place text on a point, stretch it along a line, or even, bycombining the PEN tool with the LABEL tool, use the line as a leader tothe text label, and draw the text string on the last vertex of the line.<P>Of course only few systems can support all that. But the intention hereis to have a style specification that is powerful and flexible enough toallow all types of formats to exchange style information with the leastpossible loss.<H2>1.4 Feature attributes can be used by style definitions</H2>In some cases, it might be useful for a style definition to refer to anattribute field on the feature for a given tool parmeter's value insteadof having a hardcoded value inside the style itself.<P>Example of this are text angle, text string, etc... these values changefor every single text label, but we can share the rest of the label styleat the layer level if we lookup the angle and text string in an attributeon each feature.<P>The syntax of the style string provides a way that any parameter valuecan be either a constant value, or a lookup to an attribute field.<H2>1.5 Tool parameter units</H2>Several parameter values can be expressed in different measurement unitsdepending on the file format you are dealing with. For instance, some systemsexpress line width, or text height in points, other in pixels, and othersuse ground units. In order to accomodate all that, all parameters can bespecified in one of the following units systems:<UL><LI><B>g</B>: Map Ground Units (whatever the map coordinate units are)</LI><LI><B>px</B>: Pixels</LI><LI><B>pt</B>: Points (1/72 Inch)</LI><LI><B>mm</B>: Millimeters</LI><LI><B>cm</B>: Centimeters</LI><LI><B>in</B>: Inches</LI></UL>Some tools will have to be provided at the OGR client level to symplifythe conversion of any value from one units system to another. This wouldimply that the OGR client has to specify a map scale so that conversionsfrom ground units to paper/pixel units can be performed.<P><HR WIDTH=50%><H2>2. Feature Style String</H2>As was mentioned earlier, styles definitions will usually be stored asstrings, either in a per layer (or per dataset) table, or directly in thefeatures.<H2>2.1 Examples</H2>The best way to get familiar with something is by example.<P>Here we go with some style definition strings:<PRE> A 5 pixels wide red line: "PEN(c:#FF0000,w:5px)" A polygon filled in blue, with a black outline: "BRUSH(fc:#0000FF);PEN(c:#000000)" A point symbol: "SYMBOL(c:#00FF00,id:"points.sym-45,ogr-sym-7")" A text label, taking the text string from the "text_string" attribute field: "LABEL(f:"Times New Roman",s:12pt,t:{text_string})"</PRE>Here is what a style table that contains all the above styles could looklike:<PRE> road: PEN(c:#FF0000,w:5px) lake: BRUSH(fc:#0000FF);LINE(c:#000000) campsite: SYMBOL(c:#00FF00,id:"points.sym-45,ogr-sym-7") label: LABEL(f:"Times New Roman",s:12pt,t:{text_string})</PRE>And then individual features could refer to styles from the table aboveusing the "@" character followed by the style name in their style property.<P>For instance, a feature with its style set to "@road" would be drawnas a red line.<H2>2.2 Style String Syntax</H2>Each feature object has a style property (a string):<TABLE BORDER WIDTH="100%" ><TR><TD><PRE> <style_property> = "<style_def>" | "" | "@<style_name>" | "{<field_name>}"</PRE></TD></TR></TABLE><UL><LI>"<style_def>" is defined later in this section.</LI><LI>An empty style property means that the feature directly inherits its stylefrom the layer it is in.</LI><LI>"@<style_name>" is a reference to a predefined style in the layer orthe dataset's style table. The layer's table is lookued up first, and ifstyle_name is not found there then the dataset's table will be looked up.</LI><LI>Finally, "{<field_name>}" means that the style property should be readfrom the specified attribute field.</LI></UL>The <style_def> is the real style definition. It is a combination of1 or more style parts separated by semicolons. Each style_part uses a drawingtool to define a portion of the complete graphical representation:<TABLE BORDER WIDTH="100%" ><TR><TD><PRE> <style_def> = <style_part>[;<style_part>[;...]] <style_part> = <tool_name>([<tool_param>[,<tool_param>[,...]]]) <tool_name> = name of a drawing tool, for now: PEN | BRUSH | SYMBOL | LABEL <tool_param> = <param_name>:<param_value> <param_name> = see list of parameters names for each drawing tool <param_value> = <value> | <value><units> <value> = "<string_value>" | <numeric_value> | {<field_name>} <units> = g | px | pt | mm | cm | in</PRE></TD></TR></TABLE><P>By default, style parts are drawn in the order that they appear in thestyle_def string unless each part is assigned a different level parametervalue (see the level parameter definition).<P>All drawing tool parameters are optional. So it is legal to have a style_partwith an empty drawing tool parameter list (e.g. "PEN()"). For each parameterthat does not have any specified value, it is up to the client applicationto use its own default value. This document provides advisory default valuesfor most parameters, but it is not mandatory for an application to usethose default value.<P>When {<field_name>} is used for a tool_param value, several optionsare available with respect to the units. The units can be specified afterthe field name as in PEN(c:#FF0000,w:{line_width}pt) or can be left unspecifiedas in PEN(c:#FF0000,w:{line_width}). In the first case, the default unitswill be points (pt), but if the attribute field line_width contains a valuefollowed by a units abbreviation (e.g. "5px") then the units specifiedin the attribute fields have precedence (in this case pixels). Note thatthe attribute field does not have to contain a units value and probablywon't in most cases, it is just an optional feature to be able to overridethe default units from inside an attribute field's value.<H2>2.3 Pen Tool Parameters</H2><B>Applicable geometry types:</B><UL><LI>Point: When applied to a point, a pen tool can only define the color andthe size of the point to draw.</LI><LI>Polyline: This is the most obvious case.</LI><LI>Polygon: Defines the way the outline of a polygon should be drawn.</LI></UL>Here is the current list of PEN tool parameters, while this is sufficientto cover all the cases that we have encountered so far, new parametersmight be added in the future to handle new types of graphical representation.Note again that all parameters are optional:<TABLE BORDER WIDTH="100%" > <TR> <TH>param_name</TH> <TH>Description</TH> </TR> <TR> <TD ALIGN=CENTER>c</TD> <TD><B>Pen Color</B>, expressed in hexadecimal (#RRGGBB[AA])<BR> [AA] the last 2 digits define the alpha channel value, with 0 being transparent and FF being opaque. The default is FF (opaque) <BR> Suggested default: black (c:#000000)<BR> Example: PEN(c:#FF0000), or PEN(C:#FF0000FF)<BR> Predefined color names may be allowed in future versions of the specification.</TD> </TR> <TR> <TD ALIGN=CENTER>w</TD> <TD><B>Pen Width</B> - Expressed in a valid unit type (g, px, pt, mm, cm,in)<BR> Suggested default: 1 pixel<BR> Examples: PEN(c:#FF0000,w:5px), PEN(w:3pt), PEN(w:50g)</TD> </TR> <TR> <TD ALIGN=CENTER>p</TD> <TD><B>Pattern</B> - To create dash lines. A list of pen-down/pen-up distances<BR> Examples:<BR> <IMG SRC="style_pen1.gif" HEIGHT=15 WIDTH=75> = PEN(c:#FF0000,w:2px,p:"4px5px") - short-dash line<BR> <IMG SRC="style_pen2.gif" HEIGHT=15 WIDTH=75> = PEN(c:#FF0000,w:2px,p:"10px5px") - long-dash line<BR> <IMG SRC="style_pen3.gif" HEIGHT=15 WIDTH=75> = PEN(c:#FF0000,w:2px,p:"10px5px 4px 5px") - long/short dash line</TD> </TR> <TR> <TD ALIGN=CENTER>id</TD> <TD><B>Comma-delimited list of Pen Names or Ids</B> - For systems that identify pens with a name or an id. The names in the comma-delimited list of ids are scanned until one is recognized by the target system. <P>Pen Ids can be either system-specific ids (see further below) or be oneof the pre-defined OGR pen ids for well known line patterns. The idparameter should always include one of the OGR ids at the end of the comma-delimited list of ids so that an application never has to rely on understanding system-specific ids. <P>Here is the current list of OGR pen ids (this could grow over time):<BR> <UL> <LI>ogr-pen-0: solid (the default when no id is provided) <LI>ogr-pen-1: null pen (invisible) <LI>ogr-pen-2: dash <LI>ogr-pen-3: short-dash <LI>ogr-pen-4: long-dash <LI>ogr-pen-5: dotline <LI>ogr-pen-6: dash-dotline <LI>ogr-pen-7: dash-dot-dotline <LI>ogr-pen-8: alternate-line (sets every other pixel) </UL> <P>System-specific ids are very likely to be meaningful only to that specific system that created them. The ids should start with the system's name, followed by a dash (-), followed by whatever information is meaningful to that system (a number, a name, a filename, etc.).<BR>e.g. "mapinfo-5", or "mysoft-lines.sym-123", or "othersystems-funnyline" <P>System-specific ids are allowed in order to prevent loss of information when dealing with data from systems that store line patterns in external files or that have their own pre-defined set of line styles. (To do a MapInfo MIFto TAB translation without any loss for instance.) <P>Examples: <BR>PEN(c:#00FF00,id:"ogr-pen-0") - simple solid line<BR>PEN(c:#00FF00,id:"mapinfo-5,ogr-pen-7") - corresponds to MapInfo's Pen #5, and a system that can't understand MapInfo pens falls back on the default "ogr-pen-7" pen (dot-dot line). </TD> </TR> <TR> <TD ALIGN=CENTER>cap</TD> <TD><B>Pen Cap</B> - Set the shape of end points of lines.<BR>b=BUTT The ends of the line don't extend beyond the end points. This is the default. <BR>r=ROUND Terminate lines with a circle whose diameter is equal to the line width. <BR>p=PROJECTING Similar to BUTT, but the ends of the line extend by half of line width beyond the end points. </TD> </TR> <TR> <TD ALIGN=CENTER>j</TD> <TD><B>Pen Join</B> - Set the shape of the join point (vertex) of lines.<BR>m=MITER Extend the outer edge of the lines until they touch. This is the default. <BR>r=ROUNDED Join lines with an arc whose center is at the join point and whose diameter is equal to the line width. <BR>b=BEVEL Join the lines with butt end caps and fill the resulting triangular notch at the join position. </TD> </TR> <TR> <TD ALIGN=CENTER>dp</TD> <TD><B>Perpendicular Offset</B> - Offset from the line center<BR> If the offset is negative then the pen will be drawn left of the main segment and right otherwise. </TD> </TR> <TR> <TD ALIGN=CENTER>l</TD> <TD><B>Priority Level</B> - Numeric value defining the order in which styleparts should be drawn. Lower priority style parts are drawn first, andhigher priority ones are drawn on top.<BR> If priority level is unspecified, the default is 1.</TD> </TR></TABLE><H2>2.4 Brush Tool Parameters</H2>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -