diff --git a/src/.gitattributes b/.gitattributes similarity index 100% rename from src/.gitattributes rename to .gitattributes diff --git a/build/cite/wcs10/citewcs-1.0/coverages/img_sample/usa.prj b/build/cite/wcs10/citewcs-1.0/coverages/img_sample/usa.prj index 9612216f7fa..3d2d4d2b836 100644 --- a/build/cite/wcs10/citewcs-1.0/coverages/img_sample/usa.prj +++ b/build/cite/wcs10/citewcs-1.0/coverages/img_sample/usa.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/build/cite/wms11/citewms-1.1/mbdemos/lib/util/wz_jsgraphics/wz_jsgraphics.js b/build/cite/wms11/citewms-1.1/mbdemos/lib/util/wz_jsgraphics/wz_jsgraphics.js index 758c3bc2399..57fb0ff37c8 100644 --- a/build/cite/wms11/citewms-1.1/mbdemos/lib/util/wz_jsgraphics/wz_jsgraphics.js +++ b/build/cite/wms11/citewms-1.1/mbdemos/lib/util/wz_jsgraphics/wz_jsgraphics.js @@ -1,923 +1,923 @@ -/* This notice must be untouched at all times. - -wz_jsgraphics.js v. 2.3 -The latest version is available at -http://www.walterzorn.com -or http://www.devira.com -or http://www.walterzorn.de - -Copyright (c) 2002-2004 Walter Zorn. All rights reserved. -Created 3. 11. 2002 by Walter Zorn (Web: http://www.walterzorn.com ) -Last modified: 15. 3. 2004 - -Performance optimizations for Internet Explorer -by Thomas Frank and John Holdsworth. -fillPolygon method implemented by Matthieu Haller. - -High Performance JavaScript Graphics Library. -Provides methods -- to draw lines, rectangles, ellipses, polygons - with specifiable line thickness, -- to fill rectangles and ellipses -- to draw text. -NOTE: Operations, functions and branching have rather been optimized -to efficiency and speed than to shortness of source code. - -This program is free software; -you can redistribute it and/or modify it under the terms of the -GNU General Public License as published by the Free Software Foundation; -either version 2 of the License, or (at your option) any later version. -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; -without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -See the GNU General Public License -at http://www.gnu.org/copyleft/gpl.html for more details. -*/ - - -var jg_ihtm, jg_ie, jg_fast, jg_dom, jg_moz, -jg_n4 = (document.layers && typeof document.classes != "undefined"); - - -function chkDHTM(x, i) -{ - x = document.body || null; - jg_ie = x && typeof x.insertAdjacentHTML != "undefined"; - jg_dom = (x && !jg_ie && - typeof x.appendChild != "undefined" && - typeof document.createRange != "undefined" && - typeof (i = document.createRange()).setStartBefore != "undefined" && - typeof i.createContextualFragment != "undefined"); - jg_ihtm = !jg_ie && !jg_dom && x && typeof x.innerHTML != "undefined"; - jg_fast = jg_ie && document.all && !window.opera; - jg_moz = jg_dom && typeof x.style.MozOpacity != "undefined"; -} - - -function pntDoc() -{ - this.wnd.document.write(jg_fast? this.htmRpc() : this.htm); - this.htm = ''; -} - - -function pntCnvDom() -{ - var x = document.createRange(); - x.setStartBefore(this.cnv); - x = x.createContextualFragment(jg_fast? this.htmRpc() : this.htm); - this.cnv.appendChild(x); - this.htm = ''; -} - - -function pntCnvIe() -{ - this.cnv.insertAdjacentHTML("beforeEnd", jg_fast? this.htmRpc() : this.htm); - this.htm = ''; -} - - -function pntCnvIhtm() -{ - this.cnv.innerHTML += this.htm; - this.htm = ''; -} - - -function pntCnv() -{ - this.htm = ''; -} - - -function mkDiv(x, y, w, h) -{ - this.htm += '
<\/div>'; -} - - -function mkDivIe(x, y, w, h) -{ - this.htm += '%%'+this.color+';'+x+';'+y+';'+w+';'+h+';'; -} - - -function mkDivPrt(x, y, w, h) -{ - this.htm += '
<\/div>'; -} - - -function mkLyr(x, y, w, h) -{ - this.htm += '<\/layer>\n'; -} - - -var regex = /%%([^;]+);([^;]+);([^;]+);([^;]+);([^;]+);/g; -function htmRpc() -{ - return this.htm.replace( - regex, - '
\n'); -} - - -function htmPrtRpc() -{ - return this.htm.replace( - regex, - '
\n'); -} - - -function mkLin(x1, y1, x2, y2) -{ - if (x1 > x2) - { - var _x2 = x2; - var _y2 = y2; - x2 = x1; - y2 = y1; - x1 = _x2; - y1 = _y2; - } - var dx = x2-x1, dy = Math.abs(y2-y1), - x = x1, y = y1, - yIncr = (y1 > y2)? -1 : 1; - - if (dx >= dy) - { - var pr = dy<<1, - pru = pr - (dx<<1), - p = pr-dx, - ox = x; - while ((dx--) > 0) - { - ++x; - if (p > 0) - { - this.mkDiv(ox, y, x-ox, 1); - y += yIncr; - p += pru; - ox = x; - } - else p += pr; - } - this.mkDiv(ox, y, x2-ox+1, 1); - } - - else - { - var pr = dx<<1, - pru = pr - (dy<<1), - p = pr-dy, - oy = y; - if (y2 <= y1) - { - while ((dy--) > 0) - { - if (p > 0) - { - this.mkDiv(x++, y, 1, oy-y+1); - y += yIncr; - p += pru; - oy = y; - } - else - { - y += yIncr; - p += pr; - } - } - this.mkDiv(x2, y2, 1, oy-y2+1); - } - else - { - while ((dy--) > 0) - { - y += yIncr; - if (p > 0) - { - this.mkDiv(x++, oy, 1, y-oy); - p += pru; - oy = y; - } - else p += pr; - } - this.mkDiv(x2, oy, 1, y2-oy+1); - } - } -} - - -function mkLin2D(x1, y1, x2, y2) -{ - if (x1 > x2) - { - var _x2 = x2; - var _y2 = y2; - x2 = x1; - y2 = y1; - x1 = _x2; - y1 = _y2; - } - var dx = x2-x1, dy = Math.abs(y2-y1), - x = x1, y = y1, - yIncr = (y1 > y2)? -1 : 1; - - var s = this.stroke; - if (dx >= dy) - { - if (s-3 > 0) - { - var _s = (s*dx*Math.sqrt(1+dy*dy/(dx*dx))-dx-(s>>1)*dy) / dx; - _s = (!(s-4)? Math.ceil(_s) : Math.round(_s)) + 1; - } - else var _s = s; - var ad = Math.ceil(s/2); - - var pr = dy<<1, - pru = pr - (dx<<1), - p = pr-dx, - ox = x; - while ((dx--) > 0) - { - ++x; - if (p > 0) - { - this.mkDiv(ox, y, x-ox+ad, _s); - y += yIncr; - p += pru; - ox = x; - } - else p += pr; - } - this.mkDiv(ox, y, x2-ox+ad+1, _s); - } - - else - { - if (s-3 > 0) - { - var _s = (s*dy*Math.sqrt(1+dx*dx/(dy*dy))-(s>>1)*dx-dy) / dy; - _s = (!(s-4)? Math.ceil(_s) : Math.round(_s)) + 1; - } - else var _s = s; - var ad = Math.round(s/2); - - var pr = dx<<1, - pru = pr - (dy<<1), - p = pr-dy, - oy = y; - if (y2 <= y1) - { - ++ad; - while ((dy--) > 0) - { - if (p > 0) - { - this.mkDiv(x++, y, _s, oy-y+ad); - y += yIncr; - p += pru; - oy = y; - } - else - { - y += yIncr; - p += pr; - } - } - this.mkDiv(x2, y2, _s, oy-y2+ad); - } - else - { - while ((dy--) > 0) - { - y += yIncr; - if (p > 0) - { - this.mkDiv(x++, oy, _s, y-oy+ad); - p += pru; - oy = y; - } - else p += pr; - } - this.mkDiv(x2, oy, _s, y2-oy+ad+1); - } - } -} - - -function mkLinDott(x1, y1, x2, y2) -{ - if (x1 > x2) - { - var _x2 = x2; - var _y2 = y2; - x2 = x1; - y2 = y1; - x1 = _x2; - y1 = _y2; - } - var dx = x2-x1, dy = Math.abs(y2-y1), - x = x1, y = y1, - yIncr = (y1 > y2)? -1 : 1, - drw = true; - if (dx >= dy) - { - var pr = dy<<1, - pru = pr - (dx<<1), - p = pr-dx; - while ((dx--) > 0) - { - if (drw) this.mkDiv(x, y, 1, 1); - drw = !drw; - if (p > 0) - { - y += yIncr; - p += pru; - } - else p += pr; - ++x; - } - if (drw) this.mkDiv(x, y, 1, 1); - } - - else - { - var pr = dx<<1, - pru = pr - (dy<<1), - p = pr-dy; - while ((dy--) > 0) - { - if (drw) this.mkDiv(x, y, 1, 1); - drw = !drw; - y += yIncr; - if (p > 0) - { - ++x; - p += pru; - } - else p += pr; - } - if (drw) this.mkDiv(x, y, 1, 1); - } -} - - -function mkOv(left, top, width, height) -{ - var a = width>>1, b = height>>1, - wod = width&1, hod = (height&1)+1, - cx = left+a, cy = top+b, - x = 0, y = b, - ox = 0, oy = b, - aa = (a*a)<<1, bb = (b*b)<<1, - st = (aa>>1)*(1-(b<<1)) + bb, - tt = (bb>>1) - aa*((b<<1)-1), - w, h; - while (y > 0) - { - if (st < 0) - { - st += bb*((x<<1)+3); - tt += (bb<<1)*(++x); - } - else if (tt < 0) - { - st += bb*((x<<1)+3) - (aa<<1)*(y-1); - tt += (bb<<1)*(++x) - aa*(((y--)<<1)-3); - w = x-ox; - h = oy-y; - if (w&2 && h&2) - { - this.mkOvQds(cx, cy, -x+2, ox+wod, -oy, oy-1+hod, 1, 1); - this.mkOvQds(cx, cy, -x+1, x-1+wod, -y-1, y+hod, 1, 1); - } - else this.mkOvQds(cx, cy, -x+1, ox+wod, -oy, oy-h+hod, w, h); - ox = x; - oy = y; - } - else - { - tt -= aa*((y<<1)-3); - st -= (aa<<1)*(--y); - } - } - this.mkDiv(cx-a, cy-oy, a-ox+1, (oy<<1)+hod); - this.mkDiv(cx+ox+wod, cy-oy, a-ox+1, (oy<<1)+hod); -} - - -function mkOv2D(left, top, width, height) -{ - var s = this.stroke; - width += s-1; - height += s-1; - var a = width>>1, b = height>>1, - wod = width&1, hod = (height&1)+1, - cx = left+a, cy = top+b, - x = 0, y = b, - aa = (a*a)<<1, bb = (b*b)<<1, - st = (aa>>1)*(1-(b<<1)) + bb, - tt = (bb>>1) - aa*((b<<1)-1); - - if (s-4 < 0 && (!(s-2) || width-51 > 0 && height-51 > 0)) - { - var ox = 0, oy = b, - w, h, - pxl, pxr, pxt, pxb, pxw; - while (y > 0) - { - if (st < 0) - { - st += bb*((x<<1)+3); - tt += (bb<<1)*(++x); - } - else if (tt < 0) - { - st += bb*((x<<1)+3) - (aa<<1)*(y-1); - tt += (bb<<1)*(++x) - aa*(((y--)<<1)-3); - w = x-ox; - h = oy-y; - - if (w-1) - { - pxw = w+1+(s&1); - h = s; - } - else if (h-1) - { - pxw = s; - h += 1+(s&1); - } - else pxw = h = s; - this.mkOvQds(cx, cy, -x+1, ox-pxw+w+wod, -oy, -h+oy+hod, pxw, h); - ox = x; - oy = y; - } - else - { - tt -= aa*((y<<1)-3); - st -= (aa<<1)*(--y); - } - } - this.mkDiv(cx-a, cy-oy, s, (oy<<1)+hod); - this.mkDiv(cx+a+wod-s+1, cy-oy, s, (oy<<1)+hod); - } - - else - { - var _a = (width-((s-1)<<1))>>1, - _b = (height-((s-1)<<1))>>1, - _x = 0, _y = _b, - _aa = (_a*_a)<<1, _bb = (_b*_b)<<1, - _st = (_aa>>1)*(1-(_b<<1)) + _bb, - _tt = (_bb>>1) - _aa*((_b<<1)-1), - - pxl = new Array(), - pxt = new Array(), - _pxb = new Array(); - pxl[0] = 0; - pxt[0] = b; - _pxb[0] = _b-1; - while (y > 0) - { - if (st < 0) - { - st += bb*((x<<1)+3); - tt += (bb<<1)*(++x); - pxl[pxl.length] = x; - pxt[pxt.length] = y; - } - else if (tt < 0) - { - st += bb*((x<<1)+3) - (aa<<1)*(y-1); - tt += (bb<<1)*(++x) - aa*(((y--)<<1)-3); - pxl[pxl.length] = x; - pxt[pxt.length] = y; - } - else - { - tt -= aa*((y<<1)-3); - st -= (aa<<1)*(--y); - } - - if (_y > 0) - { - if (_st < 0) - { - _st += _bb*((_x<<1)+3); - _tt += (_bb<<1)*(++_x); - _pxb[_pxb.length] = _y-1; - } - else if (_tt < 0) - { - _st += _bb*((_x<<1)+3) - (_aa<<1)*(_y-1); - _tt += (_bb<<1)*(++_x) - _aa*(((_y--)<<1)-3); - _pxb[_pxb.length] = _y-1; - } - else - { - _tt -= _aa*((_y<<1)-3); - _st -= (_aa<<1)*(--_y); - _pxb[_pxb.length-1]--; - } - } - } - - var ox = 0, oy = b, - _oy = _pxb[0], - l = pxl.length, - w, h; - for (var i = 0; i < l; i++) - { - if (typeof _pxb[i] != "undefined") - { - if (_pxb[i] < _oy || pxt[i] < oy) - { - x = pxl[i]; - this.mkOvQds(cx, cy, -x+1, ox+wod, -oy, _oy+hod, x-ox, oy-_oy); - ox = x; - oy = pxt[i]; - _oy = _pxb[i]; - } - } - else - { - x = pxl[i]; - this.mkDiv(cx-x+1, cy-oy, 1, (oy<<1)+hod); - this.mkDiv(cx+ox+wod, cy-oy, 1, (oy<<1)+hod); - ox = x; - oy = pxt[i]; - } - } - this.mkDiv(cx-a, cy-oy, 1, (oy<<1)+hod); - this.mkDiv(cx+ox+wod, cy-oy, 1, (oy<<1)+hod); - } -} - - -function mkOvDott(left, top, width, height) -{ - var a = width>>1, b = height>>1, - wod = width&1, hod = height&1, - cx = left+a, cy = top+b, - x = 0, y = b, - aa2 = (a*a)<<1, aa4 = aa2<<1, bb = (b*b)<<1, - st = (aa2>>1)*(1-(b<<1)) + bb, - tt = (bb>>1) - aa2*((b<<1)-1), - drw = true; - while (y > 0) - { - if (st < 0) - { - st += bb*((x<<1)+3); - tt += (bb<<1)*(++x); - } - else if (tt < 0) - { - st += bb*((x<<1)+3) - aa4*(y-1); - tt += (bb<<1)*(++x) - aa2*(((y--)<<1)-3); - } - else - { - tt -= aa2*((y<<1)-3); - st -= aa4*(--y); - } - if (drw) this.mkOvQds(cx, cy, -x, x+wod, -y, y+hod, 1, 1); - drw = !drw; - } -} - - -function mkRect(x, y, w, h) -{ - var s = this.stroke; - this.mkDiv(x, y, w, s); - this.mkDiv(x+w, y, s, h); - this.mkDiv(x, y+h, w+s, s); - this.mkDiv(x, y+s, s, h-s); -} - - -function mkRectDott(x, y, w, h) -{ - this.drawLine(x, y, x+w, y); - this.drawLine(x+w, y, x+w, y+h); - this.drawLine(x, y+h, x+w, y+h); - this.drawLine(x, y, x, y+h); -} - - -function jsgFont() -{ - this.PLAIN = 'font-weight:normal;'; - this.BOLD = 'font-weight:bold;'; - this.ITALIC = 'font-style:italic;'; - this.ITALIC_BOLD = this.ITALIC + this.BOLD; - this.BOLD_ITALIC = this.ITALIC_BOLD; -} -var Font = new jsgFont(); - - -function jsgStroke() -{ - this.DOTTED = -1; -} -var Stroke = new jsgStroke(); - - -function jsGraphics(id, wnd) -{ - this.setColor = new Function('arg', 'this.color = arg.toLowerCase();'); - - this.setStroke = function(x) - { - this.stroke = x; - if (!(x+1)) - { - this.drawLine = mkLinDott; - this.mkOv = mkOvDott; - this.drawRect = mkRectDott; - } - else if (x-1 > 0) - { - this.drawLine = mkLin2D; - this.mkOv = mkOv2D; - this.drawRect = mkRect; - } - else - { - this.drawLine = mkLin; - this.mkOv = mkOv; - this.drawRect = mkRect; - } - }; - - - this.setPrintable = function(arg) - { - this.printable = arg; - if (jg_fast) - { - this.mkDiv = mkDivIe; - this.htmRpc = arg? htmPrtRpc : htmRpc; - } - else this.mkDiv = jg_n4? mkLyr : arg? mkDivPrt : mkDiv; - }; - - - this.setFont = function(fam, sz, sty) - { - this.ftFam = fam; - this.ftSz = sz; - this.ftSty = sty || Font.PLAIN; - }; - - - this.drawPolyline = this.drawPolyLine = function(x, y, s) - { - for (var i=0 ; i>1, b = (h -= 1)>>1, - wod = (w&1)+1, hod = (h&1)+1, - cx = left+a, cy = top+b, - x = 0, y = b, - ox = 0, oy = b, - aa2 = (a*a)<<1, aa4 = aa2<<1, bb = (b*b)<<1, - st = (aa2>>1)*(1-(b<<1)) + bb, - tt = (bb>>1) - aa2*((b<<1)-1), - pxl, dw, dh; - if (w+1) while (y > 0) - { - if (st < 0) - { - st += bb*((x<<1)+3); - tt += (bb<<1)*(++x); - } - else if (tt < 0) - { - st += bb*((x<<1)+3) - aa4*(y-1); - pxl = cx-x; - dw = (x<<1)+wod; - tt += (bb<<1)*(++x) - aa2*(((y--)<<1)-3); - dh = oy-y; - this.mkDiv(pxl, cy-oy, dw, dh); - this.mkDiv(pxl, cy+oy-dh+hod, dw, dh); - ox = x; - oy = y; - } - else - { - tt -= aa2*((y<<1)-3); - st -= aa4*(--y); - } - } - this.mkDiv(cx-a, cy-oy, w+1, (oy<<1)+hod); - }; - - - -/* fillPolygon method, implemented by Matthieu Haller. -This javascript function is an adaptation of the gdImageFilledPolygon for Walter Zorn lib. -C source of GD 1.8.4 found at http://www.boutell.com/gd/ - -THANKS to Kirsten Schulz for the polygon fixes! - -The intersection finding technique of this code could be improved -by remembering the previous intertersection, and by using the slope. -That could help to adjust intersections to produce a nice -interior_extrema. */ - this.fillPolygon = function(array_x, array_y) - { - var i; - var y; - var miny, maxy; - var x1, y1; - var x2, y2; - var ind1, ind2; - var ints; - - var n = array_x.length; - - if (!n) return; - - - miny = array_y[0]; - maxy = array_y[0]; - for (i = 1; i < n; i++) - { - if (array_y[i] < miny) - miny = array_y[i]; - - if (array_y[i] > maxy) - maxy = array_y[i]; - } - for (y = miny; y <= maxy; y++) - { - var polyInts = new Array(); - ints = 0; - for (i = 0; i < n; i++) - { - if (!i) - { - ind1 = n-1; - ind2 = 0; - } - else - { - ind1 = i-1; - ind2 = i; - } - y1 = array_y[ind1]; - y2 = array_y[ind2]; - if (y1 < y2) - { - x1 = array_x[ind1]; - x2 = array_x[ind2]; - } - else if (y1 > y2) - { - y2 = array_y[ind1]; - y1 = array_y[ind2]; - x2 = array_x[ind1]; - x1 = array_x[ind2]; - } - else continue; - - // modified 11. 2. 2004 Walter Zorn - if ((y >= y1) && (y < y2)) - polyInts[ints++] = Math.round((y-y1) * (x2-x1) / (y2-y1) + x1); - - else if ((y == maxy) && (y > y1) && (y <= y2)) - polyInts[ints++] = Math.round((y-y1) * (x2-x1) / (y2-y1) + x1); - } - polyInts.sort(integer_compare); - - for (i = 0; i < ints; i+=2) - { - w = polyInts[i+1]-polyInts[i] - this.mkDiv(polyInts[i], y, polyInts[i+1]-polyInts[i]+1, 1); - } - } - }; - - - this.drawString = function(txt, x, y) - { - this.htm += '
'+ - txt + - '<\/div>'; - } - - - this.drawImage = function(imgSrc, x, y, w, h) - { - this.htm += '
'+ - ''+ - '<\/div>'; - } - - - this.clear = function() - { - this.htm = ""; - if (this.cnv) this.cnv.innerHTML = this.defhtm; - }; - - - this.mkOvQds = function(cx, cy, xl, xr, yt, yb, w, h) - { - this.mkDiv(xr+cx, yt+cy, w, h); - this.mkDiv(xr+cx, yb+cy, w, h); - this.mkDiv(xl+cx, yb+cy, w, h); - this.mkDiv(xl+cx, yt+cy, w, h); - }; - - this.setStroke(1); - this.setFont('verdana,geneva,helvetica,sans-serif', String.fromCharCode(0x31, 0x32, 0x70, 0x78), Font.PLAIN); - this.color = '#000000'; - this.htm = ''; - this.wnd = wnd || window; - - if (!(jg_ie || jg_dom || jg_ihtm)) chkDHTM(); - if (typeof id != 'string' || !id) this.paint = pntDoc; - else - { - this.cnv = document.all? (this.wnd.document.all[id] || null) - : document.getElementById? (this.wnd.document.getElementById(id) || null) - : null; - this.defhtm = (this.cnv && this.cnv.innerHTML)? this.cnv.innerHTML : ''; - this.paint = jg_dom? pntCnvDom : jg_ie? pntCnvIe : jg_ihtm? pntCnvIhtm : pntCnv; - } - - this.setPrintable(false); -} - - - -function integer_compare(x,y) -{ - return (x < y) ? -1 : ((x > y)*1); -} - +/* This notice must be untouched at all times. + +wz_jsgraphics.js v. 2.3 +The latest version is available at +http://www.walterzorn.com +or http://www.devira.com +or http://www.walterzorn.de + +Copyright (c) 2002-2004 Walter Zorn. All rights reserved. +Created 3. 11. 2002 by Walter Zorn (Web: http://www.walterzorn.com ) +Last modified: 15. 3. 2004 + +Performance optimizations for Internet Explorer +by Thomas Frank and John Holdsworth. +fillPolygon method implemented by Matthieu Haller. + +High Performance JavaScript Graphics Library. +Provides methods +- to draw lines, rectangles, ellipses, polygons + with specifiable line thickness, +- to fill rectangles and ellipses +- to draw text. +NOTE: Operations, functions and branching have rather been optimized +to efficiency and speed than to shortness of source code. + +This program is free software; +you can redistribute it and/or modify it under the terms of the +GNU General Public License as published by the Free Software Foundation; +either version 2 of the License, or (at your option) any later version. +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; +without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +See the GNU General Public License +at http://www.gnu.org/copyleft/gpl.html for more details. +*/ + + +var jg_ihtm, jg_ie, jg_fast, jg_dom, jg_moz, +jg_n4 = (document.layers && typeof document.classes != "undefined"); + + +function chkDHTM(x, i) +{ + x = document.body || null; + jg_ie = x && typeof x.insertAdjacentHTML != "undefined"; + jg_dom = (x && !jg_ie && + typeof x.appendChild != "undefined" && + typeof document.createRange != "undefined" && + typeof (i = document.createRange()).setStartBefore != "undefined" && + typeof i.createContextualFragment != "undefined"); + jg_ihtm = !jg_ie && !jg_dom && x && typeof x.innerHTML != "undefined"; + jg_fast = jg_ie && document.all && !window.opera; + jg_moz = jg_dom && typeof x.style.MozOpacity != "undefined"; +} + + +function pntDoc() +{ + this.wnd.document.write(jg_fast? this.htmRpc() : this.htm); + this.htm = ''; +} + + +function pntCnvDom() +{ + var x = document.createRange(); + x.setStartBefore(this.cnv); + x = x.createContextualFragment(jg_fast? this.htmRpc() : this.htm); + this.cnv.appendChild(x); + this.htm = ''; +} + + +function pntCnvIe() +{ + this.cnv.insertAdjacentHTML("beforeEnd", jg_fast? this.htmRpc() : this.htm); + this.htm = ''; +} + + +function pntCnvIhtm() +{ + this.cnv.innerHTML += this.htm; + this.htm = ''; +} + + +function pntCnv() +{ + this.htm = ''; +} + + +function mkDiv(x, y, w, h) +{ + this.htm += '
<\/div>'; +} + + +function mkDivIe(x, y, w, h) +{ + this.htm += '%%'+this.color+';'+x+';'+y+';'+w+';'+h+';'; +} + + +function mkDivPrt(x, y, w, h) +{ + this.htm += '
<\/div>'; +} + + +function mkLyr(x, y, w, h) +{ + this.htm += '<\/layer>\n'; +} + + +var regex = /%%([^;]+);([^;]+);([^;]+);([^;]+);([^;]+);/g; +function htmRpc() +{ + return this.htm.replace( + regex, + '
\n'); +} + + +function htmPrtRpc() +{ + return this.htm.replace( + regex, + '
\n'); +} + + +function mkLin(x1, y1, x2, y2) +{ + if (x1 > x2) + { + var _x2 = x2; + var _y2 = y2; + x2 = x1; + y2 = y1; + x1 = _x2; + y1 = _y2; + } + var dx = x2-x1, dy = Math.abs(y2-y1), + x = x1, y = y1, + yIncr = (y1 > y2)? -1 : 1; + + if (dx >= dy) + { + var pr = dy<<1, + pru = pr - (dx<<1), + p = pr-dx, + ox = x; + while ((dx--) > 0) + { + ++x; + if (p > 0) + { + this.mkDiv(ox, y, x-ox, 1); + y += yIncr; + p += pru; + ox = x; + } + else p += pr; + } + this.mkDiv(ox, y, x2-ox+1, 1); + } + + else + { + var pr = dx<<1, + pru = pr - (dy<<1), + p = pr-dy, + oy = y; + if (y2 <= y1) + { + while ((dy--) > 0) + { + if (p > 0) + { + this.mkDiv(x++, y, 1, oy-y+1); + y += yIncr; + p += pru; + oy = y; + } + else + { + y += yIncr; + p += pr; + } + } + this.mkDiv(x2, y2, 1, oy-y2+1); + } + else + { + while ((dy--) > 0) + { + y += yIncr; + if (p > 0) + { + this.mkDiv(x++, oy, 1, y-oy); + p += pru; + oy = y; + } + else p += pr; + } + this.mkDiv(x2, oy, 1, y2-oy+1); + } + } +} + + +function mkLin2D(x1, y1, x2, y2) +{ + if (x1 > x2) + { + var _x2 = x2; + var _y2 = y2; + x2 = x1; + y2 = y1; + x1 = _x2; + y1 = _y2; + } + var dx = x2-x1, dy = Math.abs(y2-y1), + x = x1, y = y1, + yIncr = (y1 > y2)? -1 : 1; + + var s = this.stroke; + if (dx >= dy) + { + if (s-3 > 0) + { + var _s = (s*dx*Math.sqrt(1+dy*dy/(dx*dx))-dx-(s>>1)*dy) / dx; + _s = (!(s-4)? Math.ceil(_s) : Math.round(_s)) + 1; + } + else var _s = s; + var ad = Math.ceil(s/2); + + var pr = dy<<1, + pru = pr - (dx<<1), + p = pr-dx, + ox = x; + while ((dx--) > 0) + { + ++x; + if (p > 0) + { + this.mkDiv(ox, y, x-ox+ad, _s); + y += yIncr; + p += pru; + ox = x; + } + else p += pr; + } + this.mkDiv(ox, y, x2-ox+ad+1, _s); + } + + else + { + if (s-3 > 0) + { + var _s = (s*dy*Math.sqrt(1+dx*dx/(dy*dy))-(s>>1)*dx-dy) / dy; + _s = (!(s-4)? Math.ceil(_s) : Math.round(_s)) + 1; + } + else var _s = s; + var ad = Math.round(s/2); + + var pr = dx<<1, + pru = pr - (dy<<1), + p = pr-dy, + oy = y; + if (y2 <= y1) + { + ++ad; + while ((dy--) > 0) + { + if (p > 0) + { + this.mkDiv(x++, y, _s, oy-y+ad); + y += yIncr; + p += pru; + oy = y; + } + else + { + y += yIncr; + p += pr; + } + } + this.mkDiv(x2, y2, _s, oy-y2+ad); + } + else + { + while ((dy--) > 0) + { + y += yIncr; + if (p > 0) + { + this.mkDiv(x++, oy, _s, y-oy+ad); + p += pru; + oy = y; + } + else p += pr; + } + this.mkDiv(x2, oy, _s, y2-oy+ad+1); + } + } +} + + +function mkLinDott(x1, y1, x2, y2) +{ + if (x1 > x2) + { + var _x2 = x2; + var _y2 = y2; + x2 = x1; + y2 = y1; + x1 = _x2; + y1 = _y2; + } + var dx = x2-x1, dy = Math.abs(y2-y1), + x = x1, y = y1, + yIncr = (y1 > y2)? -1 : 1, + drw = true; + if (dx >= dy) + { + var pr = dy<<1, + pru = pr - (dx<<1), + p = pr-dx; + while ((dx--) > 0) + { + if (drw) this.mkDiv(x, y, 1, 1); + drw = !drw; + if (p > 0) + { + y += yIncr; + p += pru; + } + else p += pr; + ++x; + } + if (drw) this.mkDiv(x, y, 1, 1); + } + + else + { + var pr = dx<<1, + pru = pr - (dy<<1), + p = pr-dy; + while ((dy--) > 0) + { + if (drw) this.mkDiv(x, y, 1, 1); + drw = !drw; + y += yIncr; + if (p > 0) + { + ++x; + p += pru; + } + else p += pr; + } + if (drw) this.mkDiv(x, y, 1, 1); + } +} + + +function mkOv(left, top, width, height) +{ + var a = width>>1, b = height>>1, + wod = width&1, hod = (height&1)+1, + cx = left+a, cy = top+b, + x = 0, y = b, + ox = 0, oy = b, + aa = (a*a)<<1, bb = (b*b)<<1, + st = (aa>>1)*(1-(b<<1)) + bb, + tt = (bb>>1) - aa*((b<<1)-1), + w, h; + while (y > 0) + { + if (st < 0) + { + st += bb*((x<<1)+3); + tt += (bb<<1)*(++x); + } + else if (tt < 0) + { + st += bb*((x<<1)+3) - (aa<<1)*(y-1); + tt += (bb<<1)*(++x) - aa*(((y--)<<1)-3); + w = x-ox; + h = oy-y; + if (w&2 && h&2) + { + this.mkOvQds(cx, cy, -x+2, ox+wod, -oy, oy-1+hod, 1, 1); + this.mkOvQds(cx, cy, -x+1, x-1+wod, -y-1, y+hod, 1, 1); + } + else this.mkOvQds(cx, cy, -x+1, ox+wod, -oy, oy-h+hod, w, h); + ox = x; + oy = y; + } + else + { + tt -= aa*((y<<1)-3); + st -= (aa<<1)*(--y); + } + } + this.mkDiv(cx-a, cy-oy, a-ox+1, (oy<<1)+hod); + this.mkDiv(cx+ox+wod, cy-oy, a-ox+1, (oy<<1)+hod); +} + + +function mkOv2D(left, top, width, height) +{ + var s = this.stroke; + width += s-1; + height += s-1; + var a = width>>1, b = height>>1, + wod = width&1, hod = (height&1)+1, + cx = left+a, cy = top+b, + x = 0, y = b, + aa = (a*a)<<1, bb = (b*b)<<1, + st = (aa>>1)*(1-(b<<1)) + bb, + tt = (bb>>1) - aa*((b<<1)-1); + + if (s-4 < 0 && (!(s-2) || width-51 > 0 && height-51 > 0)) + { + var ox = 0, oy = b, + w, h, + pxl, pxr, pxt, pxb, pxw; + while (y > 0) + { + if (st < 0) + { + st += bb*((x<<1)+3); + tt += (bb<<1)*(++x); + } + else if (tt < 0) + { + st += bb*((x<<1)+3) - (aa<<1)*(y-1); + tt += (bb<<1)*(++x) - aa*(((y--)<<1)-3); + w = x-ox; + h = oy-y; + + if (w-1) + { + pxw = w+1+(s&1); + h = s; + } + else if (h-1) + { + pxw = s; + h += 1+(s&1); + } + else pxw = h = s; + this.mkOvQds(cx, cy, -x+1, ox-pxw+w+wod, -oy, -h+oy+hod, pxw, h); + ox = x; + oy = y; + } + else + { + tt -= aa*((y<<1)-3); + st -= (aa<<1)*(--y); + } + } + this.mkDiv(cx-a, cy-oy, s, (oy<<1)+hod); + this.mkDiv(cx+a+wod-s+1, cy-oy, s, (oy<<1)+hod); + } + + else + { + var _a = (width-((s-1)<<1))>>1, + _b = (height-((s-1)<<1))>>1, + _x = 0, _y = _b, + _aa = (_a*_a)<<1, _bb = (_b*_b)<<1, + _st = (_aa>>1)*(1-(_b<<1)) + _bb, + _tt = (_bb>>1) - _aa*((_b<<1)-1), + + pxl = new Array(), + pxt = new Array(), + _pxb = new Array(); + pxl[0] = 0; + pxt[0] = b; + _pxb[0] = _b-1; + while (y > 0) + { + if (st < 0) + { + st += bb*((x<<1)+3); + tt += (bb<<1)*(++x); + pxl[pxl.length] = x; + pxt[pxt.length] = y; + } + else if (tt < 0) + { + st += bb*((x<<1)+3) - (aa<<1)*(y-1); + tt += (bb<<1)*(++x) - aa*(((y--)<<1)-3); + pxl[pxl.length] = x; + pxt[pxt.length] = y; + } + else + { + tt -= aa*((y<<1)-3); + st -= (aa<<1)*(--y); + } + + if (_y > 0) + { + if (_st < 0) + { + _st += _bb*((_x<<1)+3); + _tt += (_bb<<1)*(++_x); + _pxb[_pxb.length] = _y-1; + } + else if (_tt < 0) + { + _st += _bb*((_x<<1)+3) - (_aa<<1)*(_y-1); + _tt += (_bb<<1)*(++_x) - _aa*(((_y--)<<1)-3); + _pxb[_pxb.length] = _y-1; + } + else + { + _tt -= _aa*((_y<<1)-3); + _st -= (_aa<<1)*(--_y); + _pxb[_pxb.length-1]--; + } + } + } + + var ox = 0, oy = b, + _oy = _pxb[0], + l = pxl.length, + w, h; + for (var i = 0; i < l; i++) + { + if (typeof _pxb[i] != "undefined") + { + if (_pxb[i] < _oy || pxt[i] < oy) + { + x = pxl[i]; + this.mkOvQds(cx, cy, -x+1, ox+wod, -oy, _oy+hod, x-ox, oy-_oy); + ox = x; + oy = pxt[i]; + _oy = _pxb[i]; + } + } + else + { + x = pxl[i]; + this.mkDiv(cx-x+1, cy-oy, 1, (oy<<1)+hod); + this.mkDiv(cx+ox+wod, cy-oy, 1, (oy<<1)+hod); + ox = x; + oy = pxt[i]; + } + } + this.mkDiv(cx-a, cy-oy, 1, (oy<<1)+hod); + this.mkDiv(cx+ox+wod, cy-oy, 1, (oy<<1)+hod); + } +} + + +function mkOvDott(left, top, width, height) +{ + var a = width>>1, b = height>>1, + wod = width&1, hod = height&1, + cx = left+a, cy = top+b, + x = 0, y = b, + aa2 = (a*a)<<1, aa4 = aa2<<1, bb = (b*b)<<1, + st = (aa2>>1)*(1-(b<<1)) + bb, + tt = (bb>>1) - aa2*((b<<1)-1), + drw = true; + while (y > 0) + { + if (st < 0) + { + st += bb*((x<<1)+3); + tt += (bb<<1)*(++x); + } + else if (tt < 0) + { + st += bb*((x<<1)+3) - aa4*(y-1); + tt += (bb<<1)*(++x) - aa2*(((y--)<<1)-3); + } + else + { + tt -= aa2*((y<<1)-3); + st -= aa4*(--y); + } + if (drw) this.mkOvQds(cx, cy, -x, x+wod, -y, y+hod, 1, 1); + drw = !drw; + } +} + + +function mkRect(x, y, w, h) +{ + var s = this.stroke; + this.mkDiv(x, y, w, s); + this.mkDiv(x+w, y, s, h); + this.mkDiv(x, y+h, w+s, s); + this.mkDiv(x, y+s, s, h-s); +} + + +function mkRectDott(x, y, w, h) +{ + this.drawLine(x, y, x+w, y); + this.drawLine(x+w, y, x+w, y+h); + this.drawLine(x, y+h, x+w, y+h); + this.drawLine(x, y, x, y+h); +} + + +function jsgFont() +{ + this.PLAIN = 'font-weight:normal;'; + this.BOLD = 'font-weight:bold;'; + this.ITALIC = 'font-style:italic;'; + this.ITALIC_BOLD = this.ITALIC + this.BOLD; + this.BOLD_ITALIC = this.ITALIC_BOLD; +} +var Font = new jsgFont(); + + +function jsgStroke() +{ + this.DOTTED = -1; +} +var Stroke = new jsgStroke(); + + +function jsGraphics(id, wnd) +{ + this.setColor = new Function('arg', 'this.color = arg.toLowerCase();'); + + this.setStroke = function(x) + { + this.stroke = x; + if (!(x+1)) + { + this.drawLine = mkLinDott; + this.mkOv = mkOvDott; + this.drawRect = mkRectDott; + } + else if (x-1 > 0) + { + this.drawLine = mkLin2D; + this.mkOv = mkOv2D; + this.drawRect = mkRect; + } + else + { + this.drawLine = mkLin; + this.mkOv = mkOv; + this.drawRect = mkRect; + } + }; + + + this.setPrintable = function(arg) + { + this.printable = arg; + if (jg_fast) + { + this.mkDiv = mkDivIe; + this.htmRpc = arg? htmPrtRpc : htmRpc; + } + else this.mkDiv = jg_n4? mkLyr : arg? mkDivPrt : mkDiv; + }; + + + this.setFont = function(fam, sz, sty) + { + this.ftFam = fam; + this.ftSz = sz; + this.ftSty = sty || Font.PLAIN; + }; + + + this.drawPolyline = this.drawPolyLine = function(x, y, s) + { + for (var i=0 ; i>1, b = (h -= 1)>>1, + wod = (w&1)+1, hod = (h&1)+1, + cx = left+a, cy = top+b, + x = 0, y = b, + ox = 0, oy = b, + aa2 = (a*a)<<1, aa4 = aa2<<1, bb = (b*b)<<1, + st = (aa2>>1)*(1-(b<<1)) + bb, + tt = (bb>>1) - aa2*((b<<1)-1), + pxl, dw, dh; + if (w+1) while (y > 0) + { + if (st < 0) + { + st += bb*((x<<1)+3); + tt += (bb<<1)*(++x); + } + else if (tt < 0) + { + st += bb*((x<<1)+3) - aa4*(y-1); + pxl = cx-x; + dw = (x<<1)+wod; + tt += (bb<<1)*(++x) - aa2*(((y--)<<1)-3); + dh = oy-y; + this.mkDiv(pxl, cy-oy, dw, dh); + this.mkDiv(pxl, cy+oy-dh+hod, dw, dh); + ox = x; + oy = y; + } + else + { + tt -= aa2*((y<<1)-3); + st -= aa4*(--y); + } + } + this.mkDiv(cx-a, cy-oy, w+1, (oy<<1)+hod); + }; + + + +/* fillPolygon method, implemented by Matthieu Haller. +This javascript function is an adaptation of the gdImageFilledPolygon for Walter Zorn lib. +C source of GD 1.8.4 found at http://www.boutell.com/gd/ + +THANKS to Kirsten Schulz for the polygon fixes! + +The intersection finding technique of this code could be improved +by remembering the previous intertersection, and by using the slope. +That could help to adjust intersections to produce a nice +interior_extrema. */ + this.fillPolygon = function(array_x, array_y) + { + var i; + var y; + var miny, maxy; + var x1, y1; + var x2, y2; + var ind1, ind2; + var ints; + + var n = array_x.length; + + if (!n) return; + + + miny = array_y[0]; + maxy = array_y[0]; + for (i = 1; i < n; i++) + { + if (array_y[i] < miny) + miny = array_y[i]; + + if (array_y[i] > maxy) + maxy = array_y[i]; + } + for (y = miny; y <= maxy; y++) + { + var polyInts = new Array(); + ints = 0; + for (i = 0; i < n; i++) + { + if (!i) + { + ind1 = n-1; + ind2 = 0; + } + else + { + ind1 = i-1; + ind2 = i; + } + y1 = array_y[ind1]; + y2 = array_y[ind2]; + if (y1 < y2) + { + x1 = array_x[ind1]; + x2 = array_x[ind2]; + } + else if (y1 > y2) + { + y2 = array_y[ind1]; + y1 = array_y[ind2]; + x2 = array_x[ind1]; + x1 = array_x[ind2]; + } + else continue; + + // modified 11. 2. 2004 Walter Zorn + if ((y >= y1) && (y < y2)) + polyInts[ints++] = Math.round((y-y1) * (x2-x1) / (y2-y1) + x1); + + else if ((y == maxy) && (y > y1) && (y <= y2)) + polyInts[ints++] = Math.round((y-y1) * (x2-x1) / (y2-y1) + x1); + } + polyInts.sort(integer_compare); + + for (i = 0; i < ints; i+=2) + { + w = polyInts[i+1]-polyInts[i] + this.mkDiv(polyInts[i], y, polyInts[i+1]-polyInts[i]+1, 1); + } + } + }; + + + this.drawString = function(txt, x, y) + { + this.htm += '
'+ + txt + + '<\/div>'; + } + + + this.drawImage = function(imgSrc, x, y, w, h) + { + this.htm += '
'+ + ''+ + '<\/div>'; + } + + + this.clear = function() + { + this.htm = ""; + if (this.cnv) this.cnv.innerHTML = this.defhtm; + }; + + + this.mkOvQds = function(cx, cy, xl, xr, yt, yb, w, h) + { + this.mkDiv(xr+cx, yt+cy, w, h); + this.mkDiv(xr+cx, yb+cy, w, h); + this.mkDiv(xl+cx, yb+cy, w, h); + this.mkDiv(xl+cx, yt+cy, w, h); + }; + + this.setStroke(1); + this.setFont('verdana,geneva,helvetica,sans-serif', String.fromCharCode(0x31, 0x32, 0x70, 0x78), Font.PLAIN); + this.color = '#000000'; + this.htm = ''; + this.wnd = wnd || window; + + if (!(jg_ie || jg_dom || jg_ihtm)) chkDHTM(); + if (typeof id != 'string' || !id) this.paint = pntDoc; + else + { + this.cnv = document.all? (this.wnd.document.all[id] || null) + : document.getElementById? (this.wnd.document.getElementById(id) || null) + : null; + this.defhtm = (this.cnv && this.cnv.innerHTML)? this.cnv.innerHTML : ''; + this.paint = jg_dom? pntCnvDom : jg_ie? pntCnvIe : jg_ihtm? pntCnvIhtm : pntCnv; + } + + this.setPrintable(false); +} + + + +function integer_compare(x,y) +{ + return (x < y) ? -1 : ((x > y)*1); +} + diff --git a/build/cite/wms11/citewms-1.1/mbdemos/lib/widget/SaveModel.js b/build/cite/wms11/citewms-1.1/mbdemos/lib/widget/SaveModel.js index 7f960a87c13..4eb9ebbf8cd 100644 --- a/build/cite/wms11/citewms-1.1/mbdemos/lib/widget/SaveModel.js +++ b/build/cite/wms11/citewms-1.1/mbdemos/lib/widget/SaveModel.js @@ -1,44 +1,44 @@ -/* -Author: Mike Adair mike.adairATccrs.nrcan.gc.ca -License: GPL as per: http://www.gnu.org/copyleft/gpl.html - -$Id: SaveModel.js,v 1.8 2004/11/26 15:55:20 madair1 Exp $ -*/ - -// Ensure this object's dependancies are loaded. -mapbuilder.loadScript(baseDir+"/widget/WidgetBase.js"); - -/** - * Widget which will display some anchor tags for accessing model URLs. - * TBD: which is the prefered method to use here, - * - * @constructor - * @base WidgetBase - * @param widgetNode This widget's object node from the configuration document. - * @param model The model that this widget is a view of. - */ - -function SaveModel(widgetNode, model) { - var base = new WidgetBase(this, widgetNode, model); - - /** - * Initialise params. - * @param objRef Pointer to this SaveModel object. - */ - this.init = function(objRef) { - objRef.stylesheet.setParameter("modelUrl", objRef.model.url); - } - this.model.addListener("loadModel", this.init, this); - - /** - * a listenet to set the saved model URL as the href attribute in an anchor link - * @param objRef Pointer to this SaveModel object. - */ - this.saveLink = function(objRef, fileUrl) { - var modelAnchor = document.getElementById(objRef.model.id+"."+objRef.id+".modelUrl"); - modelAnchor.href = fileUrl; - } - this.model.addListener("modelSaved", this.saveLink, this); - -} - +/* +Author: Mike Adair mike.adairATccrs.nrcan.gc.ca +License: GPL as per: http://www.gnu.org/copyleft/gpl.html + +$Id: SaveModel.js,v 1.8 2004/11/26 15:55:20 madair1 Exp $ +*/ + +// Ensure this object's dependancies are loaded. +mapbuilder.loadScript(baseDir+"/widget/WidgetBase.js"); + +/** + * Widget which will display some anchor tags for accessing model URLs. + * TBD: which is the prefered method to use here, + * + * @constructor + * @base WidgetBase + * @param widgetNode This widget's object node from the configuration document. + * @param model The model that this widget is a view of. + */ + +function SaveModel(widgetNode, model) { + var base = new WidgetBase(this, widgetNode, model); + + /** + * Initialise params. + * @param objRef Pointer to this SaveModel object. + */ + this.init = function(objRef) { + objRef.stylesheet.setParameter("modelUrl", objRef.model.url); + } + this.model.addListener("loadModel", this.init, this); + + /** + * a listenet to set the saved model URL as the href attribute in an anchor link + * @param objRef Pointer to this SaveModel object. + */ + this.saveLink = function(objRef, fileUrl) { + var modelAnchor = document.getElementById(objRef.model.id+"."+objRef.id+".modelUrl"); + modelAnchor.href = fileUrl; + } + this.model.addListener("modelSaved", this.saveLink, this); + +} + diff --git a/build/cite/wms11/citewms-1.1/mbdemos/lib/widget/wms/WmsCapabilities.js b/build/cite/wms11/citewms-1.1/mbdemos/lib/widget/wms/WmsCapabilities.js index 8125bc312b9..36006143746 100644 --- a/build/cite/wms11/citewms-1.1/mbdemos/lib/widget/wms/WmsCapabilities.js +++ b/build/cite/wms11/citewms-1.1/mbdemos/lib/widget/wms/WmsCapabilities.js @@ -1,27 +1,27 @@ -/** - * Build a Web Map Context (WMC) from a Web Map Server getCapabilities response. - * @constructor - * @param url TBD Comment me. - * @param node TBD Comment me. - */ -function WMS(url, node) { - this.url = url; - this.node=node; - this.wms = Sarissa.getDomDocument(); - this.wms.async = false; - // the following two lines are needed for IE - this.wms.setProperty("SelectionNamespaces", "xmlns:xsl='http://www.w3.org/1999/XSL/Transform'"); - this.wms.setProperty("SelectionLanguage", "XPath"); - - url = proxyScript + "?onlineresource=" + escape(url); - this.wms.load(url); - this.wmsCapabilities2Context=new XslProcessor(baseDir + "/widget/wms/WMSCapabilities2Context.xsl"); - - /** - * Request a new URL of a WMS document. - */ - this.paint= function() { - var s = this.wmsCapabilities2Context.transformNode(this.wms); - prompt(s); - } -} +/** + * Build a Web Map Context (WMC) from a Web Map Server getCapabilities response. + * @constructor + * @param url TBD Comment me. + * @param node TBD Comment me. + */ +function WMS(url, node) { + this.url = url; + this.node=node; + this.wms = Sarissa.getDomDocument(); + this.wms.async = false; + // the following two lines are needed for IE + this.wms.setProperty("SelectionNamespaces", "xmlns:xsl='http://www.w3.org/1999/XSL/Transform'"); + this.wms.setProperty("SelectionLanguage", "XPath"); + + url = proxyScript + "?onlineresource=" + escape(url); + this.wms.load(url); + this.wmsCapabilities2Context=new XslProcessor(baseDir + "/widget/wms/WMSCapabilities2Context.xsl"); + + /** + * Request a new URL of a WMS document. + */ + this.paint= function() { + var s = this.wmsCapabilities2Context.transformNode(this.wms); + prompt(s); + } +} diff --git a/build/cite/wms13/citewms-1.3/styles/BasicPolygon.sld b/build/cite/wms13/citewms-1.3/styles/BasicPolygon.sld index 56471af32b4..08c0cde52b0 100644 --- a/build/cite/wms13/citewms-1.3/styles/BasicPolygon.sld +++ b/build/cite/wms13/citewms-1.3/styles/BasicPolygon.sld @@ -1,24 +1,24 @@ - - - - Blue - - Blue - Blue Polygon - A filled polygon with outline of 2 pixel width - - name - - - - #0000C0 - - - 2 - - - - - - + + + + Blue + + Blue + Blue Polygon + A filled polygon with outline of 2 pixel width + + name + + + + #0000C0 + + + 2 + + + + + + \ No newline at end of file diff --git a/build/cite/wms13/citewms-1.3/styles/Forests.sld b/build/cite/wms13/citewms-1.3/styles/Forests.sld index d06531281a0..8812b39613a 100644 --- a/build/cite/wms13/citewms-1.3/styles/Forests.sld +++ b/build/cite/wms13/citewms-1.3/styles/Forests.sld @@ -1,67 +1,67 @@ - - - - Default Styler - PNG Filled Polygon - - - Feature - - name - External graphic is used as a pattern to fill polygon - PNG Filled Polygon - - - - - - 30 - - - 1.0 - - - 0.5 - - - image/png - - - - - - #808080 - - - 1.0 - - - - - #000000 - - - butt - - - miter - - - 1 - - - 1 - - - 0 - - - - - - - + + + + Default Styler + PNG Filled Polygon + + + Feature + + name + External graphic is used as a pattern to fill polygon + PNG Filled Polygon + + + + + + 30 + + + 1.0 + + + 0.5 + + + image/png + + + + + + #808080 + + + 1.0 + + + + + #000000 + + + butt + + + miter + + + 1 + + + 1 + + + 0 + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/Autos.xml b/build/cite/wms13/citewms-1.3/www/Autos.xml index 1f4f0b769bd..68d415b1d2b 100644 --- a/build/cite/wms13/citewms-1.3/www/Autos.xml +++ b/build/cite/wms13/citewms-1.3/www/Autos.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - point - - - - - - - - - - - <gco:CharacterString>CITE Autos</gco:CharacterString> - - - - - 2009-01-07 - - - creation - - - - - - - This is the cite:Autos layer from the test dataset for the TIME dimension tests in the CITE WMS 1.3.0 test suite. It contains points representing automobile locations at different points in time. - - - eng - - - location - - - - - - - -0.00342 - - - 0.0029 - - - -0.0022 - - - 0.0022 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + point + + + + + + + + + + + <gco:CharacterString>CITE Autos</gco:CharacterString> + + + + + 2009-01-07 + + + creation + + + + + + + This is the cite:Autos layer from the test dataset for the TIME dimension tests in the CITE WMS 1.3.0 test suite. It contains points representing automobile locations at different points in time. + + + eng + + + location + + + + + + + -0.00342 + + + 0.0029 + + + -0.0022 + + + 0.0022 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/BasicPolygons.xml b/build/cite/wms13/citewms-1.3/www/BasicPolygons.xml index 105e44f9ea8..b09ed5c851b 100644 --- a/build/cite/wms13/citewms-1.3/www/BasicPolygons.xml +++ b/build/cite/wms13/citewms-1.3/www/BasicPolygons.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - surface - - - - - - - - - - - <gco:CharacterString>CITE BasicPolygons</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:BasicPolygons layer from the test dataset for the CITE WMS 1.3.0 test suite. Contains a diamond and two overlapping squares. - - - eng - - - boundaries - - - - - - - -2.0 - - - 2.0 - - - -1.0 - - - 6.0 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + surface + + + + + + + + + + + <gco:CharacterString>CITE BasicPolygons</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:BasicPolygons layer from the test dataset for the CITE WMS 1.3.0 test suite. Contains a diamond and two overlapping squares. + + + eng + + + boundaries + + + + + + + -2.0 + + + 2.0 + + + -1.0 + + + 6.0 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/Bridges.xml b/build/cite/wms13/citewms-1.3/www/Bridges.xml index 9ac36f49bad..6536175d735 100644 --- a/build/cite/wms13/citewms-1.3/www/Bridges.xml +++ b/build/cite/wms13/citewms-1.3/www/Bridges.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - point - - - - - - - - - - - <gco:CharacterString>CITE Bridges</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:Bridges layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains Cam Bridge. - - - eng - - - transportation - - - - - - - 0.0001 - - - 0.0003 - - - 0.0006 - - - 0.0008 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + point + + + + + + + + + + + <gco:CharacterString>CITE Bridges</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:Bridges layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains Cam Bridge. + + + eng + + + transportation + + + + + + + 0.0001 + + + 0.0003 + + + 0.0006 + + + 0.0008 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/BuildingCenters.xml b/build/cite/wms13/citewms-1.3/www/BuildingCenters.xml index 3c7acd9dd9c..e8305a81185 100644 --- a/build/cite/wms13/citewms-1.3/www/BuildingCenters.xml +++ b/build/cite/wms13/citewms-1.3/www/BuildingCenters.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - point - - - - - - - - - - - <gco:CharacterString>CITE BuildingCenters</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:BuildingCenters layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains the center points for the two buildings along Main Street. - - - eng - - - location - - - - - - - 0.0008 - - - 0.0024 - - - 0.0005 - - - 0.0010 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + point + + + + + + + + + + + <gco:CharacterString>CITE BuildingCenters</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:BuildingCenters layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains the center points for the two buildings along Main Street. + + + eng + + + location + + + + + + + 0.0008 + + + 0.0024 + + + 0.0005 + + + 0.0010 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/Buildings.xml b/build/cite/wms13/citewms-1.3/www/Buildings.xml index 36b4da4336d..2112ca8c5a7 100644 --- a/build/cite/wms13/citewms-1.3/www/Buildings.xml +++ b/build/cite/wms13/citewms-1.3/www/Buildings.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - surface - - - - - - - - - - - <gco:CharacterString>CITE Buildings</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:Buildings layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains the two buildings along Main Street. - - - eng - - - structure - - - - - - - 0.0008 - - - 0.0024 - - - 0.0005 - - - 0.0010 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + surface + + + + + + + + + + + <gco:CharacterString>CITE Buildings</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:Buildings layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains the two buildings along Main Street. + + + eng + + + structure + + + + + + + 0.0008 + + + 0.0024 + + + 0.0005 + + + 0.0010 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/DividedRoutes.xml b/build/cite/wms13/citewms-1.3/www/DividedRoutes.xml index 3f46e4e3500..9c12c0f646c 100644 --- a/build/cite/wms13/citewms-1.3/www/DividedRoutes.xml +++ b/build/cite/wms13/citewms-1.3/www/DividedRoutes.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - curve - - - - - - - - - - - <gco:CharacterString>CITE DividedRoutes</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:DividedRoutes layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains both lanes of Route 75. - - - eng - - - transportation - - - - - - - -0.0034 - - - -0.0026 - - - -0.0024 - - - 0.0024 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + curve + + + + + + + + + + + <gco:CharacterString>CITE DividedRoutes</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:DividedRoutes layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains both lanes of Route 75. + + + eng + + + transportation + + + + + + + -0.0034 + + + -0.0026 + + + -0.0024 + + + 0.0024 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/Forests.xml b/build/cite/wms13/citewms-1.3/www/Forests.xml index 36875254385..48c983f1d8a 100644 --- a/build/cite/wms13/citewms-1.3/www/Forests.xml +++ b/build/cite/wms13/citewms-1.3/www/Forests.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - surface - - - - - - - - - - - <gco:CharacterString>CITE Forests</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:Forests layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains the State Forest polygon. - - - eng - - - biota - - - - - - - -0.0014 - - - 0.0042 - - - -0.0024 - - - 0.0018 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + surface + + + + + + + + + + + <gco:CharacterString>CITE Forests</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:Forests layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains the State Forest polygon. + + + eng + + + biota + + + + + + + -0.0014 + + + 0.0042 + + + -0.0024 + + + 0.0018 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/Lakes.xml b/build/cite/wms13/citewms-1.3/www/Lakes.xml index f5a7c1fc2a3..49cf9c13ffe 100644 --- a/build/cite/wms13/citewms-1.3/www/Lakes.xml +++ b/build/cite/wms13/citewms-1.3/www/Lakes.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - surface - - - - - - - - - - - <gco:CharacterString>CITE Lakes</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:Lakes layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains Blue Lake. - - - eng - - - inlandWaters - - - - - - - 0.0006 - - - 0.0032 - - - -0.0018 - - - -0.0002 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + surface + + + + + + + + + + + <gco:CharacterString>CITE Lakes</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:Lakes layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains Blue Lake. + + + eng + + + inlandWaters + + + + + + + 0.0006 + + + 0.0032 + + + -0.0018 + + + -0.0002 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/LakesWithElevation.xml b/build/cite/wms13/citewms-1.3/www/LakesWithElevation.xml index d69b8ef3f4b..de10fedc043 100644 --- a/build/cite/wms13/citewms-1.3/www/LakesWithElevation.xml +++ b/build/cite/wms13/citewms-1.3/www/LakesWithElevation.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - surface - - - - - - - - - - - <gco:CharacterString>CITE Lakes</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:Lakes layer from the test dataset for the vector elevation tests in the CITE WMS 1.3.0 test suite. It contains contains polygons representing the edge of Blue Lake at serveral depths. - - - eng - - - inlandWaters - - - - - - - 0.0006 - - - 0.0032 - - - -0.0018 - - - -0.0002 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + surface + + + + + + + + + + + <gco:CharacterString>CITE Lakes</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:Lakes layer from the test dataset for the vector elevation tests in the CITE WMS 1.3.0 test suite. It contains contains polygons representing the edge of Blue Lake at serveral depths. + + + eng + + + inlandWaters + + + + + + + 0.0006 + + + 0.0032 + + + -0.0018 + + + -0.0002 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/MapNeatline.xml b/build/cite/wms13/citewms-1.3/www/MapNeatline.xml index 3a23bf59e00..8a7d56a75ad 100644 --- a/build/cite/wms13/citewms-1.3/www/MapNeatline.xml +++ b/build/cite/wms13/citewms-1.3/www/MapNeatline.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - curve - - - - - - - - - - - <gco:CharacterString>CITE MapNeatline</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:MapNeatline layer from the test dataset for the CITE WMS 1.3.0 tests. It contains the border surrounding the Blue Lake vicinity. - - - eng - - - boundaries - - - - - - - -0.0042 - - - 0.0042 - - - -0.0024 - - - 0.0024 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + curve + + + + + + + + + + + <gco:CharacterString>CITE MapNeatline</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:MapNeatline layer from the test dataset for the CITE WMS 1.3.0 tests. It contains the border surrounding the Blue Lake vicinity. + + + eng + + + boundaries + + + + + + + -0.0042 + + + 0.0042 + + + -0.0024 + + + 0.0024 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/NamedPlaces.xml b/build/cite/wms13/citewms-1.3/www/NamedPlaces.xml index 9b5599004a7..11fb5e53164 100644 --- a/build/cite/wms13/citewms-1.3/www/NamedPlaces.xml +++ b/build/cite/wms13/citewms-1.3/www/NamedPlaces.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - surface - - - - - - - - - - - <gco:CharacterString>CITE NamedPlaces</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:NamedPlaces layer from the test dataset for the CITE WMS 1.3.0 tests. It contains Ashton and Goose Island. - - - eng - - - boundaries - - - - - - - 0.0014 - - - 0.0042 - - - -0.0011 - - - 0.0024 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + surface + + + + + + + + + + + <gco:CharacterString>CITE NamedPlaces</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:NamedPlaces layer from the test dataset for the CITE WMS 1.3.0 tests. It contains Ashton and Goose Island. + + + eng + + + boundaries + + + + + + + 0.0014 + + + 0.0042 + + + -0.0011 + + + 0.0024 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/Ponds.xml b/build/cite/wms13/citewms-1.3/www/Ponds.xml index e1450c2130e..ef5f50ba400 100644 --- a/build/cite/wms13/citewms-1.3/www/Ponds.xml +++ b/build/cite/wms13/citewms-1.3/www/Ponds.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - surface - - - - - - - - - - - <gco:CharacterString>CITE Ponds</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:Ponds layer from the test dataset for the CITE WMS 1.3.0 tests. It contains both pools of Stock Pond. - - - eng - - - inlandWaters - - - - - - - -0.0020 - - - -0.0014 - - - 0.0016 - - - 0.0020 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + surface + + + + + + + + + + + <gco:CharacterString>CITE Ponds</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:Ponds layer from the test dataset for the CITE WMS 1.3.0 tests. It contains both pools of Stock Pond. + + + eng + + + inlandWaters + + + + + + + -0.0020 + + + -0.0014 + + + 0.0016 + + + 0.0020 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/RoadSegments.xml b/build/cite/wms13/citewms-1.3/www/RoadSegments.xml index 9f87da6387f..97370fafeb9 100644 --- a/build/cite/wms13/citewms-1.3/www/RoadSegments.xml +++ b/build/cite/wms13/citewms-1.3/www/RoadSegments.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - curve - - - - - - - - - - - <gco:CharacterString>CITE RoadSegments</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:RoadSegments layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains all the sections of Route 5, Main Street, and the dirt road. - - - eng - - - transportation - - - - - - - -0.0042 - - - 0.0042 - - - -0.0024 - - - 0.0024 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + curve + + + + + + + + + + + <gco:CharacterString>CITE RoadSegments</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:RoadSegments layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains all the sections of Route 5, Main Street, and the dirt road. + + + eng + + + transportation + + + + + + + -0.0042 + + + 0.0042 + + + -0.0024 + + + 0.0024 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/Streams.xml b/build/cite/wms13/citewms-1.3/www/Streams.xml index fedeb998d8c..b87de215c23 100644 --- a/build/cite/wms13/citewms-1.3/www/Streams.xml +++ b/build/cite/wms13/citewms-1.3/www/Streams.xml @@ -1,87 +1,87 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - - - curve - - - - - - - - - - - <gco:CharacterString>CITE Streams</gco:CharacterString> - - - - - 2009-01-07 - - - revision - - - - - - - This is the cite:Streams layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains Cam Stream and the unnamed stream south of Blue Lake. - - - eng - - - inlandWaters - - - - - - - -0.0004 - - - 0.0036 - - - -0.0024 - - - 0.0024 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + + + curve + + + + + + + + + + + <gco:CharacterString>CITE Streams</gco:CharacterString> + + + + + 2009-01-07 + + + revision + + + + + + + This is the cite:Streams layer from the test dataset for the CITE WMS 1.3.0 test suite. It contains Cam Stream and the unnamed stream south of Blue Lake. + + + eng + + + inlandWaters + + + + + + + -0.0004 + + + 0.0036 + + + -0.0024 + + + 0.0024 + + + + + + + + + diff --git a/build/cite/wms13/citewms-1.3/www/Terrain.xml b/build/cite/wms13/citewms-1.3/www/Terrain.xml index b513734cc4d..99cb48d640f 100644 --- a/build/cite/wms13/citewms-1.3/www/Terrain.xml +++ b/build/cite/wms13/citewms-1.3/www/Terrain.xml @@ -1,118 +1,118 @@ - - - - - - Open Geospatial Consortium - - - originator - - - - - 2009-03-17 - - - - - 1 - - - - - vertical - - - 1 - - - 1 - - - - - area - - - false - - - false - - - - -0.5 -0.5 - - - - - 0.49833333333333333333333333333333 0.49833333333333333333333333333333 - - - - lowerLeft - - - - - - - - - <gco:CharacterString>CITE Terrain</gco:CharacterString> - - - - - 2009-01-07 - - - creation - - - - - - - This is the cite:Terrain layer from the test dataset for the raster elevation tests in the CITE WMS 1.3.0 test suite. It has values that range from 0 to 425m that include a "high spot" with values greater than 325m and a "low spot" with values less than 200m. The remainder of the dataset is filled with values between 200m and 325m, including a few values that are exactly 250m. - - - eng - - - elevation - - - - - - - -0.5 - - - 0.5 - - - -0.5 - - - 0.5 - - - - - - - - - + + + + + + Open Geospatial Consortium + + + originator + + + + + 2009-03-17 + + + + + 1 + + + + + vertical + + + 1 + + + 1 + + + + + area + + + false + + + false + + + + -0.5 -0.5 + + + + + 0.49833333333333333333333333333333 0.49833333333333333333333333333333 + + + + lowerLeft + + + + + + + + + <gco:CharacterString>CITE Terrain</gco:CharacterString> + + + + + 2009-01-07 + + + creation + + + + + + + This is the cite:Terrain layer from the test dataset for the raster elevation tests in the CITE WMS 1.3.0 test suite. It has values that range from 0 to 425m that include a "high spot" with values greater than 325m and a "low spot" with values less than 200m. The remainder of the dataset is filled with values between 200m and 325m, including a few values that are exactly 250m. + + + eng + + + elevation + + + + + + + -0.5 + + + 0.5 + + + -0.5 + + + 0.5 + + + + + + + + + diff --git a/data/citensg-1.0/styles/raster_with_scales.sld b/data/citensg-1.0/styles/raster_with_scales.sld index a61e195e97b..73580e331fa 100644 --- a/data/citensg-1.0/styles/raster_with_scales.sld +++ b/data/citensg-1.0/styles/raster_with_scales.sld @@ -1,22 +1,22 @@ - - - - raster_layer - - raster - Opaque Raster - A sample style for rasters visible between 300000 and 1000000 map scale - - Feature - - 300000 - 1000000 - - 1.0 - - - - - + + + + raster_layer + + raster + Opaque Raster + A sample style for rasters visible between 300000 and 1000000 map scale + + Feature + + 300000 + 1000000 + + 1.0 + + + + + \ No newline at end of file diff --git a/data/citensg-1.0/workspaces/cite_wmts_10/styles/Default_style.sld b/data/citensg-1.0/workspaces/cite_wmts_10/styles/Default_style.sld index 7c2c230e984..43e64353456 100644 --- a/data/citensg-1.0/workspaces/cite_wmts_10/styles/Default_style.sld +++ b/data/citensg-1.0/workspaces/cite_wmts_10/styles/Default_style.sld @@ -1,20 +1,20 @@ - - - - Default_style - - Default_style - A boring default style - A sample style for rasters - - Feature - - - 1.0 - - - - - + + + + Default_style + + Default_style + A boring default style + A sample style for rasters + + Feature + + + 1.0 + + + + + \ No newline at end of file diff --git a/data/release/coverages/arc_sample/precip30min.prj b/data/release/coverages/arc_sample/precip30min.prj index 2051f9e4e1a..41844c0a090 100644 --- a/data/release/coverages/arc_sample/precip30min.prj +++ b/data/release/coverages/arc_sample/precip30min.prj @@ -1,9 +1,9 @@ - GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], + GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/img_sample/usa.prj b/data/release/coverages/img_sample/usa.prj index 9612216f7fa..3d2d4d2b836 100644 --- a/data/release/coverages/img_sample/usa.prj +++ b/data/release/coverages/img_sample/usa.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_0.pgw b/data/release/coverages/mosaic_sample/global_mosaic_0.pgw index 9c17b085d94..91299c7c910 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_0.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_0.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -6.375141924963005 -38.491372862272705 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +6.375141924963005 +38.491372862272705 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_0.prj b/data/release/coverages/mosaic_sample/global_mosaic_0.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_0.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_0.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_1.pgw b/data/release/coverages/mosaic_sample/global_mosaic_1.pgw index 1b856af4dc5..48c4bb19a00 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_1.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_1.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -9.271843573824427 -38.491372862272705 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +9.271843573824427 +38.491372862272705 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_1.prj b/data/release/coverages/mosaic_sample/global_mosaic_1.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_1.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_1.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_10.pgw b/data/release/coverages/mosaic_sample/global_mosaic_10.pgw index 6f402ef4ea3..86d39348241 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_10.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_10.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -6.375141924963005 -42.530970923550704 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +6.375141924963005 +42.530970923550704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_10.prj b/data/release/coverages/mosaic_sample/global_mosaic_10.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_10.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_10.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_11.pgw b/data/release/coverages/mosaic_sample/global_mosaic_11.pgw index 49570a2fa4e..d0cb1c6d0be 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_11.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_11.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -9.271843573824427 -42.530970923550704 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +9.271843573824427 +42.530970923550704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_11.prj b/data/release/coverages/mosaic_sample/global_mosaic_11.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_11.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_11.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_12.pgw b/data/release/coverages/mosaic_sample/global_mosaic_12.pgw index dbaa7ba2ce5..66e4e418036 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_12.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_12.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -12.168545222685848 -42.530970923550704 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +12.168545222685848 +42.530970923550704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_12.prj b/data/release/coverages/mosaic_sample/global_mosaic_12.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_12.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_12.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_13.pgw b/data/release/coverages/mosaic_sample/global_mosaic_13.pgw index 5ae587d3899..a6008d0f10b 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_13.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_13.pgw @@ -1,6 +1,6 @@ -0.0579340329772284 -0.0 -0.0 --0.04039598061277999 -15.06524687154727 -42.530970923550704 +0.0579340329772284 +0.0 +0.0 +-0.04039598061277999 +15.06524687154727 +42.530970923550704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_13.prj b/data/release/coverages/mosaic_sample/global_mosaic_13.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_13.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_13.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_14.pgw b/data/release/coverages/mosaic_sample/global_mosaic_14.pgw index a2ead6af5fc..40b265e573e 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_14.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_14.pgw @@ -1,6 +1,6 @@ -0.05793403297722847 -0.0 -0.0 --0.04039598061277999 -17.96194852040869 -42.530970923550704 +0.05793403297722847 +0.0 +0.0 +-0.04039598061277999 +17.96194852040869 +42.530970923550704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_14.prj b/data/release/coverages/mosaic_sample/global_mosaic_14.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_14.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_14.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_15.pgw b/data/release/coverages/mosaic_sample/global_mosaic_15.pgw index 19ed00a97b9..451d2776769 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_15.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_15.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -6.375141924963005 -44.550769954189704 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +6.375141924963005 +44.550769954189704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_15.prj b/data/release/coverages/mosaic_sample/global_mosaic_15.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_15.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_15.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_16.pgw b/data/release/coverages/mosaic_sample/global_mosaic_16.pgw index bcf3f5e7f3a..eadd170f15d 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_16.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_16.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -9.271843573824427 -44.550769954189704 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +9.271843573824427 +44.550769954189704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_16.prj b/data/release/coverages/mosaic_sample/global_mosaic_16.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_16.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_16.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_17.pgw b/data/release/coverages/mosaic_sample/global_mosaic_17.pgw index 6e5b27ebbc3..4b6005c27de 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_17.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_17.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -12.168545222685848 -44.550769954189704 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +12.168545222685848 +44.550769954189704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_17.prj b/data/release/coverages/mosaic_sample/global_mosaic_17.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_17.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_17.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_18.pgw b/data/release/coverages/mosaic_sample/global_mosaic_18.pgw index 8bb26ac6a41..ee91f085bdd 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_18.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_18.pgw @@ -1,6 +1,6 @@ -0.0579340329772284 -0.0 -0.0 --0.04039598061277999 -15.06524687154727 -44.550769954189704 +0.0579340329772284 +0.0 +0.0 +-0.04039598061277999 +15.06524687154727 +44.550769954189704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_18.prj b/data/release/coverages/mosaic_sample/global_mosaic_18.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_18.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_18.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_19.pgw b/data/release/coverages/mosaic_sample/global_mosaic_19.pgw index 61f8ed61c88..febce4ea548 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_19.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_19.pgw @@ -1,6 +1,6 @@ -0.05793403297722847 -0.0 -0.0 --0.04039598061277999 -17.96194852040869 -44.550769954189704 +0.05793403297722847 +0.0 +0.0 +-0.04039598061277999 +17.96194852040869 +44.550769954189704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_19.prj b/data/release/coverages/mosaic_sample/global_mosaic_19.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_19.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_19.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_2.pgw b/data/release/coverages/mosaic_sample/global_mosaic_2.pgw index 34b05a51a52..3da5eae95a1 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_2.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_2.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -12.168545222685848 -38.491372862272705 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +12.168545222685848 +38.491372862272705 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_2.prj b/data/release/coverages/mosaic_sample/global_mosaic_2.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_2.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_2.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_20.pgw b/data/release/coverages/mosaic_sample/global_mosaic_20.pgw index 5ab5e404b06..bbf96375cfa 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_20.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_20.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -6.375141924963005 -46.570568984828704 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +6.375141924963005 +46.570568984828704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_20.prj b/data/release/coverages/mosaic_sample/global_mosaic_20.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_20.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_20.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_21.pgw b/data/release/coverages/mosaic_sample/global_mosaic_21.pgw index b98048e2501..377d3a18c33 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_21.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_21.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -9.271843573824427 -46.570568984828704 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +9.271843573824427 +46.570568984828704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_21.prj b/data/release/coverages/mosaic_sample/global_mosaic_21.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_21.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_21.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_22.pgw b/data/release/coverages/mosaic_sample/global_mosaic_22.pgw index a9e22e22a53..5d3847a103b 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_22.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_22.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -12.168545222685848 -46.570568984828704 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +12.168545222685848 +46.570568984828704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_22.prj b/data/release/coverages/mosaic_sample/global_mosaic_22.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_22.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_22.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_23.pgw b/data/release/coverages/mosaic_sample/global_mosaic_23.pgw index f8050467bdb..de6a430b7a4 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_23.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_23.pgw @@ -1,6 +1,6 @@ -0.0579340329772284 -0.0 -0.0 --0.04039598061277999 -15.06524687154727 -46.570568984828704 +0.0579340329772284 +0.0 +0.0 +-0.04039598061277999 +15.06524687154727 +46.570568984828704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_23.prj b/data/release/coverages/mosaic_sample/global_mosaic_23.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_23.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_23.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_24.pgw b/data/release/coverages/mosaic_sample/global_mosaic_24.pgw index 9e94502203b..8a1684e78ee 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_24.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_24.pgw @@ -1,6 +1,6 @@ -0.05793403297722847 -0.0 -0.0 --0.04039598061277999 -17.96194852040869 -46.570568984828704 +0.05793403297722847 +0.0 +0.0 +-0.04039598061277999 +17.96194852040869 +46.570568984828704 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_24.prj b/data/release/coverages/mosaic_sample/global_mosaic_24.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_24.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_24.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_3.pgw b/data/release/coverages/mosaic_sample/global_mosaic_3.pgw index 0a56cb45cab..c4e3bafa41b 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_3.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_3.pgw @@ -1,6 +1,6 @@ -0.0579340329772284 -0.0 -0.0 --0.04039598061277999 -15.06524687154727 -38.491372862272705 +0.0579340329772284 +0.0 +0.0 +-0.04039598061277999 +15.06524687154727 +38.491372862272705 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_3.prj b/data/release/coverages/mosaic_sample/global_mosaic_3.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_3.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_3.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_4.pgw b/data/release/coverages/mosaic_sample/global_mosaic_4.pgw index ec6a6a854fa..47fffc86cec 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_4.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_4.pgw @@ -1,6 +1,6 @@ -0.05793403297722847 -0.0 -0.0 --0.04039598061277999 -17.96194852040869 -38.491372862272705 +0.05793403297722847 +0.0 +0.0 +-0.04039598061277999 +17.96194852040869 +38.491372862272705 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_4.prj b/data/release/coverages/mosaic_sample/global_mosaic_4.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_4.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_4.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_5.pgw b/data/release/coverages/mosaic_sample/global_mosaic_5.pgw index 16516b5338f..7444b35b873 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_5.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_5.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -6.375141924963005 -40.511171892911705 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +6.375141924963005 +40.511171892911705 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_5.prj b/data/release/coverages/mosaic_sample/global_mosaic_5.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_5.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_5.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_6.pgw b/data/release/coverages/mosaic_sample/global_mosaic_6.pgw index 48f082649a8..018545b41fc 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_6.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_6.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -9.271843573824427 -40.511171892911705 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +9.271843573824427 +40.511171892911705 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_6.prj b/data/release/coverages/mosaic_sample/global_mosaic_6.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_6.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_6.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_7.pgw b/data/release/coverages/mosaic_sample/global_mosaic_7.pgw index dfcdf8de663..9b70a4fdd16 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_7.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_7.pgw @@ -1,6 +1,6 @@ -0.057934032977228433 -0.0 -0.0 --0.04039598061277999 -12.168545222685848 -40.511171892911705 +0.057934032977228433 +0.0 +0.0 +-0.04039598061277999 +12.168545222685848 +40.511171892911705 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_7.prj b/data/release/coverages/mosaic_sample/global_mosaic_7.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_7.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_7.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_8.pgw b/data/release/coverages/mosaic_sample/global_mosaic_8.pgw index bbd1b45809e..b50b21c14b3 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_8.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_8.pgw @@ -1,6 +1,6 @@ -0.0579340329772284 -0.0 -0.0 --0.04039598061277999 -15.06524687154727 -40.511171892911705 +0.0579340329772284 +0.0 +0.0 +-0.04039598061277999 +15.06524687154727 +40.511171892911705 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_8.prj b/data/release/coverages/mosaic_sample/global_mosaic_8.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_8.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_8.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/global_mosaic_9.pgw b/data/release/coverages/mosaic_sample/global_mosaic_9.pgw index 606f237eb54..12f9b43f205 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_9.pgw +++ b/data/release/coverages/mosaic_sample/global_mosaic_9.pgw @@ -1,6 +1,6 @@ -0.05793403297722847 -0.0 -0.0 --0.04039598061277999 -17.96194852040869 -40.511171892911705 +0.05793403297722847 +0.0 +0.0 +-0.04039598061277999 +17.96194852040869 +40.511171892911705 diff --git a/data/release/coverages/mosaic_sample/global_mosaic_9.prj b/data/release/coverages/mosaic_sample/global_mosaic_9.prj index 60c0b45b355..7cb3bb426d9 100644 --- a/data/release/coverages/mosaic_sample/global_mosaic_9.prj +++ b/data/release/coverages/mosaic_sample/global_mosaic_9.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/coverages/mosaic_sample/mosaic.prj b/data/release/coverages/mosaic_sample/mosaic.prj index 187c589b0db..88167c9581a 100644 --- a/data/release/coverages/mosaic_sample/mosaic.prj +++ b/data/release/coverages/mosaic_sample/mosaic.prj @@ -1,9 +1,9 @@ -GEOGCS["WGS 84", - DATUM["World Geodetic System 1984", - SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], +GEOGCS["WGS 84", + DATUM["World Geodetic System 1984", + SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4326"]] \ No newline at end of file diff --git a/data/release/styles/burg.sld b/data/release/styles/burg.sld index 29fc0bf54af..f0329472bbf 100644 --- a/data/release/styles/burg.sld +++ b/data/release/styles/burg.sld @@ -1,31 +1,31 @@ - - - - redflag - - burg - A small red flag - A sample of how to use an SVG based symbolizer - - - - Red flag - - - - - image/svg+xml - - - 20 - - - - - - - - - + + + + redflag + + burg + A small red flag + A sample of how to use an SVG based symbolizer + + + + Red flag + + + + + image/svg+xml + + + 20 + + + + + + + + + diff --git a/doc/en/developer/source/programming-guide/app-schema/index.rst b/doc/en/developer/source/programming-guide/app-schema/index.rst index 670955d4c8e..4a0cce27328 100644 --- a/doc/en/developer/source/programming-guide/app-schema/index.rst +++ b/doc/en/developer/source/programming-guide/app-schema/index.rst @@ -1,171 +1,171 @@ -.. _app-schema_online_tests: - -App-Schema Online Tests -======================= - -The offline tests in app-schema-test suite use properties files as data source. In reality, properties files are only used as testing means, whereas in production, users would use databases as data source. Users would often encounter problems/bugs that cannot be recreated using properties files, which raises the need to run with a test database. Moreover, Niels' joining support to increase performance can only be tested online, and we need to ensure that it works with the current features/bug fixes covered in the tests. - -Prerequisites -------------- - -This requires installation of Oracle driver in Maven repository:: - - mvn install:install-file -Dfile=ojdbc7.jar -DgroupId=com.oracle -DartifactId=ojdbc7 -Dversion=12.1.0.2 -Dpackaging=jar - -You would also need to have test databases for both Oracle and Postgis. Then follow these steps: - -* Create oracle.properties and postgis.properties in {user directory}/.geoserver directory. - -* Populate each properties file with database details, e.g.:: - - password=onlinetestuser - - passwd=onlinetestuser - - user=onlinetestuser - - port=5432 - - url=jdbc\:postgresql\://localhost:5432/onlinetest - - host=localhost - - database=onlinetest - - driver=org.postgresql.Driver - - dbtype=postgisng - -Running tests from Maven ------------------------- - -Without specifying any profile, the default Maven configuration for app-schema-test is to run offline tests only. - -To run online tests, enable the profile:: - - -Papp-schema-online-test - -This profile enables the data reference set tests and offline tests to run online. Data reference set tests are online tests based on data and use cases from GeoScience Victoria. Each is explicit for a database type (Oracle and Postgis) and has a copy to run with joining enabled. - -The offline tests are configured to run online with joining through separate modules for each database: app-schema-oracle-test and app-schema-postgis-test. These modules are placeholders for pom.xml files containing database specific parameters. This makes it easy to identify when a test fails with a particular database when running from Maven/buildbot. - -Memory requirements -``````````````````` - -The online tests require more memory than usual, so specifying the usual -Dtest.maxHeapSize=256m is not enough. Specify --Dtest.maxHeapSize=1024m instead. - -When the build is successful, you would see this in the "Reactor Summary":: - - [INFO] Application Schema Integration Online Test with Oracle Database SUCCESS [5:52.980s] - [INFO] Application Schema Integration Online Test with Postgis Database SUCCESS [1:42.428s] - -Running tests from JUnit ------------------------- - -There is no need to import the online test modules as they are empty and you cannot run the tests through them in Eclipse. - -To run offline tests (in app-schema-test/src/test/java/org/geoserver/test) with a test database, -enable joining and specify the database. Add these parameters in VM Arguments for postgis:: - - -Dapp-schema.joining=true -DtestDatabase=postgis -Xmx256m - -Similarly, to test with oracle:: - - -Dapp-schema.joining=true -DtestDatabase=oracle -Xmx256m - -Additionally for Oracle, you also need to add ojdbc14.jar in the test Classpath. - -.. note:: Please note that you should only run the tests in org.geoserver.test package with the above parameters, since the data reference tests in org.geoserver.test.onlineTest package contain non-joining tests which would fail. - -You do not need to specify these VM Arguments for running data reference tests (in app-schema-test/src/test/java/org/geoserver/test/onlineTest). However, you would still need to specify the Oracle JDBC driver in the Classpath for Oracle specific tests. Data reference tests package also requires 768m memory to run from JUnit. - -Adding new tests ----------------- - -When adding new tests to app-schema-test suite (except for onlineTest package for data reference tests), please note the following: - -Test offline only -````````````````` - -If your test is a special case and does not need to be tested online, exclude them in both app-schema-oracle-test and app-schema-postgis-test pom.xml and ignore the points beyond this. Otherwise, read on. - -idExpression -```````````` - -If your test database does not use primary keys, ensure idExpression is specified for the top level element in your mapping file. - -Multi-valued properties ordering -```````````````````````````````` - -When testing multi-valued properties, the order of the values could vary depending on the data source type. To be safe, compare your values as a list, instead of evaluating individual xpath node against a single value for such properties. E.g.:: - - List names = new ArrayList(); - names.add("New Group"); - names.add("-Xy"); - String name = evaluate("//gsml:MappedFeature[@gml:id='" + id - + "']/gsml:specification/gsml:GeologicUnit/gml:name[1]", doc); - assertTrue(names.contains(name)); - names.remove(name); - name = evaluate("//gsml:MappedFeature[@gml:id='" + id - + "']/gsml:specification/gsml:GeologicUnit/gml:name[2]", doc); - assertTrue(names.contains(name)); - names.remove(name); - assertTrue(names.isEmpty()); - -This is because of the difference in the handling of queries with joining. Joining uses order by when querying tables. When the tests run offline, property data store returns data from properties file unordered. - -When joining is enabled: - -* If the multi-valued properties are not feature chained, the order is unpredictable. - -* If the multi-valued properties are feature chained, they are ordered by the foreign key used in feature chaining. - -Column names in upper case -`````````````````````````` - -Ensure column names in mapping files are in upper case, even if they are in lower case in the properties file. This is to avoid failures with Oracle database, due to OracleDialect not wrapping names with escape characters. To work around this, the script for online tests creates the columns in upper case, therefore should be referred by with upper case. - -Functions in feature chaining -````````````````````````````` - -If using feature chaining, avoid using functions in sourceExpression for linking attributes, i.e. attribute used in both OCQL and linkField. This is because functions used in feature chaining are not supported with joining support. - -3D tests -```````` -There are a number of tests that try out 3D features in App-schema. To run these as online tests against a postgis or oracle database, a number of prerequisites must be met. - -For PostGIS: - - * You must use postgis 2 to support 3D. - * In your postgis, if it hasn't been done yet, this command must be executed to support srid 4979 (wgs84 with 3d):: - - INSERT into spatial_ref_sys (srid, auth_name, auth_srid, proj4text, srtext) values ( 4979, 'epsg', 4979, '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ', 'GEOGCS["WGS 84",DATUM["World Geodetic System 1984",SPHEROID["WGS 84",6378137.0,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0.0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.017453292519943295],AXIS["Geodetic latitude",NORTH],AXIS["Geodetic longitude",EAST],AXIS["Ellipsoidal height",UP],AUTHORITY["EPSG","4979"]]'); - - -For Oracle: - - * You must use Oracle 11g Release 2, preferably the latest version that can be downloaded for best 3D support - * Oracle does NOT support WKT parsing of 3d geometries, so some extra DBA work is needed to set this up. Otherwise the online tests, which rely on WKT to enter data in the database, will fail. - - You need the following package 'SC4O' (Spatial Companion for Oracle), created Simon Greener: download at http://www.spatialdbadvisor.com/files/SC4O.zip. - It has an installation script for linux and windows that must be run from the server that runs oracle. The package will provide JTS functionality that can be called from PL/SQL. - - If the online test user is different from the user used for the installation of the package, the online test user must be given permission to use the package. - You must also execute as an admin user the following command (with 'onlinetestuser' being the online test user):: - - CALL DBMS_JAVA.GRANT_PERMISSION('onlinetestuser','java.lang.RuntimePermission','getClassLoader',''); - - Afterwards, you have to specify the user where the SC4O package was installed to the online testing system. You do this by specifying the system property -DSC4OUser. If it is the same as the online test user, you can omit this parameter. - The online test will use the JTS method for wkt parsing (ST_GeomFromEWKT) rather than the regular oracle method SDO_GEOMETRY. - For example, I installed the package using the System user. Then I gave onlinetestuser permission to execute it. - I run the tests with -DSC4OUser=System so it knows to use the System.SC4O.ST_GeomFromEWKT method. - -Running MongoDB Online Tests ----------------------------- - -MongoDB online tests are activated by the ``app-schema-online-test`` profile and will run if configuration file ``{user directory}/.geoserver/mongodb.properties`` is available. If the configuration file is not available an example file will be created and tests will be skipped. The content of the configuration file should look like this:: - - mongo.port=27017 - mongo.host=127.0.0.1 - +.. _app-schema_online_tests: + +App-Schema Online Tests +======================= + +The offline tests in app-schema-test suite use properties files as data source. In reality, properties files are only used as testing means, whereas in production, users would use databases as data source. Users would often encounter problems/bugs that cannot be recreated using properties files, which raises the need to run with a test database. Moreover, Niels' joining support to increase performance can only be tested online, and we need to ensure that it works with the current features/bug fixes covered in the tests. + +Prerequisites +------------- + +This requires installation of Oracle driver in Maven repository:: + + mvn install:install-file -Dfile=ojdbc7.jar -DgroupId=com.oracle -DartifactId=ojdbc7 -Dversion=12.1.0.2 -Dpackaging=jar + +You would also need to have test databases for both Oracle and Postgis. Then follow these steps: + +* Create oracle.properties and postgis.properties in {user directory}/.geoserver directory. + +* Populate each properties file with database details, e.g.:: + + password=onlinetestuser + + passwd=onlinetestuser + + user=onlinetestuser + + port=5432 + + url=jdbc\:postgresql\://localhost:5432/onlinetest + + host=localhost + + database=onlinetest + + driver=org.postgresql.Driver + + dbtype=postgisng + +Running tests from Maven +------------------------ + +Without specifying any profile, the default Maven configuration for app-schema-test is to run offline tests only. + +To run online tests, enable the profile:: + + -Papp-schema-online-test + +This profile enables the data reference set tests and offline tests to run online. Data reference set tests are online tests based on data and use cases from GeoScience Victoria. Each is explicit for a database type (Oracle and Postgis) and has a copy to run with joining enabled. + +The offline tests are configured to run online with joining through separate modules for each database: app-schema-oracle-test and app-schema-postgis-test. These modules are placeholders for pom.xml files containing database specific parameters. This makes it easy to identify when a test fails with a particular database when running from Maven/buildbot. + +Memory requirements +``````````````````` + +The online tests require more memory than usual, so specifying the usual -Dtest.maxHeapSize=256m is not enough. Specify --Dtest.maxHeapSize=1024m instead. + +When the build is successful, you would see this in the "Reactor Summary":: + + [INFO] Application Schema Integration Online Test with Oracle Database SUCCESS [5:52.980s] + [INFO] Application Schema Integration Online Test with Postgis Database SUCCESS [1:42.428s] + +Running tests from JUnit +------------------------ + +There is no need to import the online test modules as they are empty and you cannot run the tests through them in Eclipse. + +To run offline tests (in app-schema-test/src/test/java/org/geoserver/test) with a test database, +enable joining and specify the database. Add these parameters in VM Arguments for postgis:: + + -Dapp-schema.joining=true -DtestDatabase=postgis -Xmx256m + +Similarly, to test with oracle:: + + -Dapp-schema.joining=true -DtestDatabase=oracle -Xmx256m + +Additionally for Oracle, you also need to add ojdbc14.jar in the test Classpath. + +.. note:: Please note that you should only run the tests in org.geoserver.test package with the above parameters, since the data reference tests in org.geoserver.test.onlineTest package contain non-joining tests which would fail. + +You do not need to specify these VM Arguments for running data reference tests (in app-schema-test/src/test/java/org/geoserver/test/onlineTest). However, you would still need to specify the Oracle JDBC driver in the Classpath for Oracle specific tests. Data reference tests package also requires 768m memory to run from JUnit. + +Adding new tests +---------------- + +When adding new tests to app-schema-test suite (except for onlineTest package for data reference tests), please note the following: + +Test offline only +````````````````` + +If your test is a special case and does not need to be tested online, exclude them in both app-schema-oracle-test and app-schema-postgis-test pom.xml and ignore the points beyond this. Otherwise, read on. + +idExpression +```````````` + +If your test database does not use primary keys, ensure idExpression is specified for the top level element in your mapping file. + +Multi-valued properties ordering +```````````````````````````````` + +When testing multi-valued properties, the order of the values could vary depending on the data source type. To be safe, compare your values as a list, instead of evaluating individual xpath node against a single value for such properties. E.g.:: + + List names = new ArrayList(); + names.add("New Group"); + names.add("-Xy"); + String name = evaluate("//gsml:MappedFeature[@gml:id='" + id + + "']/gsml:specification/gsml:GeologicUnit/gml:name[1]", doc); + assertTrue(names.contains(name)); + names.remove(name); + name = evaluate("//gsml:MappedFeature[@gml:id='" + id + + "']/gsml:specification/gsml:GeologicUnit/gml:name[2]", doc); + assertTrue(names.contains(name)); + names.remove(name); + assertTrue(names.isEmpty()); + +This is because of the difference in the handling of queries with joining. Joining uses order by when querying tables. When the tests run offline, property data store returns data from properties file unordered. + +When joining is enabled: + +* If the multi-valued properties are not feature chained, the order is unpredictable. + +* If the multi-valued properties are feature chained, they are ordered by the foreign key used in feature chaining. + +Column names in upper case +`````````````````````````` + +Ensure column names in mapping files are in upper case, even if they are in lower case in the properties file. This is to avoid failures with Oracle database, due to OracleDialect not wrapping names with escape characters. To work around this, the script for online tests creates the columns in upper case, therefore should be referred by with upper case. + +Functions in feature chaining +````````````````````````````` + +If using feature chaining, avoid using functions in sourceExpression for linking attributes, i.e. attribute used in both OCQL and linkField. This is because functions used in feature chaining are not supported with joining support. + +3D tests +```````` +There are a number of tests that try out 3D features in App-schema. To run these as online tests against a postgis or oracle database, a number of prerequisites must be met. + +For PostGIS: + + * You must use postgis 2 to support 3D. + * In your postgis, if it hasn't been done yet, this command must be executed to support srid 4979 (wgs84 with 3d):: + + INSERT into spatial_ref_sys (srid, auth_name, auth_srid, proj4text, srtext) values ( 4979, 'epsg', 4979, '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ', 'GEOGCS["WGS 84",DATUM["World Geodetic System 1984",SPHEROID["WGS 84",6378137.0,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0.0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.017453292519943295],AXIS["Geodetic latitude",NORTH],AXIS["Geodetic longitude",EAST],AXIS["Ellipsoidal height",UP],AUTHORITY["EPSG","4979"]]'); + + +For Oracle: + + * You must use Oracle 11g Release 2, preferably the latest version that can be downloaded for best 3D support + * Oracle does NOT support WKT parsing of 3d geometries, so some extra DBA work is needed to set this up. Otherwise the online tests, which rely on WKT to enter data in the database, will fail. + + You need the following package 'SC4O' (Spatial Companion for Oracle), created Simon Greener: download at http://www.spatialdbadvisor.com/files/SC4O.zip. + It has an installation script for linux and windows that must be run from the server that runs oracle. The package will provide JTS functionality that can be called from PL/SQL. + + If the online test user is different from the user used for the installation of the package, the online test user must be given permission to use the package. + You must also execute as an admin user the following command (with 'onlinetestuser' being the online test user):: + + CALL DBMS_JAVA.GRANT_PERMISSION('onlinetestuser','java.lang.RuntimePermission','getClassLoader',''); + + Afterwards, you have to specify the user where the SC4O package was installed to the online testing system. You do this by specifying the system property -DSC4OUser. If it is the same as the online test user, you can omit this parameter. + The online test will use the JTS method for wkt parsing (ST_GeomFromEWKT) rather than the regular oracle method SDO_GEOMETRY. + For example, I installed the package using the System user. Then I gave onlinetestuser permission to execute it. + I run the tests with -DSC4OUser=System so it knows to use the System.SC4O.ST_GeomFromEWKT method. + +Running MongoDB Online Tests +---------------------------- + +MongoDB online tests are activated by the ``app-schema-online-test`` profile and will run if configuration file ``{user directory}/.geoserver/mongodb.properties`` is available. If the configuration file is not available an example file will be created and tests will be skipped. The content of the configuration file should look like this:: + + mongo.port=27017 + mongo.host=127.0.0.1 + During the tests a new database will be created in MongoDB and when the tests end that database will be removed. \ No newline at end of file diff --git a/doc/en/developer/source/programming-guide/index.rst b/doc/en/developer/source/programming-guide/index.rst index 52084f19688..fe6c2c8425a 100644 --- a/doc/en/developer/source/programming-guide/index.rst +++ b/doc/en/developer/source/programming-guide/index.rst @@ -1,18 +1,18 @@ -.. _programming_guide: - -Programming Guide -================= - -.. toctree:: - :maxdepth: 1 - - ows-services/index.rst - rest-services/index.rst - web-ui/index.rst - wicket-pages/index.rst - extension-points/index.rst - wps-services/index.rst - testing/index.rst - security/index.rst - app-schema/index.rst - +.. _programming_guide: + +Programming Guide +================= + +.. toctree:: + :maxdepth: 1 + + ows-services/index.rst + rest-services/index.rst + web-ui/index.rst + wicket-pages/index.rst + extension-points/index.rst + wps-services/index.rst + testing/index.rst + security/index.rst + app-schema/index.rst + diff --git a/doc/en/user/source/community/csw-iso/index.rst b/doc/en/user/source/community/csw-iso/index.rst index 890bb68e972..743af30832e 100644 --- a/doc/en/user/source/community/csw-iso/index.rst +++ b/doc/en/user/source/community/csw-iso/index.rst @@ -1,13 +1,13 @@ -.. _csw_iso: - -Catalog Services for the Web (CSW) - ISO Metadata Profile -========================================================= - -This section discusses the Catalog Services for Web (CSW) ISO Metadata Profile community module. With this community module on top of the general :ref:`csw` extension, GeoServer supports the ISO Metadata Profile as an additional scheme for the CSW service. - -.. toctree:: - :maxdepth: 2 - - installing - mapping - tutorial +.. _csw_iso: + +Catalog Services for the Web (CSW) - ISO Metadata Profile +========================================================= + +This section discusses the Catalog Services for Web (CSW) ISO Metadata Profile community module. With this community module on top of the general :ref:`csw` extension, GeoServer supports the ISO Metadata Profile as an additional scheme for the CSW service. + +.. toctree:: + :maxdepth: 2 + + installing + mapping + tutorial diff --git a/doc/en/user/source/community/csw-iso/tutorial.rst b/doc/en/user/source/community/csw-iso/tutorial.rst index 8d2f32c510c..15044d06bc2 100644 --- a/doc/en/user/source/community/csw-iso/tutorial.rst +++ b/doc/en/user/source/community/csw-iso/tutorial.rst @@ -1,174 +1,174 @@ -.. _csw_iso_tutorial: - -Catalog Services for the Web (CSW) ISO Metadata tutorial -======================================================== - -This tutorial will show how to use the CSW module with the ISO Metadata Profile scheme. It assumes a fresh installation of GeoServer with the :ref:`CSW ISO Metadata Profile module installed `. - -Configuration -------------- - -In the :file:`/csw` directory, create a new file named :file:`MD_Metadata.properties` (ISO Metadata Profile mapping file) with the following contents:: - - @fileIdentifier.CharacterString=prefixedName - identificationInfo.AbstractMD_Identification.citation.CI_Citation.title.CharacterString=title - identificationInfo.AbstractMD_Identification.descriptiveKeywords.MD_Keywords.keyword.CharacterString=keywords - identificationInfo.AbstractMD_Identification.abstract.CharacterString=abstract - $dateStamp.Date= if_then_else ( isNull("metadata.date") , 'Unknown', "metadata.date") - hierarchyLevel.MD_ScopeCode.@codeListValue='http://purl.org/dc/dcmitype/Dataset' - $contact.CI_ResponsibleParty.individualName.CharacterString='John Smith' - -Services --------- - -With GeoServer running (and responding on ``http://localhost:8080``), test GeoServer CSW in a web browser by querying the CSW capabilities as follows:: - - http://localhost:8080/geoserver/csw?service=csw&version=2.0.2&request=GetCapabilities - -We can request a description of our Metadata record:: - - http://localhost:8080/geoserver/csw?service=CSW&version=2.0.2&request=DescribeRecord&typeName=gmd:MD_Metadata - -This yields the following result:: - - - - - - - - Geographic MetaData (GMD) extensible markup language is a component of the XML Schema Implementation of Geographic Information Metadata documented in ISO/TS 19139:2007. GMD includes all the definitions of http://www.isotc211.org/2005/gmd namespace. The root document of this namespace is the file gmd.xsd. This identification.xsd schema implements the UML conceptual schema defined in A.2.2 of ISO 19115:2003. It contains the implementation of the following classes: MD_Identification, MD_BrowseGraphic, MD_DataIdentification, MD_ServiceIdentification, MD_RepresentativeFraction, MD_Usage, MD_Keywords, DS_Association, MD_AggregateInformation, MD_CharacterSetCode, MD_SpatialRepresentationTypeCode, MD_TopicCategoryCode, MD_ProgressCode, MD_KeywordTypeCode, DS_AssociationTypeCode, DS_InitiativeTypeCode, MD_ResolutionType. - - ... - -Query all layers as follows:: - - http://localhost:8080/geoserver/csw?service=CSW&version=2.0.2&request=GetRecords&typeNames=gmd:MD_Metadata&resultType=results&elementSetName=full&outputSchema=http://www.isotc211.org/2005/gmd - -Request a particular layer by ID...:: - - http://localhost:8080/geoserver/csw?service=CSW&version=2.0.2&request=GetRecordById&elementsetname=summary&id=CoverageInfoImpl--4a9eec43:132d48aac79:-8000&typeNames=gmd:MD_Metadata&resultType=results&elementSetName=full&outputSchema=http://www.isotc211.org/2005/gmd - -...or use a filter to retrieve it by Title:: - - http://localhost:8080/geoserver/csw?service=CSW&version=2.0.2&request=GetRecords&typeNames=gmd:MD_Metadata&resultType=results&elementSetName=full&outputSchema=http://www.isotc211.org/2005/gmd&constraint=Title=%27mosaic%27 - -Either case should return:: - - - - - - - - CoverageInfoImpl--4a9eec43:132d48aac79:-8000 - - - Unknown - - - - - - - - 36.492 - 6.346 - 46.591 - 20.83 - - - - - - - - - - mosaic - - - - - - - WCS - - - ImageMosaic - - - mosaic - - - - - - - - - John Smith - - - - - - - - - - -We can request the domain of a property. For example, all values of "Title":: - - http://localhost:8080/geoserver/csw?service=csw&version=2.0.2&request=GetDomain&propertyName=Title - -This should yield the following result:: - - - - - Title - - A sample ArcGrid file - Manhattan (NY) landmarks - Manhattan (NY) points of interest - Manhattan (NY) roads - North America sample imagery - Pk50095 is a A raster file accompanied by a spatial data file - Spearfish archeological sites - Spearfish bug locations - Spearfish restricted areas - Spearfish roads - Spearfish streams - Tasmania cities - Tasmania roads - Tasmania state boundaries - Tasmania water bodies - USA Population - World rectangle - mosaic - sfdem is a Tagged Image File Format with Geographic information - - - - -To request more than the first 10 records or for more complex queries you can use a HTTP POST request with an XML query as the request body. For example, using the maxRecords option in the following request it is possible to return the first 50 layers with "ImageMosaic" in a keyword:: - - http://localhost:8080/geoserver/csw - -Postbody:: - - - - - full - - - - dc:subject - %ImageMosaic% - - - - - +.. _csw_iso_tutorial: + +Catalog Services for the Web (CSW) ISO Metadata tutorial +======================================================== + +This tutorial will show how to use the CSW module with the ISO Metadata Profile scheme. It assumes a fresh installation of GeoServer with the :ref:`CSW ISO Metadata Profile module installed `. + +Configuration +------------- + +In the :file:`/csw` directory, create a new file named :file:`MD_Metadata.properties` (ISO Metadata Profile mapping file) with the following contents:: + + @fileIdentifier.CharacterString=prefixedName + identificationInfo.AbstractMD_Identification.citation.CI_Citation.title.CharacterString=title + identificationInfo.AbstractMD_Identification.descriptiveKeywords.MD_Keywords.keyword.CharacterString=keywords + identificationInfo.AbstractMD_Identification.abstract.CharacterString=abstract + $dateStamp.Date= if_then_else ( isNull("metadata.date") , 'Unknown', "metadata.date") + hierarchyLevel.MD_ScopeCode.@codeListValue='http://purl.org/dc/dcmitype/Dataset' + $contact.CI_ResponsibleParty.individualName.CharacterString='John Smith' + +Services +-------- + +With GeoServer running (and responding on ``http://localhost:8080``), test GeoServer CSW in a web browser by querying the CSW capabilities as follows:: + + http://localhost:8080/geoserver/csw?service=csw&version=2.0.2&request=GetCapabilities + +We can request a description of our Metadata record:: + + http://localhost:8080/geoserver/csw?service=CSW&version=2.0.2&request=DescribeRecord&typeName=gmd:MD_Metadata + +This yields the following result:: + + + + + + + + Geographic MetaData (GMD) extensible markup language is a component of the XML Schema Implementation of Geographic Information Metadata documented in ISO/TS 19139:2007. GMD includes all the definitions of http://www.isotc211.org/2005/gmd namespace. The root document of this namespace is the file gmd.xsd. This identification.xsd schema implements the UML conceptual schema defined in A.2.2 of ISO 19115:2003. It contains the implementation of the following classes: MD_Identification, MD_BrowseGraphic, MD_DataIdentification, MD_ServiceIdentification, MD_RepresentativeFraction, MD_Usage, MD_Keywords, DS_Association, MD_AggregateInformation, MD_CharacterSetCode, MD_SpatialRepresentationTypeCode, MD_TopicCategoryCode, MD_ProgressCode, MD_KeywordTypeCode, DS_AssociationTypeCode, DS_InitiativeTypeCode, MD_ResolutionType. + + ... + +Query all layers as follows:: + + http://localhost:8080/geoserver/csw?service=CSW&version=2.0.2&request=GetRecords&typeNames=gmd:MD_Metadata&resultType=results&elementSetName=full&outputSchema=http://www.isotc211.org/2005/gmd + +Request a particular layer by ID...:: + + http://localhost:8080/geoserver/csw?service=CSW&version=2.0.2&request=GetRecordById&elementsetname=summary&id=CoverageInfoImpl--4a9eec43:132d48aac79:-8000&typeNames=gmd:MD_Metadata&resultType=results&elementSetName=full&outputSchema=http://www.isotc211.org/2005/gmd + +...or use a filter to retrieve it by Title:: + + http://localhost:8080/geoserver/csw?service=CSW&version=2.0.2&request=GetRecords&typeNames=gmd:MD_Metadata&resultType=results&elementSetName=full&outputSchema=http://www.isotc211.org/2005/gmd&constraint=Title=%27mosaic%27 + +Either case should return:: + + + + + + + + CoverageInfoImpl--4a9eec43:132d48aac79:-8000 + + + Unknown + + + + + + + + 36.492 + 6.346 + 46.591 + 20.83 + + + + + + + + + + mosaic + + + + + + + WCS + + + ImageMosaic + + + mosaic + + + + + + + + + John Smith + + + + + + + + + + +We can request the domain of a property. For example, all values of "Title":: + + http://localhost:8080/geoserver/csw?service=csw&version=2.0.2&request=GetDomain&propertyName=Title + +This should yield the following result:: + + + + + Title + + A sample ArcGrid file + Manhattan (NY) landmarks + Manhattan (NY) points of interest + Manhattan (NY) roads + North America sample imagery + Pk50095 is a A raster file accompanied by a spatial data file + Spearfish archeological sites + Spearfish bug locations + Spearfish restricted areas + Spearfish roads + Spearfish streams + Tasmania cities + Tasmania roads + Tasmania state boundaries + Tasmania water bodies + USA Population + World rectangle + mosaic + sfdem is a Tagged Image File Format with Geographic information + + + + +To request more than the first 10 records or for more complex queries you can use a HTTP POST request with an XML query as the request body. For example, using the maxRecords option in the following request it is possible to return the first 50 layers with "ImageMosaic" in a keyword:: + + http://localhost:8080/geoserver/csw + +Postbody:: + + + + + full + + + + dc:subject + %ImageMosaic% + + + + + diff --git a/doc/en/user/source/community/dds/index.rst b/doc/en/user/source/community/dds/index.rst index 4059bd73696..f76a68e0215 100644 --- a/doc/en/user/source/community/dds/index.rst +++ b/doc/en/user/source/community/dds/index.rst @@ -1,70 +1,70 @@ -.. _community_dds: - -DDS/BIL(World Wind Data Formats) Extension -========================================== - -This output module allows GeoServer to output imagery and terrain in formats -understood by `NASA World Wind `_. The -mime-types supported are: - - #. Direct Draw Surface (DDS) - image/dds. This format allows efficient loading of textures to the GPU and takes the task off the WorldWind client CPU in converting downloaded PNG, JPEG or TIFF tiles. The DDS compression is done using `DXT3 `_ with help from the worldwind library on server side. - - #. Binary Interleaved by Line(BIL) - image/bil. This is actually a very simple raw binary format produced using the `RAW Image Writer `_. The supplied GridCoverage2D undergoes appropriate subsampling, reprojection and bit-depth conversion. The output can be requested as 16bit Int or 32bit Float. - - -Installing the DDS/BIL extension ------------------------------------ - - #. Download the DDS/BIL extension from the `nightly GeoServer community module builds `_. A prebuilt version for GeoServer 2.0.x can be found on Jira - :geos:`3586`. - - .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! - - #. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. - -Checking if the extension is enabled ------------------------------------- - -Once the extension is installed, the provided mime-types should appear in the layer preview dropbox as shown: - -.. figure:: images/bil_dds.jpg - :align: center - -The mime-types will also be listed in the ``GetCapabilities`` document:: - -image/bil -image/dds - -Configuring the BIL format ------------------------------------- - -For a client application to use a BIL layer, it must know the data encoding of the BIL file (e.g. 16-bit integer, 32-bit floating point, etc), the byte order of the data, and the value that indicates missing data. BIL files do not contain this metadata, so it may be necessary to configure the server to produce BIL files in the format that a client application expects. - -.. figure:: images/bil_config.png - :align: center - -The BIL output format can be configured for each layer in the Publishing tab of the layer configuration. The plugin supports the following options: - -.. list-table:: - :widths: 50 50 - - * - **Option** - - **Description** - * - ``Default encoding`` - - The data encoding to use if the request does not specify an encoding. For example, application/bil does not specify the response encoding, while application/bil16 does specify an encoding. Default: use same encoding as layer source files. - * - ``Byte order`` - - Byte order of the response. Default: network byte order (big endian). - * - ``No Data value`` - - The value that indicates missing data. If this option is set, missing data values will be recoded to this value. Default: no data translation. - -For compatibility with the default behavior of NASA World Wind, use these settings: - -* Default encoding: application/bil16 -* Byte order: Little endian -* No data: -9999 - -Configuring World Wind to access Imagery/Terrain from GeoServer ---------------------------------------------------------------- - -Please refer to the `WorldWind Forums `_ for instructions on how to setup World Wind to work with layers -published via GeoServer. For image layers(DDS) the user need to create a `WMSTiledImageLayer `_ either via XML configuration or programmatically. -For terrain layers (BIL) the equivalent class is `WMSBasicElevationModel `_. +.. _community_dds: + +DDS/BIL(World Wind Data Formats) Extension +========================================== + +This output module allows GeoServer to output imagery and terrain in formats +understood by `NASA World Wind `_. The +mime-types supported are: + + #. Direct Draw Surface (DDS) - image/dds. This format allows efficient loading of textures to the GPU and takes the task off the WorldWind client CPU in converting downloaded PNG, JPEG or TIFF tiles. The DDS compression is done using `DXT3 `_ with help from the worldwind library on server side. + + #. Binary Interleaved by Line(BIL) - image/bil. This is actually a very simple raw binary format produced using the `RAW Image Writer `_. The supplied GridCoverage2D undergoes appropriate subsampling, reprojection and bit-depth conversion. The output can be requested as 16bit Int or 32bit Float. + + +Installing the DDS/BIL extension +----------------------------------- + + #. Download the DDS/BIL extension from the `nightly GeoServer community module builds `_. A prebuilt version for GeoServer 2.0.x can be found on Jira - :geos:`3586`. + + .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! + + #. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. + +Checking if the extension is enabled +------------------------------------ + +Once the extension is installed, the provided mime-types should appear in the layer preview dropbox as shown: + +.. figure:: images/bil_dds.jpg + :align: center + +The mime-types will also be listed in the ``GetCapabilities`` document:: + +image/bil +image/dds + +Configuring the BIL format +------------------------------------ + +For a client application to use a BIL layer, it must know the data encoding of the BIL file (e.g. 16-bit integer, 32-bit floating point, etc), the byte order of the data, and the value that indicates missing data. BIL files do not contain this metadata, so it may be necessary to configure the server to produce BIL files in the format that a client application expects. + +.. figure:: images/bil_config.png + :align: center + +The BIL output format can be configured for each layer in the Publishing tab of the layer configuration. The plugin supports the following options: + +.. list-table:: + :widths: 50 50 + + * - **Option** + - **Description** + * - ``Default encoding`` + - The data encoding to use if the request does not specify an encoding. For example, application/bil does not specify the response encoding, while application/bil16 does specify an encoding. Default: use same encoding as layer source files. + * - ``Byte order`` + - Byte order of the response. Default: network byte order (big endian). + * - ``No Data value`` + - The value that indicates missing data. If this option is set, missing data values will be recoded to this value. Default: no data translation. + +For compatibility with the default behavior of NASA World Wind, use these settings: + +* Default encoding: application/bil16 +* Byte order: Little endian +* No data: -9999 + +Configuring World Wind to access Imagery/Terrain from GeoServer +--------------------------------------------------------------- + +Please refer to the `WorldWind Forums `_ for instructions on how to setup World Wind to work with layers +published via GeoServer. For image layers(DDS) the user need to create a `WMSTiledImageLayer `_ either via XML configuration or programmatically. +For terrain layers (BIL) the equivalent class is `WMSBasicElevationModel `_. diff --git a/doc/en/user/source/community/flatgeobuf/index.rst b/doc/en/user/source/community/flatgeobuf/index.rst index f246a42b82f..6c5b9634622 100644 --- a/doc/en/user/source/community/flatgeobuf/index.rst +++ b/doc/en/user/source/community/flatgeobuf/index.rst @@ -1,11 +1,11 @@ -.. _flatgeobuf: - -WFS FlatGeobuf output format -============================ - -This section discusses the WFS FlatGeobuf output format. - -.. toctree:: - :maxdepth: 2 - - installing +.. _flatgeobuf: + +WFS FlatGeobuf output format +============================ + +This section discusses the WFS FlatGeobuf output format. + +.. toctree:: + :maxdepth: 2 + + installing diff --git a/doc/en/user/source/community/gdal/index.rst b/doc/en/user/source/community/gdal/index.rst index 09b7ab34bc4..6f0d10778fe 100644 --- a/doc/en/user/source/community/gdal/index.rst +++ b/doc/en/user/source/community/gdal/index.rst @@ -1,125 +1,125 @@ -.. _gdal_wcs_output_format: - -GDAL based WCS Output Format -============================ - -The gdal_translate based output format leverages the availability of the gdal_translate command to allow the generation of more output formats than GeoServer can natively produce. -The basic idea is to dump to the file system a file that gdal_translate can translate, invoke it, zip and return the output of the translation. - -This extension is thus the equivalent of the :ref:`OGR extension ` for raster data. - - -Out of the box behaviour ------------------------- - -Out of the box the plugin assumes the following: - -* gdal_translate is available in the path -* the GDAL_DATA variable is pointing to the GDAL data directory (which stores the spatial reference information for GDAL) - -In the default configuration the following formats are supported: - -* JPEG-2000 part 1 (ISO/IEC 15444-1) -* Geospatial PDF -* Arc/Info ASCII Grid -* ASCII Gridded XYZ - -The list might be shorter if gdal_translate has not been built with support for the above formats (for example, the default JPEG-2000 format relies on the `JasPer-based GDAL driver `_). - -Once installed in GeoServer, a bunch of new supported formats will be listed in the ``ServiceMetadata`` section of the WCS 2.0 GetCapabilities document, e.g. ``image/jp2`` and ``application/pdf``. - -gdal_translate conversion abilities ------------------------------------ - -The gdal_translate utility is usually able to convert more formats than the default setup of this output format allows for, but the exact list depends on how the utility was built from sources. To get a full list of the formats available by your ogr2ogr build just run:: - - gdal_translate --long-usage - -and you'll get the full set of options usable by the program, along with the supported formats. - -.. include:: usage_example.txt - -The full list of formats that gdal_translate is able to support is available on the `GDAL site `_. Mind that this output format can handle only outputs that are file based and that do support creation. So, for example, you won't be able to use the PostGIS Raster output (since it's database based) or the Arc/Info Binary Grid (creation not supported). - -Customisation -------------- - -If gdal_translate is not available in the default path, the GDAL_DATA environment variable is not set, or if the output formats needs tweaking, a ``gdal_translate.xml`` configuration file can be created to customize the output format. The file should be put inside a ``gdal`` folder in the root of the GeoServer data directory. - -.. note:: GeoServer will automatically detect any change to the file and reload the configuration, without a need to restart. - - -The default configuration is equivalent to the following xml file: - -.. code-block:: xml - - - gdal_translate - - - - - - JPEG2000 - GDAL-JPEG2000 - .jp2 - true - image/jp2 - binary - - - - - PDF - GDAL-PDF - .pdf - true - application/pdf - - - - - - - AAIGrid - GDAL-ArcInfoGrid - .asc - false - - - XYZ - GDAL-XYZ - .txt - true - text/plain - text - - - - -The file showcases all possible usage of the configuration elements: - -* ``executable`` can be just gdal_translate if the command is in the path, otherwise it should be the full path to the executable. For example, on a Linux box with a custom build GDAL library might be:: - - /usr/local/bin/gdal_translate - -* ``environment`` contains a list of ``variable`` elements, which can be used to define environment variables that should be set prior to invoking gdal_translate. For example, to setup a GDAL_DATA environment variable pointing to the GDAL data directory, the configuration might be:: - - - - - -* ``Format`` defines a single format, which is defined by the following tags: - - * ``toolFormat``: the name of the format to be passed to gdal_translate with the -of option (case insensitive). - * ``geoserverFormat``: is the name of the output format as advertised by GeoServer - * ``fileExtension``: is the extension of the file generated after the translation, if any (can be omitted) - * ``option``: can be used to add one or more options to the gdal_translate command line. As you can see by the JPEG2000 example, each item must be contained in its own ``option`` tag. You can get a full list of options by running ``gdal_translate --help`` or by visiting the `GDAL web site `_). Also, consider that each format supports specific creation options, listed in the description page for each format (for example, here is the `JPEG2000 one `_). - * ``singleFile``: if true the output of the conversion is supposed to be a single file that can be streamed directly back without the need to wrap it into a zip file - * ``mimeType``: the mime type of the file returned when using ``singleFile``. If not specified ``application/octet-stream`` will be used as a default. - * ``formatAdapters``: transformations on the coverage that might need to be applied in order to successfully encode the output. The transformations are applied only if their input conditions are met. - -The available format adapters are: - -* ``GrayAlphaToRGBA``: expands a gray image with alpha channel to RGBA (mandatory for geospatial PDF for example) -* ``PallettedToRGB``: expands a paletted image RGB(A) (mandatory for geospatial PDF for example) +.. _gdal_wcs_output_format: + +GDAL based WCS Output Format +============================ + +The gdal_translate based output format leverages the availability of the gdal_translate command to allow the generation of more output formats than GeoServer can natively produce. +The basic idea is to dump to the file system a file that gdal_translate can translate, invoke it, zip and return the output of the translation. + +This extension is thus the equivalent of the :ref:`OGR extension ` for raster data. + + +Out of the box behaviour +------------------------ + +Out of the box the plugin assumes the following: + +* gdal_translate is available in the path +* the GDAL_DATA variable is pointing to the GDAL data directory (which stores the spatial reference information for GDAL) + +In the default configuration the following formats are supported: + +* JPEG-2000 part 1 (ISO/IEC 15444-1) +* Geospatial PDF +* Arc/Info ASCII Grid +* ASCII Gridded XYZ + +The list might be shorter if gdal_translate has not been built with support for the above formats (for example, the default JPEG-2000 format relies on the `JasPer-based GDAL driver `_). + +Once installed in GeoServer, a bunch of new supported formats will be listed in the ``ServiceMetadata`` section of the WCS 2.0 GetCapabilities document, e.g. ``image/jp2`` and ``application/pdf``. + +gdal_translate conversion abilities +----------------------------------- + +The gdal_translate utility is usually able to convert more formats than the default setup of this output format allows for, but the exact list depends on how the utility was built from sources. To get a full list of the formats available by your ogr2ogr build just run:: + + gdal_translate --long-usage + +and you'll get the full set of options usable by the program, along with the supported formats. + +.. include:: usage_example.txt + +The full list of formats that gdal_translate is able to support is available on the `GDAL site `_. Mind that this output format can handle only outputs that are file based and that do support creation. So, for example, you won't be able to use the PostGIS Raster output (since it's database based) or the Arc/Info Binary Grid (creation not supported). + +Customisation +------------- + +If gdal_translate is not available in the default path, the GDAL_DATA environment variable is not set, or if the output formats needs tweaking, a ``gdal_translate.xml`` configuration file can be created to customize the output format. The file should be put inside a ``gdal`` folder in the root of the GeoServer data directory. + +.. note:: GeoServer will automatically detect any change to the file and reload the configuration, without a need to restart. + + +The default configuration is equivalent to the following xml file: + +.. code-block:: xml + + + gdal_translate + + + + + + JPEG2000 + GDAL-JPEG2000 + .jp2 + true + image/jp2 + binary + + + + + PDF + GDAL-PDF + .pdf + true + application/pdf + + + + + + + AAIGrid + GDAL-ArcInfoGrid + .asc + false + + + XYZ + GDAL-XYZ + .txt + true + text/plain + text + + + + +The file showcases all possible usage of the configuration elements: + +* ``executable`` can be just gdal_translate if the command is in the path, otherwise it should be the full path to the executable. For example, on a Linux box with a custom build GDAL library might be:: + + /usr/local/bin/gdal_translate + +* ``environment`` contains a list of ``variable`` elements, which can be used to define environment variables that should be set prior to invoking gdal_translate. For example, to setup a GDAL_DATA environment variable pointing to the GDAL data directory, the configuration might be:: + + + + + +* ``Format`` defines a single format, which is defined by the following tags: + + * ``toolFormat``: the name of the format to be passed to gdal_translate with the -of option (case insensitive). + * ``geoserverFormat``: is the name of the output format as advertised by GeoServer + * ``fileExtension``: is the extension of the file generated after the translation, if any (can be omitted) + * ``option``: can be used to add one or more options to the gdal_translate command line. As you can see by the JPEG2000 example, each item must be contained in its own ``option`` tag. You can get a full list of options by running ``gdal_translate --help`` or by visiting the `GDAL web site `_). Also, consider that each format supports specific creation options, listed in the description page for each format (for example, here is the `JPEG2000 one `_). + * ``singleFile``: if true the output of the conversion is supposed to be a single file that can be streamed directly back without the need to wrap it into a zip file + * ``mimeType``: the mime type of the file returned when using ``singleFile``. If not specified ``application/octet-stream`` will be used as a default. + * ``formatAdapters``: transformations on the coverage that might need to be applied in order to successfully encode the output. The transformations are applied only if their input conditions are met. + +The available format adapters are: + +* ``GrayAlphaToRGBA``: expands a gray image with alpha channel to RGBA (mandatory for geospatial PDF for example) +* ``PallettedToRGB``: expands a paletted image RGB(A) (mandatory for geospatial PDF for example) diff --git a/doc/en/user/source/community/geomesa/index.rst b/doc/en/user/source/community/geomesa/index.rst index ca9dd0aa97a..2684ce59eae 100644 --- a/doc/en/user/source/community/geomesa/index.rst +++ b/doc/en/user/source/community/geomesa/index.rst @@ -1,6 +1,6 @@ -.. _community_geomesa: - -GeoMesa data store -================== - -`GeoMesa `_ provides a GeoTools DataStore to access SimpleFeatures stored in Apache Accumulo. +.. _community_geomesa: + +GeoMesa data store +================== + +`GeoMesa `_ provides a GeoTools DataStore to access SimpleFeatures stored in Apache Accumulo. diff --git a/doc/en/user/source/community/index.rst b/doc/en/user/source/community/index.rst index 74604ba4b37..c26567bc4be 100644 --- a/doc/en/user/source/community/index.rst +++ b/doc/en/user/source/community/index.rst @@ -1,61 +1,61 @@ -.. _community: - -Community modules -================= - -This section is devoted to GeoServer community modules. Community modules are considered "pending" in that they are not -officially part of the GeoServer releases. They are however built along with the -`nightly builds `_, so you can download and play with them. - -.. warning:: - - Community modules are generally considered experimental in nature and are often under constant development. For that reason documentation in this section should not be considered solid or final and will be subject to change. - - -.. toctree:: - :maxdepth: 1 - - oauth2/index - keycloak/index - keycloak/keycloak_role_service - dds/index - colormap/index - jdbcconfig/index - mbtiles/index - geopkg/index - pgraster/pgraster - jms-cluster/index - solr/index - elasticsearch/index - geomesa/index - gwc-distributed/index - flatgeobuf/index - gdal/index - gwc-azure-blob/index - gwc-sqlite/index - remote-wps/index - jdbcstore/index - ncwms/index - backuprestore/index - saml/index - notification/index - opensearch-eo/index - s3-geotiff/index - netcdf-ghrsst/index - monitor-hibernate/index - taskmanager/index - metadata/index - ogr-store/index - geostyler/index - csw-iso/index - importer-jdbc/index - hana/index - features-templating/index - ogc-api/index - gsr/index - cog/index - cov-json/index - smart-data-loader/index - schemaless-features/index - web-service-auth/index - gwc-mbtiles/index +.. _community: + +Community modules +================= + +This section is devoted to GeoServer community modules. Community modules are considered "pending" in that they are not +officially part of the GeoServer releases. They are however built along with the +`nightly builds `_, so you can download and play with them. + +.. warning:: + + Community modules are generally considered experimental in nature and are often under constant development. For that reason documentation in this section should not be considered solid or final and will be subject to change. + + +.. toctree:: + :maxdepth: 1 + + oauth2/index + keycloak/index + keycloak/keycloak_role_service + dds/index + colormap/index + jdbcconfig/index + mbtiles/index + geopkg/index + pgraster/pgraster + jms-cluster/index + solr/index + elasticsearch/index + geomesa/index + gwc-distributed/index + flatgeobuf/index + gdal/index + gwc-azure-blob/index + gwc-sqlite/index + remote-wps/index + jdbcstore/index + ncwms/index + backuprestore/index + saml/index + notification/index + opensearch-eo/index + s3-geotiff/index + netcdf-ghrsst/index + monitor-hibernate/index + taskmanager/index + metadata/index + ogr-store/index + geostyler/index + csw-iso/index + importer-jdbc/index + hana/index + features-templating/index + ogc-api/index + gsr/index + cog/index + cov-json/index + smart-data-loader/index + schemaless-features/index + web-service-auth/index + gwc-mbtiles/index diff --git a/doc/en/user/source/community/jdbcconfig/index.rst b/doc/en/user/source/community/jdbcconfig/index.rst index 49bcff4fc2b..196bca80ddf 100644 --- a/doc/en/user/source/community/jdbcconfig/index.rst +++ b/doc/en/user/source/community/jdbcconfig/index.rst @@ -1,15 +1,15 @@ -.. _community_jdbcconfig: - -JDBCConfig -========== - -The ``JDBCConfig module`` enhances the scalibility performance of the GeoServer Catalog. -It allows externalising the storage of the Catalog configuration objects (such as workspaces, stores, layers) to a Relational Database Management System, -rather than using xml files in the :ref:`datadir`. This way the Catalog can support access to unlimited numbers of those configuration objects efficiently. - -.. toctree:: - :maxdepth: 2 - - installing - configuration - +.. _community_jdbcconfig: + +JDBCConfig +========== + +The ``JDBCConfig module`` enhances the scalibility performance of the GeoServer Catalog. +It allows externalising the storage of the Catalog configuration objects (such as workspaces, stores, layers) to a Relational Database Management System, +rather than using xml files in the :ref:`datadir`. This way the Catalog can support access to unlimited numbers of those configuration objects efficiently. + +.. toctree:: + :maxdepth: 2 + + installing + configuration + diff --git a/doc/en/user/source/community/jdbcstore/index.rst b/doc/en/user/source/community/jdbcstore/index.rst index 4dc6f2c309a..53a58803dc5 100644 --- a/doc/en/user/source/community/jdbcstore/index.rst +++ b/doc/en/user/source/community/jdbcstore/index.rst @@ -1,13 +1,13 @@ -.. _community_jdbcstore: - -JDBCStore -========== - -The ``JDBCStore module`` allows efficient sharing of configuration data in a clustered deployment of GeoServer. It allows externalising the storage of all configuration resources to a Relational Database Management System, rather than using the default File System based :ref:`datadir`. This way the multiple instances of GeoServer can use the same Database and therefore share in the same configuration. - -.. toctree:: - :maxdepth: 2 - - installing - configuration - +.. _community_jdbcstore: + +JDBCStore +========== + +The ``JDBCStore module`` allows efficient sharing of configuration data in a clustered deployment of GeoServer. It allows externalising the storage of all configuration resources to a Relational Database Management System, rather than using the default File System based :ref:`datadir`. This way the multiple instances of GeoServer can use the same Database and therefore share in the same configuration. + +.. toctree:: + :maxdepth: 2 + + installing + configuration + diff --git a/doc/en/user/source/community/monitor-hibernate/index.rst b/doc/en/user/source/community/monitor-hibernate/index.rst index 5fa0d546fc9..14881575b91 100644 --- a/doc/en/user/source/community/monitor-hibernate/index.rst +++ b/doc/en/user/source/community/monitor-hibernate/index.rst @@ -1,18 +1,18 @@ -.. _monitor_hibernate_extension: - -Monitoring Hibernate storage -============================ - -The monitor hibernate storage allows to track the requests made against a GeoServer instance -in a relational database, as opposed to keeping the data in memory for a short time, or -logging it on a audit file. - -.. toctree:: - :maxdepth: 2 - - installation/ - configuration/ - db/ - upgrade/ - - +.. _monitor_hibernate_extension: + +Monitoring Hibernate storage +============================ + +The monitor hibernate storage allows to track the requests made against a GeoServer instance +in a relational database, as opposed to keeping the data in memory for a short time, or +logging it on a audit file. + +.. toctree:: + :maxdepth: 2 + + installation/ + configuration/ + db/ + upgrade/ + + diff --git a/doc/en/user/source/community/netcdf-ghrsst/index.rst b/doc/en/user/source/community/netcdf-ghrsst/index.rst index 9935c1dc803..be631297989 100644 --- a/doc/en/user/source/community/netcdf-ghrsst/index.rst +++ b/doc/en/user/source/community/netcdf-ghrsst/index.rst @@ -1,80 +1,80 @@ -.. _community_netcdf_ghrsst: - -GHRSST NetCDF output -===================== - -`GHRSST `_ is Group for High Resolution Sea Surface Temperature. -Among its various activities it issued a `specification on how sea surface temperature data should be organized -in NetCDF files `_. - -The NetCDF GHRSST module allows to generate complaint GHRSST files as WCS outputs, given a compliant GHRSST input. - -Installation ------------- - -As a community module, the package needs to be downloaded from the `nightly builds `_, -picking the community folder of the corresponding GeoServer series (e.g. if working on the GeoServer main development branch nightly -builds, pick the zip file form ``main/community-latest``). - -To install the module, unpack the zip file contents into GeoServer own ``WEB-INF/lib`` directory and -restart GeoServer. - -For the module to work, the :ref:`netcdf` and :ref:`netcdf-out` extensions must also be installed. - -Input preparation ------------------ - -A GHRSST file contains multiple variables that are related with each other, and should be explored -toghether in order to better understand the data. Thus, it is assumed that the source GHRSST file is published -as a single coverage view holding all the variables as bands, retaining their native name (this is important for -the plugin to work): - -.. figure:: images/coverageView.png - :align: center - - *Setting up a coverage view with all variables as bands* - -A GHRSST output must also have a time, so the time dimension of this layer should be enabled (the output generation will fail -with an error otherwise). - -At the time of writing a coverage view requires the source bands to be of uniform data type, and the data sources might -not be. In case setting up the view is not possible with the data available, a NCML file can be used to reprocess -the source NetCDF into one that has bands with uniform data type. A downloadable example has been provided to facilitate -setting up the view. - -:download:`Download the reference NCML transformation ` - - -The GHRSST may also have to be setup in a image mosaic in order to provide a deep temporal layer that users can select -data from. The image mosaic setup can be complex, so a downloadable example has been provided for it as well (will require -some changes, at a minimum, fix the paths at the bottom of indexer.xml, and the database connection parameters in the -two datastore properties files). - -:download:`Download the sample mosaic configuration files ` - - -Configuring GHRSST output -------------------------- - -The normal WCS NetCDF output will pick the first band of a coverage and generate a single variable NetCDF output. -When the GHRSST plugin is installed, a new UI element will show up that enables GHRSST output: - -.. figure:: images/ghrsstConfiguration.png - :align: center - - *Enabling GHRSST output mode* - -Notes about the configuration UI: - -* Various normal configurations such as variable name, unit of measure, and data packing will be ignored (each - variable in GHRSST has its own assigned data type and packing, as from specification) -* For the output to be compliant, enable copy of both global and per variable attributes -* The RDAC, Processing Level, SST Type and Product String have to be filled in order to generate a valid GHRSST - file name in output. The user interface provides auto-complete with names picked from the specification, but others - can be inputed as well. - -For the output to generate correctly the coverage band names have to follow exactly the expected specification variable -names (which comes naturally if the input is valid GHRSST), variable will be re-packed in output according to -specification, so even if the inputs are all floats, the output will follow the expected data types. - -Any extra coverage band not present in the specification will be copied from input to output un-modified. +.. _community_netcdf_ghrsst: + +GHRSST NetCDF output +===================== + +`GHRSST `_ is Group for High Resolution Sea Surface Temperature. +Among its various activities it issued a `specification on how sea surface temperature data should be organized +in NetCDF files `_. + +The NetCDF GHRSST module allows to generate complaint GHRSST files as WCS outputs, given a compliant GHRSST input. + +Installation +------------ + +As a community module, the package needs to be downloaded from the `nightly builds `_, +picking the community folder of the corresponding GeoServer series (e.g. if working on the GeoServer main development branch nightly +builds, pick the zip file form ``main/community-latest``). + +To install the module, unpack the zip file contents into GeoServer own ``WEB-INF/lib`` directory and +restart GeoServer. + +For the module to work, the :ref:`netcdf` and :ref:`netcdf-out` extensions must also be installed. + +Input preparation +----------------- + +A GHRSST file contains multiple variables that are related with each other, and should be explored +toghether in order to better understand the data. Thus, it is assumed that the source GHRSST file is published +as a single coverage view holding all the variables as bands, retaining their native name (this is important for +the plugin to work): + +.. figure:: images/coverageView.png + :align: center + + *Setting up a coverage view with all variables as bands* + +A GHRSST output must also have a time, so the time dimension of this layer should be enabled (the output generation will fail +with an error otherwise). + +At the time of writing a coverage view requires the source bands to be of uniform data type, and the data sources might +not be. In case setting up the view is not possible with the data available, a NCML file can be used to reprocess +the source NetCDF into one that has bands with uniform data type. A downloadable example has been provided to facilitate +setting up the view. + +:download:`Download the reference NCML transformation ` + + +The GHRSST may also have to be setup in a image mosaic in order to provide a deep temporal layer that users can select +data from. The image mosaic setup can be complex, so a downloadable example has been provided for it as well (will require +some changes, at a minimum, fix the paths at the bottom of indexer.xml, and the database connection parameters in the +two datastore properties files). + +:download:`Download the sample mosaic configuration files ` + + +Configuring GHRSST output +------------------------- + +The normal WCS NetCDF output will pick the first band of a coverage and generate a single variable NetCDF output. +When the GHRSST plugin is installed, a new UI element will show up that enables GHRSST output: + +.. figure:: images/ghrsstConfiguration.png + :align: center + + *Enabling GHRSST output mode* + +Notes about the configuration UI: + +* Various normal configurations such as variable name, unit of measure, and data packing will be ignored (each + variable in GHRSST has its own assigned data type and packing, as from specification) +* For the output to be compliant, enable copy of both global and per variable attributes +* The RDAC, Processing Level, SST Type and Product String have to be filled in order to generate a valid GHRSST + file name in output. The user interface provides auto-complete with names picked from the specification, but others + can be inputed as well. + +For the output to generate correctly the coverage band names have to follow exactly the expected specification variable +names (which comes naturally if the input is valid GHRSST), variable will be re-packed in output according to +specification, so even if the inputs are all floats, the output will follow the expected data types. + +Any extra coverage band not present in the specification will be copied from input to output un-modified. diff --git a/doc/en/user/source/community/ogr-store/index.rst b/doc/en/user/source/community/ogr-store/index.rst index 24c4e4045f3..b0caf9997ba 100644 --- a/doc/en/user/source/community/ogr-store/index.rst +++ b/doc/en/user/source/community/ogr-store/index.rst @@ -1,118 +1,118 @@ -.. _ogr_store: - -OGR datastore -============= - -The OGR datastore module allows to use the `GDAL/OGR ` native library -to access a wide variety of vector spatial formats and publish them in GeoServer. - -This library is recommended to use when a particular data source does not have a GeoServer pure Java -datastore fulfilling the same needs, in particular, compared to built in sources, it has the following limitations: - -* Generally slower than the existing pure Java counterparts, especially for map rendering (the GeoServer - stores can help rendering by providing reduced resolution version of the geometries, OGR provides no - such facility) -* Less scalable than the pure Java counterparts, as the DataSource objects used to access data are not - thread safe (see the pooling options below) -* More risky than the pure java counterparts, a SEGFAULT occurring inside OGR will take down the entire - GeoServer process (while a pure Java exception is managed and reported, but won't have consequences - on the server itself) - -The OGR store has been tested with GDAL 2.2.x, but might be working with other versions as well. -In case of malfunctions, you can try to remove the ``gdal-.jar`` file from the GeoServer -installation package, and replace it with the specific version jar instead, which you should find -in your GDAL installation. - - -Installing ----------- - -This is a community module, which means that it will not be available in the GeoServer official releases and needs to be installed manually. - -This module can be installed following these steps: - -1. Download this module package from the `nightly builds `_, the module version should match the desired GeoServer version. - -2. Extract the contents of the package into the ``WEB-INF/lib`` directory of the GeoServer installation. - -3. Make sure that the GDAL library as well as the GDAL JNI native library are available in the GeoServer path (see below). - -Linux installation details -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -On Linux the native librariers are commonly available via packages such as ``gdal`` and ``gdal-java``, -which, on installation, make available the required libraries on the file system (the specific name may vary):: - - /usr/lib/libgdal.so - /usr/lib/jni/libgdaljni.so - -Normally these directories are already in the ``PATH``, so no further configuration is required. - -If using a custom build instead, the ``LD_LIBRARY_PATH`` and ``GDAL_DATA`` directories:: - - export LD_LIBRARY_PATH /path/to/gdal/libraries - export GDAL_DATA /path/to/gdal/data - -See also the GDAL FAQ `about the GDAL_DATA setup `_. - -Windows installation details -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -On windows the files in question might look like:: - - gdal204.dll - gdalalljni.dll - -Locating a pre-build GDAL that includes Java support might be difficult. One option is to download -the `gisinternals.com `_ packages, in particular the -release zip packages including both mapserver and GDAL (these are rather complete and include the necessary libraries, -whilst the MSI installers are typically missing the Java support). - -Once the package is available on disk, one has to set the following environment variables before -starting GeoServer (the path might change depending on the package that is being downloaded):: - - set PATH=%PATH%;C:\path\to\release-1900-x64-gdal-2-4-0-mapserver-7-2-1\bin;C:\tmp\release-1900-x64-gdal-2-4-0-mapserver-7-2-1\bin\gdal\java - set GDAL_DRIVER_PATH=C:\path\to\release-1900-x64-gdal-2-4-0-mapserver-7-2-1\bin\gdal\plugins - set GDAL_DATA=C:\path\to\release-1900-x64-gdal-2-4-0-mapserver-7-2-1\bin\gdal-data - -Configuring a store -------------------- - -If the library is properly installed you will get the "OGR" data store among the supported stores -in the "new store" page. In case it's not there, check the logs, they might be reporting that -the GDAL/OGR native libs are missing, if the error is not there, check that the jars have been -unpacked in the right position instead. - -Creating a new store requires configuration of only the :guilabel:`DatasourceName` field, any other parameter is -optional: - -.. figure:: images/store_config.png - :align: center - - *The OGR datasore configuration page* - -The :guilabel:`DatasourceName` can be a reference to a file, a directory, or a set of connection parameters to -a server. For example, to connect to a PostGIS database the connection parameters could be: - - ``PG:user=theUser password=thePassword dbname=theDatabase`` - -Notice how, unlike documented in the OGR page, single quotes are not needed (and actually harmful) around the -user/password/dbname section. -The :guilabel:`Browse` button can be used to quickly peek files or directories from the file system. - -The :guilabel:`Driver` parameter is optional, OGR should be able to recognize the appropriate driver automatically, -but it's useful to force a specific choice when multiple competing drivers are available for the same -data source (e.g., OpenFileGDB vs FileGDB). - -The pooling parameters, similar to those found in a database, merit an explanation. -OGR exposes access to data throught DataSource objects, which are not thread safe, so only one -request at a time can use them. At the same time, they can be expensive to create and hold onto -useful state, like in memory data caches, spatial indexes and the like. -As such, they have been stored in a pool much like relational database connections. - -The :guilabel:`Prime DataSources` option can be enabled to force a full read of the source data -before the GDAL ``DataSource`` object is used. In some formats this allows the creation of useful -support data structures, like an in memory spatial index in the ``OpenFileGDB`` format. -Since the full read can be expensive, care should be taken to configure the pooling options so that -it gets reused as much as possible (e.g., setting a higher ``min connections``, eventually setting +.. _ogr_store: + +OGR datastore +============= + +The OGR datastore module allows to use the `GDAL/OGR ` native library +to access a wide variety of vector spatial formats and publish them in GeoServer. + +This library is recommended to use when a particular data source does not have a GeoServer pure Java +datastore fulfilling the same needs, in particular, compared to built in sources, it has the following limitations: + +* Generally slower than the existing pure Java counterparts, especially for map rendering (the GeoServer + stores can help rendering by providing reduced resolution version of the geometries, OGR provides no + such facility) +* Less scalable than the pure Java counterparts, as the DataSource objects used to access data are not + thread safe (see the pooling options below) +* More risky than the pure java counterparts, a SEGFAULT occurring inside OGR will take down the entire + GeoServer process (while a pure Java exception is managed and reported, but won't have consequences + on the server itself) + +The OGR store has been tested with GDAL 2.2.x, but might be working with other versions as well. +In case of malfunctions, you can try to remove the ``gdal-.jar`` file from the GeoServer +installation package, and replace it with the specific version jar instead, which you should find +in your GDAL installation. + + +Installing +---------- + +This is a community module, which means that it will not be available in the GeoServer official releases and needs to be installed manually. + +This module can be installed following these steps: + +1. Download this module package from the `nightly builds `_, the module version should match the desired GeoServer version. + +2. Extract the contents of the package into the ``WEB-INF/lib`` directory of the GeoServer installation. + +3. Make sure that the GDAL library as well as the GDAL JNI native library are available in the GeoServer path (see below). + +Linux installation details +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On Linux the native librariers are commonly available via packages such as ``gdal`` and ``gdal-java``, +which, on installation, make available the required libraries on the file system (the specific name may vary):: + + /usr/lib/libgdal.so + /usr/lib/jni/libgdaljni.so + +Normally these directories are already in the ``PATH``, so no further configuration is required. + +If using a custom build instead, the ``LD_LIBRARY_PATH`` and ``GDAL_DATA`` directories:: + + export LD_LIBRARY_PATH /path/to/gdal/libraries + export GDAL_DATA /path/to/gdal/data + +See also the GDAL FAQ `about the GDAL_DATA setup `_. + +Windows installation details +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On windows the files in question might look like:: + + gdal204.dll + gdalalljni.dll + +Locating a pre-build GDAL that includes Java support might be difficult. One option is to download +the `gisinternals.com `_ packages, in particular the +release zip packages including both mapserver and GDAL (these are rather complete and include the necessary libraries, +whilst the MSI installers are typically missing the Java support). + +Once the package is available on disk, one has to set the following environment variables before +starting GeoServer (the path might change depending on the package that is being downloaded):: + + set PATH=%PATH%;C:\path\to\release-1900-x64-gdal-2-4-0-mapserver-7-2-1\bin;C:\tmp\release-1900-x64-gdal-2-4-0-mapserver-7-2-1\bin\gdal\java + set GDAL_DRIVER_PATH=C:\path\to\release-1900-x64-gdal-2-4-0-mapserver-7-2-1\bin\gdal\plugins + set GDAL_DATA=C:\path\to\release-1900-x64-gdal-2-4-0-mapserver-7-2-1\bin\gdal-data + +Configuring a store +------------------- + +If the library is properly installed you will get the "OGR" data store among the supported stores +in the "new store" page. In case it's not there, check the logs, they might be reporting that +the GDAL/OGR native libs are missing, if the error is not there, check that the jars have been +unpacked in the right position instead. + +Creating a new store requires configuration of only the :guilabel:`DatasourceName` field, any other parameter is +optional: + +.. figure:: images/store_config.png + :align: center + + *The OGR datasore configuration page* + +The :guilabel:`DatasourceName` can be a reference to a file, a directory, or a set of connection parameters to +a server. For example, to connect to a PostGIS database the connection parameters could be: + + ``PG:user=theUser password=thePassword dbname=theDatabase`` + +Notice how, unlike documented in the OGR page, single quotes are not needed (and actually harmful) around the +user/password/dbname section. +The :guilabel:`Browse` button can be used to quickly peek files or directories from the file system. + +The :guilabel:`Driver` parameter is optional, OGR should be able to recognize the appropriate driver automatically, +but it's useful to force a specific choice when multiple competing drivers are available for the same +data source (e.g., OpenFileGDB vs FileGDB). + +The pooling parameters, similar to those found in a database, merit an explanation. +OGR exposes access to data throught DataSource objects, which are not thread safe, so only one +request at a time can use them. At the same time, they can be expensive to create and hold onto +useful state, like in memory data caches, spatial indexes and the like. +As such, they have been stored in a pool much like relational database connections. + +The :guilabel:`Prime DataSources` option can be enabled to force a full read of the source data +before the GDAL ``DataSource`` object is used. In some formats this allows the creation of useful +support data structures, like an in memory spatial index in the ``OpenFileGDB`` format. +Since the full read can be expensive, care should be taken to configure the pooling options so that +it gets reused as much as possible (e.g., setting a higher ``min connections``, eventually setting it to the same value as ``max connections``). \ No newline at end of file diff --git a/doc/en/user/source/community/solr/configure.rst b/doc/en/user/source/community/solr/configure.rst index df25c2f7fc1..bafd961af25 100644 --- a/doc/en/user/source/community/solr/configure.rst +++ b/doc/en/user/source/community/solr/configure.rst @@ -1,156 +1,156 @@ -.. _community_solr_configure: - -SOLR layer configuration -======================== - -Mapping documents to layers ---------------------------- - -SOLR indexes almost free form documents, the SOLR instance has a collection of fields, and -each document can contain any field, in any combination. -On the other side, GeoServer organizes data in fixed structure feature types, and exposes -data in separate layers. This leaves the question of how documents in the index -should be organized into layers. - -By default the store exposes a single layer, normally named after the SOLR collection the store is connected -to, by publishing it one can decide which fields to include, and eventually add a filter -to select which attributes it will contain. - -This single layer can be published multiple times, giving each published layer a different name, -set of selected attributes, and a different filter to select the documents contained in the layer. - -Installing the SOLR extension ------------------------------------ - -#. Download the SOLR extension from the `nightly GeoServer community module builds `_. - - .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance. - -#. If GeoServer is running, stop it. - -#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. - -#. Restart GeoServer, the SOLR data store should show up as an option when going through the new store - creation workflow. - -Connecting to a SOLR server ----------------------------- - -Once the extension is properly installed ``SOLR`` will show up as an option when creating a new data store. - -.. figure:: images/solr_store.png - :align: center - - *SOLR in the list of vector data sources* - -.. _community_solr_configure_store: - -Configuring a SOLR data store ------------------------------ - -.. figure:: images/solr_configuration.png - :align: center - - *Configuring a SOLR data store* - -.. list-table:: - :widths: 20 80 - - * - ``solr_url`` - - Provide a link to the SOLR server that provides the documents - -Once the parameters are entered and confirmed, GeoServer will contact the SOLR server and -fetch a list of layer names and fill the layer chooser page accordingly: - -.. figure:: images/solr_layerlist.png - :align: center - - *List of layers available in the SOLR server* - -Configuring a new SOLR base layer ---------------------------------- - -Once the layer name is chosen, the usual layer configuration panel will appear, with a pop-up showing -in a table the fields available: - -.. figure:: images/solr_fieldlist.png - :align: center - - *The layer field list configuration* - -.. list-table:: - :widths: 20 80 - - * - ``Is empty`` - - Read only fields, checked if the field has no values in the documents associated to this layer - * - ``Use`` - - Used to select the fields that will make up this layer features - * - ``Name`` - - Name of the field - * - ``Type`` - - Type of the field, as derived from the SOLR schema. For geometry types, you have the option to provide a more specific data type - * - ``SRID`` - - Native spatial reference ID of the geometries - * - ``Default geometry`` - - Indicates if the geometry field is the default one. Useful if the documents contain more than one geometry field, - as SLDs and spatial filters will hit the default geometry field unless otherwise specified - * - ``Identifier`` - - Check if the field can be used as the feature identifier - - -By default the list will contain only the fields that have at least one non null value in the documents -associated to the layer, but it is possible to get the full list by un-checking the "Hide field if empty" -check-box: - -.. figure:: images/solr_fieldlist_all.png - :align: center - - *Showing all fields available in SOLR* - -Once the table is filled with the all the required parameters, press the "Apply" button to confirm -and go back to the main layer configuration panel. -Should the choice of fields be modified, you can click the "Configure SOLR fields" just below the "Feature Type Details" panel. - -.. figure:: images/solr_fieldlist_edit.png - :align: center - - *Going back to the field list editor* - -The rest of the layer configuration works as normal, once all the fields are provided you'll be able to -save and use the layer in WMS and WFS. - -.. warning:: In order to compute the bounding box GeoServer will have to fetch all the geometries making up the layer out of SOLR, - this operation might take some time, you're advised to manually entered the native bounding box when configuring a - layer out of a large document set - -Custom ``q`` and ``fq`` parameters ----------------------------------- - -The SOLR store will translate most OGC filters, as specified in SLD, CQL Filter or OGC filter, -down into the SOLR engine for native filtering, using the ``fq`` parameter. -However, in some occasions you might need to specify manually either ``q`` or ``fq``, to leverage -some native SOLR filtering ability that cannot be expressed via OGC filters. - -This can be done by specifying those as ``viewparams``, pretty much like in parametric sql views -atop relational databases. - -For example, the following URL:: - - http://localhost:8080/geoserver/nurc/wms?service=WMS&version=1.1.0&request=GetMap - &layers=nurc:active&styles=geo2&bbox=0.0,0.0,24.0,44.0&width=279&height=512 - &srs=EPSG:4326&format=application/openlayers - &viewparams=fq:security_ss:WEP - -Will send down to SOLR a query looking like:: - - omitHeader=true&fl=geo,id&q=*:*&rows=2147483647&sort=id asc - &fq=status_s:active AND geo:"Intersects(POLYGON ((-0.125 -0.5333333333333333, -0.125 44.53333333333333, - 24.125 44.53333333333333, 24.125 -0.5333333333333333, -0.125 -0.5333333333333333)))" - &fq=security_ss:WEP&cursorMark=* - -You can notice that: - -* Only the columns needed for the display (in this case, a single geometry) are retrieved -* The bbox and layer identification filters are specified in the first ``fq`` -* The custom ``fq`` is passed as a second ``fq`` parameter (SOLR will treat it as being and-ed with - the previuos one) +.. _community_solr_configure: + +SOLR layer configuration +======================== + +Mapping documents to layers +--------------------------- + +SOLR indexes almost free form documents, the SOLR instance has a collection of fields, and +each document can contain any field, in any combination. +On the other side, GeoServer organizes data in fixed structure feature types, and exposes +data in separate layers. This leaves the question of how documents in the index +should be organized into layers. + +By default the store exposes a single layer, normally named after the SOLR collection the store is connected +to, by publishing it one can decide which fields to include, and eventually add a filter +to select which attributes it will contain. + +This single layer can be published multiple times, giving each published layer a different name, +set of selected attributes, and a different filter to select the documents contained in the layer. + +Installing the SOLR extension +----------------------------------- + +#. Download the SOLR extension from the `nightly GeoServer community module builds `_. + + .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance. + +#. If GeoServer is running, stop it. + +#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. + +#. Restart GeoServer, the SOLR data store should show up as an option when going through the new store + creation workflow. + +Connecting to a SOLR server +---------------------------- + +Once the extension is properly installed ``SOLR`` will show up as an option when creating a new data store. + +.. figure:: images/solr_store.png + :align: center + + *SOLR in the list of vector data sources* + +.. _community_solr_configure_store: + +Configuring a SOLR data store +----------------------------- + +.. figure:: images/solr_configuration.png + :align: center + + *Configuring a SOLR data store* + +.. list-table:: + :widths: 20 80 + + * - ``solr_url`` + - Provide a link to the SOLR server that provides the documents + +Once the parameters are entered and confirmed, GeoServer will contact the SOLR server and +fetch a list of layer names and fill the layer chooser page accordingly: + +.. figure:: images/solr_layerlist.png + :align: center + + *List of layers available in the SOLR server* + +Configuring a new SOLR base layer +--------------------------------- + +Once the layer name is chosen, the usual layer configuration panel will appear, with a pop-up showing +in a table the fields available: + +.. figure:: images/solr_fieldlist.png + :align: center + + *The layer field list configuration* + +.. list-table:: + :widths: 20 80 + + * - ``Is empty`` + - Read only fields, checked if the field has no values in the documents associated to this layer + * - ``Use`` + - Used to select the fields that will make up this layer features + * - ``Name`` + - Name of the field + * - ``Type`` + - Type of the field, as derived from the SOLR schema. For geometry types, you have the option to provide a more specific data type + * - ``SRID`` + - Native spatial reference ID of the geometries + * - ``Default geometry`` + - Indicates if the geometry field is the default one. Useful if the documents contain more than one geometry field, + as SLDs and spatial filters will hit the default geometry field unless otherwise specified + * - ``Identifier`` + - Check if the field can be used as the feature identifier + + +By default the list will contain only the fields that have at least one non null value in the documents +associated to the layer, but it is possible to get the full list by un-checking the "Hide field if empty" +check-box: + +.. figure:: images/solr_fieldlist_all.png + :align: center + + *Showing all fields available in SOLR* + +Once the table is filled with the all the required parameters, press the "Apply" button to confirm +and go back to the main layer configuration panel. +Should the choice of fields be modified, you can click the "Configure SOLR fields" just below the "Feature Type Details" panel. + +.. figure:: images/solr_fieldlist_edit.png + :align: center + + *Going back to the field list editor* + +The rest of the layer configuration works as normal, once all the fields are provided you'll be able to +save and use the layer in WMS and WFS. + +.. warning:: In order to compute the bounding box GeoServer will have to fetch all the geometries making up the layer out of SOLR, + this operation might take some time, you're advised to manually entered the native bounding box when configuring a + layer out of a large document set + +Custom ``q`` and ``fq`` parameters +---------------------------------- + +The SOLR store will translate most OGC filters, as specified in SLD, CQL Filter or OGC filter, +down into the SOLR engine for native filtering, using the ``fq`` parameter. +However, in some occasions you might need to specify manually either ``q`` or ``fq``, to leverage +some native SOLR filtering ability that cannot be expressed via OGC filters. + +This can be done by specifying those as ``viewparams``, pretty much like in parametric sql views +atop relational databases. + +For example, the following URL:: + + http://localhost:8080/geoserver/nurc/wms?service=WMS&version=1.1.0&request=GetMap + &layers=nurc:active&styles=geo2&bbox=0.0,0.0,24.0,44.0&width=279&height=512 + &srs=EPSG:4326&format=application/openlayers + &viewparams=fq:security_ss:WEP + +Will send down to SOLR a query looking like:: + + omitHeader=true&fl=geo,id&q=*:*&rows=2147483647&sort=id asc + &fq=status_s:active AND geo:"Intersects(POLYGON ((-0.125 -0.5333333333333333, -0.125 44.53333333333333, + 24.125 44.53333333333333, 24.125 -0.5333333333333333, -0.125 -0.5333333333333333)))" + &fq=security_ss:WEP&cursorMark=* + +You can notice that: + +* Only the columns needed for the display (in this case, a single geometry) are retrieved +* The bbox and layer identification filters are specified in the first ``fq`` +* The custom ``fq`` is passed as a second ``fq`` parameter (SOLR will treat it as being and-ed with + the previuos one) diff --git a/doc/en/user/source/community/solr/index.rst b/doc/en/user/source/community/solr/index.rst index 05543484994..60f0601b563 100644 --- a/doc/en/user/source/community/solr/index.rst +++ b/doc/en/user/source/community/solr/index.rst @@ -1,29 +1,29 @@ -.. _community_solr: - -SOLR data store -=============== - -`SOLR `_ is a popular search platform based on Apache Lucene project. -Its major features include powerful full-text search, hit highlighting, faceted search, near real-time indexing, -dynamic clustering, database integration, rich document (e.g., Word, PDF) handling, and most -importantly for the GeoServer integration, geospatial search. - -The latest versions of SOLR can host most basic types of geometries (points, lines and polygons) -as WKT and index them with a spatial index. - -.. note:: GeoServer does not come built-in with support for SOLR; it must be installed through this community module. - -The GeoServer SOLR extension has been tested with SOLR version 4.8, 4.9, and 4.10. - -The extension supports all WKT geometry types (all linear types, point, lines and polygons, SQL/MMcurves are not supported), -plus "bounding box" (available starting SOLR 4.10). -It does not support the ``solr.LatLonType`` type yet. - -The following pages shows how to use the SOLR data store. - -.. toctree:: - :maxdepth: 2 - - configure - load - optimize +.. _community_solr: + +SOLR data store +=============== + +`SOLR `_ is a popular search platform based on Apache Lucene project. +Its major features include powerful full-text search, hit highlighting, faceted search, near real-time indexing, +dynamic clustering, database integration, rich document (e.g., Word, PDF) handling, and most +importantly for the GeoServer integration, geospatial search. + +The latest versions of SOLR can host most basic types of geometries (points, lines and polygons) +as WKT and index them with a spatial index. + +.. note:: GeoServer does not come built-in with support for SOLR; it must be installed through this community module. + +The GeoServer SOLR extension has been tested with SOLR version 4.8, 4.9, and 4.10. + +The extension supports all WKT geometry types (all linear types, point, lines and polygons, SQL/MMcurves are not supported), +plus "bounding box" (available starting SOLR 4.10). +It does not support the ``solr.LatLonType`` type yet. + +The following pages shows how to use the SOLR data store. + +.. toctree:: + :maxdepth: 2 + + configure + load + optimize diff --git a/doc/en/user/source/community/solr/load.rst b/doc/en/user/source/community/solr/load.rst index ce6f485faa1..251168a20f8 100644 --- a/doc/en/user/source/community/solr/load.rst +++ b/doc/en/user/source/community/solr/load.rst @@ -1,80 +1,80 @@ -.. _community_solr_load: - -Loading spatial data into SOLR ------------------------------- - -This section provides a simple example on how to convert and load a shapefile into a SOLR instance. -For more advanced needs and details about spatial support in SOLR consult the SOLR documentation, -making sure to read the one associated to the version at hand (spatial support is still rapidly -evolving). - -The current example has been developed and tested using GDAL 1.11 and SOLR 4.8, different versions -of the tools and server might require a different syntax for upload. - -The SOLR instance is supposed to have the following definitions in its schema: - -.. code-block:: xml - - - - - -The above defines "geo" as explicit fields, leaving the other types to dynamic field interpretation. - -The SpatialRecursivePrefixTreeFieldType accepts geometries as WKT, so as a preparation for the -import we are going to turn a shapefile into a CSV file with WKT syntax for the geometry. -Let's also remember that SOLR needs a unique id field for the records, and that the coordinates -are supposed to be in WGS84. -The shapefile in question is instead in UTM, has a linestring geometry, and some fields, cat,id and label. - -The following command translates the shapefile in CSV (the command should be typed in a single line, -it has been split over multiple lines for ease of reading):: - - ogr2ogr -f CSV - -sql 'select FID as id, cat as cat_i, label as label_s, - "roads" as layer FROM roads' - -lco geometry=AS_WKT -s_srs "EPSG:26713" -t_srs "EPSG:4326" - /tmp/roads.csv roads.shp - -Some observations: - - * The SQL is used mostly to include the special FID field into the results (a unique field is required) - * The reprojection is performed to ensure the output geometries are in WGS84 - * The ``layer_s`` dynamic field is added to - -.. note: - - The "roads" syntax might not work correctly starting from GDAL 2.0, where a single quote should be - used instead. Starting with GDAL 2.1 it will also be possible to add a ``-lco GEOMETRY_NAME=geo`` - to directly set the desired geometry name - -This will generate a CSV file looking as follows:: - - WKT,id,cat_i,label_s,layer - "LINESTRING (-103.763291353072518 44.375039982911382,-103.763393874038698 44.375282535746727,-103.764152625689903 44.376816068582023,-103.763893508430911 44.377653708326527,-103.76287152579593 44.378473197876396,-103.762075892308829 44.379009292692757,-103.76203441159079 44.379195585236509,-103.762124217456204 44.379295262047272,-103.762168141872152 44.379399997909999,-103.762326134985983 44.379527769244149,-103.763328403265064 44.380245486928708,-103.764011871363465 44.381295133519728,-103.76411460103661 44.381526706124056,-103.764953940327757 44.382396618315049,-103.765097289111338 44.382919576408355,-103.765147974157941 44.383073790503197,-103.76593766187851 44.384162856249255,-103.765899236602976 44.384607239970421,-103.765854384388703 44.384597320206453)",0,5,unimproved road,roads - "LINESTRING (-103.762930948900078 44.385847721442218,-103.763012156628747 44.386002223293282,-103.763510654805799 44.386297912655408,-103.763869052966967 44.386746022746649,-103.763971116268394 44.387444295314552,-103.764244098825387 44.387545690358827,-103.764264649212294 44.387677659170357,-103.764160551326043 44.387951214930865,-103.764540576800869 44.388042632912118,-103.764851624437995 44.388149874425885,-103.764841258550391 44.388303515682807,-103.76484332449354 44.388616502755184,-103.765188923261391 44.388927221995502,-103.765110961905023 44.389448103450221,-103.765245311197177 44.389619574129583,-103.765545516097987 44.389907903843323,-103.765765403056434 44.390420596862072,-103.766285436779711 44.391655378673697,-103.766354640463163 44.39205684519964,-103.76638734105434 44.392364628456725,-103.766410556756725 44.392776645318136,-103.765934443919321 44.393365174368313,-103.766220869020188 44.393571013181166,-103.766661604125247 44.393684955690581,-103.767294323528063 44.393734806102117,-103.767623238680557 44.394127721518785,-103.769273719703676 44.394900867042516,-103.769609703946827 44.395326786724503,-103.769732072038536 44.395745219647871,-103.769609607364416 44.396194309461826,-103.769310708537489 44.396691166475954,-103.768865902286791 44.397236074649896)",1,5,unimproved road,roads - -At this point the CSV can be imported into SOLR using CURL:: - - curl "http://solr.geo-solutions.it/solr/collection1/update/csv?commit=true&separator=%2C&fieldnames=geo,id,cat_i,label_s,layer_s&header=true" - -H 'Content-type:text/csv; charset=utf-8' --data-binary @/tmp/roads.csv - -Some observations: - - * The files gets uploaded as a ``text/csv`` file, older versions might require a ``text/plain`` mime type - * The ``fieldnames`` overrides the CSV header and allows us to specify the field name as expected by SOLR - -At this point it's possible to configure a layer showing only the roads in the GeoServer UI: - -.. figure:: images/solr_roads_configure.png - :align: center - - *Setting up the roads layer* - -After setting the bounding box and the proper style, the layer preview will show the roads stored -in SOLR: - -.. figure:: images/solr_roads_preview.png - :align: center - +.. _community_solr_load: + +Loading spatial data into SOLR +------------------------------ + +This section provides a simple example on how to convert and load a shapefile into a SOLR instance. +For more advanced needs and details about spatial support in SOLR consult the SOLR documentation, +making sure to read the one associated to the version at hand (spatial support is still rapidly +evolving). + +The current example has been developed and tested using GDAL 1.11 and SOLR 4.8, different versions +of the tools and server might require a different syntax for upload. + +The SOLR instance is supposed to have the following definitions in its schema: + +.. code-block:: xml + + + + + +The above defines "geo" as explicit fields, leaving the other types to dynamic field interpretation. + +The SpatialRecursivePrefixTreeFieldType accepts geometries as WKT, so as a preparation for the +import we are going to turn a shapefile into a CSV file with WKT syntax for the geometry. +Let's also remember that SOLR needs a unique id field for the records, and that the coordinates +are supposed to be in WGS84. +The shapefile in question is instead in UTM, has a linestring geometry, and some fields, cat,id and label. + +The following command translates the shapefile in CSV (the command should be typed in a single line, +it has been split over multiple lines for ease of reading):: + + ogr2ogr -f CSV + -sql 'select FID as id, cat as cat_i, label as label_s, + "roads" as layer FROM roads' + -lco geometry=AS_WKT -s_srs "EPSG:26713" -t_srs "EPSG:4326" + /tmp/roads.csv roads.shp + +Some observations: + + * The SQL is used mostly to include the special FID field into the results (a unique field is required) + * The reprojection is performed to ensure the output geometries are in WGS84 + * The ``layer_s`` dynamic field is added to + +.. note: + + The "roads" syntax might not work correctly starting from GDAL 2.0, where a single quote should be + used instead. Starting with GDAL 2.1 it will also be possible to add a ``-lco GEOMETRY_NAME=geo`` + to directly set the desired geometry name + +This will generate a CSV file looking as follows:: + + WKT,id,cat_i,label_s,layer + "LINESTRING (-103.763291353072518 44.375039982911382,-103.763393874038698 44.375282535746727,-103.764152625689903 44.376816068582023,-103.763893508430911 44.377653708326527,-103.76287152579593 44.378473197876396,-103.762075892308829 44.379009292692757,-103.76203441159079 44.379195585236509,-103.762124217456204 44.379295262047272,-103.762168141872152 44.379399997909999,-103.762326134985983 44.379527769244149,-103.763328403265064 44.380245486928708,-103.764011871363465 44.381295133519728,-103.76411460103661 44.381526706124056,-103.764953940327757 44.382396618315049,-103.765097289111338 44.382919576408355,-103.765147974157941 44.383073790503197,-103.76593766187851 44.384162856249255,-103.765899236602976 44.384607239970421,-103.765854384388703 44.384597320206453)",0,5,unimproved road,roads + "LINESTRING (-103.762930948900078 44.385847721442218,-103.763012156628747 44.386002223293282,-103.763510654805799 44.386297912655408,-103.763869052966967 44.386746022746649,-103.763971116268394 44.387444295314552,-103.764244098825387 44.387545690358827,-103.764264649212294 44.387677659170357,-103.764160551326043 44.387951214930865,-103.764540576800869 44.388042632912118,-103.764851624437995 44.388149874425885,-103.764841258550391 44.388303515682807,-103.76484332449354 44.388616502755184,-103.765188923261391 44.388927221995502,-103.765110961905023 44.389448103450221,-103.765245311197177 44.389619574129583,-103.765545516097987 44.389907903843323,-103.765765403056434 44.390420596862072,-103.766285436779711 44.391655378673697,-103.766354640463163 44.39205684519964,-103.76638734105434 44.392364628456725,-103.766410556756725 44.392776645318136,-103.765934443919321 44.393365174368313,-103.766220869020188 44.393571013181166,-103.766661604125247 44.393684955690581,-103.767294323528063 44.393734806102117,-103.767623238680557 44.394127721518785,-103.769273719703676 44.394900867042516,-103.769609703946827 44.395326786724503,-103.769732072038536 44.395745219647871,-103.769609607364416 44.396194309461826,-103.769310708537489 44.396691166475954,-103.768865902286791 44.397236074649896)",1,5,unimproved road,roads + +At this point the CSV can be imported into SOLR using CURL:: + + curl "http://solr.geo-solutions.it/solr/collection1/update/csv?commit=true&separator=%2C&fieldnames=geo,id,cat_i,label_s,layer_s&header=true" + -H 'Content-type:text/csv; charset=utf-8' --data-binary @/tmp/roads.csv + +Some observations: + + * The files gets uploaded as a ``text/csv`` file, older versions might require a ``text/plain`` mime type + * The ``fieldnames`` overrides the CSV header and allows us to specify the field name as expected by SOLR + +At this point it's possible to configure a layer showing only the roads in the GeoServer UI: + +.. figure:: images/solr_roads_configure.png + :align: center + + *Setting up the roads layer* + +After setting the bounding box and the proper style, the layer preview will show the roads stored +in SOLR: + +.. figure:: images/solr_roads_preview.png + :align: center + *Preview roads from SOLR layer* \ No newline at end of file diff --git a/doc/en/user/source/community/solr/optimize.rst b/doc/en/user/source/community/solr/optimize.rst index 3321792370e..e1e698d3c5b 100644 --- a/doc/en/user/source/community/solr/optimize.rst +++ b/doc/en/user/source/community/solr/optimize.rst @@ -1,50 +1,50 @@ -.. _community_solr_optimize: - -Optimize rendering of complex polygons --------------------------------------- - -Rendering large maps with complex polygons, to show the overall distribution of the data, can -take a significant toll, especially if GeoServer cannot connect to the SOLR server via a high -speed network. - -A common approach to handle this issue is to add a second geometry to the SOLR documents, -representing the centroid of the polygon, and using that one to render the features when -fairly zoomed out. - -Once the SOLR documents have been updated with a centroid column, and it has been populated, -the column can be added as a secondary geometry. Make sure to keep the polygonal geometry -as the default one: - -.. figure:: images/optimize_ft1.png - :align: center - -... (other fields omitted) - -.. figure:: images/optimize_ft2.png - :align: center - - - *Configuring a layer with multiple geometries* - -With this setup the polygonal geometry will still be used for all spatial filters, and for -rendering, unless the style otherwise specifical demands for the centroid. - -Then, a style with scale dependencies can be setup in order to fetch only then centroids -when fairly zoomed out, like in the following CSS example: :: - - [@scale > 50000] { - geometry: [centroid]; - mark: symbol(square); - } - :mark { - fill: red; - size: 3; - }​ - [@scale <= 50000] { - fill: red; - stroke: black; - } - -Using this style the ``spatial`` field will still be used to resolve the BBOX filter implicit -in the WMS requests, but only the much smaller ``centroid`` one will be transferred to GeoServer +.. _community_solr_optimize: + +Optimize rendering of complex polygons +-------------------------------------- + +Rendering large maps with complex polygons, to show the overall distribution of the data, can +take a significant toll, especially if GeoServer cannot connect to the SOLR server via a high +speed network. + +A common approach to handle this issue is to add a second geometry to the SOLR documents, +representing the centroid of the polygon, and using that one to render the features when +fairly zoomed out. + +Once the SOLR documents have been updated with a centroid column, and it has been populated, +the column can be added as a secondary geometry. Make sure to keep the polygonal geometry +as the default one: + +.. figure:: images/optimize_ft1.png + :align: center + +... (other fields omitted) + +.. figure:: images/optimize_ft2.png + :align: center + + + *Configuring a layer with multiple geometries* + +With this setup the polygonal geometry will still be used for all spatial filters, and for +rendering, unless the style otherwise specifical demands for the centroid. + +Then, a style with scale dependencies can be setup in order to fetch only then centroids +when fairly zoomed out, like in the following CSS example: :: + + [@scale > 50000] { + geometry: [centroid]; + mark: symbol(square); + } + :mark { + fill: red; + size: 3; + }​ + [@scale <= 50000] { + fill: red; + stroke: black; + } + +Using this style the ``spatial`` field will still be used to resolve the BBOX filter implicit +in the WMS requests, but only the much smaller ``centroid`` one will be transferred to GeoServer for rendering. \ No newline at end of file diff --git a/doc/en/user/source/configuration/crshandling/configurecrs.rst b/doc/en/user/source/configuration/crshandling/configurecrs.rst index 2b50d96caf3..2b380ef6357 100644 --- a/doc/en/user/source/configuration/crshandling/configurecrs.rst +++ b/doc/en/user/source/configuration/crshandling/configurecrs.rst @@ -1,37 +1,37 @@ -.. _crs_configure: - -Coordinate Reference System Configuration -========================================= - -When adding data, GeoServer tries to inspect data headers looking for an EPSG code: - -* If the data has a CRS with an explicit EPSG code and the full CRS definition behind the code matches the one in GeoServer, the CRS will be already set for the data. -* If the data has a CRS but no EPSG code, you can use the :guilabel:`Find` option on the :ref:`data_webadmin_layers` page to make GeoServer perform a lookup operation where the data CRS is compared against every other known CRS. If this succeeds, an EPSG code will be selected. The common case for a CRS that has no EPSG code is shapefiles whose .PRJ file contains a valid WKT string without the EPSG identifiers (as these are optional). - -If an EPSG code cannot be found, then either the data has no CRS or it is unknown to GeoServer. In this case, there are a few options: - -* Force the declared CRS, ignoring the native one. This is the best solution if the native CRS is known to be wrong. -* Reproject from the native to the declared CRS. This is the best solution if the native CRS is correct, but cannot be matched to an EPSG number. (An alternative is to add a custom EPSG code that matches exactly the native SRS. See the section on :ref:`crs_custom` for more information.) - -If your data has no native CRS information, the only option is to specify/force an EPSG code. - -Increasing Comparison Tolerance -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Decimal numbers comparisons are made using a comparison tolerance. This means, as an instance, that an ellipsoid's semi_major axis -equals a candidate EPSG's ellipsoid semi_major axis only if their difference is within that tolerance. -Default value is 10^-9 although it can be changed by setting a COMPARISON_TOLERANCE Java System property to your container's JVM to specify a different value. - -.. warning:: - - The default value should be changed only if you are aware of use cases which require a wider tolerance. - Don't change it unless really needed (See the following example). - -Example -....... - -* Your sample dataset is known to be a LambertConformalConic projection and the related EPSG code defines latitude_of_origin value = 25.0. -* The coverageStore plugin is exposing raster projection details through a third party library which provides projection parameter definitions as float numbers. -* Due to the underlying math computations occurring in that third party library, the exposed projection parameters are subject to some accuracy loss, so that the provided latitude_of_origin is something like 25.0000012 whilst all the other params match the EPSG definition. -* You notice that the native CRS isn't properly recognized as the expected EPSG due to that small difference in latitude_of_origin - -In that case you could consider increasing a bit the tolerance. +.. _crs_configure: + +Coordinate Reference System Configuration +========================================= + +When adding data, GeoServer tries to inspect data headers looking for an EPSG code: + +* If the data has a CRS with an explicit EPSG code and the full CRS definition behind the code matches the one in GeoServer, the CRS will be already set for the data. +* If the data has a CRS but no EPSG code, you can use the :guilabel:`Find` option on the :ref:`data_webadmin_layers` page to make GeoServer perform a lookup operation where the data CRS is compared against every other known CRS. If this succeeds, an EPSG code will be selected. The common case for a CRS that has no EPSG code is shapefiles whose .PRJ file contains a valid WKT string without the EPSG identifiers (as these are optional). + +If an EPSG code cannot be found, then either the data has no CRS or it is unknown to GeoServer. In this case, there are a few options: + +* Force the declared CRS, ignoring the native one. This is the best solution if the native CRS is known to be wrong. +* Reproject from the native to the declared CRS. This is the best solution if the native CRS is correct, but cannot be matched to an EPSG number. (An alternative is to add a custom EPSG code that matches exactly the native SRS. See the section on :ref:`crs_custom` for more information.) + +If your data has no native CRS information, the only option is to specify/force an EPSG code. + +Increasing Comparison Tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Decimal numbers comparisons are made using a comparison tolerance. This means, as an instance, that an ellipsoid's semi_major axis +equals a candidate EPSG's ellipsoid semi_major axis only if their difference is within that tolerance. +Default value is 10^-9 although it can be changed by setting a COMPARISON_TOLERANCE Java System property to your container's JVM to specify a different value. + +.. warning:: + + The default value should be changed only if you are aware of use cases which require a wider tolerance. + Don't change it unless really needed (See the following example). + +Example +....... + +* Your sample dataset is known to be a LambertConformalConic projection and the related EPSG code defines latitude_of_origin value = 25.0. +* The coverageStore plugin is exposing raster projection details through a third party library which provides projection parameter definitions as float numbers. +* Due to the underlying math computations occurring in that third party library, the exposed projection parameters are subject to some accuracy loss, so that the provided latitude_of_origin is something like 25.0000012 whilst all the other params match the EPSG definition. +* You notice that the native CRS isn't properly recognized as the expected EPSG due to that small difference in latitude_of_origin + +In that case you could consider increasing a bit the tolerance. diff --git a/doc/en/user/source/configuration/crshandling/customcrs.rst b/doc/en/user/source/configuration/crshandling/customcrs.rst index e694a370fa8..4d622360a3b 100644 --- a/doc/en/user/source/configuration/crshandling/customcrs.rst +++ b/doc/en/user/source/configuration/crshandling/customcrs.rst @@ -1,128 +1,128 @@ -.. _crs_custom: - -Custom CRS Definitions -====================== - -Add a custom CRS ----------------- - -This example shows how to add a custom projection in GeoServer. - -#. The projection parameters need to be provided as a WKT (well known text) definition. The code sample below is just an example:: - - PROJCS["NAD83 / Austin", - GEOGCS["NAD83", - DATUM["North_American_Datum_1983", - SPHEROID["GRS 1980", 6378137.0, 298.257222101], - TOWGS84[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]], - PRIMEM["Greenwich", 0.0], - UNIT["degree", 0.017453292519943295], - AXIS["Lon", EAST], - AXIS["Lat", NORTH]], - PROJECTION["Lambert_Conformal_Conic_2SP"], - PARAMETER["central_meridian", -100.333333333333], - PARAMETER["latitude_of_origin", 29.6666666666667], - PARAMETER["standard_parallel_1", 31.883333333333297], - PARAMETER["false_easting", 2296583.333333], - PARAMETER["false_northing", 9842500.0], - PARAMETER["standard_parallel_2", 30.1166666666667], - UNIT["m", 1.0], - AXIS["x", EAST], - AXIS["y", NORTH], - AUTHORITY["EPSG","100002"]] - - .. note:: This code sample has been formatted for readability. The information will need to be provided on a single line instead, or with backslash characters at the end of every line (except the last one). - -#. Go into the :file:`user_projections` directory inside your data directory, and open the :file:`epsg.properties` file. If this file doesn't exist, you can create it. - -#. Insert the code WKT for the projection at the end of the file (on a single line or with backslash characters):: - - 100002=PROJCS["NAD83 / Austin", \ - GEOGCS["NAD83", \ - DATUM["North_American_Datum_1983", \ - SPHEROID["GRS 1980", 6378137.0, 298.257222101], \ - TOWGS84[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]], \ - PRIMEM["Greenwich", 0.0], \ - UNIT["degree", 0.017453292519943295], \ - AXIS["Lon", EAST], \ - AXIS["Lat", NORTH]], \ - PROJECTION["Lambert_Conformal_Conic_2SP"], \ - PARAMETER["central_meridian", -100.333333333333], \ - PARAMETER["latitude_of_origin", 29.6666666666667], \ - PARAMETER["standard_parallel_1", 31.883333333333297], \ - PARAMETER["false_easting", 2296583.333333], \ - PARAMETER["false_northing", 9842500.0], \ - PARAMETER["standard_parallel_2", 30.1166666666667], \ - UNIT["m", 1.0], \ - AXIS["x", EAST], \ - AXIS["y", NORTH], \ - AUTHORITY["EPSG","100002"]] - -.. note:: Note the number that precedes the WKT. This will determine the EPSG code. So in this example, the EPSG code is 100002. - -#. Save the file. - -#. Restart GeoServer. - -#. Verify that the CRS has been properly parsed by navigating to the :ref:`srs_list` page in the :ref:`web_admin`. - -#. If the projection wasn't listed, examine the logs for any errors. - -Override an official EPSG code ------------------------------- - -In some situations it is necessary to override an official EPSG code with a custom definition. A common case is the need to change the TOWGS84 parameters in order to get better reprojection accuracy in specific areas. - -The GeoServer referencing subsystem checks the existence of another property file, :file:`epsg_overrides.properties`, whose format is the same as :file:`epsg.properties`. Any definition contained in :file:`epsg_overrides.properties` will **override** the EPSG code, while definitions stored in :file:`epsg.proeprties` can only **add** to the database. - -Special care must be taken when overriding the Datum parameters, in particular the **TOWGS84** parameters. To make sure the override parameters are actually used the code of the Datum must be removed, otherwise the referencing subsystem will keep on reading the official database in search of the best Datum shift method (grid, 7 or 5 parameters transformation, plain affine transform). - -For example, if you need to override the official **TOWGS84** parameters of EPSG:23031:: - - PROJCS["ED50 / UTM zone 31N", - GEOGCS["ED50", - DATUM["European Datum 1950", - SPHEROID["International 1924", 6378388.0, 297.0, AUTHORITY["EPSG","7022"]], - TOWGS84[-157.89, -17.16, -78.41, 2.118, 2.697, -1.434, -1.1097046576093785], - AUTHORITY["EPSG","6230"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH], - AUTHORITY["EPSG","4230"]], - PROJECTION["Transverse_Mercator"], - PARAMETER["central_meridian", 3.0], - PARAMETER["latitude_of_origin", 0.0], - PARAMETER["scale_factor", 0.9996], - PARAMETER["false_easting", 500000.0], - PARAMETER["false_northing", 0.0], - UNIT["m", 1.0], - AXIS["Easting", EAST], - AXIS["Northing", NORTH], - AUTHORITY["EPSG","23031"]] - -You should write the following (in a single line, here it's reported formatted over multiple lines for readability):: - - 23031= - PROJCS["ED50 / UTM zone 31N", - GEOGCS["ED50", - DATUM["European Datum 1950", - SPHEROID["International 1924", 6378388.0, 297.0, AUTHORITY["EPSG","7022"]], - TOWGS84[-136.65549, -141.4658, -167.29848, 2.093088, 0.001405, 0.107709, 11.54611], - AUTHORITY["EPSG","6230"]], - PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], - UNIT["degree", 0.017453292519943295], - AXIS["Geodetic longitude", EAST], - AXIS["Geodetic latitude", NORTH]], - PROJECTION["Transverse_Mercator"], - PARAMETER["central_meridian", 3.0], - PARAMETER["latitude_of_origin", 0.0], - PARAMETER["scale_factor", 0.9996], - PARAMETER["false_easting", 500000.0], - PARAMETER["false_northing", 0.0], - UNIT["m", 1.0], - AXIS["Easting", EAST], - AXIS["Northing", NORTH], - AUTHORITY["EPSG","23031"]] - +.. _crs_custom: + +Custom CRS Definitions +====================== + +Add a custom CRS +---------------- + +This example shows how to add a custom projection in GeoServer. + +#. The projection parameters need to be provided as a WKT (well known text) definition. The code sample below is just an example:: + + PROJCS["NAD83 / Austin", + GEOGCS["NAD83", + DATUM["North_American_Datum_1983", + SPHEROID["GRS 1980", 6378137.0, 298.257222101], + TOWGS84[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]], + PRIMEM["Greenwich", 0.0], + UNIT["degree", 0.017453292519943295], + AXIS["Lon", EAST], + AXIS["Lat", NORTH]], + PROJECTION["Lambert_Conformal_Conic_2SP"], + PARAMETER["central_meridian", -100.333333333333], + PARAMETER["latitude_of_origin", 29.6666666666667], + PARAMETER["standard_parallel_1", 31.883333333333297], + PARAMETER["false_easting", 2296583.333333], + PARAMETER["false_northing", 9842500.0], + PARAMETER["standard_parallel_2", 30.1166666666667], + UNIT["m", 1.0], + AXIS["x", EAST], + AXIS["y", NORTH], + AUTHORITY["EPSG","100002"]] + + .. note:: This code sample has been formatted for readability. The information will need to be provided on a single line instead, or with backslash characters at the end of every line (except the last one). + +#. Go into the :file:`user_projections` directory inside your data directory, and open the :file:`epsg.properties` file. If this file doesn't exist, you can create it. + +#. Insert the code WKT for the projection at the end of the file (on a single line or with backslash characters):: + + 100002=PROJCS["NAD83 / Austin", \ + GEOGCS["NAD83", \ + DATUM["North_American_Datum_1983", \ + SPHEROID["GRS 1980", 6378137.0, 298.257222101], \ + TOWGS84[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]], \ + PRIMEM["Greenwich", 0.0], \ + UNIT["degree", 0.017453292519943295], \ + AXIS["Lon", EAST], \ + AXIS["Lat", NORTH]], \ + PROJECTION["Lambert_Conformal_Conic_2SP"], \ + PARAMETER["central_meridian", -100.333333333333], \ + PARAMETER["latitude_of_origin", 29.6666666666667], \ + PARAMETER["standard_parallel_1", 31.883333333333297], \ + PARAMETER["false_easting", 2296583.333333], \ + PARAMETER["false_northing", 9842500.0], \ + PARAMETER["standard_parallel_2", 30.1166666666667], \ + UNIT["m", 1.0], \ + AXIS["x", EAST], \ + AXIS["y", NORTH], \ + AUTHORITY["EPSG","100002"]] + +.. note:: Note the number that precedes the WKT. This will determine the EPSG code. So in this example, the EPSG code is 100002. + +#. Save the file. + +#. Restart GeoServer. + +#. Verify that the CRS has been properly parsed by navigating to the :ref:`srs_list` page in the :ref:`web_admin`. + +#. If the projection wasn't listed, examine the logs for any errors. + +Override an official EPSG code +------------------------------ + +In some situations it is necessary to override an official EPSG code with a custom definition. A common case is the need to change the TOWGS84 parameters in order to get better reprojection accuracy in specific areas. + +The GeoServer referencing subsystem checks the existence of another property file, :file:`epsg_overrides.properties`, whose format is the same as :file:`epsg.properties`. Any definition contained in :file:`epsg_overrides.properties` will **override** the EPSG code, while definitions stored in :file:`epsg.proeprties` can only **add** to the database. + +Special care must be taken when overriding the Datum parameters, in particular the **TOWGS84** parameters. To make sure the override parameters are actually used the code of the Datum must be removed, otherwise the referencing subsystem will keep on reading the official database in search of the best Datum shift method (grid, 7 or 5 parameters transformation, plain affine transform). + +For example, if you need to override the official **TOWGS84** parameters of EPSG:23031:: + + PROJCS["ED50 / UTM zone 31N", + GEOGCS["ED50", + DATUM["European Datum 1950", + SPHEROID["International 1924", 6378388.0, 297.0, AUTHORITY["EPSG","7022"]], + TOWGS84[-157.89, -17.16, -78.41, 2.118, 2.697, -1.434, -1.1097046576093785], + AUTHORITY["EPSG","6230"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH], + AUTHORITY["EPSG","4230"]], + PROJECTION["Transverse_Mercator"], + PARAMETER["central_meridian", 3.0], + PARAMETER["latitude_of_origin", 0.0], + PARAMETER["scale_factor", 0.9996], + PARAMETER["false_easting", 500000.0], + PARAMETER["false_northing", 0.0], + UNIT["m", 1.0], + AXIS["Easting", EAST], + AXIS["Northing", NORTH], + AUTHORITY["EPSG","23031"]] + +You should write the following (in a single line, here it's reported formatted over multiple lines for readability):: + + 23031= + PROJCS["ED50 / UTM zone 31N", + GEOGCS["ED50", + DATUM["European Datum 1950", + SPHEROID["International 1924", 6378388.0, 297.0, AUTHORITY["EPSG","7022"]], + TOWGS84[-136.65549, -141.4658, -167.29848, 2.093088, 0.001405, 0.107709, 11.54611], + AUTHORITY["EPSG","6230"]], + PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], + UNIT["degree", 0.017453292519943295], + AXIS["Geodetic longitude", EAST], + AXIS["Geodetic latitude", NORTH]], + PROJECTION["Transverse_Mercator"], + PARAMETER["central_meridian", 3.0], + PARAMETER["latitude_of_origin", 0.0], + PARAMETER["scale_factor", 0.9996], + PARAMETER["false_easting", 500000.0], + PARAMETER["false_northing", 0.0], + UNIT["m", 1.0], + AXIS["Easting", EAST], + AXIS["Northing", NORTH], + AUTHORITY["EPSG","23031"]] + The definition has been changed in two places, the **TOWGS84** paramerers, and the Datum code, ``AUTHORITY["EPSG","4230"]``, has been removed. \ No newline at end of file diff --git a/doc/en/user/source/configuration/crshandling/manualepsg.rst b/doc/en/user/source/configuration/crshandling/manualepsg.rst index dda32d03089..876f4c4b348 100644 --- a/doc/en/user/source/configuration/crshandling/manualepsg.rst +++ b/doc/en/user/source/configuration/crshandling/manualepsg.rst @@ -1,64 +1,64 @@ -.. _crs_manual_epsg: - -Manually editing the EPSG database -================================== - -.. warning:: These instructions are very advanced, and are here mainly for the curious who want to know details about the EPSG database subsystem. - -To define a custom projection, edit the EPSG.sql file, which is used to create the cached EPSG database. - -#. Navigate to the :file:`WEB-INF/lib` directory - -#. Uncompress the :file:`gt2-epsg-h.jar` file. On Linux, the command is:: - - jar xvf gt2-epsg-h.jar - -#. Open :file:`org/geotools/referencing/factory/epsg/EPSG.sql` with a text editor. To add a custom projection, these entries are essential: - - #. An entry in the EPSG_COORDINATEREFERENCESYSTEM table:: - - (41111,'WGC 84 / WRF Lambert',1324,'projected',4400,NULL,4326,20000,NULL,NULL,'US Nat. scale mapping.','Entered by Alex Petkov','Missoula Firelab WRF','WRF','2000-10-19','',1,0), - - where: - - * **1324** is the EPSG_AREA code that describes the area covered by my projection - * **4400** is the EPSG_COORDINATESYSTEM code for my projection - * **20000** is the EPSG_COORDOPERATIONPARAMVALUE key for the array that contains my projection parameters - - #. An entry in the EPSG_COORDOPERATIONPARAMVALUE table:: - - (20000,9802,8821,40,'',9102), //latitude of origin - (20000,9802,8822,-97.0,'',9102), //central meridian - (20000,9802,8823,33,'',9110), //st parallel 1 - (20000,9802,8824,45,'',9110), //st parallel 2 - (20000,9802,8826,0.0,'',9001), //false easting - (20000,9802,8827,0.0,'',9001) //false northing - - where: - - * **9802** is the EPSG_COORDOPERATIONMETHOD key for the Lambert Conic Conformal (2SP) formula - - #. An entry in the EPSG_COORDOPERATION table: - - (20000,'WRF Lambert','conversion',NULL,NULL,'',NULL,1324,'Used for weather forecasting.',0.0,9802,NULL,NULL,'Used with the WRF-Chem model for weather forecasting','Firelab in Missoula, MT','EPSG','2005-11-23','2005.01',1,0) - - where: - - * **1324** is the EPSG_AREA code that describes the area covered by my projection - * **9802** is the EPSG_COORDOPERATIONMETHOD key for the Lambert Conic Conformal (2SP) formula - -.. note:: Observe the commas. If you enter a line that is at the end of an INSERT statement, the comma is omitted (make sure the row before that has a comma at the end). Otherwise, add a comma at the end of your entry. - -#. After all edits, save the file and exit. - -#. Compress the gt2-epsg-h.jar file. On Linux, the command is:: - - jar -Mcvf gt2-epsg-h.jar META-INF org - -#. Remove the cached copy of the EPSG database, so that can be recreated. On Linux, the command is:: - - rm -rf /tmp/Geotools/Databases/HSQL - -#. Restart GeoServer. - -The new projection will be successfully parsed. Verify that the CRS has been properly parsed by navigating to the :ref:`srs_list` page in the :ref:`web_admin`. +.. _crs_manual_epsg: + +Manually editing the EPSG database +================================== + +.. warning:: These instructions are very advanced, and are here mainly for the curious who want to know details about the EPSG database subsystem. + +To define a custom projection, edit the EPSG.sql file, which is used to create the cached EPSG database. + +#. Navigate to the :file:`WEB-INF/lib` directory + +#. Uncompress the :file:`gt2-epsg-h.jar` file. On Linux, the command is:: + + jar xvf gt2-epsg-h.jar + +#. Open :file:`org/geotools/referencing/factory/epsg/EPSG.sql` with a text editor. To add a custom projection, these entries are essential: + + #. An entry in the EPSG_COORDINATEREFERENCESYSTEM table:: + + (41111,'WGC 84 / WRF Lambert',1324,'projected',4400,NULL,4326,20000,NULL,NULL,'US Nat. scale mapping.','Entered by Alex Petkov','Missoula Firelab WRF','WRF','2000-10-19','',1,0), + + where: + + * **1324** is the EPSG_AREA code that describes the area covered by my projection + * **4400** is the EPSG_COORDINATESYSTEM code for my projection + * **20000** is the EPSG_COORDOPERATIONPARAMVALUE key for the array that contains my projection parameters + + #. An entry in the EPSG_COORDOPERATIONPARAMVALUE table:: + + (20000,9802,8821,40,'',9102), //latitude of origin + (20000,9802,8822,-97.0,'',9102), //central meridian + (20000,9802,8823,33,'',9110), //st parallel 1 + (20000,9802,8824,45,'',9110), //st parallel 2 + (20000,9802,8826,0.0,'',9001), //false easting + (20000,9802,8827,0.0,'',9001) //false northing + + where: + + * **9802** is the EPSG_COORDOPERATIONMETHOD key for the Lambert Conic Conformal (2SP) formula + + #. An entry in the EPSG_COORDOPERATION table: + + (20000,'WRF Lambert','conversion',NULL,NULL,'',NULL,1324,'Used for weather forecasting.',0.0,9802,NULL,NULL,'Used with the WRF-Chem model for weather forecasting','Firelab in Missoula, MT','EPSG','2005-11-23','2005.01',1,0) + + where: + + * **1324** is the EPSG_AREA code that describes the area covered by my projection + * **9802** is the EPSG_COORDOPERATIONMETHOD key for the Lambert Conic Conformal (2SP) formula + +.. note:: Observe the commas. If you enter a line that is at the end of an INSERT statement, the comma is omitted (make sure the row before that has a comma at the end). Otherwise, add a comma at the end of your entry. + +#. After all edits, save the file and exit. + +#. Compress the gt2-epsg-h.jar file. On Linux, the command is:: + + jar -Mcvf gt2-epsg-h.jar META-INF org + +#. Remove the cached copy of the EPSG database, so that can be recreated. On Linux, the command is:: + + rm -rf /tmp/Geotools/Databases/HSQL + +#. Restart GeoServer. + +The new projection will be successfully parsed. Verify that the CRS has been properly parsed by navigating to the :ref:`srs_list` page in the :ref:`web_admin`. diff --git a/doc/en/user/source/data/app-schema/joining.rst b/doc/en/user/source/data/app-schema/joining.rst index e24ac2abd70..4c848820f6b 100644 --- a/doc/en/user/source/data/app-schema/joining.rst +++ b/doc/en/user/source/data/app-schema/joining.rst @@ -1,109 +1,109 @@ -.. _app-schema.joining: - -Joining Support For Performance -=============================== - -App-schema joining is a optional configuration parameter that tells app-schema to use a different implementation for :ref:`app-schema.feature-chaining`, -which in many cases can improve performance considerably, by reducing the amount of SQL queries sent to the DBMS. - -Conditions ----------- -In order to use App-schema Joining, the following configuration conditions must be met: - -* All feature mappings used must be mapped to JDBC datastores. - -* All feature mappings that are chained to each other must map to the same physical database. - -* In your mappings, there are restrictions on the CQL expressions specified in the of both the referencing field in the parent feature as well as the referenced field in the nested feature (like FEATURE_LINK). Any operators or functions used in this expression must be supported by the filter capibilities, i.e. geotools must be able to translate them directly to SQL code. This can be different for each DBMS, though as a general rule it can assumed that comparison operators, logical operators and arithmetic operators are all supported but functions are not. Using simple field names for feature chaining is guaranteed to always work. - -Failing to comply with any of these three restrictions when turning on Joining will result in exceptions thrown at run-time. - -When using app-schema with Joining turned on, the following restrictions exist with respect to normal behaviour: - -* XPaths specified inside Filters do not support handling referenced features (see :ref:`app-schema.feature-chaining-by-reference`) as if they were actual nested features, i.e. XPaths can only be evaluated when they can be evaluated against the actual XML code produced by WFS according to the XPath standard. - -Configuration -------------- -Joining is turned on by default. It is disabled by adding this simple line to your app-schema.properties file (see :ref:`app-schema.property-interpolation`) :: - - app-schema.joining = false - -Or, alternatively, by setting the value of the Java System Property "app-schema.joining" to "false", for example :: - - java -DGEOSERVER_DATA_DIR=... -Dapp-schema.joining=false Start - -Not specifying "app-schema.joining" parameter will enable joining by default. - -Database Design Guidelines --------------------------- - -* Databases should be optimised for fast on-the-fly joining and ordering. - -* Make sure to put indexes on all fields used as identifiers and for feature chaining, unique indexes where possible. Lack of indices may result in data being encoded in the wrong order or corrupted output when feature chaining is involved. - -* Map your features preferably to normalised tables. - -* It is recommended to apply feature chaining to regular one-to-many relationships, i.e. there should be a unique constraint defined on one of the fields used for the chaining, and if possible a foreign key constraint defined on the other field. - -Effects on Performance ----------------------- - -Typical curves of response time for configurations with and without joining against the amount of features -produced will be shaped like this: - -.. image:: joining.png - -In the default implementation, response time increases rapidly with respect to the amount of produced features. This is because feature chaining -is implemented by sending multiple SQL requests to the DBMS per feature, so the amount of requests increases with the amount -of features produced. When Joining is turned on, response time will be almost constant with respect to the number of features. This is because in this implementation a small amount of larger queries is sent to the DBMS, independant of the amount of features produced. -In summary, difference in performance becomes greater as the amount of features requested gets bigger. General performance of joining will be dependant on database and mapping design (see above) and database size. - -Using joining is strongly recommended when a large number of features need to be produced, for example -when producing maps with WMS (see :ref:`app-schema.wms-support`). - -Optimising the performance of the database will maximise the benefit of using joining, including for small queries. - -Native Encoding of Filters on Nested Attributes ------------------------------------------------ - -When App-Schema Joining is active, filters operating on nested attributes (i.e. attributes of features that are joined to the queried type via :ref:`app-schema.feature-chaining`) are translated to SQL and executed directly in the database backend, rather than being evaluated in memory after all features have been loaded (which was standard behavior in earlier versions of GeoServer). Native encoding can yield significant performance improvements, especially when the total number of features in the database is high (several thousands or more), but only a few of them would satisfy the filter. - -There are, however, a few limitations in the current implementation: - -1. Joining support must not have been explicitly disabled and all its pre-conditions must be met (see above) -2. Only binary comparison operators (e.g. ``PropertyIsEqualTo``, ``PropertyIsGreaterThan``, etc...), ``PropertyIsLike`` and ``PropertyIsNull`` filters are translated to SQL -3. Filters involving conditional polymorphic mappings are evaluated in memory -4. Filters comparing two or more different nested attributes are evaluated in memory -5. Filters matching multiple nested attribute mappings are evaluated in memory - -Much like joining support, native encoding of nested filters is turned on by default, and it is disabled by adding to your app-schema.properties file the line :: - - app-schema.encodeNestedFilters = false - -Or, alternatively, by setting the value of the Java System Property "app-schema.encodeNestedFilters" to "false", for example :: - - java -DGEOSERVER_DATA_DIR=... -Dapp-schema.encodeNestedFilters=false Start - -UNION performance improvement for OR conditions ------------------------------------------------ - -OR conditions are difficult to optimize for postgresql and are usually slow. App-Schema improves OR condition performance using UNION clauses instead OR for nested filter subqueries. - -With UNION improvement enabled main OR binary operator on nested filter subquery will rebuild normal OR query like:: - - SELECT id, name FROM table WHERE name = "A" OR name = "B" - -to:: - - SELECT id, name FROM table WHERE name = "A" UNION SELECT id, name FROM table WHERE name = "B" - -UNION improvement is enabled by default, and it is disabled by adding to your app-schema.properties file the line :: - - app-schema.orUnionReplace = false - -Or, alternatively, by setting the value of the Java System Property "app-schema.orUnionReplace" to "false", for example :: - - java -DGEOSERVER_DATA_DIR=... -Dapp-schema.orUnionReplace=false Start - -.. note:: +.. _app-schema.joining: + +Joining Support For Performance +=============================== + +App-schema joining is a optional configuration parameter that tells app-schema to use a different implementation for :ref:`app-schema.feature-chaining`, +which in many cases can improve performance considerably, by reducing the amount of SQL queries sent to the DBMS. + +Conditions +---------- +In order to use App-schema Joining, the following configuration conditions must be met: + +* All feature mappings used must be mapped to JDBC datastores. + +* All feature mappings that are chained to each other must map to the same physical database. + +* In your mappings, there are restrictions on the CQL expressions specified in the of both the referencing field in the parent feature as well as the referenced field in the nested feature (like FEATURE_LINK). Any operators or functions used in this expression must be supported by the filter capibilities, i.e. geotools must be able to translate them directly to SQL code. This can be different for each DBMS, though as a general rule it can assumed that comparison operators, logical operators and arithmetic operators are all supported but functions are not. Using simple field names for feature chaining is guaranteed to always work. + +Failing to comply with any of these three restrictions when turning on Joining will result in exceptions thrown at run-time. + +When using app-schema with Joining turned on, the following restrictions exist with respect to normal behaviour: + +* XPaths specified inside Filters do not support handling referenced features (see :ref:`app-schema.feature-chaining-by-reference`) as if they were actual nested features, i.e. XPaths can only be evaluated when they can be evaluated against the actual XML code produced by WFS according to the XPath standard. + +Configuration +------------- +Joining is turned on by default. It is disabled by adding this simple line to your app-schema.properties file (see :ref:`app-schema.property-interpolation`) :: + + app-schema.joining = false + +Or, alternatively, by setting the value of the Java System Property "app-schema.joining" to "false", for example :: + + java -DGEOSERVER_DATA_DIR=... -Dapp-schema.joining=false Start + +Not specifying "app-schema.joining" parameter will enable joining by default. + +Database Design Guidelines +-------------------------- + +* Databases should be optimised for fast on-the-fly joining and ordering. + +* Make sure to put indexes on all fields used as identifiers and for feature chaining, unique indexes where possible. Lack of indices may result in data being encoded in the wrong order or corrupted output when feature chaining is involved. + +* Map your features preferably to normalised tables. + +* It is recommended to apply feature chaining to regular one-to-many relationships, i.e. there should be a unique constraint defined on one of the fields used for the chaining, and if possible a foreign key constraint defined on the other field. + +Effects on Performance +---------------------- + +Typical curves of response time for configurations with and without joining against the amount of features +produced will be shaped like this: + +.. image:: joining.png + +In the default implementation, response time increases rapidly with respect to the amount of produced features. This is because feature chaining +is implemented by sending multiple SQL requests to the DBMS per feature, so the amount of requests increases with the amount +of features produced. When Joining is turned on, response time will be almost constant with respect to the number of features. This is because in this implementation a small amount of larger queries is sent to the DBMS, independant of the amount of features produced. +In summary, difference in performance becomes greater as the amount of features requested gets bigger. General performance of joining will be dependant on database and mapping design (see above) and database size. + +Using joining is strongly recommended when a large number of features need to be produced, for example +when producing maps with WMS (see :ref:`app-schema.wms-support`). + +Optimising the performance of the database will maximise the benefit of using joining, including for small queries. + +Native Encoding of Filters on Nested Attributes +----------------------------------------------- + +When App-Schema Joining is active, filters operating on nested attributes (i.e. attributes of features that are joined to the queried type via :ref:`app-schema.feature-chaining`) are translated to SQL and executed directly in the database backend, rather than being evaluated in memory after all features have been loaded (which was standard behavior in earlier versions of GeoServer). Native encoding can yield significant performance improvements, especially when the total number of features in the database is high (several thousands or more), but only a few of them would satisfy the filter. + +There are, however, a few limitations in the current implementation: + +1. Joining support must not have been explicitly disabled and all its pre-conditions must be met (see above) +2. Only binary comparison operators (e.g. ``PropertyIsEqualTo``, ``PropertyIsGreaterThan``, etc...), ``PropertyIsLike`` and ``PropertyIsNull`` filters are translated to SQL +3. Filters involving conditional polymorphic mappings are evaluated in memory +4. Filters comparing two or more different nested attributes are evaluated in memory +5. Filters matching multiple nested attribute mappings are evaluated in memory + +Much like joining support, native encoding of nested filters is turned on by default, and it is disabled by adding to your app-schema.properties file the line :: + + app-schema.encodeNestedFilters = false + +Or, alternatively, by setting the value of the Java System Property "app-schema.encodeNestedFilters" to "false", for example :: + + java -DGEOSERVER_DATA_DIR=... -Dapp-schema.encodeNestedFilters=false Start + +UNION performance improvement for OR conditions +----------------------------------------------- + +OR conditions are difficult to optimize for postgresql and are usually slow. App-Schema improves OR condition performance using UNION clauses instead OR for nested filter subqueries. + +With UNION improvement enabled main OR binary operator on nested filter subquery will rebuild normal OR query like:: + + SELECT id, name FROM table WHERE name = "A" OR name = "B" + +to:: + + SELECT id, name FROM table WHERE name = "A" UNION SELECT id, name FROM table WHERE name = "B" + +UNION improvement is enabled by default, and it is disabled by adding to your app-schema.properties file the line :: + + app-schema.orUnionReplace = false + +Or, alternatively, by setting the value of the Java System Property "app-schema.orUnionReplace" to "false", for example :: + + java -DGEOSERVER_DATA_DIR=... -Dapp-schema.orUnionReplace=false Start + +.. note:: This optimization will only be applied when a PostgresSQL database is being used. \ No newline at end of file diff --git a/doc/en/user/source/data/app-schema/polymorphism.rst b/doc/en/user/source/data/app-schema/polymorphism.rst index c4b3cfdc85d..54e1dbc4340 100644 --- a/doc/en/user/source/data/app-schema/polymorphism.rst +++ b/doc/en/user/source/data/app-schema/polymorphism.rst @@ -1,317 +1,317 @@ -.. _app-schema.polymorphism: - -Polymorphism -============ - -Polymorphism in this context refers to the ability of an attribute to have different forms. -Depending on the source value, it could be encoded with a specific structure, type, as an xlink:href reference, or not encoded at all. -To achieve this, we reuse feature chaining syntax and allow OCQL functions in the linkElement tag. -Read more about :ref:`app-schema.feature-chaining`, if you're not familiar with the syntax. - - -Data-type polymorphism ----------------------- -You can use normal feature chaining to get an attribute to be encoded as a certain type. -For example:: - - - ex:someAttribute - - VALUE_ID - NumericType - FEATURE_LINK - - - - ex:someAttribute - - VALUE_ID - gsml:CGI_TermValue - FEATURE_LINK - - - -Note: NumericType here is a mappingName, whereas gsml:CGI_TermValue is a targetElement. - -In the above example, ex:someAttribute would be encoded with the configuration in NumericType if the foreign key matches the linkField. -Both instances would be encoded if the foreign key matches the candidate keys in both linked configurations. -Therefore this would only work for 0 to many relationships. - -Functions can be used for single attribute instances. See `useful functions`_ for a list of commonly used functions. Specify the function in the linkElement, and it would map it to the first matching FeatureTypeMapping. -For example:: - - - ex:someAttribute - - VALUE_ID - - Recode(CLASS_TEXT, 'numeric', 'NumericType', 'literal', 'gsml:CGI_TermValue') - - FEATURE_LINK - - true - - -The above example means, if the CLASS_TEXT value is 'numeric', it would link to 'NumericType' FeatureTypeMapping, with VALUE_ID as foreign key to the linked type. -It would require all the potential matching types to have a common attribute that is specified in linkField. In this example, the linkField is FEATURE_LINK, which is a fake attribute used only for feature chaining. -You can omit the linkField and OCQL if the FeatureTypeMapping being linked to has the same sourceType with the container type. -This would save us from unnecessary extra queries, which would affect performance. -For example: - -FeatureTypeMapping of the container type:: - - - PropertyFiles - PolymorphicFeature - -FeatureTypeMapping of NumericType points to the same table:: - - - NumericType - PropertyFiles - PolymorphicFeature - -FeatureTypeMapping of gsml:CGI_TermValue also points to the same table:: - - - PropertyFiles - PolymorphicFeature - gsml:CGI_TermValue - -In this case, we can omit linkField in the polymorphic attribute mapping:: - - - ex:someAttribute - - - Recode(CLASS_TEXT, 'numeric', 'NumericType', 'literal', 'gsml:CGI_TermValue') - - - true - - - -Referential polymorphism ------------------------- -This is when an attribute is set to be encoded as an xlink:href reference on the top level. -When the scenario only has reference cases in it, setting a function in Client Property will do the job. E.g.:: - - - ex:someAttribute - - xlink:href - if_then_else(isNull(NUMERIC_VALUE), 'urn:ogc:def:nil:OGC:1.0:missing', strConcat('#', NUMERIC_VALUE)) - - - -The above example means, if NUMERIC_VALUE is null, the attribute should be encoded as:: - - - -Otherwise, it would be encoded as:: - - - where NUMERIC_VALUE = '123' - -However, this is not possible when we have cases where a fully structured attribute is also a possibility. -The `toxlinkhref`_ function can be used for this scenario. E.g.:: - - - ex:someAttribute - - - if_then_else(isNull(NUMERIC_VALUE), toXlinkHref('urn:ogc:def:nil:OGC:1.0:missing'), - if_then_else(lessEqualThan(NUMERIC_VALUE, 1000), 'numeric_value', toXlinkHref('urn:ogc:def:nil:OGC:1.0:missing'))) - - - - -The above example means, if NUMERIC_VALUE is null, the output would be encoded as:: - - - -Otherwise, if NUMERIC_VALUE is less or equal than 1000, it would be encoded with attributes from FeatureTypeMapping with 'numeric_value' mappingName. -If NUMERIC_VALUE is greater than 1000, it would be encoded as the first scenario. - - -Useful functions ----------------- -if_then_else function -````````````````````` - -**Syntax**:: - - if_then_else(BOOLEAN_EXPRESSION, value, default value) - -* **BOOLEAN_EXPRESSION**: could be a Boolean column value, or a Boolean function -* **value**: the value to map to, if BOOLEAN_EXPRESSION is true -* **default value**: the value to map to, if BOOLEAN_EXPRESSION is false - -Recode function -``````````````` - -**Syntax**:: - - Recode(EXPRESSION, key1, value1, key2, value2,...) - -* **EXPRESSION**: column name to get values from, or another function -* **key-n**: - * key expression to map to value-n - * if the evaluated value of EXPRESSION doesn't match any key, nothing would be encoded for the attribute. -* **value-n**: value expression which translates to a mappingName or targetElement - -lessEqualThan -````````````` -Returns true if ATTRIBUTE_EXPRESSION evaluates to less or equal than LIMIT_EXPRESSION. - -**Syntax**:: - - lessEqualThan(ATTRIBUTE_EXPRESSION, LIMIT_EXPRESSION) - -* **ATTRIBUTE_EXPRESSION**: expression of the attribute being evaluated. -* **LIMIT_EXPRESSION**: expression of the numeric value to be compared against. - -lessThan -```````` -Returns true if ATTRIBUTE_EXPRESSION evaluates to less than LIMIT_EXPRESSION. - -**Syntax**:: - - lessThan(ATTRIBUTE_EXPRESSION, LIMIT_EXPRESSION) - -* **ATTRIBUTE_EXPRESSION**: expression of the attribute being evaluated. -* **LIMIT_EXPRESSION**: expression of the numeric value to be compared against. - -equalTo -``````` -Compares two expressions and returns true if they're equal. - -**Syntax**:: - - equalTo(LHS_EXPRESSION, RHS_EXPRESSION) - -isNull -`````` -Returns a Boolean that is true if the expression evaluates to null. - -**Syntax**:: - - isNull(EXPRESSION) - -* **EXPRESSION**: expression to be evaluated. - -toXlinkHref -``````````` -Special function written for referential polymorphism and feature chaining, not to be used outside of linkElement. -It infers that the attribute should be encoded as xlink:href. - -**Syntax**:: - - toXlinkHref(XLINK_HREF_EXPRESSION) - -* **XLINK_HREF_EXPRESSION**: - * could be a function or a literal - * has to be wrapped in single quotes if it's a literal - -.. note:: - * To get toXlinkHref function working, you need to declare xlink URI in the namespaces. - -Other functions -``````````````` -Please refer to :ref:`filter_function_reference`. - -Combinations -```````````` -You can combine functions, but it might affect performance. -E.g.:: - - if_then_else(isNull(NUMERIC_VALUE), toXlinkHref('urn:ogc:def:nil:OGC:1.0:missing'), - if_then_else(lessEqualThan(NUMERIC_VALUE, 1000), 'numeric_value', toXlinkHref('urn:ogc:def:nil:OGC:1.0:missing'))) - - -.. note:: - * When specifying a mappingName or targetElement as a value in functions, make sure they're enclosed in single quotes. - * Some functions have no null checking, and will fail when they encounter null. - * The workaround for this is to wrap the expression with isNull() function if null is known to exist in the data set. - - -Null or missing value ---------------------- -To skip the attribute for a specific case, you can use Expression.NIL as a value in if_then_else or not include the key in `Recode function`_ . -E.g.:: - - if_then_else(isNull(VALUE), Expression.NIL, 'gsml:CGI_TermValue') - means the attribute would not be encoded if VALUE is null. - - Recode(VALUE, 'term_value', 'gsml:CGI_TermValue') - means the attribute would not be encoded if VALUE is anything but 'term_value'. - -To encode an attribute as xlink:href that represents missing value on the top level, see `Referential Polymorphism`_. - - -Any type --------- -Having xs:anyType as the attribute type itself infers that it is polymorphic, since they can be encoded as any type. - -If the type is pre-determined and would always be the same, we might need to specify :ref:`app-schema.mapping-file.targetAttributeNode`. -E.g.:: - - - om:result - gml:MeasureType - - TOPAGE - - - xsi:type - 'gml:MeasureType' - - - uom - 'http://www.opengis.net/def/uom/UCUM/0/Ma' - - - -If the casting type is complex, this is not a requirement as app-schema is able to automatically determine the type from the XPath in targetAttribute. -E.g., in this example ``om:result`` is automatically specialised as a MappedFeatureType:: - - - om:result/gsml:MappedFeature/gml:name - - NAME - - - -Alternatively, we can use feature chaining. For the same example above, the mapping would be:: - - - om:result - - LEX_D - gsml:MappedFeature - gml:name - - - -If the type is conditional, the mapping style for such attributes is the same as any other polymorphic attributes. E.g.:: - - - om:result - - - Recode(NAME, Expression.Nil, toXlinkHref('urn:ogc:def:nil:OGC::missing'),'numeric', - toXlinkHref(strConcat('urn:numeric-value::', NUMERIC_VALUE)), 'literal', 'TermValue2') - - - - - -Filters -------- -Filters should work as usual, as long as the users know what they want to filter. -For example, when an attribute could be encoded as gsml:CGI_TermValue or gsml:CGI_NumericValue, users can run filters with property names of: - - * ex:someAttribute/gsml:CGI_TermValue/gsml:value to return matching attributes that are encoded as gsml:CGI_TermValue and satisfy the filter. - * likewise, ex:someAttribute/gsml:CGI_NumericValue/gsml:principalValue should return matching gsml:CGI_NumericValue attributes. - -Another limitation is filtering attributes of an xlink:href attribute pointing to an instance outside of the document. +.. _app-schema.polymorphism: + +Polymorphism +============ + +Polymorphism in this context refers to the ability of an attribute to have different forms. +Depending on the source value, it could be encoded with a specific structure, type, as an xlink:href reference, or not encoded at all. +To achieve this, we reuse feature chaining syntax and allow OCQL functions in the linkElement tag. +Read more about :ref:`app-schema.feature-chaining`, if you're not familiar with the syntax. + + +Data-type polymorphism +---------------------- +You can use normal feature chaining to get an attribute to be encoded as a certain type. +For example:: + + + ex:someAttribute + + VALUE_ID + NumericType + FEATURE_LINK + + + + ex:someAttribute + + VALUE_ID + gsml:CGI_TermValue + FEATURE_LINK + + + +Note: NumericType here is a mappingName, whereas gsml:CGI_TermValue is a targetElement. + +In the above example, ex:someAttribute would be encoded with the configuration in NumericType if the foreign key matches the linkField. +Both instances would be encoded if the foreign key matches the candidate keys in both linked configurations. +Therefore this would only work for 0 to many relationships. + +Functions can be used for single attribute instances. See `useful functions`_ for a list of commonly used functions. Specify the function in the linkElement, and it would map it to the first matching FeatureTypeMapping. +For example:: + + + ex:someAttribute + + VALUE_ID + + Recode(CLASS_TEXT, 'numeric', 'NumericType', 'literal', 'gsml:CGI_TermValue') + + FEATURE_LINK + + true + + +The above example means, if the CLASS_TEXT value is 'numeric', it would link to 'NumericType' FeatureTypeMapping, with VALUE_ID as foreign key to the linked type. +It would require all the potential matching types to have a common attribute that is specified in linkField. In this example, the linkField is FEATURE_LINK, which is a fake attribute used only for feature chaining. +You can omit the linkField and OCQL if the FeatureTypeMapping being linked to has the same sourceType with the container type. +This would save us from unnecessary extra queries, which would affect performance. +For example: + +FeatureTypeMapping of the container type:: + + + PropertyFiles + PolymorphicFeature + +FeatureTypeMapping of NumericType points to the same table:: + + + NumericType + PropertyFiles + PolymorphicFeature + +FeatureTypeMapping of gsml:CGI_TermValue also points to the same table:: + + + PropertyFiles + PolymorphicFeature + gsml:CGI_TermValue + +In this case, we can omit linkField in the polymorphic attribute mapping:: + + + ex:someAttribute + + + Recode(CLASS_TEXT, 'numeric', 'NumericType', 'literal', 'gsml:CGI_TermValue') + + + true + + + +Referential polymorphism +------------------------ +This is when an attribute is set to be encoded as an xlink:href reference on the top level. +When the scenario only has reference cases in it, setting a function in Client Property will do the job. E.g.:: + + + ex:someAttribute + + xlink:href + if_then_else(isNull(NUMERIC_VALUE), 'urn:ogc:def:nil:OGC:1.0:missing', strConcat('#', NUMERIC_VALUE)) + + + +The above example means, if NUMERIC_VALUE is null, the attribute should be encoded as:: + + + +Otherwise, it would be encoded as:: + + + where NUMERIC_VALUE = '123' + +However, this is not possible when we have cases where a fully structured attribute is also a possibility. +The `toxlinkhref`_ function can be used for this scenario. E.g.:: + + + ex:someAttribute + + + if_then_else(isNull(NUMERIC_VALUE), toXlinkHref('urn:ogc:def:nil:OGC:1.0:missing'), + if_then_else(lessEqualThan(NUMERIC_VALUE, 1000), 'numeric_value', toXlinkHref('urn:ogc:def:nil:OGC:1.0:missing'))) + + + + +The above example means, if NUMERIC_VALUE is null, the output would be encoded as:: + + + +Otherwise, if NUMERIC_VALUE is less or equal than 1000, it would be encoded with attributes from FeatureTypeMapping with 'numeric_value' mappingName. +If NUMERIC_VALUE is greater than 1000, it would be encoded as the first scenario. + + +Useful functions +---------------- +if_then_else function +````````````````````` + +**Syntax**:: + + if_then_else(BOOLEAN_EXPRESSION, value, default value) + +* **BOOLEAN_EXPRESSION**: could be a Boolean column value, or a Boolean function +* **value**: the value to map to, if BOOLEAN_EXPRESSION is true +* **default value**: the value to map to, if BOOLEAN_EXPRESSION is false + +Recode function +``````````````` + +**Syntax**:: + + Recode(EXPRESSION, key1, value1, key2, value2,...) + +* **EXPRESSION**: column name to get values from, or another function +* **key-n**: + * key expression to map to value-n + * if the evaluated value of EXPRESSION doesn't match any key, nothing would be encoded for the attribute. +* **value-n**: value expression which translates to a mappingName or targetElement + +lessEqualThan +````````````` +Returns true if ATTRIBUTE_EXPRESSION evaluates to less or equal than LIMIT_EXPRESSION. + +**Syntax**:: + + lessEqualThan(ATTRIBUTE_EXPRESSION, LIMIT_EXPRESSION) + +* **ATTRIBUTE_EXPRESSION**: expression of the attribute being evaluated. +* **LIMIT_EXPRESSION**: expression of the numeric value to be compared against. + +lessThan +```````` +Returns true if ATTRIBUTE_EXPRESSION evaluates to less than LIMIT_EXPRESSION. + +**Syntax**:: + + lessThan(ATTRIBUTE_EXPRESSION, LIMIT_EXPRESSION) + +* **ATTRIBUTE_EXPRESSION**: expression of the attribute being evaluated. +* **LIMIT_EXPRESSION**: expression of the numeric value to be compared against. + +equalTo +``````` +Compares two expressions and returns true if they're equal. + +**Syntax**:: + + equalTo(LHS_EXPRESSION, RHS_EXPRESSION) + +isNull +`````` +Returns a Boolean that is true if the expression evaluates to null. + +**Syntax**:: + + isNull(EXPRESSION) + +* **EXPRESSION**: expression to be evaluated. + +toXlinkHref +``````````` +Special function written for referential polymorphism and feature chaining, not to be used outside of linkElement. +It infers that the attribute should be encoded as xlink:href. + +**Syntax**:: + + toXlinkHref(XLINK_HREF_EXPRESSION) + +* **XLINK_HREF_EXPRESSION**: + * could be a function or a literal + * has to be wrapped in single quotes if it's a literal + +.. note:: + * To get toXlinkHref function working, you need to declare xlink URI in the namespaces. + +Other functions +``````````````` +Please refer to :ref:`filter_function_reference`. + +Combinations +```````````` +You can combine functions, but it might affect performance. +E.g.:: + + if_then_else(isNull(NUMERIC_VALUE), toXlinkHref('urn:ogc:def:nil:OGC:1.0:missing'), + if_then_else(lessEqualThan(NUMERIC_VALUE, 1000), 'numeric_value', toXlinkHref('urn:ogc:def:nil:OGC:1.0:missing'))) + + +.. note:: + * When specifying a mappingName or targetElement as a value in functions, make sure they're enclosed in single quotes. + * Some functions have no null checking, and will fail when they encounter null. + * The workaround for this is to wrap the expression with isNull() function if null is known to exist in the data set. + + +Null or missing value +--------------------- +To skip the attribute for a specific case, you can use Expression.NIL as a value in if_then_else or not include the key in `Recode function`_ . +E.g.:: + + if_then_else(isNull(VALUE), Expression.NIL, 'gsml:CGI_TermValue') + means the attribute would not be encoded if VALUE is null. + + Recode(VALUE, 'term_value', 'gsml:CGI_TermValue') + means the attribute would not be encoded if VALUE is anything but 'term_value'. + +To encode an attribute as xlink:href that represents missing value on the top level, see `Referential Polymorphism`_. + + +Any type +-------- +Having xs:anyType as the attribute type itself infers that it is polymorphic, since they can be encoded as any type. + +If the type is pre-determined and would always be the same, we might need to specify :ref:`app-schema.mapping-file.targetAttributeNode`. +E.g.:: + + + om:result + gml:MeasureType + + TOPAGE + + + xsi:type + 'gml:MeasureType' + + + uom + 'http://www.opengis.net/def/uom/UCUM/0/Ma' + + + +If the casting type is complex, this is not a requirement as app-schema is able to automatically determine the type from the XPath in targetAttribute. +E.g., in this example ``om:result`` is automatically specialised as a MappedFeatureType:: + + + om:result/gsml:MappedFeature/gml:name + + NAME + + + +Alternatively, we can use feature chaining. For the same example above, the mapping would be:: + + + om:result + + LEX_D + gsml:MappedFeature + gml:name + + + +If the type is conditional, the mapping style for such attributes is the same as any other polymorphic attributes. E.g.:: + + + om:result + + + Recode(NAME, Expression.Nil, toXlinkHref('urn:ogc:def:nil:OGC::missing'),'numeric', + toXlinkHref(strConcat('urn:numeric-value::', NUMERIC_VALUE)), 'literal', 'TermValue2') + + + + + +Filters +------- +Filters should work as usual, as long as the users know what they want to filter. +For example, when an attribute could be encoded as gsml:CGI_TermValue or gsml:CGI_NumericValue, users can run filters with property names of: + + * ex:someAttribute/gsml:CGI_TermValue/gsml:value to return matching attributes that are encoded as gsml:CGI_TermValue and satisfy the filter. + * likewise, ex:someAttribute/gsml:CGI_NumericValue/gsml:principalValue should return matching gsml:CGI_NumericValue attributes. + +Another limitation is filtering attributes of an xlink:href attribute pointing to an instance outside of the document. diff --git a/doc/en/user/source/data/cascaded/wfs.rst b/doc/en/user/source/data/cascaded/wfs.rst index f9122f4e1a0..07f5eff471a 100644 --- a/doc/en/user/source/data/cascaded/wfs.rst +++ b/doc/en/user/source/data/cascaded/wfs.rst @@ -1,93 +1,93 @@ -.. _data_external_wfs: - -External Web Feature Server -=========================== - -GeoServer has the ability to load data from a remote Web Feature Server (WFS). This is useful if the remote WFS lacks certain functionality that GeoServer contains. For example, if the remote WFS is not also a Web Map Server (WMS), data from the WFS can be cascaded through GeoServer to utilize GeoServer's WMS. If the remote WFS has a WMS but that WMS cannot output KML, data can be cascaded through GeoServer's WMS to output KML. - -Adding an external WFS ----------------------- - -To connect to an external WFS, it is necessary to load it as a new datastore. To start, navigate to :menuselection:`Stores --> Add a new store --> Web Feature Server`. - -.. figure:: images/externalwfs.png - :align: center - - *Adding an external WFS as a store* - -.. list-table:: - :widths: 20 80 - - * - **Option** - - **Description** - * - :guilabel:`Workspace` - - Name of the workspace to contain the store. This will also be the prefix of all of the layer names created from the store. - * - :guilabel:`Data Source Name` - - Name of the store as known to GeoServer. - * - :guilabel:`Description` - - Description of the store. - * - :guilabel:`Enabled` - - Enables the store. If disabled, no data from the external WFS will be served. - * - :guilabel:`GET_CAPABILITIES_URL` - - URL to access the capabilities document of the remote WFS. - * - :guilabel:`PROTOCOL` - - When checked, connects with POST, otherwise uses GET. - * - :guilabel:`USERNAME` - - The user name to connect to the external WFS. - * - :guilabel:`PASSWORD` - - The password associated with the above user name. - * - :guilabel:`ENCODING` - - The character encoding of the XML requests sent to the server. Defaults to ``UTF-8``. - * - :guilabel:`TIMEOUT` - - Time (in milliseconds) before timing out. Default is ``3000``. - * - :guilabel:`BUFFER_SIZE` - - Specifies a buffer size (in number of features). Default is ``10`` features. - * - :guilabel:`TRY_GZIP` - - Specifies that the server should transfer data using compressed HTTP if supported by the server. - * - :guilabel:`LENIENT` - - When checked, will try to render features that don't match the appropriate schema. Errors will be logged. - * - :guilabel:`MAXFEATURES` - - Maximum amount of features to retrieve for each featuretype. Default is no limit. - * - :guilabel:`AXIS_ORDER` - - Axis order used in result coordinates (It applies only to WFS 1.x.0 servers). Default is Compliant. - * - :guilabel:`AXIS_ORDER_FILTER` - - Axis order used in filter (It applies only to WFS 1.x.0 servers). Default is Compliant. - * - :guilabel:`OUTPUTFORMAT` - - Output format to request (instead of the default remote service one). - * - :guilabel:`GML_COMPLIANCE_LEVEL` - - OCG GML compliance level. i.e. (simple feature) 0, 1 or 2. Default is 0. - * - :guilabel:`GML_COMPATIBLE_TYPENAMES` - - Use Gml Compatible TypeNames (replace : by _). Default is no false. - * - :guilabel:`USE_HTTP_CONNECTION_POOLING` - - Use connection pooling to connect to the remote WFS service. Also enables digest authentcation. - -When finished, click :guilabel:`Save`. - -Configuring external WFS layers -------------------------------- - -When properly loaded, all layers served by the external WFS will be available to GeoServer. Before they can be served, however, they will need to be individually configured as new layers. See the section on :ref:`data_webadmin_layers` for how to add and edit new layers. - -Connecting to an external WFS layer via a proxy server ------------------------------------------------------- - -In a corporate environment it may be necessary to connect to an external WFS through a proxy server. To achieve this, various java variables need to be set. - -For a Windows install running GeoServer as a service, this is done by modifying the wrapper.conf file. For a default Windows install, modify :file:`C:\\Program Files\\GeoServer x.x.x\\wrapper\\wrapper.conf` similarly to the following. - - # Java Additional Parameters - - wrapper.java.additional.1=-Djetty.home=. - wrapper.java.additional.2=-DGEOSERVER_DATA_DIR="%GEOSERVER_DATA_DIR%" - wrapper.java.additional.3=-Dhttp.proxySet=true - wrapper.java.additional.4=-Dhttp.proxyHost=maitproxy - wrapper.java.additional.5=-Dhttp.proxyPort=8080 - wrapper.java.additional.6=-Dhttps.proxyHost=maitproxy - wrapper.java.additional.7=-Dhttps.proxyPort=8080 - wrapper.java.additional.8=-Dhttp.nonProxyHosts="mait*|dpi*|localhost" - -Note that the :command:`http.proxySet=true` parameter is required. Also, the parameter numbers must be consecutive - ie. no gaps. - -For a Windows install not running GeoServer as a service, modify :file:`startup.bat` so that the :command:`java` command runs with similar -D parameters. - -For a Linux/UNIX install, modify :file:`startup.sh` so that the :command:`java` command runs with similar -D parameters. +.. _data_external_wfs: + +External Web Feature Server +=========================== + +GeoServer has the ability to load data from a remote Web Feature Server (WFS). This is useful if the remote WFS lacks certain functionality that GeoServer contains. For example, if the remote WFS is not also a Web Map Server (WMS), data from the WFS can be cascaded through GeoServer to utilize GeoServer's WMS. If the remote WFS has a WMS but that WMS cannot output KML, data can be cascaded through GeoServer's WMS to output KML. + +Adding an external WFS +---------------------- + +To connect to an external WFS, it is necessary to load it as a new datastore. To start, navigate to :menuselection:`Stores --> Add a new store --> Web Feature Server`. + +.. figure:: images/externalwfs.png + :align: center + + *Adding an external WFS as a store* + +.. list-table:: + :widths: 20 80 + + * - **Option** + - **Description** + * - :guilabel:`Workspace` + - Name of the workspace to contain the store. This will also be the prefix of all of the layer names created from the store. + * - :guilabel:`Data Source Name` + - Name of the store as known to GeoServer. + * - :guilabel:`Description` + - Description of the store. + * - :guilabel:`Enabled` + - Enables the store. If disabled, no data from the external WFS will be served. + * - :guilabel:`GET_CAPABILITIES_URL` + - URL to access the capabilities document of the remote WFS. + * - :guilabel:`PROTOCOL` + - When checked, connects with POST, otherwise uses GET. + * - :guilabel:`USERNAME` + - The user name to connect to the external WFS. + * - :guilabel:`PASSWORD` + - The password associated with the above user name. + * - :guilabel:`ENCODING` + - The character encoding of the XML requests sent to the server. Defaults to ``UTF-8``. + * - :guilabel:`TIMEOUT` + - Time (in milliseconds) before timing out. Default is ``3000``. + * - :guilabel:`BUFFER_SIZE` + - Specifies a buffer size (in number of features). Default is ``10`` features. + * - :guilabel:`TRY_GZIP` + - Specifies that the server should transfer data using compressed HTTP if supported by the server. + * - :guilabel:`LENIENT` + - When checked, will try to render features that don't match the appropriate schema. Errors will be logged. + * - :guilabel:`MAXFEATURES` + - Maximum amount of features to retrieve for each featuretype. Default is no limit. + * - :guilabel:`AXIS_ORDER` + - Axis order used in result coordinates (It applies only to WFS 1.x.0 servers). Default is Compliant. + * - :guilabel:`AXIS_ORDER_FILTER` + - Axis order used in filter (It applies only to WFS 1.x.0 servers). Default is Compliant. + * - :guilabel:`OUTPUTFORMAT` + - Output format to request (instead of the default remote service one). + * - :guilabel:`GML_COMPLIANCE_LEVEL` + - OCG GML compliance level. i.e. (simple feature) 0, 1 or 2. Default is 0. + * - :guilabel:`GML_COMPATIBLE_TYPENAMES` + - Use Gml Compatible TypeNames (replace : by _). Default is no false. + * - :guilabel:`USE_HTTP_CONNECTION_POOLING` + - Use connection pooling to connect to the remote WFS service. Also enables digest authentcation. + +When finished, click :guilabel:`Save`. + +Configuring external WFS layers +------------------------------- + +When properly loaded, all layers served by the external WFS will be available to GeoServer. Before they can be served, however, they will need to be individually configured as new layers. See the section on :ref:`data_webadmin_layers` for how to add and edit new layers. + +Connecting to an external WFS layer via a proxy server +------------------------------------------------------ + +In a corporate environment it may be necessary to connect to an external WFS through a proxy server. To achieve this, various java variables need to be set. + +For a Windows install running GeoServer as a service, this is done by modifying the wrapper.conf file. For a default Windows install, modify :file:`C:\\Program Files\\GeoServer x.x.x\\wrapper\\wrapper.conf` similarly to the following. + + # Java Additional Parameters + + wrapper.java.additional.1=-Djetty.home=. + wrapper.java.additional.2=-DGEOSERVER_DATA_DIR="%GEOSERVER_DATA_DIR%" + wrapper.java.additional.3=-Dhttp.proxySet=true + wrapper.java.additional.4=-Dhttp.proxyHost=maitproxy + wrapper.java.additional.5=-Dhttp.proxyPort=8080 + wrapper.java.additional.6=-Dhttps.proxyHost=maitproxy + wrapper.java.additional.7=-Dhttps.proxyPort=8080 + wrapper.java.additional.8=-Dhttp.nonProxyHosts="mait*|dpi*|localhost" + +Note that the :command:`http.proxySet=true` parameter is required. Also, the parameter numbers must be consecutive - ie. no gaps. + +For a Windows install not running GeoServer as a service, modify :file:`startup.bat` so that the :command:`java` command runs with similar -D parameters. + +For a Linux/UNIX install, modify :file:`startup.sh` so that the :command:`java` command runs with similar -D parameters. diff --git a/doc/en/user/source/data/database/db2.rst b/doc/en/user/source/data/database/db2.rst index f7eceffa1ee..c6586e62f46 100644 --- a/doc/en/user/source/data/database/db2.rst +++ b/doc/en/user/source/data/database/db2.rst @@ -1,63 +1,63 @@ -.. _data_Db2: - -Db2 -=== - -.. note:: GeoServer does not come built-in with support for Db2; it must be installed through an extension. Proceed to :ref:`Db2_install` for installation details. - -The Db2 spatial support implements the OGC specification "Simple Features for SQL using types and functions" and the ISO "SQL/MM Part 3 Spatial" standard. When installing Db2 on Linux, Unix and Windows platforms, the "custom" option must be selected and the server spatial support included. - -A free of charge copy of Db2 can be downloaded from https://www.ibm.com/analytics/db2/trials. - - -.. _Db2_install: - -Installing the Db2 extension ----------------------------- - -.. warning:: Due to licensing requirements, not all files are included with the extension. To install Db2 support, it is necessary to download additional files. **Just installing the Db2 extension will have no effect.** - -GeoServer files -``````````````` - -#. Download the Db2 extension from the `GeoServer download page - `_. - - .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! - -#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of - the GeoServer installation. - -Required external files -``````````````````````` - -The Db2 JDBC driver is not packaged with the GeoServer extension: :file:`db2jcc4.jar`. This file should be available in the :file:`java` subdirectory of your Db2 installation directory. Copy this file to the ``WEB-INF/lib`` directory of the GeoServer installation. - - -After all GeoServer files and external files have been downloaded and copied, restart GeoServer. - -Adding a Db2 data store ------------------------ - -When properly installed, :guilabel:`Db2` will be an option in the :guilabel:`Vector Data Sources` list when creating a new data store. - -.. figure:: images/db2create.png - :align: center - - *Db2 in the list of raster data stores* - -Configuring a Db2 data store ----------------------------- - -.. figure:: images/db2configure.png - :align: center - - *Configuring a Db2 data store* - -Configuring a Db2 data store with JNDI --------------------------------------- - -Notes on usage --------------- - -Db2 schema, table, and column names are all case-sensitive when working with GeoTools/GeoServer. When working with Db2 scripts and the Db2 command window, the default is to treat these names as upper-case unless enclosed in double-quote characters but this is not the case in GeoServer. +.. _data_Db2: + +Db2 +=== + +.. note:: GeoServer does not come built-in with support for Db2; it must be installed through an extension. Proceed to :ref:`Db2_install` for installation details. + +The Db2 spatial support implements the OGC specification "Simple Features for SQL using types and functions" and the ISO "SQL/MM Part 3 Spatial" standard. When installing Db2 on Linux, Unix and Windows platforms, the "custom" option must be selected and the server spatial support included. + +A free of charge copy of Db2 can be downloaded from https://www.ibm.com/analytics/db2/trials. + + +.. _Db2_install: + +Installing the Db2 extension +---------------------------- + +.. warning:: Due to licensing requirements, not all files are included with the extension. To install Db2 support, it is necessary to download additional files. **Just installing the Db2 extension will have no effect.** + +GeoServer files +``````````````` + +#. Download the Db2 extension from the `GeoServer download page + `_. + + .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! + +#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of + the GeoServer installation. + +Required external files +``````````````````````` + +The Db2 JDBC driver is not packaged with the GeoServer extension: :file:`db2jcc4.jar`. This file should be available in the :file:`java` subdirectory of your Db2 installation directory. Copy this file to the ``WEB-INF/lib`` directory of the GeoServer installation. + + +After all GeoServer files and external files have been downloaded and copied, restart GeoServer. + +Adding a Db2 data store +----------------------- + +When properly installed, :guilabel:`Db2` will be an option in the :guilabel:`Vector Data Sources` list when creating a new data store. + +.. figure:: images/db2create.png + :align: center + + *Db2 in the list of raster data stores* + +Configuring a Db2 data store +---------------------------- + +.. figure:: images/db2configure.png + :align: center + + *Configuring a Db2 data store* + +Configuring a Db2 data store with JNDI +-------------------------------------- + +Notes on usage +-------------- + +Db2 schema, table, and column names are all case-sensitive when working with GeoTools/GeoServer. When working with Db2 scripts and the Db2 command window, the default is to treat these names as upper-case unless enclosed in double-quote characters but this is not the case in GeoServer. diff --git a/doc/en/user/source/data/database/h2.rst b/doc/en/user/source/data/database/h2.rst index 1f487d57993..f2a4f5c0f75 100644 --- a/doc/en/user/source/data/database/h2.rst +++ b/doc/en/user/source/data/database/h2.rst @@ -1,39 +1,39 @@ -.. _data_h2: - -H2 -== - -.. note:: GeoServer does not come built-in with support for H2; it must be installed through an extension. Proceed to :ref:`h2_install` for installation details. - -.. _h2_install: - -Installing the H2 extension ----------------------------- - -#. Download the H2 extension from the `GeoServer download page - `_. - - .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! - -#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. - -Adding an H2 data store ------------------------ - -Once the extension is properly installed :guilabel:`H2` will be an option in the :guilabel:`Vector Data Sources` list when creating a new data store. - -.. figure:: images/h2create.png - :align: center - - *H2 in the list of vector data stores* - -Configuring an H2 data store ----------------------------- - -.. figure:: images/h2configure.png - :align: center - - *Configuring an H2 data store* - -Configuring an H2 data store with JNDI +.. _data_h2: + +H2 +== + +.. note:: GeoServer does not come built-in with support for H2; it must be installed through an extension. Proceed to :ref:`h2_install` for installation details. + +.. _h2_install: + +Installing the H2 extension +---------------------------- + +#. Download the H2 extension from the `GeoServer download page + `_. + + .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! + +#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. + +Adding an H2 data store +----------------------- + +Once the extension is properly installed :guilabel:`H2` will be an option in the :guilabel:`Vector Data Sources` list when creating a new data store. + +.. figure:: images/h2create.png + :align: center + + *H2 in the list of vector data stores* + +Configuring an H2 data store +---------------------------- + +.. figure:: images/h2configure.png + :align: center + + *Configuring an H2 data store* + +Configuring an H2 data store with JNDI -------------------------------------- \ No newline at end of file diff --git a/doc/en/user/source/data/database/mysql.rst b/doc/en/user/source/data/database/mysql.rst index 92f3f556a96..592ae3fd1c7 100644 --- a/doc/en/user/source/data/database/mysql.rst +++ b/doc/en/user/source/data/database/mysql.rst @@ -1,63 +1,63 @@ -.. _data_mysql: - -MySQL -===== - -.. note:: GeoServer does not come built-in with support for MySQL; it must be installed through an extension. Proceed to :ref:`mysql_install` for installation details. - -.. warning:: Currently the MySQL extension is unmaintained and carries unsupported status. While still usable, do not expect the same reliability as with other extensions. - -`MySQL `_ is an open source relational database with some limited spatial functionality. - -.. _mysql_install: - -Installing the MySQL extension ------------------------------- - -#. Download the MySQL extension from the `GeoServer download page `_. - - .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! - -#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. - -Adding a MySQL database ------------------------ - -Once the extension is properly installed ``MySQL`` will show up as an option when creating a new data store. - -.. figure:: images/mysqlcreate.png - :align: center - - *MySQL in the list of data sources* - -Configuring a MySQL data store ------------------------------- - -.. figure:: images/mysqlconfigure.png - :align: center - - *Configuring a MySQL data store* - -.. list-table:: - :widths: 20 80 - - * - ``host`` - - The mysql server host name or ip address. - * - ``port`` - - The port on which the mysql server is accepting connections. - * - ``database`` - - The name of the database to connect to. Can also contain a suffix with a connection URL query, such as mydbname?useSSL=false - * - ``user`` - - The name of the user to connect to the mysql database as. - * - ``password`` - - The password to use when connecting to the database. Left blank for no - password. - * - ``max connections`` - - ``min connections`` - - ``validate connections`` - - - Connection pool configuration parameters. See the - :ref:`connection_pooling` section for details. - +.. _data_mysql: + +MySQL +===== + +.. note:: GeoServer does not come built-in with support for MySQL; it must be installed through an extension. Proceed to :ref:`mysql_install` for installation details. + +.. warning:: Currently the MySQL extension is unmaintained and carries unsupported status. While still usable, do not expect the same reliability as with other extensions. + +`MySQL `_ is an open source relational database with some limited spatial functionality. + +.. _mysql_install: + +Installing the MySQL extension +------------------------------ + +#. Download the MySQL extension from the `GeoServer download page `_. + + .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! + +#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. + +Adding a MySQL database +----------------------- + +Once the extension is properly installed ``MySQL`` will show up as an option when creating a new data store. + +.. figure:: images/mysqlcreate.png + :align: center + + *MySQL in the list of data sources* + +Configuring a MySQL data store +------------------------------ + +.. figure:: images/mysqlconfigure.png + :align: center + + *Configuring a MySQL data store* + +.. list-table:: + :widths: 20 80 + + * - ``host`` + - The mysql server host name or ip address. + * - ``port`` + - The port on which the mysql server is accepting connections. + * - ``database`` + - The name of the database to connect to. Can also contain a suffix with a connection URL query, such as mydbname?useSSL=false + * - ``user`` + - The name of the user to connect to the mysql database as. + * - ``password`` + - The password to use when connecting to the database. Left blank for no + password. + * - ``max connections`` + + ``min connections`` + + ``validate connections`` + + - Connection pool configuration parameters. See the + :ref:`connection_pooling` section for details. + diff --git a/doc/en/user/source/data/database/oracle.rst b/doc/en/user/source/data/database/oracle.rst index 2fcbb43f188..b70f205bd3f 100644 --- a/doc/en/user/source/data/database/oracle.rst +++ b/doc/en/user/source/data/database/oracle.rst @@ -1,148 +1,148 @@ -.. _data_oracle: - -Oracle -====== - -.. note:: GeoServer does not come built-in with support for Oracle; it must be installed through an extension. Proceed to :ref:`oracle_install` for installation details. - -`Oracle Spatial and Locator `_ are the spatial components of Oracle. -**Locator** is provided with all Oracle versions, but has limited spatial functions. -**Spatial** is Oracle's full-featured spatial offering, but requires a specific license to use. - -.. _oracle_install: - -Installing the Oracle extension -------------------------------- - -#. Download the Oracle extension from the `GeoServer download page `_. - - .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! - -#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. - -Adding an Oracle datastore --------------------------- - -Once the extension is properly installed :guilabel:`Oracle` appears as an option in the :guilabel:`Vector Data Sources` list when creating a new data store. - -.. figure:: images/oraclecreate.png - :align: center - - *Oracle in the list of data sources* - -Configuring an Oracle datastore -------------------------------- - -.. figure:: images/oracleconfigure.png - :align: center - - *Configuring an Oracle datastore* - -.. list-table:: - :widths: 20 80 - - * - **Option** - - **Description** - * - ``host`` - - The Oracle server host name or IP address. - * - ``port`` - - The port on which the Oracle server is accepting connections (often this is port 1521). - * - ``database`` - - The name of the database to connect to. - By default this is interpreted as a SID name. To connect to a Service, prefix the name with a ``/``. - * - ``schema`` - - The database schema to access tables from. Setting this value greatly increases the speed at which the data store displays its publishable tables and views, so it is advisable to set this. - * - ``user`` - - The name of the user to use when connecting to the database. - * - ``password`` - - The password to use when connecting to the database. Leave blank for no password. - * - ``max connections`` - ``min connections`` - ``fetch size`` - ``Connection timeout`` - ``validate connections`` - - Connection pool configuration parameters. See :ref:`connection_pooling` for details. - * - ``Loose bbox`` - - Controls how bounding box filters are made against geometries in the database. See the :ref:`oracle_loose_bbox` section below. - * - ``Metadata bbox`` - - Flag controlling the use of MDSYS.USER_SDO_GEOM_METADATA or MDSYS.ALL_SDO_GEOM_METADATA table for bounding box calculations, this brings a better performance if the views access is fast and the bounds are configured right in the tables default is false - -Connecting to an Oracle cluster -------------------------------- - -In order to connect to an Oracle RAC one can use an almost full JDBC url as the ``database``, provided it starts with ``(`` it will be used verbatim and options "host" and "port" will be ignored. Here is an example "database" value used to connect to an Oracle RAC:: - - (DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=host1) (PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2) (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=service))) - -More information about this syntax can be found in the `Oracle documentation `_. - -Connecting to a SID or a Service -```````````````````````````````` - -Recent versions of Oracle support connecting to a database via either a SID name or a Service name. -A SID connection descriptor has the form: ``host:port:database``, -while a Service connection descriptor has the format ``host:port/database``. -GeoServer uses the SID form by default. To connect via a Service, -prefix the ``database`` name configuration entry with a ``/``. - -Connecting to database through LDAP -````````````````````````````````````` - -For instance if you want to establish a connection with the jdbc thin driver through LDAP, you can use following connect string for the input field ``database`` -``ldap://[host]:[Port]/[db],cn=OracleContext,dc=[oracle_ldap_context]``. - -If you are using referrals, enable it by placing a jndi.properties file in geoserver's CLASSPATH, which is in geoserver/WEB-INF/classes. -This property file contains: - - java.naming.referral=follow - - -.. _oracle_loose_bbox: - -Using loose bounding box -```````````````````````` - -When the ``Loose bbox`` option is set, only the bounding box of database geometries is used in spatial queries. This results in a significant performance gain. The downside is that some geometries may be reported as intersecting a BBOX when they actually do not. - -If the primary use of the database is through the :ref:`WMS` this flag can be set safely, since querying more geometries does not have any visible effect. However, if using the :ref:`WFS` and making use of BBOX filtering capabilities, this flag should not be set. - -Using the geometry metadata table -````````````````````````````````` - -The Oracle data store by default looks at the ``MDSYS.USER_SDO*`` and ``MDSYS.ALL_SDO*`` views -to determine the geometry type and native SRID of each geometry column. -Those views are automatically populated with information about the geometry columns stored in tables that the current -user owns (for the ``MDSYS.USER_SDO*`` views) or can otherwise access (for the ``MDSYS.ALL_SDO*`` views). - -There are a few issues with this strategy: - - * if the connection pool user cannot access the tables (because :ref:`impersonation ` is used) - the MDSYS views will be empty, making it impossible to determine both the geometry type and the native SRID - * the geometry type can be specified only while building the spatial indexes, as an index constraint. However - such information is often not included when creating the indexes - * the views are populated dynamically based on the current user. If the database has thousands of tables and users - the views can become very slow - -Starting with GeoServer 2.1.4 the administrator can address the above issues by manually creating a geometry metadata table -describing each geometry column. -Its presence is indicated via the Oracle datastore connection parameter named *Geometry metadata table* -(which may be a simple table name or a schema-qualified one). -The table has the following structure (the table name is flexible, just specify the one chosen in the data store connection parameter):: - - CREATE TABLE GEOMETRY_COLUMNS( - F_TABLE_SCHEMA VARCHAR(30) NOT NULL, - F_TABLE_NAME VARCHAR(30) NOT NULL, - F_GEOMETRY_COLUMN VARCHAR(30) NOT NULL, - COORD_DIMENSION INTEGER, - SRID INTEGER NOT NULL, - TYPE VARCHAR(30) NOT NULL, - UNIQUE(F_TABLE_SCHEMA, F_TABLE_NAME, F_GEOMETRY_COLUMN), - CHECK(TYPE IN ('POINT','LINE', 'POLYGON', 'COLLECTION', 'MULTIPOINT', 'MULTILINE', 'MULTIPOLYGON', 'GEOMETRY') )); - -When the table is present the store first searches it for information about each geometry column -to be classified, and falls back on the MDSYS views only if the table does not contain any information. - -Configuring an Oracle database with JNDI ----------------------------------------- - -See :ref:`tomcat_jndi` for a guide on setting up an Oracle connection using JNDI. +.. _data_oracle: + +Oracle +====== + +.. note:: GeoServer does not come built-in with support for Oracle; it must be installed through an extension. Proceed to :ref:`oracle_install` for installation details. + +`Oracle Spatial and Locator `_ are the spatial components of Oracle. +**Locator** is provided with all Oracle versions, but has limited spatial functions. +**Spatial** is Oracle's full-featured spatial offering, but requires a specific license to use. + +.. _oracle_install: + +Installing the Oracle extension +------------------------------- + +#. Download the Oracle extension from the `GeoServer download page `_. + + .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! + +#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. + +Adding an Oracle datastore +-------------------------- + +Once the extension is properly installed :guilabel:`Oracle` appears as an option in the :guilabel:`Vector Data Sources` list when creating a new data store. + +.. figure:: images/oraclecreate.png + :align: center + + *Oracle in the list of data sources* + +Configuring an Oracle datastore +------------------------------- + +.. figure:: images/oracleconfigure.png + :align: center + + *Configuring an Oracle datastore* + +.. list-table:: + :widths: 20 80 + + * - **Option** + - **Description** + * - ``host`` + - The Oracle server host name or IP address. + * - ``port`` + - The port on which the Oracle server is accepting connections (often this is port 1521). + * - ``database`` + - The name of the database to connect to. + By default this is interpreted as a SID name. To connect to a Service, prefix the name with a ``/``. + * - ``schema`` + - The database schema to access tables from. Setting this value greatly increases the speed at which the data store displays its publishable tables and views, so it is advisable to set this. + * - ``user`` + - The name of the user to use when connecting to the database. + * - ``password`` + - The password to use when connecting to the database. Leave blank for no password. + * - ``max connections`` + ``min connections`` + ``fetch size`` + ``Connection timeout`` + ``validate connections`` + - Connection pool configuration parameters. See :ref:`connection_pooling` for details. + * - ``Loose bbox`` + - Controls how bounding box filters are made against geometries in the database. See the :ref:`oracle_loose_bbox` section below. + * - ``Metadata bbox`` + - Flag controlling the use of MDSYS.USER_SDO_GEOM_METADATA or MDSYS.ALL_SDO_GEOM_METADATA table for bounding box calculations, this brings a better performance if the views access is fast and the bounds are configured right in the tables default is false + +Connecting to an Oracle cluster +------------------------------- + +In order to connect to an Oracle RAC one can use an almost full JDBC url as the ``database``, provided it starts with ``(`` it will be used verbatim and options "host" and "port" will be ignored. Here is an example "database" value used to connect to an Oracle RAC:: + + (DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=host1) (PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2) (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=service))) + +More information about this syntax can be found in the `Oracle documentation `_. + +Connecting to a SID or a Service +```````````````````````````````` + +Recent versions of Oracle support connecting to a database via either a SID name or a Service name. +A SID connection descriptor has the form: ``host:port:database``, +while a Service connection descriptor has the format ``host:port/database``. +GeoServer uses the SID form by default. To connect via a Service, +prefix the ``database`` name configuration entry with a ``/``. + +Connecting to database through LDAP +````````````````````````````````````` + +For instance if you want to establish a connection with the jdbc thin driver through LDAP, you can use following connect string for the input field ``database`` +``ldap://[host]:[Port]/[db],cn=OracleContext,dc=[oracle_ldap_context]``. + +If you are using referrals, enable it by placing a jndi.properties file in geoserver's CLASSPATH, which is in geoserver/WEB-INF/classes. +This property file contains: + + java.naming.referral=follow + + +.. _oracle_loose_bbox: + +Using loose bounding box +```````````````````````` + +When the ``Loose bbox`` option is set, only the bounding box of database geometries is used in spatial queries. This results in a significant performance gain. The downside is that some geometries may be reported as intersecting a BBOX when they actually do not. + +If the primary use of the database is through the :ref:`WMS` this flag can be set safely, since querying more geometries does not have any visible effect. However, if using the :ref:`WFS` and making use of BBOX filtering capabilities, this flag should not be set. + +Using the geometry metadata table +````````````````````````````````` + +The Oracle data store by default looks at the ``MDSYS.USER_SDO*`` and ``MDSYS.ALL_SDO*`` views +to determine the geometry type and native SRID of each geometry column. +Those views are automatically populated with information about the geometry columns stored in tables that the current +user owns (for the ``MDSYS.USER_SDO*`` views) or can otherwise access (for the ``MDSYS.ALL_SDO*`` views). + +There are a few issues with this strategy: + + * if the connection pool user cannot access the tables (because :ref:`impersonation ` is used) + the MDSYS views will be empty, making it impossible to determine both the geometry type and the native SRID + * the geometry type can be specified only while building the spatial indexes, as an index constraint. However + such information is often not included when creating the indexes + * the views are populated dynamically based on the current user. If the database has thousands of tables and users + the views can become very slow + +Starting with GeoServer 2.1.4 the administrator can address the above issues by manually creating a geometry metadata table +describing each geometry column. +Its presence is indicated via the Oracle datastore connection parameter named *Geometry metadata table* +(which may be a simple table name or a schema-qualified one). +The table has the following structure (the table name is flexible, just specify the one chosen in the data store connection parameter):: + + CREATE TABLE GEOMETRY_COLUMNS( + F_TABLE_SCHEMA VARCHAR(30) NOT NULL, + F_TABLE_NAME VARCHAR(30) NOT NULL, + F_GEOMETRY_COLUMN VARCHAR(30) NOT NULL, + COORD_DIMENSION INTEGER, + SRID INTEGER NOT NULL, + TYPE VARCHAR(30) NOT NULL, + UNIQUE(F_TABLE_SCHEMA, F_TABLE_NAME, F_GEOMETRY_COLUMN), + CHECK(TYPE IN ('POINT','LINE', 'POLYGON', 'COLLECTION', 'MULTIPOINT', 'MULTILINE', 'MULTIPOLYGON', 'GEOMETRY') )); + +When the table is present the store first searches it for information about each geometry column +to be classified, and falls back on the MDSYS views only if the table does not contain any information. + +Configuring an Oracle database with JNDI +---------------------------------------- + +See :ref:`tomcat_jndi` for a guide on setting up an Oracle connection using JNDI. diff --git a/doc/en/user/source/data/database/sqlserver.rst b/doc/en/user/source/data/database/sqlserver.rst index 61d14f6eb4a..03b810be3b0 100644 --- a/doc/en/user/source/data/database/sqlserver.rst +++ b/doc/en/user/source/data/database/sqlserver.rst @@ -1,102 +1,102 @@ -.. _data_sqlserver: - -Microsoft SQL Server and SQL Azure -================================== - -.. note:: GeoServer does not come built-in with support for SQL Server; it must be installed through an extension. Proceed to :ref:`sqlserver_install` for installation details. - -Microsoft's `SQL Server `_ is a relational database with spatial functionality. SQL Azure is the database option provided in the Azure cloud solution which is in many respects similar to SQL Server. - -Supported versions ------------------- - -The extension supports SQL Server 2008 - 2019 and SQL Azure. - -.. _sqlserver_install: - -Installing the SQL Server extension ------------------------------------ - -GeoServer files -``````````````` - -#. Download the SQL Server extension from the `GeoServer download page `_. - - .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! - -#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. - -#. Restart the GeoServer to load the extension. - -Adding a SQL Server database ----------------------------- - -Once the extension is properly installed ``SQL Server`` will show up as an option when creating a new data store. - -.. figure:: images/sqlservercreate.png - :align: center - - *SQL Server in the list of vector data sources* - -Configuring a SQL Server data store ------------------------------------ - -.. figure:: images/sqlserverconfigure.png - :align: center - - *Configuring a SQL Server data store* - -.. list-table:: - :widths: 20 80 - - * - ``host`` - - The sql server instance host name or ip address, only. Note that ``server\instance`` notation is not accepted - specify the port below, instead, if you have a non-default instance. - * - ``port`` - - The port on which the SQL server instance is accepting connections. See the :ref:`note ` below. - * - ``database`` - - The name of the database to connect to. Might be left blank if the user connecting to SQL Server has a "default database" set in the user configuration - * - ``schema`` - - The database schema to access tables from (optional). - * - ``user`` - - The name of the user to connect to the database as. - * - ``password`` - - The password to use when connecting to the database. Leave blank for no password. - * - ``max connections`` - - ``min connections`` - - - Connection pool configuration parameters. See the :ref:`connection_pooling` section for details. If you are connecting to SQL Azure make sure to set the ``validate connections`` flag as SQL Azure closes inactive connections after a very short delay. - -.. _port_notes: - -Determining the port used by the SQL Server instance -```````````````````````````````````````````````````` - -You can determine the port in use by connecting to your SQL server instance using some other software, and then using :command:`netstat` to display details on network connections. In the following example on a Windows PC, the port is 2646 :: - - C:\>netstat -a | find "sql1" - TCP DPI908194:1918 maittestsql1.dpi.nsw.gov.au:2646 ESTABLISHED - - -Using the geometry metadata table -````````````````````````````````` - -The SQL server data store can determine the geometry type and native SRID of a particular column only by data inspection, -by looking at the first row in the table. Of course this is error prone, and works only if there is data in the table. -The administrator can address the above issue by manually creating a geometry metadata table describing each geometry column. -Its presence is indicated via the SQL Server datastore connection parameter named *Geometry metadata table* -(which may be a simple table name or a schema-qualified one). -The table has the following structure (the table name is flexible, just specify the one chosen in the data store connection parameter):: - - CREATE TABLE GEOMETRY_COLUMNS( - F_TABLE_SCHEMA VARCHAR(30) NOT NULL, - F_TABLE_NAME VARCHAR(30) NOT NULL, - F_GEOMETRY_COLUMN VARCHAR(30) NOT NULL, - COORD_DIMENSION INTEGER, - SRID INTEGER NOT NULL, - TYPE VARCHAR(30) NOT NULL, - UNIQUE(F_TABLE_SCHEMA, F_TABLE_NAME, F_GEOMETRY_COLUMN), - CHECK(TYPE IN ('POINT', 'LINESTRING', 'POLYGON', 'MULTIPOINT', 'MULTILINESTRING', 'MULTIPOLYGON', 'GEOMETRYCOLLECTION') )); - -When the table is present the store first searches it for information about each geometry column -to be classified, and falls back on data inspection only if the table does not contain any information. +.. _data_sqlserver: + +Microsoft SQL Server and SQL Azure +================================== + +.. note:: GeoServer does not come built-in with support for SQL Server; it must be installed through an extension. Proceed to :ref:`sqlserver_install` for installation details. + +Microsoft's `SQL Server `_ is a relational database with spatial functionality. SQL Azure is the database option provided in the Azure cloud solution which is in many respects similar to SQL Server. + +Supported versions +------------------ + +The extension supports SQL Server 2008 - 2019 and SQL Azure. + +.. _sqlserver_install: + +Installing the SQL Server extension +----------------------------------- + +GeoServer files +``````````````` + +#. Download the SQL Server extension from the `GeoServer download page `_. + + .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! + +#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. + +#. Restart the GeoServer to load the extension. + +Adding a SQL Server database +---------------------------- + +Once the extension is properly installed ``SQL Server`` will show up as an option when creating a new data store. + +.. figure:: images/sqlservercreate.png + :align: center + + *SQL Server in the list of vector data sources* + +Configuring a SQL Server data store +----------------------------------- + +.. figure:: images/sqlserverconfigure.png + :align: center + + *Configuring a SQL Server data store* + +.. list-table:: + :widths: 20 80 + + * - ``host`` + - The sql server instance host name or ip address, only. Note that ``server\instance`` notation is not accepted - specify the port below, instead, if you have a non-default instance. + * - ``port`` + - The port on which the SQL server instance is accepting connections. See the :ref:`note ` below. + * - ``database`` + - The name of the database to connect to. Might be left blank if the user connecting to SQL Server has a "default database" set in the user configuration + * - ``schema`` + - The database schema to access tables from (optional). + * - ``user`` + - The name of the user to connect to the database as. + * - ``password`` + - The password to use when connecting to the database. Leave blank for no password. + * - ``max connections`` + + ``min connections`` + + - Connection pool configuration parameters. See the :ref:`connection_pooling` section for details. If you are connecting to SQL Azure make sure to set the ``validate connections`` flag as SQL Azure closes inactive connections after a very short delay. + +.. _port_notes: + +Determining the port used by the SQL Server instance +```````````````````````````````````````````````````` + +You can determine the port in use by connecting to your SQL server instance using some other software, and then using :command:`netstat` to display details on network connections. In the following example on a Windows PC, the port is 2646 :: + + C:\>netstat -a | find "sql1" + TCP DPI908194:1918 maittestsql1.dpi.nsw.gov.au:2646 ESTABLISHED + + +Using the geometry metadata table +````````````````````````````````` + +The SQL server data store can determine the geometry type and native SRID of a particular column only by data inspection, +by looking at the first row in the table. Of course this is error prone, and works only if there is data in the table. +The administrator can address the above issue by manually creating a geometry metadata table describing each geometry column. +Its presence is indicated via the SQL Server datastore connection parameter named *Geometry metadata table* +(which may be a simple table name or a schema-qualified one). +The table has the following structure (the table name is flexible, just specify the one chosen in the data store connection parameter):: + + CREATE TABLE GEOMETRY_COLUMNS( + F_TABLE_SCHEMA VARCHAR(30) NOT NULL, + F_TABLE_NAME VARCHAR(30) NOT NULL, + F_GEOMETRY_COLUMN VARCHAR(30) NOT NULL, + COORD_DIMENSION INTEGER, + SRID INTEGER NOT NULL, + TYPE VARCHAR(30) NOT NULL, + UNIQUE(F_TABLE_SCHEMA, F_TABLE_NAME, F_GEOMETRY_COLUMN), + CHECK(TYPE IN ('POINT', 'LINESTRING', 'POLYGON', 'MULTIPOINT', 'MULTILINESTRING', 'MULTIPOLYGON', 'GEOMETRYCOLLECTION') )); + +When the table is present the store first searches it for information about each geometry column +to be classified, and falls back on data inspection only if the table does not contain any information. diff --git a/doc/en/user/source/data/database/sqlsession.rst b/doc/en/user/source/data/database/sqlsession.rst index 41e184bca1e..cd94db0aa77 100644 --- a/doc/en/user/source/data/database/sqlsession.rst +++ b/doc/en/user/source/data/database/sqlsession.rst @@ -1,71 +1,71 @@ -.. _data_sqlsession: - -Custom SQL session start/stop scripts -===================================== - -Starting with version 2.1.4 GeoServer support custom SQL scripts that can be run every time GeoServer -grabs a connection from the connection pool, and every time the session is returned to the pool. - -These scripts can be parametrized with the expansion of environment variables, which can be in turn -set into the OGC request parameters with the same mechanism as :ref:`sld_variable_substitution`. - -In addition to the parameters provided via the request the ``GSUSER`` variable is guaranteed to -contain the current GeoServer user, or be null if no authentication is available. This is useful -if the SQL sessions scripts are used to provide tight control over database access - -The SQL script can expand environment variables using the ``${variableName, defaultValue}`` syntax, -for example the following alters the current database user to be the same as the GeoServer current user, -or ``geoserver`` in case no user was authenticated - - SET SESSION AUTHORIZATION ${GSUSER,geoserver} - -Using SQL session scripts to control authorizations at the database level -------------------------------------------------------------------------- - -GeoServer connects to a database via a connection pool, using the same rights as the user that -is specified in the connection pool setup. -In a setup that provides a variety of services and tables the connection pool user must have -a rather large set of rights, such as table selection (WMS), table insert/update/delete (WFS-T) and -even table creation (data upload via RESTConfig, WPS Import process and eventual new processes leveraging -direct database connections). - -What a user can do can be controlled by means of the GeoServer security subsystem, but in high security -setups this might not be considered enough, and a database level access control be preferred instead. -In these setups normally the connection pool user has limited access, such as simple read only access, -while specific users are allowed to perform more operations. - -When setting up such a solution remember the following guidelines: - -* The connection pool user must be able to access all table metadata regardless of whether it is able - to actually perform a select on the tables (dictionary tables/describe functionality must be always accessible) -* The connection pool must see each and every column of tables and views, in other words, the - structure of the tables must not change as the current user changes -* the database users and the GeoServer user must be kept in synch with some external tools, GeoServer - provides no out of the box facilities -* during the GeoServer startup the code will access the database to perform some sanity checks, - in that moment there is no user authenticated in GeoServer so the code will run under whatever - user was specified as the "default value" for the ``GSUSER`` variable. -* The user that administers GeoServer (normally ``admin``, but it can be renamed, and other users - given the administration roles too) must also be a database user, all administrative access on the - GeoServer GUI will have that specific user controlling the session - -Typical use cases: - -* Give insert/update/delete rights only to users that must use WFS-T -* Only allow the administrator to create new tables -* Limit what rows of a table a user can see by using dynamic SQL views taking into account the - current user to decide what rows to return - -To make a point in case, if we want the PostgreSQL session to run with the current GeoServer user -credentials the following scripts will be used: - -.. figure:: images/postgresqlSession.png - :align: center - - *Setting up session authorization for PostgreSQL* - -The first command makes the database session use either the current GeoServer user, or the ``geoserver`` -user if no authentication was available (anonymous user, or startup situation). -The second command resets the session to the rights of the connection pool user. - - +.. _data_sqlsession: + +Custom SQL session start/stop scripts +===================================== + +Starting with version 2.1.4 GeoServer support custom SQL scripts that can be run every time GeoServer +grabs a connection from the connection pool, and every time the session is returned to the pool. + +These scripts can be parametrized with the expansion of environment variables, which can be in turn +set into the OGC request parameters with the same mechanism as :ref:`sld_variable_substitution`. + +In addition to the parameters provided via the request the ``GSUSER`` variable is guaranteed to +contain the current GeoServer user, or be null if no authentication is available. This is useful +if the SQL sessions scripts are used to provide tight control over database access + +The SQL script can expand environment variables using the ``${variableName, defaultValue}`` syntax, +for example the following alters the current database user to be the same as the GeoServer current user, +or ``geoserver`` in case no user was authenticated + + SET SESSION AUTHORIZATION ${GSUSER,geoserver} + +Using SQL session scripts to control authorizations at the database level +------------------------------------------------------------------------- + +GeoServer connects to a database via a connection pool, using the same rights as the user that +is specified in the connection pool setup. +In a setup that provides a variety of services and tables the connection pool user must have +a rather large set of rights, such as table selection (WMS), table insert/update/delete (WFS-T) and +even table creation (data upload via RESTConfig, WPS Import process and eventual new processes leveraging +direct database connections). + +What a user can do can be controlled by means of the GeoServer security subsystem, but in high security +setups this might not be considered enough, and a database level access control be preferred instead. +In these setups normally the connection pool user has limited access, such as simple read only access, +while specific users are allowed to perform more operations. + +When setting up such a solution remember the following guidelines: + +* The connection pool user must be able to access all table metadata regardless of whether it is able + to actually perform a select on the tables (dictionary tables/describe functionality must be always accessible) +* The connection pool must see each and every column of tables and views, in other words, the + structure of the tables must not change as the current user changes +* the database users and the GeoServer user must be kept in synch with some external tools, GeoServer + provides no out of the box facilities +* during the GeoServer startup the code will access the database to perform some sanity checks, + in that moment there is no user authenticated in GeoServer so the code will run under whatever + user was specified as the "default value" for the ``GSUSER`` variable. +* The user that administers GeoServer (normally ``admin``, but it can be renamed, and other users + given the administration roles too) must also be a database user, all administrative access on the + GeoServer GUI will have that specific user controlling the session + +Typical use cases: + +* Give insert/update/delete rights only to users that must use WFS-T +* Only allow the administrator to create new tables +* Limit what rows of a table a user can see by using dynamic SQL views taking into account the + current user to decide what rows to return + +To make a point in case, if we want the PostgreSQL session to run with the current GeoServer user +credentials the following scripts will be used: + +.. figure:: images/postgresqlSession.png + :align: center + + *Setting up session authorization for PostgreSQL* + +The first command makes the database session use either the current GeoServer user, or the ``geoserver`` +user if no authentication was available (anonymous user, or startup situation). +The second command resets the session to the rights of the connection pool user. + + diff --git a/doc/en/user/source/data/database/sqlview.rst b/doc/en/user/source/data/database/sqlview.rst index 6e28ab3e23f..4e8e544ece6 100644 --- a/doc/en/user/source/data/database/sqlview.rst +++ b/doc/en/user/source/data/database/sqlview.rst @@ -1,227 +1,227 @@ -.. _sql_views: - -SQL Views -========= - -The traditional way to access database data is to configure layers against either tables or database views. -Starting with GeoServer 2.1.0, layers can also be defined as SQL Views. -SQL Views allow executing a custom SQL query on each request to the layer. -This avoids the need to create a database view for complex queries. - -Even more usefully, SQL View queries can be parameterized via string substitution. -Parameter values can be supplied in both WMS and WFS requests. -Default values can be supplied for parameters, and input values can be validated by Regular Expressions -to eliminate the risk of SQL injection attacks. - -.. note:: - - SQL Views are read-only, and thus cannot be updated by WFS-T transactions. - -Creating a SQL View -------------------------- - -In order to create a SQL View the administrator invokes the :guilabel:`Create new layer` page. -When a database store is selected, the usual list of tables and views available for publication appears, -A link :guilabel:`Configure new SQL view...` also appears: - -.. figure:: images/createsqlview.png - :align: center - -Selecting the :guilabel:`Configure new SQL view...` link opens a new page where the SQL view query can be specified: - -.. figure:: images/createsql.png - :align: center - -.. note:: - - The query can be any SQL statement that is valid as a subquery in a FROM clause (that is, ``select * from () [as] vtable``). - This is the case for most SQL statements, but in some databases special syntax may be needed to call stored procedures. - Also, all the columns returned by the SQL statement must have names. - In some databases alias names are required for function calls. - -When a valid SQL query has been entered, press the :guilabel:`Refresh` link in the **Attributes** table to get the list of the attribute columns determined from the query: - -.. figure:: images/sqlview-attributes.png - :align: center - -GeoServer attempts to determine the geometry column type and the native SRID, but these should be verified and corrected if necessary. - -.. note:: - - Having a correct SRID (spatial reference id) is essential for spatial queries to work. - In many spatial databases the SRID is equal to the EPSG code for the specific spatial reference system, but this is not always the case (for instance, Oracle has a number of non-EPSG SRID codes). - - -If stable feature ids are desired for the view's features, one or more columns providing a unique id for the features should be checked in the **Identifier** column. -Always ensure these attributes generate a unique key, or filtering and WFS requests will not work correctly. - -Once the query and the attribute details are defined, press :guilabel:`Save`. -The usual :guilabel:`New Layer` configuration page will appear. -If further changes to the view are required, the page has a link to the SQL View editor at the bottom of the :guilabel:`Data` tab: - -.. figure:: images/sqlview-edit.png - :align: center - -Once created, the SQL view layer is used in the same way as a conventional table-backed layer, -with the one limitation of being read-only. - -.. warning:: Saving the SQL view definition here is not sufficient, the layer containing it must be saved as well for the change to have any effect. - This is because the SQL view definition is actually just one component of the layer/featuretype/coverage attributes. - -Parameterizing SQL Views ------------------------- - -A parametric SQL view is based on a SQL query containing named parameters. -The values for the parameters can be provided dynamically in WMS and WFS requests -using the ``viewparams`` request parameter. -Parameters can have default values specified, -to handle the situation where they are not supplied in a request. -Validation of supplied parameter values is supported by specifying validation regular expressions. -Parameter values are only accepted if they match the regular expression defined for them. -Appropriate parameter validation should always be used to avoid the risk of `SQL injection attacks `_. - -.. warning:: - - SQL View parameter substitution should be used with caution, since improperly validated parameters open the risk of SQL injection attack. - Where possible, consider using safer methods such as :ref:`dynamic filtering ` in the request, or :ref:`sld_variable_substitution`. - - -Defining parameters -^^^^^^^^^^^^^^^^^^^ - -Within the SQL View query, parameter names are delimited by leading and trailing ``%`` signs. -The parameters can occur anywhere within the query text, -including such uses as within SQL string constants, -in place of SQL keywords, or representing entire SQL clauses. - -Here is an example of a SQL View query for a layer called ``popstates`` with two parameters, ``low`` and ``high``: - -.. figure:: images/sqlview-parametricsql.png - :align: center - -Each parameter needs to be defined with its name, an optional default value, and a validation expression. -The :guilabel:`Guess parameters from SQL` link can be clicked to infer the query parameters automatically, or they can be entered manually. -The result is a table filled with the parameter names, default values and validation expressions: - -.. figure:: images/sqlview-paramdefault.png - :align: center - -In this case the default values should be specified, since the query cannot be executed without values for the parameters (because the expanded query ``select gid, state_name, the_geom from pgstates where persons between and`` is invalid SQL). -Since the use of the parameters in the SQL query requires their values to be positive integer numbers, the validation regular expressions are specified to allow only numeric input (i.e. ``^[\d]+$``): - -.. figure:: images/sqlview-paramcustom.png - :align: center - -Once the parameters have been defined, -the **Attributes** :guilabel:`Refresh` link is clicked to parse the query and retrieve the attribute columns. -The computed geometry type and column identifier details can be corrected if required. -From this point on the workflow is the same as for a non-parameterized query. - - -.. _using_a_parametric_sql_view: - -Using a parametric SQL View -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The SQL view parameters are specified by adding the ``viewparams`` parameter to the WMS ``GetMap`` -or the WFS ``GetFeature`` request. -The ``viewparams`` argument is a list of ``key:value`` pairs, separated by semicolons: - - ``viewparams=p1:v1;p2:v2;...`` - -If the values contain semicolons or commas these must be escaped with a backslash (e.g. ``\,`` and ``\;``). - -For example, the ``popstates`` SQL View layer can be displayed by invoking the :ref:`layerpreview`. -Initially no parameter values are supplied, so the defaults are used and all the states are displayed. - -To display all states having more than 20 million inhabitants the following parameter is added to the ``GetMap`` request: ``&viewparams=low:20000000`` - -.. figure:: images/sqlview-20millions.png - :align: center - -To display all states having between 2 and 5 million inhabitants the view parameters are: ``&viewparams=low:2000000;high:5000000`` - -.. figure:: images/sqlview-2m-5m.png - :align: center - - -Parameters can be provided for multiple layers by separating each parameter map with a comma: - - ``&viewparams=l1p1:v1;l1p2:v2,l2p1:v1;l2p2:v2,...`` - -The number of parameter maps must match the number of layers (featuretypes) included in the request. - -Parameters and validation -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The value of a SQL View parameter can be an arbitrary string of text. -The only constraint is that the attribute names and types returned by the view query must never change. -This makes it possible to create views containing parameters representing complex SQL fragments. -For example, using the view query ``select * from pgstates %where%`` allows specifying the WHERE clause of the query dynamically. -However, this would likely require an empty validation expression. -which presents a serious risk of `SQL injection attacks `_. -This technique should only be used if access to the server is restricted to trusted clients. - -In general, SQL parameters must be used with care. -They should always include validation regular expressions that accept only the intended parameter values. -Note that while validation expressions should be constructed to prevent illegal values, -they do not necessarily have to ensure the values are syntactically correct, -since this will be checked by the database SQL parser. -For example: - - * ``^[\d\.\+-eE]+$`` checks that a parameter value contains valid characters for floating-point numbers (including scientific notation), but does not check that the value is actually a valid number - * ``[^;']+`` checks that a parameter value does not contain quotes or semicolons. This prevents common SQL injection attacks, but otherwise does not impose much limitation on the actual value - -Resources for Validation Regular expressions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Defining effective validation regular expressions is important for security. -Regular expressions are a complex topic that cannot be fully addressed here. -The following are some resources for constructing regular expressions: - - * GeoServer uses the standard Java regular expression engine. The `Pattern class Javadocs `_ contain the full specification of the allowed syntax. - * ``_ has many tutorials and examples of regular expressions. - * The `myregexp `_ applet can be used to test regular expressions online. - -Place holder for the SQL WHERE clause -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The SQL ``WHERE`` clause produced by GeoServer using the context filters, e.g. the bounding box filter of a WMS query, will be added around the SQL view definition. This comes handy (better performance) when we have extra operations that can be done on top of the rows filtered with the GeoServer produced filter first. - -A typical use case for this functionality is the execution of analytic functions on top of the filtered results: - -.. code-block:: sql - - SELECT STATION_NAME, - MEASUREMENT, - MEASUREMENT_TYPE, - LOCATION - FROM - (SELECT STATION_NAME, - MEASUREMENT, - MEASUREMENT_TYPE, - LOCATION, - ROW_NUMBER() OVER(PARTITION BY STATION_ID, MEASUREMENT_TYPE - ORDER BY TIME DESC) AS RANK - FROM - (SELECT st.id AS STATION_ID, - st.common_name AS STATION_NAME, - ob.value AS MEASUREMENT, - pr.param_name AS MEASUREMENT_TYPE, - ob.time AS TIME, - st.position AS LOCATION - FROM meteo.meteo_stations st - LEFT JOIN meteo.meteo_observations ob ON st.id = ob.station_id - LEFT JOIN meteo.meteo_parameters pr ON ob.parameter_id = pr.id - - -- SQL WHERE clause place holder for GeoServer - WHERE 1 = 1 :where_clause:) AS stations_filtered) AS stations - - WHERE RANK = 1; - -A few restrictions apply when using the explicit ``:where_clause:`` place holder: - - * it needs to be added in a position where all the attributes known by GeoServer are already present - * the ``:where_clause:`` can only appear once - -When a ``WHERE`` clause place holder is present, GeoServer will always add an explicit ``AND`` at the beginning of the produced ``WHERE`` clause. This allows the injection of the produced ``WHERE`` in the middle of complex expressions if needed. +.. _sql_views: + +SQL Views +========= + +The traditional way to access database data is to configure layers against either tables or database views. +Starting with GeoServer 2.1.0, layers can also be defined as SQL Views. +SQL Views allow executing a custom SQL query on each request to the layer. +This avoids the need to create a database view for complex queries. + +Even more usefully, SQL View queries can be parameterized via string substitution. +Parameter values can be supplied in both WMS and WFS requests. +Default values can be supplied for parameters, and input values can be validated by Regular Expressions +to eliminate the risk of SQL injection attacks. + +.. note:: + + SQL Views are read-only, and thus cannot be updated by WFS-T transactions. + +Creating a SQL View +------------------------- + +In order to create a SQL View the administrator invokes the :guilabel:`Create new layer` page. +When a database store is selected, the usual list of tables and views available for publication appears, +A link :guilabel:`Configure new SQL view...` also appears: + +.. figure:: images/createsqlview.png + :align: center + +Selecting the :guilabel:`Configure new SQL view...` link opens a new page where the SQL view query can be specified: + +.. figure:: images/createsql.png + :align: center + +.. note:: + + The query can be any SQL statement that is valid as a subquery in a FROM clause (that is, ``select * from () [as] vtable``). + This is the case for most SQL statements, but in some databases special syntax may be needed to call stored procedures. + Also, all the columns returned by the SQL statement must have names. + In some databases alias names are required for function calls. + +When a valid SQL query has been entered, press the :guilabel:`Refresh` link in the **Attributes** table to get the list of the attribute columns determined from the query: + +.. figure:: images/sqlview-attributes.png + :align: center + +GeoServer attempts to determine the geometry column type and the native SRID, but these should be verified and corrected if necessary. + +.. note:: + + Having a correct SRID (spatial reference id) is essential for spatial queries to work. + In many spatial databases the SRID is equal to the EPSG code for the specific spatial reference system, but this is not always the case (for instance, Oracle has a number of non-EPSG SRID codes). + + +If stable feature ids are desired for the view's features, one or more columns providing a unique id for the features should be checked in the **Identifier** column. +Always ensure these attributes generate a unique key, or filtering and WFS requests will not work correctly. + +Once the query and the attribute details are defined, press :guilabel:`Save`. +The usual :guilabel:`New Layer` configuration page will appear. +If further changes to the view are required, the page has a link to the SQL View editor at the bottom of the :guilabel:`Data` tab: + +.. figure:: images/sqlview-edit.png + :align: center + +Once created, the SQL view layer is used in the same way as a conventional table-backed layer, +with the one limitation of being read-only. + +.. warning:: Saving the SQL view definition here is not sufficient, the layer containing it must be saved as well for the change to have any effect. + This is because the SQL view definition is actually just one component of the layer/featuretype/coverage attributes. + +Parameterizing SQL Views +------------------------ + +A parametric SQL view is based on a SQL query containing named parameters. +The values for the parameters can be provided dynamically in WMS and WFS requests +using the ``viewparams`` request parameter. +Parameters can have default values specified, +to handle the situation where they are not supplied in a request. +Validation of supplied parameter values is supported by specifying validation regular expressions. +Parameter values are only accepted if they match the regular expression defined for them. +Appropriate parameter validation should always be used to avoid the risk of `SQL injection attacks `_. + +.. warning:: + + SQL View parameter substitution should be used with caution, since improperly validated parameters open the risk of SQL injection attack. + Where possible, consider using safer methods such as :ref:`dynamic filtering ` in the request, or :ref:`sld_variable_substitution`. + + +Defining parameters +^^^^^^^^^^^^^^^^^^^ + +Within the SQL View query, parameter names are delimited by leading and trailing ``%`` signs. +The parameters can occur anywhere within the query text, +including such uses as within SQL string constants, +in place of SQL keywords, or representing entire SQL clauses. + +Here is an example of a SQL View query for a layer called ``popstates`` with two parameters, ``low`` and ``high``: + +.. figure:: images/sqlview-parametricsql.png + :align: center + +Each parameter needs to be defined with its name, an optional default value, and a validation expression. +The :guilabel:`Guess parameters from SQL` link can be clicked to infer the query parameters automatically, or they can be entered manually. +The result is a table filled with the parameter names, default values and validation expressions: + +.. figure:: images/sqlview-paramdefault.png + :align: center + +In this case the default values should be specified, since the query cannot be executed without values for the parameters (because the expanded query ``select gid, state_name, the_geom from pgstates where persons between and`` is invalid SQL). +Since the use of the parameters in the SQL query requires their values to be positive integer numbers, the validation regular expressions are specified to allow only numeric input (i.e. ``^[\d]+$``): + +.. figure:: images/sqlview-paramcustom.png + :align: center + +Once the parameters have been defined, +the **Attributes** :guilabel:`Refresh` link is clicked to parse the query and retrieve the attribute columns. +The computed geometry type and column identifier details can be corrected if required. +From this point on the workflow is the same as for a non-parameterized query. + + +.. _using_a_parametric_sql_view: + +Using a parametric SQL View +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The SQL view parameters are specified by adding the ``viewparams`` parameter to the WMS ``GetMap`` +or the WFS ``GetFeature`` request. +The ``viewparams`` argument is a list of ``key:value`` pairs, separated by semicolons: + + ``viewparams=p1:v1;p2:v2;...`` + +If the values contain semicolons or commas these must be escaped with a backslash (e.g. ``\,`` and ``\;``). + +For example, the ``popstates`` SQL View layer can be displayed by invoking the :ref:`layerpreview`. +Initially no parameter values are supplied, so the defaults are used and all the states are displayed. + +To display all states having more than 20 million inhabitants the following parameter is added to the ``GetMap`` request: ``&viewparams=low:20000000`` + +.. figure:: images/sqlview-20millions.png + :align: center + +To display all states having between 2 and 5 million inhabitants the view parameters are: ``&viewparams=low:2000000;high:5000000`` + +.. figure:: images/sqlview-2m-5m.png + :align: center + + +Parameters can be provided for multiple layers by separating each parameter map with a comma: + + ``&viewparams=l1p1:v1;l1p2:v2,l2p1:v1;l2p2:v2,...`` + +The number of parameter maps must match the number of layers (featuretypes) included in the request. + +Parameters and validation +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value of a SQL View parameter can be an arbitrary string of text. +The only constraint is that the attribute names and types returned by the view query must never change. +This makes it possible to create views containing parameters representing complex SQL fragments. +For example, using the view query ``select * from pgstates %where%`` allows specifying the WHERE clause of the query dynamically. +However, this would likely require an empty validation expression. +which presents a serious risk of `SQL injection attacks `_. +This technique should only be used if access to the server is restricted to trusted clients. + +In general, SQL parameters must be used with care. +They should always include validation regular expressions that accept only the intended parameter values. +Note that while validation expressions should be constructed to prevent illegal values, +they do not necessarily have to ensure the values are syntactically correct, +since this will be checked by the database SQL parser. +For example: + + * ``^[\d\.\+-eE]+$`` checks that a parameter value contains valid characters for floating-point numbers (including scientific notation), but does not check that the value is actually a valid number + * ``[^;']+`` checks that a parameter value does not contain quotes or semicolons. This prevents common SQL injection attacks, but otherwise does not impose much limitation on the actual value + +Resources for Validation Regular expressions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defining effective validation regular expressions is important for security. +Regular expressions are a complex topic that cannot be fully addressed here. +The following are some resources for constructing regular expressions: + + * GeoServer uses the standard Java regular expression engine. The `Pattern class Javadocs `_ contain the full specification of the allowed syntax. + * ``_ has many tutorials and examples of regular expressions. + * The `myregexp `_ applet can be used to test regular expressions online. + +Place holder for the SQL WHERE clause +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The SQL ``WHERE`` clause produced by GeoServer using the context filters, e.g. the bounding box filter of a WMS query, will be added around the SQL view definition. This comes handy (better performance) when we have extra operations that can be done on top of the rows filtered with the GeoServer produced filter first. + +A typical use case for this functionality is the execution of analytic functions on top of the filtered results: + +.. code-block:: sql + + SELECT STATION_NAME, + MEASUREMENT, + MEASUREMENT_TYPE, + LOCATION + FROM + (SELECT STATION_NAME, + MEASUREMENT, + MEASUREMENT_TYPE, + LOCATION, + ROW_NUMBER() OVER(PARTITION BY STATION_ID, MEASUREMENT_TYPE + ORDER BY TIME DESC) AS RANK + FROM + (SELECT st.id AS STATION_ID, + st.common_name AS STATION_NAME, + ob.value AS MEASUREMENT, + pr.param_name AS MEASUREMENT_TYPE, + ob.time AS TIME, + st.position AS LOCATION + FROM meteo.meteo_stations st + LEFT JOIN meteo.meteo_observations ob ON st.id = ob.station_id + LEFT JOIN meteo.meteo_parameters pr ON ob.parameter_id = pr.id + + -- SQL WHERE clause place holder for GeoServer + WHERE 1 = 1 :where_clause:) AS stations_filtered) AS stations + + WHERE RANK = 1; + +A few restrictions apply when using the explicit ``:where_clause:`` place holder: + + * it needs to be added in a position where all the attributes known by GeoServer are already present + * the ``:where_clause:`` can only appear once + +When a ``WHERE`` clause place holder is present, GeoServer will always add an explicit ``AND`` at the beginning of the produced ``WHERE`` clause. This allows the injection of the produced ``WHERE`` in the middle of complex expressions if needed. diff --git a/doc/en/user/source/data/raster/arcgrid.rst b/doc/en/user/source/data/raster/arcgrid.rst index 1010e4e9756..019dcbf90b5 100644 --- a/doc/en/user/source/data/raster/arcgrid.rst +++ b/doc/en/user/source/data/raster/arcgrid.rst @@ -1,40 +1,40 @@ -.. _data_arcgrid: - -ArcGrid -======= - -ArcGrid is a coverage file format created by ESRI. - -Adding an ArcGrid data store ----------------------------- - -By default, :guilabel:`ArcGrid` will be an option in the :guilabel:`Raster Data Sources` list when creating a new data store. - -.. figure:: images/arcgridcreate.png - :align: center - - *ArcGrid in the list of raster data stores* - -Configuring a ArcGrid data store --------------------------------- - -.. figure:: images/arcgridconfigure.png - :align: center - - *Configuring an ArcGrid data store* - -.. list-table:: - :widths: 20 80 - - * - **Option** - - **Description** - * - ``Workspace`` - - - * - ``Data Source Name`` - - - * - ``Description`` - - - * - ``Enabled`` - - - * - ``URL`` +.. _data_arcgrid: + +ArcGrid +======= + +ArcGrid is a coverage file format created by ESRI. + +Adding an ArcGrid data store +---------------------------- + +By default, :guilabel:`ArcGrid` will be an option in the :guilabel:`Raster Data Sources` list when creating a new data store. + +.. figure:: images/arcgridcreate.png + :align: center + + *ArcGrid in the list of raster data stores* + +Configuring a ArcGrid data store +-------------------------------- + +.. figure:: images/arcgridconfigure.png + :align: center + + *Configuring an ArcGrid data store* + +.. list-table:: + :widths: 20 80 + + * - **Option** + - **Description** + * - ``Workspace`` + - + * - ``Data Source Name`` + - + * - ``Description`` + - + * - ``Enabled`` + - + * - ``URL`` - \ No newline at end of file diff --git a/doc/en/user/source/data/raster/geotiff.rst b/doc/en/user/source/data/raster/geotiff.rst index d4bd73507d3..e5b41f6ac4e 100644 --- a/doc/en/user/source/data/raster/geotiff.rst +++ b/doc/en/user/source/data/raster/geotiff.rst @@ -1,47 +1,47 @@ -.. _data_geotiff: - -GeoTIFF -======= - -A GeoTIFF is a georeferenced TIFF (Tagged Image File Format) file. - -Adding a GeoTIFF data store ---------------------------- - -By default, :guilabel:`GeoTIFF` will be an option in the :guilabel:`Raster Data Sources` list when creating a new data store. - -.. figure:: images/geotiffcreate.png - :align: center - - *GeoTIFF in the list of raster data stores* - -Configuring a GeoTIFF data store --------------------------------- - -.. figure:: images/geotiffconfigure.png - :align: center - - *Configuring a GeoTIFF data store* - -.. list-table:: - :widths: 20 80 - - * - **Option** - - **Description** - * - ``Workspace`` - - Name of the workspace to contain the GeoTIFF store. This will also be the prefix of the raster layer created from the store. - * - ``Data Source Name`` - - Name of the GeoTIFF as it will be known to GeoServer. This can be different from the filename. The combination of the workspace name and this name will be the full layer name (ex: world:landbase) - * - ``Description`` - - A full free-form description of the GeoTIFF store. - * - ``Enabled`` - - If checked, it enables the store. If unchecked (disabled), no data in the GeoTIFF will be served from GeoServer. - * - ``URL`` - - Location of the GeoTIFF file. This can be an absolute path (such as :file:`file:C:\\Data\\landbase.tif`) or a path relative to GeoServer's data directory (such as :file:`file:data/landbase.tif`). - -.. note:: Notice that the GeoTiff plugin is able to handle internal/external overviews and internal/external masks. - -Custom CRS definition -````````````````````` - -Creating an auxiliary ``.prj`` file that contains coordinate reference system information as described in the :ref:`crs_custom` chapter will override internal CRS tags that are included in the original GeoTIFF file. This can be used to work-around problematic source files without making modifications to the file. +.. _data_geotiff: + +GeoTIFF +======= + +A GeoTIFF is a georeferenced TIFF (Tagged Image File Format) file. + +Adding a GeoTIFF data store +--------------------------- + +By default, :guilabel:`GeoTIFF` will be an option in the :guilabel:`Raster Data Sources` list when creating a new data store. + +.. figure:: images/geotiffcreate.png + :align: center + + *GeoTIFF in the list of raster data stores* + +Configuring a GeoTIFF data store +-------------------------------- + +.. figure:: images/geotiffconfigure.png + :align: center + + *Configuring a GeoTIFF data store* + +.. list-table:: + :widths: 20 80 + + * - **Option** + - **Description** + * - ``Workspace`` + - Name of the workspace to contain the GeoTIFF store. This will also be the prefix of the raster layer created from the store. + * - ``Data Source Name`` + - Name of the GeoTIFF as it will be known to GeoServer. This can be different from the filename. The combination of the workspace name and this name will be the full layer name (ex: world:landbase) + * - ``Description`` + - A full free-form description of the GeoTIFF store. + * - ``Enabled`` + - If checked, it enables the store. If unchecked (disabled), no data in the GeoTIFF will be served from GeoServer. + * - ``URL`` + - Location of the GeoTIFF file. This can be an absolute path (such as :file:`file:C:\\Data\\landbase.tif`) or a path relative to GeoServer's data directory (such as :file:`file:data/landbase.tif`). + +.. note:: Notice that the GeoTiff plugin is able to handle internal/external overviews and internal/external masks. + +Custom CRS definition +````````````````````` + +Creating an auxiliary ``.prj`` file that contains coordinate reference system information as described in the :ref:`crs_custom` chapter will override internal CRS tags that are included in the original GeoTIFF file. This can be used to work-around problematic source files without making modifications to the file. diff --git a/doc/en/user/source/data/raster/imagepyramid.rst b/doc/en/user/source/data/raster/imagepyramid.rst index 37569f5588c..3fb5db579a4 100644 --- a/doc/en/user/source/data/raster/imagepyramid.rst +++ b/doc/en/user/source/data/raster/imagepyramid.rst @@ -1,54 +1,54 @@ -.. _data_imagepyramid: - -ImagePyramid -============= - -.. note:: GeoServer does not come built-in with support for Image Pyramid; it must be installed through an extension. Proceed to :ref:`imagepyramid_install` for installation details. - -An image pyramid is several layers of an image rendered at various image sizes, to be shown at different zoom levels. - -.. _imagepyramid_install: - -Installing the ImagePyramid extension -------------------------------------- - -#. Download the ImagePyramid extension from the `GeoServer download page - `_. - - .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! - -#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. - -Adding an ImagePyramid data store ---------------------------------- - -Once the extension is properly installed :guilabel:`ImagePyramid` will be an option in the :guilabel:`Raster Data Sources` list when creating a new data store. - -.. figure:: images/imagepyramidcreate.png - :align: center - - *ImagePyramid in the list of raster data stores* - -Configuring an ImagePyramid data store --------------------------------------- - -.. figure:: images/imagepyramidconfigure.png - :align: center - - *Configuring an ImagePyramid data store* - -.. list-table:: - :widths: 20 80 - - * - **Option** - - **Description** - * - ``Workspace`` - - - * - ``Data Source Name`` - - - * - ``Description`` - - - * - ``Enabled`` - - - * - ``URL`` +.. _data_imagepyramid: + +ImagePyramid +============= + +.. note:: GeoServer does not come built-in with support for Image Pyramid; it must be installed through an extension. Proceed to :ref:`imagepyramid_install` for installation details. + +An image pyramid is several layers of an image rendered at various image sizes, to be shown at different zoom levels. + +.. _imagepyramid_install: + +Installing the ImagePyramid extension +------------------------------------- + +#. Download the ImagePyramid extension from the `GeoServer download page + `_. + + .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! + +#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. + +Adding an ImagePyramid data store +--------------------------------- + +Once the extension is properly installed :guilabel:`ImagePyramid` will be an option in the :guilabel:`Raster Data Sources` list when creating a new data store. + +.. figure:: images/imagepyramidcreate.png + :align: center + + *ImagePyramid in the list of raster data stores* + +Configuring an ImagePyramid data store +-------------------------------------- + +.. figure:: images/imagepyramidconfigure.png + :align: center + + *Configuring an ImagePyramid data store* + +.. list-table:: + :widths: 20 80 + + * - **Option** + - **Description** + * - ``Workspace`` + - + * - ``Data Source Name`` + - + * - ``Description`` + - + * - ``Enabled`` + - + * - ``URL`` - \ No newline at end of file diff --git a/doc/en/user/source/data/raster/worldimage.rst b/doc/en/user/source/data/raster/worldimage.rst index 57abaaa0a07..3c3c70ffeb5 100644 --- a/doc/en/user/source/data/raster/worldimage.rst +++ b/doc/en/user/source/data/raster/worldimage.rst @@ -1,40 +1,40 @@ -.. _data_worldimage: - -WorldImage -========== - -A world file is a plain text file used to georeference raster map images. This file (often with an extension of ``.jgw`` or ``.tfw``) accompanies an associated image file (``.jpg`` or ``.tif``). Together, the world file and the corresponding image file is known as a WorldImage in GeoServer. - -Adding a WorldImage data store ------------------------------- - -By default, :guilabel:`WorldImage` will be an option in the :guilabel:`Raster Data Sources` list when creating a new data store. - -.. figure:: images/worldimagecreate.png - :align: center - - *WorldImage in the list of raster data stores* - -Configuring a WorldImage data store ------------------------------------ - -.. figure:: images/worldimageconfigure.png - :align: center - - *Configuring a WorldImage data store* - -.. list-table:: - :widths: 20 80 - - * - **Option** - - **Description** - * - ``Workspace`` - - - * - ``Data Source Name`` - - - * - ``Description`` - - - * - ``Enabled`` - - - * - ``URL`` +.. _data_worldimage: + +WorldImage +========== + +A world file is a plain text file used to georeference raster map images. This file (often with an extension of ``.jgw`` or ``.tfw``) accompanies an associated image file (``.jpg`` or ``.tif``). Together, the world file and the corresponding image file is known as a WorldImage in GeoServer. + +Adding a WorldImage data store +------------------------------ + +By default, :guilabel:`WorldImage` will be an option in the :guilabel:`Raster Data Sources` list when creating a new data store. + +.. figure:: images/worldimagecreate.png + :align: center + + *WorldImage in the list of raster data stores* + +Configuring a WorldImage data store +----------------------------------- + +.. figure:: images/worldimageconfigure.png + :align: center + + *Configuring a WorldImage data store* + +.. list-table:: + :widths: 20 80 + + * - **Option** + - **Description** + * - ``Workspace`` + - + * - ``Data Source Name`` + - + * - ``Description`` + - + * - ``Enabled`` + - + * - ``URL`` - \ No newline at end of file diff --git a/doc/en/user/source/data/vector/featurepregen.rst b/doc/en/user/source/data/vector/featurepregen.rst index 4e47dc63f97..218ffe35b0a 100644 --- a/doc/en/user/source/data/vector/featurepregen.rst +++ b/doc/en/user/source/data/vector/featurepregen.rst @@ -1,36 +1,36 @@ -.. _data_featurepregen: - -Pregeneralized Features -======================= - -.. note:: GeoServer does not come built-in with support for Pregeneralized Features; it must be installed through an extension. - -Installing the Pregeneralized Features extension ------------------------------------------------- - -#. Download the Pregeneralized Features extension from the `GeoServer download page - `_. - - .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! - -#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. - -Adding a Pregeneralized Features data store -------------------------------------------- - -If the extension is properly installed, :guilabel:`Generalized Data Store` will be listed as an option when creating a new data store. - -.. figure:: images/featurepregencreate.png - :align: center - - *Generalized Data Store in the list of vector data stores* - -Configuring a Pregeneralized Features data store ------------------------------------------------- - -.. figure:: images/featurepregenconfigure.png - :align: center - - *Configuring a Pregeneralized Features data store* - -For a detailed description, look at the :doc:`Tutorial` +.. _data_featurepregen: + +Pregeneralized Features +======================= + +.. note:: GeoServer does not come built-in with support for Pregeneralized Features; it must be installed through an extension. + +Installing the Pregeneralized Features extension +------------------------------------------------ + +#. Download the Pregeneralized Features extension from the `GeoServer download page + `_. + + .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! + +#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. + +Adding a Pregeneralized Features data store +------------------------------------------- + +If the extension is properly installed, :guilabel:`Generalized Data Store` will be listed as an option when creating a new data store. + +.. figure:: images/featurepregencreate.png + :align: center + + *Generalized Data Store in the list of vector data stores* + +Configuring a Pregeneralized Features data store +------------------------------------------------ + +.. figure:: images/featurepregenconfigure.png + :align: center + + *Configuring a Pregeneralized Features data store* + +For a detailed description, look at the :doc:`Tutorial` diff --git a/doc/en/user/source/data/vector/gml.rst b/doc/en/user/source/data/vector/gml.rst index 96bfe17c98b..bb15865a177 100644 --- a/doc/en/user/source/data/vector/gml.rst +++ b/doc/en/user/source/data/vector/gml.rst @@ -1,47 +1,47 @@ -.. _data_gml: - -GML -=== - -.. note:: GeoServer does not come built-in with support for GML; it must be installed through an extension. Proceed to :ref:`gml_install` for installation details. - -.. warning:: Currently the GML extension is unmaintained and carries unsupported status. While still usable, do not expect the same reliability as with other extension. - -Geographic Markup Language (GML) is a XML based format for representing vector based spatial data. - - -Supported versions ------------------- - -Currently GML version 2 is supported. - -.. _gml_install: - -Installing the GML extension ----------------------------- - -#. Download the GML extension from the `GeoServer download page - `_. - - .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! - -#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. - -Adding a GML data store ------------------------ - -Once the extension is properly installed :guilabel:`GML` will be an option in the :guilabel:`Vector Data Sources` list when creating a new data store. - -.. figure:: images/gmlcreate.png - :align: center - - *GML in the list of vector data stores* - -Configuring a GML data store ----------------------------- - -.. figure:: images/gmlconfigure.png - :align: center - - *Configuring a GML data store* +.. _data_gml: + +GML +=== + +.. note:: GeoServer does not come built-in with support for GML; it must be installed through an extension. Proceed to :ref:`gml_install` for installation details. + +.. warning:: Currently the GML extension is unmaintained and carries unsupported status. While still usable, do not expect the same reliability as with other extension. + +Geographic Markup Language (GML) is a XML based format for representing vector based spatial data. + + +Supported versions +------------------ + +Currently GML version 2 is supported. + +.. _gml_install: + +Installing the GML extension +---------------------------- + +#. Download the GML extension from the `GeoServer download page + `_. + + .. warning:: Make sure to match the version of the extension to the version of the GeoServer instance! + +#. Extract the contents of the archive into the ``WEB-INF/lib`` directory of the GeoServer installation. + +Adding a GML data store +----------------------- + +Once the extension is properly installed :guilabel:`GML` will be an option in the :guilabel:`Vector Data Sources` list when creating a new data store. + +.. figure:: images/gmlcreate.png + :align: center + + *GML in the list of vector data stores* + +Configuring a GML data store +---------------------------- + +.. figure:: images/gmlconfigure.png + :align: center + + *Configuring a GML data store* \ No newline at end of file diff --git a/doc/en/user/source/extensions/excel.rst b/doc/en/user/source/extensions/excel.rst index 46140b15636..23ce34497b3 100644 --- a/doc/en/user/source/extensions/excel.rst +++ b/doc/en/user/source/extensions/excel.rst @@ -1,50 +1,50 @@ -.. _excel_extension: - -Excel WFS Output Format -======================= - -The GeoServer Excel plugin adds the ability to output WFS responses in either Excel 97-2003 (``.xls``) or Excel 2007 (``.xlsx``) formats. - -Installation ------------- - - 1. Download the Excel plugin for your version of GeoServer from the `download page `_. - 2. Unzip the archive into the WEB-INF/lib directory of the GeoServer installation. - 3. Restart GeoServer. - -Usage ------ - -When making a WFS request, set the ``outputFormat`` to ``excel`` (for Excel 97-2003) or ``excel2007`` (for Excel 2007). - -Examples --------- - -Excel 97-2003 GET: - http://localhost:8080/geoserver/wfs?request=GetFeature&version=1.1.0&typeName=topp:states&outputFormat=excel - -Excel 2007 GET: - http://localhost:8080/geoserver/wfs?request=GetFeature&version=1.1.0&typeName=topp:states&outputFormat=excel2007 - -**Excel 97-2003 POST**:: - - - - - -Limitations ------------ - -Excel 97-2003 files are stored in a binary format and are thus space-efficient, but have inherent size limitations (65,526 rows per sheet; 256 columns per sheet). - -Excel 2007 files are XML-based, and have much higher limits (1,048,576 rows per sheet; 16,384 columns per sheet). -However, because they are text files Excel 2007 files are usually larger than Excel 97-2003 files. - -If the number of rows in a sheet or characters in a cell exceeds the limits of the chosen Excel file format, warning text is inserted to indicate the truncation. +.. _excel_extension: + +Excel WFS Output Format +======================= + +The GeoServer Excel plugin adds the ability to output WFS responses in either Excel 97-2003 (``.xls``) or Excel 2007 (``.xlsx``) formats. + +Installation +------------ + + 1. Download the Excel plugin for your version of GeoServer from the `download page `_. + 2. Unzip the archive into the WEB-INF/lib directory of the GeoServer installation. + 3. Restart GeoServer. + +Usage +----- + +When making a WFS request, set the ``outputFormat`` to ``excel`` (for Excel 97-2003) or ``excel2007`` (for Excel 2007). + +Examples +-------- + +Excel 97-2003 GET: + http://localhost:8080/geoserver/wfs?request=GetFeature&version=1.1.0&typeName=topp:states&outputFormat=excel + +Excel 2007 GET: + http://localhost:8080/geoserver/wfs?request=GetFeature&version=1.1.0&typeName=topp:states&outputFormat=excel2007 + +**Excel 97-2003 POST**:: + + + + + +Limitations +----------- + +Excel 97-2003 files are stored in a binary format and are thus space-efficient, but have inherent size limitations (65,526 rows per sheet; 256 columns per sheet). + +Excel 2007 files are XML-based, and have much higher limits (1,048,576 rows per sheet; 16,384 columns per sheet). +However, because they are text files Excel 2007 files are usually larger than Excel 97-2003 files. + +If the number of rows in a sheet or characters in a cell exceeds the limits of the chosen Excel file format, warning text is inserted to indicate the truncation. diff --git a/doc/en/user/source/extensions/imagemap.rst b/doc/en/user/source/extensions/imagemap.rst index 045136fc33f..67fc86c30d5 100644 --- a/doc/en/user/source/extensions/imagemap.rst +++ b/doc/en/user/source/extensions/imagemap.rst @@ -1,63 +1,63 @@ -.. _imagemap_extension: - -Imagemap -======== - -HTML ImageMaps have been used for a long time to create interactive images in a light way. Without using Flash, SVG or VML you can simply associate different links or tooltips to different regions of an image. -Why can't we use this technique to achieve the same result on a GeoServer map? -The idea is to combine a raster map (png, gif, jpeg, ...) with an HTML ImageMap overlay to add links, tooltips, or mouse events behavior to the map. - -An example of an ImageMap adding tooltips to a map: - -.. code-block:: xml - - - - - - - -An example of an ImageMap adding links to a map: - -.. code-block:: xml - - - - - - - -A more complex example adding interactive behaviour on mouse events: - -.. code-block:: xml - - - - - - - -To realize this in GeoServer some great community contributors developed an HTMLImageMap GetMapProducer for GeoServer, able to render an HTMLImageMap in response to a WMS GetMap request. - -The GetMapProducer is associated to the text/html mime type. It produces, for each requested layer, a ... section containing the geometries of the layer as distinct tags. -Due to the limitations in the shape types supported by the tag, a single geometry can be split into multiple ones. This way almost any complex geometry can be rendered transforming it into simpler ones. - -To add interactive attributes we use styling. In particular, an SLD Rule containing a TextSymbolizer with a Label definition can be used to define dynamic values for the tags attributes. The Rule name will be used as the attribute name. - -As an example, to define a title attribute (associating a tooltip to the geometries of the layer) you can use a rule like the following one: - -.. code-block:: xml - - - title - - - - - -To render multiple attributes, just define multiple rules, with different names (href, onmouseover, etc.) - -Styling support is not limited to TextSymbolizers, you can currently use other symbolizers to detail rendering. For example you can: - - * use a PointSymbolizer with a Size property to define point sizes. - * use LineSymbolizer with a stroke-width CssParameter to create thick lines. +.. _imagemap_extension: + +Imagemap +======== + +HTML ImageMaps have been used for a long time to create interactive images in a light way. Without using Flash, SVG or VML you can simply associate different links or tooltips to different regions of an image. +Why can't we use this technique to achieve the same result on a GeoServer map? +The idea is to combine a raster map (png, gif, jpeg, ...) with an HTML ImageMap overlay to add links, tooltips, or mouse events behavior to the map. + +An example of an ImageMap adding tooltips to a map: + +.. code-block:: xml + + + + + + + +An example of an ImageMap adding links to a map: + +.. code-block:: xml + + + + + + + +A more complex example adding interactive behaviour on mouse events: + +.. code-block:: xml + + + + + + + +To realize this in GeoServer some great community contributors developed an HTMLImageMap GetMapProducer for GeoServer, able to render an HTMLImageMap in response to a WMS GetMap request. + +The GetMapProducer is associated to the text/html mime type. It produces, for each requested layer, a ... section containing the geometries of the layer as distinct tags. +Due to the limitations in the shape types supported by the tag, a single geometry can be split into multiple ones. This way almost any complex geometry can be rendered transforming it into simpler ones. + +To add interactive attributes we use styling. In particular, an SLD Rule containing a TextSymbolizer with a Label definition can be used to define dynamic values for the tags attributes. The Rule name will be used as the attribute name. + +As an example, to define a title attribute (associating a tooltip to the geometries of the layer) you can use a rule like the following one: + +.. code-block:: xml + + + title + + + + + +To render multiple attributes, just define multiple rules, with different names (href, onmouseover, etc.) + +Styling support is not limited to TextSymbolizers, you can currently use other symbolizers to detail rendering. For example you can: + + * use a PointSymbolizer with a Size property to define point sizes. + * use LineSymbolizer with a stroke-width CssParameter to create thick lines. diff --git a/doc/en/user/source/extensions/index.rst b/doc/en/user/source/extensions/index.rst index e6e0328dacf..494d354b38f 100644 --- a/doc/en/user/source/extensions/index.rst +++ b/doc/en/user/source/extensions/index.rst @@ -1,43 +1,43 @@ -.. _extensions: - -Extensions -========== - -Extensions are modules that add functionality to GeoServer. They are installed as add-ons to the base GeoServer installation. - -This section describes most of the extensions available for GeoServer. Other data formats can be found in the :ref:`data_vector`, :ref:`data_raster`, :ref:`data_database`, and :ref:`styling` sections. - -.. toctree:: - :maxdepth: 1 - - authkey/index - controlflow/index - dxf/index - excel - grib/grib - imagemap - importer/index - inspire/index - jp2k/index - libjpeg-turbo/index - monitoring/index - netcdf/netcdf - netcdf-out/index - ogr - printing/index - querylayer/index - vectortiles/index - xslt/index - wcs20eo/index - mongodb/index - sldservice/index - geofence/index - geofence-server/index - cas/index - params-extractor/index - gwc-s3/index - wmts-multidimensional/index - wps-download/index - wps-jdbc/index - mapml/index - +.. _extensions: + +Extensions +========== + +Extensions are modules that add functionality to GeoServer. They are installed as add-ons to the base GeoServer installation. + +This section describes most of the extensions available for GeoServer. Other data formats can be found in the :ref:`data_vector`, :ref:`data_raster`, :ref:`data_database`, and :ref:`styling` sections. + +.. toctree:: + :maxdepth: 1 + + authkey/index + controlflow/index + dxf/index + excel + grib/grib + imagemap + importer/index + inspire/index + jp2k/index + libjpeg-turbo/index + monitoring/index + netcdf/netcdf + netcdf-out/index + ogr + printing/index + querylayer/index + vectortiles/index + xslt/index + wcs20eo/index + mongodb/index + sldservice/index + geofence/index + geofence-server/index + cas/index + params-extractor/index + gwc-s3/index + wmts-multidimensional/index + wps-download/index + wps-jdbc/index + mapml/index + diff --git a/doc/en/user/source/extensions/inspire/installing.rst b/doc/en/user/source/extensions/inspire/installing.rst index 45bdcfd6297..425b34f97ee 100644 --- a/doc/en/user/source/extensions/inspire/installing.rst +++ b/doc/en/user/source/extensions/inspire/installing.rst @@ -1,14 +1,14 @@ -.. _inspire_installing: - -Installing the INSPIRE extension -================================ - -The INSPIRE extension is a official extension available at `GeoServer download `_ pages (starting with GeoServer 2.3.2). - -#. Download the inspire zip release file from the download page of your version of GeoServer - -#. Extract the archive and copy the contents into the ``/WEB-INF/lib`` directory. - -#. Restart GeoServer. - -To verify that the extension was installed successfully, please see the next section on :ref:`inspire_using`. +.. _inspire_installing: + +Installing the INSPIRE extension +================================ + +The INSPIRE extension is a official extension available at `GeoServer download `_ pages (starting with GeoServer 2.3.2). + +#. Download the inspire zip release file from the download page of your version of GeoServer + +#. Extract the archive and copy the contents into the ``/WEB-INF/lib`` directory. + +#. Restart GeoServer. + +To verify that the extension was installed successfully, please see the next section on :ref:`inspire_using`. diff --git a/doc/en/user/source/extensions/inspire/using.rst b/doc/en/user/source/extensions/inspire/using.rst index 60db98410d6..ff65c3ddc94 100644 --- a/doc/en/user/source/extensions/inspire/using.rst +++ b/doc/en/user/source/extensions/inspire/using.rst @@ -1,191 +1,191 @@ -.. _inspire_using: - -Using the INSPIRE extension -=========================== - -When the INSPIRE extension has been properly installed, the :ref:`services_webadmin_wms`, :ref:`services_webadmin_wfs` and :ref:`services_webadmin_wcs` sections of the :ref:`web_admin` will show an extra INSPIRE configuration section. If the data directory has not been configured with INSPIRE parameters before, this section will just contain a check box to enable the creation of an INSPIRE ExtendedCapabilities element. - -.. figure:: images/noinspire.png - :align: center - -.. note:: If you do not see this content in the service configuration pages, the INSPIRE extension may not be installed properly. Reread the section on :ref:`inspire_installing` and verify that the correct file was saved to the correct directory. - -Extended WMS and WMTS configuration ------------------------------------ - -INSPIRE-specific configuration is accessed on the main :ref:`services_webadmin_wms` or WMTS settings page in the :ref:`web_admin`. This is accessed by clicking on the :guilabel:`WMS` or :guilabel:`WMTS` link on the sidebar. - -.. note:: You must be logged in as an administrator to edit WMS or WMTS configuration. - -Once on the service configuration page, there will be a block titled :guilabel:`INSPIRE`. If you enable the checkbox shown above this section will have three additional settings: - -* :guilabel:`Default Language` combo box, for setting the Default -* :guilabel:`Other Supported Languages` area for setting Supported Languages -* :guilabel:`Service Metadata URL` field, a URL containing the location of the metadata associated with the service -* :guilabel:`Service Metadata Type` combo box, for detailing whether the metadata came from a CSW (Catalog Service) or a standalone metadata file - -.. figure:: images/inspire.png - :align: center - - *INSPIRE-related options* - -After clicking :guilabel:`Submit` on this page, any changes will be immediately reflected in the services (WMS 1.3.0 or WMTS 1.0.0) capabilities document. - -.. note:: The :guilabel:`Service Metadata URL` field is mandatory so you will not be allowed to submit a blank value. - -.. note:: The :guilabel:`Service Metadata Type` combo box only allows to select the appropriate MIME type for a CSW response or standalone metadata file or to omit a value altogether. If you think other values would be useful you could raise the issue on the :ref:`GeoServer mailing list `. In the meantime it is possible to manually edit the created configuration files as a workaround. - -Extended WMS and WMTS Capabilities ----------------------------------- - -.. note:: The INSPIRE extension only modifies the WMS 1.3.0 response, so please make sure that you are viewing the correct capabilities document. - -The WMS 1.3.0 and WMTS 1.0.0 capabilities document will contain two additional entries in the ``xsi:schemaLocation`` of the root ```` tag once the INSPIRE extension is installed: - -* ``http://inspire.ec.europa.eu/schemas/inspire_vs/1.0`` -* ``https://inspire.ec.europa.eu/schemas/inspire_vs/1.0/inspire_vs.xsd`` - -If you have enabled the check box to create the INSPIRE ExtendedCapabilities element and entered the values described in the previous section then there will also be an additional ExtendedCapabilities block. This tag block shows up in between the tags for ```` and ````. It contains the following information: - -* Metadata URL and MIME type -* Supported Language(s) -* Response Language - -With the example values shown in the above configuration panel, this block would contain the following content:: - - - - - http://mysite.org/metadata.xml - - - application/vnd.iso.19139+xml - - - - - eng - - fre - - - eng - - - -ISNPIRE recommends that every layer offered by a INSPIRE WMTS should use the InspireCRS84Quad grid set which is already configured in GeoServer, but is up to the user to select it when publishing a INSPIRE WMTS layer. - -Extended WFS and WCS configuration ----------------------------------- - -INSPIRE-specific configuration is accessed on the main :ref:`services_webadmin_wfs` and :ref:`services_webadmin_wcs` pages in the :ref:`web_admin`. These are accessed by clicking on the :guilabel:`WFS` and :guilabel:`WCS` links on the sidebar respectively. - -.. note:: You must be logged in as an administrator to edit WFS configuration. - -Once on the WFS or WCS configuration page, there will be a block titled :guilabel:`INSPIRE`. If you enable the checkbox shown above this section will have the following additional settings: - -* :guilabel:`Language` combo box, for setting the Supported, Default, and Response languages -* :guilabel:`Other Supported Languages` area for setting Supported Languages -* :guilabel:`Service Metadata URL` field, a URL containing the location of the metadata associated with the WFS or WCS -* :guilabel:`Service Metadata Type` combo box, for detailing whether the metadata came from a CSW (Catalog Service) or a standalone metadata file -* :guilabel:`Spatial dataset identifers` table, where you can specify a code (mandatory), a namespace (optional) and a metadata URL (optional) for each spatial data set the WFS or WCS is offering - -.. figure:: images/inspire_wfs.png - :align: center - - *INSPIRE-related options* - -After clicking :guilabel:`Submit` on this page, any changes will be immediately reflected in the WFS 1.1 and WFS 2.0 or WCS 2.0 capabilities documents as appropriate. - -.. note:: The :guilabel:`Service Metadata URL` field and at least one :guilabel:`Spatial dataset identifers` entry are mandatory so you will not be allowed to submit the page without these. - -.. note:: The :guilabel:`Service Metadata Type` combo box only allows to select the appropriate MIME type for a CSW response or standalone metadata file or to omit a value altogether. If you think other values would be useful you could raise the issue on the :ref:`GeoServer mailing list `. In the meantime it is possible to manually edit the created configuration files as a workaround. - -Extended WFS and WCS Capabilities ---------------------------------- - -.. note:: The INSPIRE directive is relevant to WFS 1.1 and 2.0 and WCS 2.0 only, so please make sure that you are viewing the correct capabilities document. - -The WFS and WCS capabilities documents will contain two additional entries in the ``xsi:schemaLocation`` of the root element tag once the INSPIRE extension is installed: - -* ``https://inspire.ec.europa.eu/schemas/common/1.0/common.xsd`` -* ``https://inspire.ec.europa.eu/schemas/inspire_dls/1.0/inspire_dls.xsd`` - -If you have enabled the check box to create the INSPIRE ExtendedCapabilities element and entered the values described in the previous section then there will also be an additional ExtendedCapabilities block with the following information: - -* Metadata URL and MIME type -* Supported Language(s) -* Response Language -* Spatial data identifier(s) - -With the example values shown in the above configuration panel, this block would contain the following content:: - - - - - http://mysite.org/csw?SERVICE=CSW&REQUEST=GetRecord - - - application/vnd.iso.19139+xml - - - - - eng - - fre - - - eng - - - - fc929094-8a30-2617-e044-002128a47908 - - - http://metadata.mysite.org/ds - - - - -The spatial data identifiers section is mandatory, but cannot be filled by default, it is your duty to provide at least one spatial dataset identifier (see the INSPIRE download service technical guidelines for more information). - -Internationalization support ----------------------------- - -GeoServer offers the ability to configure GetCapabilities response in multiple languages. Content in different laguages can be requested by using the request parameter `Language`, e.g. `Language=eng`. At the time of writing, the following services support the parameter: WFS 2.0, WMS 1.1 and 1.3, WCS 2.0. - -At the time of writing the `INSPIRE Schemas `_ only allow 23 choices for :guilabel:`DefaultLanguage`. The GeoServer INSPIRE extension allows some other languages to be chosen. If you choose one of these your capabilities document won't be Schema valid but, as discussed in :geos:`issue 7388 <7388>`, the INSPIRE Schemas seem to be at fault. - -The language list available from the UI is define in a classpath file named ``available_languages.properties`` with the following content:: - - bul=bg - cze=cs - dan=da - dut=nl - eng=en - est=et - fin=fi - fre=fr - hrv=hr - ice=is - ger=de - gle=ga - gre=el - gsw=de-CH - hun=hu - ita=it - lav=lv - lit=lt - mlt=mt - nor=nb - pol=pl - por=pt - rum=ro - slo=sk - slv=sl - spa=es - swe=sv - -The entries of the above list represent the available INSPIRE language code matched with the corresponding ``ISO 639-1`` code. The GeoServer internationalization support is based on OWS 2.0, and thus using ISO codes internally. The INSPIRE module maps on the fly the INSPIRE names to ISO codes based on the above property file. -The property file can be overridden by placing a properties file named ``available_languages.properties`` in the ``inspire`` directory inside the GeoServer data directory. +.. _inspire_using: + +Using the INSPIRE extension +=========================== + +When the INSPIRE extension has been properly installed, the :ref:`services_webadmin_wms`, :ref:`services_webadmin_wfs` and :ref:`services_webadmin_wcs` sections of the :ref:`web_admin` will show an extra INSPIRE configuration section. If the data directory has not been configured with INSPIRE parameters before, this section will just contain a check box to enable the creation of an INSPIRE ExtendedCapabilities element. + +.. figure:: images/noinspire.png + :align: center + +.. note:: If you do not see this content in the service configuration pages, the INSPIRE extension may not be installed properly. Reread the section on :ref:`inspire_installing` and verify that the correct file was saved to the correct directory. + +Extended WMS and WMTS configuration +----------------------------------- + +INSPIRE-specific configuration is accessed on the main :ref:`services_webadmin_wms` or WMTS settings page in the :ref:`web_admin`. This is accessed by clicking on the :guilabel:`WMS` or :guilabel:`WMTS` link on the sidebar. + +.. note:: You must be logged in as an administrator to edit WMS or WMTS configuration. + +Once on the service configuration page, there will be a block titled :guilabel:`INSPIRE`. If you enable the checkbox shown above this section will have three additional settings: + +* :guilabel:`Default Language` combo box, for setting the Default +* :guilabel:`Other Supported Languages` area for setting Supported Languages +* :guilabel:`Service Metadata URL` field, a URL containing the location of the metadata associated with the service +* :guilabel:`Service Metadata Type` combo box, for detailing whether the metadata came from a CSW (Catalog Service) or a standalone metadata file + +.. figure:: images/inspire.png + :align: center + + *INSPIRE-related options* + +After clicking :guilabel:`Submit` on this page, any changes will be immediately reflected in the services (WMS 1.3.0 or WMTS 1.0.0) capabilities document. + +.. note:: The :guilabel:`Service Metadata URL` field is mandatory so you will not be allowed to submit a blank value. + +.. note:: The :guilabel:`Service Metadata Type` combo box only allows to select the appropriate MIME type for a CSW response or standalone metadata file or to omit a value altogether. If you think other values would be useful you could raise the issue on the :ref:`GeoServer mailing list `. In the meantime it is possible to manually edit the created configuration files as a workaround. + +Extended WMS and WMTS Capabilities +---------------------------------- + +.. note:: The INSPIRE extension only modifies the WMS 1.3.0 response, so please make sure that you are viewing the correct capabilities document. + +The WMS 1.3.0 and WMTS 1.0.0 capabilities document will contain two additional entries in the ``xsi:schemaLocation`` of the root ```` tag once the INSPIRE extension is installed: + +* ``http://inspire.ec.europa.eu/schemas/inspire_vs/1.0`` +* ``https://inspire.ec.europa.eu/schemas/inspire_vs/1.0/inspire_vs.xsd`` + +If you have enabled the check box to create the INSPIRE ExtendedCapabilities element and entered the values described in the previous section then there will also be an additional ExtendedCapabilities block. This tag block shows up in between the tags for ```` and ````. It contains the following information: + +* Metadata URL and MIME type +* Supported Language(s) +* Response Language + +With the example values shown in the above configuration panel, this block would contain the following content:: + + + + + http://mysite.org/metadata.xml + + + application/vnd.iso.19139+xml + + + + + eng + + fre + + + eng + + + +ISNPIRE recommends that every layer offered by a INSPIRE WMTS should use the InspireCRS84Quad grid set which is already configured in GeoServer, but is up to the user to select it when publishing a INSPIRE WMTS layer. + +Extended WFS and WCS configuration +---------------------------------- + +INSPIRE-specific configuration is accessed on the main :ref:`services_webadmin_wfs` and :ref:`services_webadmin_wcs` pages in the :ref:`web_admin`. These are accessed by clicking on the :guilabel:`WFS` and :guilabel:`WCS` links on the sidebar respectively. + +.. note:: You must be logged in as an administrator to edit WFS configuration. + +Once on the WFS or WCS configuration page, there will be a block titled :guilabel:`INSPIRE`. If you enable the checkbox shown above this section will have the following additional settings: + +* :guilabel:`Language` combo box, for setting the Supported, Default, and Response languages +* :guilabel:`Other Supported Languages` area for setting Supported Languages +* :guilabel:`Service Metadata URL` field, a URL containing the location of the metadata associated with the WFS or WCS +* :guilabel:`Service Metadata Type` combo box, for detailing whether the metadata came from a CSW (Catalog Service) or a standalone metadata file +* :guilabel:`Spatial dataset identifers` table, where you can specify a code (mandatory), a namespace (optional) and a metadata URL (optional) for each spatial data set the WFS or WCS is offering + +.. figure:: images/inspire_wfs.png + :align: center + + *INSPIRE-related options* + +After clicking :guilabel:`Submit` on this page, any changes will be immediately reflected in the WFS 1.1 and WFS 2.0 or WCS 2.0 capabilities documents as appropriate. + +.. note:: The :guilabel:`Service Metadata URL` field and at least one :guilabel:`Spatial dataset identifers` entry are mandatory so you will not be allowed to submit the page without these. + +.. note:: The :guilabel:`Service Metadata Type` combo box only allows to select the appropriate MIME type for a CSW response or standalone metadata file or to omit a value altogether. If you think other values would be useful you could raise the issue on the :ref:`GeoServer mailing list `. In the meantime it is possible to manually edit the created configuration files as a workaround. + +Extended WFS and WCS Capabilities +--------------------------------- + +.. note:: The INSPIRE directive is relevant to WFS 1.1 and 2.0 and WCS 2.0 only, so please make sure that you are viewing the correct capabilities document. + +The WFS and WCS capabilities documents will contain two additional entries in the ``xsi:schemaLocation`` of the root element tag once the INSPIRE extension is installed: + +* ``https://inspire.ec.europa.eu/schemas/common/1.0/common.xsd`` +* ``https://inspire.ec.europa.eu/schemas/inspire_dls/1.0/inspire_dls.xsd`` + +If you have enabled the check box to create the INSPIRE ExtendedCapabilities element and entered the values described in the previous section then there will also be an additional ExtendedCapabilities block with the following information: + +* Metadata URL and MIME type +* Supported Language(s) +* Response Language +* Spatial data identifier(s) + +With the example values shown in the above configuration panel, this block would contain the following content:: + + + + + http://mysite.org/csw?SERVICE=CSW&REQUEST=GetRecord + + + application/vnd.iso.19139+xml + + + + + eng + + fre + + + eng + + + + fc929094-8a30-2617-e044-002128a47908 + + + http://metadata.mysite.org/ds + + + + +The spatial data identifiers section is mandatory, but cannot be filled by default, it is your duty to provide at least one spatial dataset identifier (see the INSPIRE download service technical guidelines for more information). + +Internationalization support +---------------------------- + +GeoServer offers the ability to configure GetCapabilities response in multiple languages. Content in different laguages can be requested by using the request parameter `Language`, e.g. `Language=eng`. At the time of writing, the following services support the parameter: WFS 2.0, WMS 1.1 and 1.3, WCS 2.0. + +At the time of writing the `INSPIRE Schemas `_ only allow 23 choices for :guilabel:`DefaultLanguage`. The GeoServer INSPIRE extension allows some other languages to be chosen. If you choose one of these your capabilities document won't be Schema valid but, as discussed in :geos:`issue 7388 <7388>`, the INSPIRE Schemas seem to be at fault. + +The language list available from the UI is define in a classpath file named ``available_languages.properties`` with the following content:: + + bul=bg + cze=cs + dan=da + dut=nl + eng=en + est=et + fin=fi + fre=fr + hrv=hr + ice=is + ger=de + gle=ga + gre=el + gsw=de-CH + hun=hu + ita=it + lav=lv + lit=lt + mlt=mt + nor=nb + pol=pl + por=pt + rum=ro + slo=sk + slv=sl + spa=es + swe=sv + +The entries of the above list represent the available INSPIRE language code matched with the corresponding ``ISO 639-1`` code. The GeoServer internationalization support is based on OWS 2.0, and thus using ISO codes internally. The INSPIRE module maps on the fly the INSPIRE names to ISO codes based on the above property file. +The property file can be overridden by placing a properties file named ``available_languages.properties`` in the ``inspire`` directory inside the GeoServer data directory. diff --git a/doc/en/user/source/extensions/jp2k/index.rst b/doc/en/user/source/extensions/jp2k/index.rst index c85f76ebccd..5c334425116 100644 --- a/doc/en/user/source/extensions/jp2k/index.rst +++ b/doc/en/user/source/extensions/jp2k/index.rst @@ -1,37 +1,37 @@ -.. _jp2k_extension: - -JP2K Plugin -============ - -GeoServer can leverage the JP2K Geotools plugin to read JP2K coverage formats. -In case you have a Kakadu license and you have built your set of native libraries, -you will be able to access the JP2K data with higher performances leveraging on it. -Otherwise you will use the standard SUN's JP2K. -See :geotools:`GeoTools JP2K Plugin ` for further information. - - -Installing Kakadu -***************** - -In order for GeoServer to leverage on the Kakadu libraries, the Kakadu binaries must be -installed through your host system's OS. - -If you are on Windows, make sure that the Kakadu DLL files are on your PATH. -If you are on Linux, be sure to set the LD_LIBRARY_PATH environment variable to be the folder -where the SOs are extracted. - - -Once these steps have been completed, restart GeoServer. -If done correctly, new data formats will be in the Raster Data Sources list when creating a new data store: - - -.. figure:: images/datasets.png - :align: center - - *Raster Data Source* - - -.. figure:: images/jp2k.png - :align: center - - *Configuring a JP2K data store* +.. _jp2k_extension: + +JP2K Plugin +============ + +GeoServer can leverage the JP2K Geotools plugin to read JP2K coverage formats. +In case you have a Kakadu license and you have built your set of native libraries, +you will be able to access the JP2K data with higher performances leveraging on it. +Otherwise you will use the standard SUN's JP2K. +See :geotools:`GeoTools JP2K Plugin ` for further information. + + +Installing Kakadu +***************** + +In order for GeoServer to leverage on the Kakadu libraries, the Kakadu binaries must be +installed through your host system's OS. + +If you are on Windows, make sure that the Kakadu DLL files are on your PATH. +If you are on Linux, be sure to set the LD_LIBRARY_PATH environment variable to be the folder +where the SOs are extracted. + + +Once these steps have been completed, restart GeoServer. +If done correctly, new data formats will be in the Raster Data Sources list when creating a new data store: + + +.. figure:: images/datasets.png + :align: center + + *Raster Data Source* + + +.. figure:: images/jp2k.png + :align: center + + *Configuring a JP2K data store* diff --git a/doc/en/user/source/extensions/monitoring/audit.rst b/doc/en/user/source/extensions/monitoring/audit.rst index 6d25d5bfc98..9cf00de6757 100644 --- a/doc/en/user/source/extensions/monitoring/audit.rst +++ b/doc/en/user/source/extensions/monitoring/audit.rst @@ -1,137 +1,137 @@ -.. _monitor_audit: - -Audit Logging -============= - -The history mode logs all requests into a database. This can put a very significant strain -on the database and can lead to insertion issues as the request table begins to host -millions of records. - -As an alternative to the history mode it's possible to enable the auditing logger, which will log -the details of each request in a file, which is periodically rolled. Secondary applications can -then process these log files and built ad-hoc summaries off line. - -Configuration -------------- - -The ``monitor.properties`` file can contain the following items to enable and configure file auditing:: - - audit.enabled=true - audit.path=/path/to/the/logs/directory - audit.roll_limit=20 - -The ``audit.enable`` is used to turn on the logger (it is off by default). -The ``audit.path`` is the directory where the log files will be created. -The ``audit.roll_limit`` is the number of requests logged into a file before rolling happens. -The files are also automatically rolled at the beginning of each day. - -In clustered installations with a shared data directory the audit path will need to be different -for each node. In this case it's possible to specify the audit path by using a JVM system variable, -add the following to the JVM startup options and it will override whatever is specified in -``monitor.properties``: - - -DGEOSERVER_AUDIT_PATH=/path/to/the/logs/directory - -Log Files ---------- - -The log directory will contain a number of log files following the ``geoserver_audit_yyyymmdd_nn.log`` -pattern. The ``nn`` is increased at each roll of the file. The contents of the log directory will look like:: - - geoserver_audit_20110811_2.log - geoserver_audit_20110811_3.log - geoserver_audit_20110811_4.log - geoserver_audit_20110811_5.log - geoserver_audit_20110811_6.log - geoserver_audit_20110811_7.log - geoserver_audit_20110811_8.log - -By default each log file contents will be a xml document looking like the following:: - - - - - WMS - 1.1.1 - GetMap - - GeoSolutions:elba-deparea - 4 - 0 - /GeoSolutions/wms - LAYERS=GeoSolutions:elba-deparea&STYLES=&FORMAT=image/png&TILED=true&TILESORIGIN=9.916,42.312&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&EXCEPTIONS=application/vnd.ogc.se_inimage&SRS=EPSG:4326&BBOX=9.58375,42.64425,9.916,42.9765&WIDTH=256&HEIGHT=256 - GET - 2011-08-11T20:19:28.277Z - 2011-08-11T20:19:28.29Z - 13 - 192.168.1.5 - 192.168.1.5 - demo1.geo-solutions.it - admin - 200 - 1670 - image/png - false - - ... - - -Customizing Log Contents ------------------------- - -The log contents are driven by three FreeMarker templates. - -``header.ftl`` is used once when a new log file is created to form the first few lines of the file. -The default header template is:: - - - - -``content.ftl`` is used to write out the request details. The default template dumps all the known fields about the request:: - - <#escape x as x?xml> - - ${service!""} - ${owsVersion!""} - ${operation!""} - ${subOperation!""} - ${resourcesList!""} - ${resourcesProcessingTimeList!""} - ${labellingProcessingTime!""} - ${path!""} - ${queryString!""} - <#if bodyAsString??> - - ${bodyAsString} - - - ${httpMethod!""} - ${startTime?datetime?iso_utc_ms} - ${endTime?datetime?iso_utc_ms} - ${totalTime} - ${remoteAddr!""} - ${remoteHost!""} - ${host} - ${remoteUser!""} - ${responseStatus!""} - ${responseLength?c} - ${responseContentType!""} - ${cacheResult!""} - ${missReason!""} - <#if error??> - true - ${errorMessage!""} - <#else> - false - - - - - -``footer.ftl`` is executed just once when the log file is closed to build the last few lines of the file. -The default footer template is:: - - - -The administrator is free to provide alternate templates, they can be placed in the same directory +.. _monitor_audit: + +Audit Logging +============= + +The history mode logs all requests into a database. This can put a very significant strain +on the database and can lead to insertion issues as the request table begins to host +millions of records. + +As an alternative to the history mode it's possible to enable the auditing logger, which will log +the details of each request in a file, which is periodically rolled. Secondary applications can +then process these log files and built ad-hoc summaries off line. + +Configuration +------------- + +The ``monitor.properties`` file can contain the following items to enable and configure file auditing:: + + audit.enabled=true + audit.path=/path/to/the/logs/directory + audit.roll_limit=20 + +The ``audit.enable`` is used to turn on the logger (it is off by default). +The ``audit.path`` is the directory where the log files will be created. +The ``audit.roll_limit`` is the number of requests logged into a file before rolling happens. +The files are also automatically rolled at the beginning of each day. + +In clustered installations with a shared data directory the audit path will need to be different +for each node. In this case it's possible to specify the audit path by using a JVM system variable, +add the following to the JVM startup options and it will override whatever is specified in +``monitor.properties``: + + -DGEOSERVER_AUDIT_PATH=/path/to/the/logs/directory + +Log Files +--------- + +The log directory will contain a number of log files following the ``geoserver_audit_yyyymmdd_nn.log`` +pattern. The ``nn`` is increased at each roll of the file. The contents of the log directory will look like:: + + geoserver_audit_20110811_2.log + geoserver_audit_20110811_3.log + geoserver_audit_20110811_4.log + geoserver_audit_20110811_5.log + geoserver_audit_20110811_6.log + geoserver_audit_20110811_7.log + geoserver_audit_20110811_8.log + +By default each log file contents will be a xml document looking like the following:: + + + + + WMS + 1.1.1 + GetMap + + GeoSolutions:elba-deparea + 4 + 0 + /GeoSolutions/wms + LAYERS=GeoSolutions:elba-deparea&STYLES=&FORMAT=image/png&TILED=true&TILESORIGIN=9.916,42.312&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&EXCEPTIONS=application/vnd.ogc.se_inimage&SRS=EPSG:4326&BBOX=9.58375,42.64425,9.916,42.9765&WIDTH=256&HEIGHT=256 + GET + 2011-08-11T20:19:28.277Z + 2011-08-11T20:19:28.29Z + 13 + 192.168.1.5 + 192.168.1.5 + demo1.geo-solutions.it + admin + 200 + 1670 + image/png + false + + ... + + +Customizing Log Contents +------------------------ + +The log contents are driven by three FreeMarker templates. + +``header.ftl`` is used once when a new log file is created to form the first few lines of the file. +The default header template is:: + + + + +``content.ftl`` is used to write out the request details. The default template dumps all the known fields about the request:: + + <#escape x as x?xml> + + ${service!""} + ${owsVersion!""} + ${operation!""} + ${subOperation!""} + ${resourcesList!""} + ${resourcesProcessingTimeList!""} + ${labellingProcessingTime!""} + ${path!""} + ${queryString!""} + <#if bodyAsString??> + + ${bodyAsString} + + + ${httpMethod!""} + ${startTime?datetime?iso_utc_ms} + ${endTime?datetime?iso_utc_ms} + ${totalTime} + ${remoteAddr!""} + ${remoteHost!""} + ${host} + ${remoteUser!""} + ${responseStatus!""} + ${responseLength?c} + ${responseContentType!""} + ${cacheResult!""} + ${missReason!""} + <#if error??> + true + ${errorMessage!""} + <#else> + false + + + + + +``footer.ftl`` is executed just once when the log file is closed to build the last few lines of the file. +The default footer template is:: + + + +The administrator is free to provide alternate templates, they can be placed in the same directory as ``monitor.properties``, with the same names as above. GeoServer will pick them up automatically. \ No newline at end of file diff --git a/doc/en/user/source/extensions/monitoring/index.rst b/doc/en/user/source/extensions/monitoring/index.rst index 8c1bbb85ee9..d766b8a05a1 100644 --- a/doc/en/user/source/extensions/monitoring/index.rst +++ b/doc/en/user/source/extensions/monitoring/index.rst @@ -1,25 +1,25 @@ -.. _monitor_extension: - -Monitoring -========== - -The monitor extension tracks requests made against a GeoServer instance. With the -extension request data can be persisted to a database, used to generate simple reports -, and routed to a customized request audit log. - -To get the extension proceed to :ref:`monitor_installation`. To learn more about how -it works jump to the :ref:`monitor_overview` section. - - -.. toctree:: - :maxdepth: 2 - - installation/ - overview/ - reference/ - configuration/ - audit/ - query/ - geoip/ - - +.. _monitor_extension: + +Monitoring +========== + +The monitor extension tracks requests made against a GeoServer instance. With the +extension request data can be persisted to a database, used to generate simple reports +, and routed to a customized request audit log. + +To get the extension proceed to :ref:`monitor_installation`. To learn more about how +it works jump to the :ref:`monitor_overview` section. + + +.. toctree:: + :maxdepth: 2 + + installation/ + overview/ + reference/ + configuration/ + audit/ + query/ + geoip/ + + diff --git a/doc/en/user/source/extensions/ogr.rst b/doc/en/user/source/extensions/ogr.rst index a8c5449bd9e..7c12d220a3f 100644 --- a/doc/en/user/source/extensions/ogr.rst +++ b/doc/en/user/source/extensions/ogr.rst @@ -1,214 +1,214 @@ -.. _ogr_extension: - -OGR based WFS Output Format -============================ - -The ogr2ogr based output format leverages the availability of the ogr2ogr command to allow the generation of more output formats than GeoServer can natively produce. -The basics idea is to dump to the file system a file that ogr2ogr can translate, invoke it, zip and return the output of the translation. - -Out of the box behaviour ------------------------- - -Out of the box the plugin assumes the following: - -* ogr2ogr is available in the path -* the GDAL_DATA variable is pointing to the GDAL data directory (which stores the spatial reference information for GDAL) - -In the default configuration the following formats are supported: - -* MapInfo in TAB format -* MapInfo in MIF format -* Un-styled KML -* CSV (without geometry data dumps) - -The list might be shorter if ogr2ogr has not been built with support for the above formats. - -Once installed in GeoServer four new GetFeature output formats will be available, in particular, ``OGR-TAB``, ``OGR-MIF``, ``OGR-KML``, ``OGR-CSV``. - -ogr2ogr conversion abilities ----------------------------- - -The ogr2ogr utility is usually able to convert more formats than the default setup of this output format allows for, but the exact list depends on how the utility was built from sources. To get a full list of the formats available by your ogr2ogr build just run:: - - ogr2ogr --help - -and you'll get the full set of options usable by the program, along with the supported formats. For example, the above produces the following output using the FWTools 2.2.8 distribution (which includes ogr2ogr among other useful information and conversion tools):: - - Usage: ogr2ogr [--help-general] [-skipfailures] [-append] [-update] [-gt n] - [-select field_list] [-where restricted_where] - [-sql ] - [-spat xmin ymin xmax ymax] [-preserve_fid] [-fid FID] - [-a_srs srs_def] [-t_srs srs_def] [-s_srs srs_def] - [-f format_name] [-overwrite] [[-dsco NAME=VALUE] ...] - [-segmentize max_dist] - dst_datasource_name src_datasource_name - [-lco NAME=VALUE] [-nln name] [-nlt type] [layer [layer ...]] - - -f format_name: output file format name, possible values are: - -f "ESRI Shapefile" - -f "MapInfo File" - -f "TIGER" - -f "S57" - -f "DGN" - -f "Memory" - -f "BNA" - -f "CSV" - -f "GML" - -f "GPX" - -f "KML" - -f "GeoJSON" - -f "Interlis 1" - -f "Interlis 2" - -f "GMT" - -f "SQLite" - -f "ODBC" - -f "PostgreSQL" - -f "MySQL" - -f "Geoconcept" - -append: Append to existing layer instead of creating new if it exists - -overwrite: delete the output layer and recreate it empty - -update: Open existing output datasource in update mode - -select field_list: Comma-delimited list of fields from input layer to - copy to the new layer (defaults to all) - -where restricted_where: Attribute query (like SQL WHERE) - -sql statement: Execute given SQL statement and save result. - -skipfailures: skip features or layers that fail to convert - -gt n: group n features per transaction (default 200) - -spat xmin ymin xmax ymax: spatial query extents - -segmentize max_dist: maximum distance between 2 nodes. - Used to create intermediate points - -dsco NAME=VALUE: Dataset creation option (format specific) - -lco NAME=VALUE: Layer creation option (format specific) - -nln name: Assign an alternate name to the new layer - -nlt type: Force a geometry type for new layer. One of NONE, GEOMETRY, - POINT, LINESTRING, POLYGON, GEOMETRYCOLLECTION, MULTIPOINT, - MULTIPOLYGON, or MULTILINESTRING. Add "25D" for 3D layers. - Default is type of source layer. - -a_srs srs_def: Assign an output SRS - -t_srs srs_def: Reproject/transform to this SRS on output - -s_srs srs_def: Override source SRS - - Srs_def can be a full WKT definition (hard to escape properly), - or a well known definition (ie. EPSG:4326) or a file with a WKT - definition. - -The full list of formats that ogr2ogr is able to support is available on the `OGR site `_. Mind that this output format can handle only outputs that are file based and that do support creation. So, for example, you won't be able to use the Postgres output (since it's database based) or the ArcInfo binary coverage (creation not supported). - -Customisation -------------- - -If ogr2ogr is not available in the default path, the GDAL_DATA is not set, or if the output formats needs tweaking, a ``ogr2ogr.xml`` file can be put in the root of the GeoServer data directory to customize the output format. - -The default GeoServer configuration is equivalent to the following xml file: - -.. code-block:: xml - - - ogr2ogr - - - - MapInfo File - OGR-TAB - .tab - - - MapInfo File - OGR-MIF - .mif - - - - - CSV - OGR-CSV - .csv - true - text/csv - - - KML - OGR-KML - .kml - true - application/vnd.google-earth.kml - - - - -The file showcases all possible usage of the configuration elements: - -* ``ogr2ogrLocation`` can be just ogr2ogr if the command is in the path, otherwise it should be the full path to the executable. For example, on a Windows box with FWTools installed it might be:: - - c:\Programmi\FWTools2.2.8\bin\ogr2ogr.exe - -* ``gdalData`` must point to the GDAL data directory. For example, on a Windows box with FWTools installed it might be:: - - c:\Programmi\FWTools2.2.8\data - -* ``Format`` defines a single format, which is defined by the following tags: - - * ``ogrFormat``: the name of the format to be passed to ogr2ogr with the -f option (it's case sensitive). - * ``formatName``: is the name of the output format as advertised by GeoServer - * ``fileExtension``: is the extension of the file generated after the translation, if any (can be omitted) - * ``option``: can be used to add one or more options to the ogr2ogr command line. As you can see by the MIF example, each item must be contained in its own tag. You can get a full list of options by running ogr2ogr --help or by visiting the ogr2ogr web page. Also consider that each format supports specific creation options, listed in the description page for each format (for example, here is the MapInfo one). - * ``singleFile`` (since 2.0.3): if true the output of the conversion is supposed to be a single file that can be streamed directly back without the need to wrap it into a zip file - * ``mimeType`` (since 2.0.3): the mime type of the file returned when using ``singleFile``. If not specified ``application/octet-stream`` will be used as a default. - -OGR based WPS Output Format -=========================== - -The OGR based WPS output format provides the ability to turn feature collection (vector layer) output types into formats supported by OGR, -using the same configuration and same machinery provided by the OGR WFS output format (which should also be installed for the WPS portion to work). - -Unlike the WFS case the WPS output formats are receiving different treatment in WPS responses depending on whether they are binary, text, or xml, when the Execute response -style chosen by the client is "document": - -* Binary types need to be base64 encoded for XML embedding -* Text types need to be included inside a CDATA section -* XML types can be integrated in the response as-is - -In order to understand the nature of the output format a new optional configuration element, ````, can -be added to the ``ogr2ogr.xml`` configuration file in order to specify the output nature. -The possible values are ``binary``, ``text``, ``xml``, in case the value is missing, ``binary`` is assumed. -Here is an example showing all possible combinations: - -.. code-block:: xml - - - ogr2ogr - - - - MapInfo File - OGR-TAB - .tab - binary - - - MapInfo File - OGR-MIF - .mif - - - - - CSV - OGR-CSV - .csv - true - text/csv - - - text - - - KML - OGR-KML - .kml - true - application/vnd.google-earth.kml - xml - - - +.. _ogr_extension: + +OGR based WFS Output Format +============================ + +The ogr2ogr based output format leverages the availability of the ogr2ogr command to allow the generation of more output formats than GeoServer can natively produce. +The basics idea is to dump to the file system a file that ogr2ogr can translate, invoke it, zip and return the output of the translation. + +Out of the box behaviour +------------------------ + +Out of the box the plugin assumes the following: + +* ogr2ogr is available in the path +* the GDAL_DATA variable is pointing to the GDAL data directory (which stores the spatial reference information for GDAL) + +In the default configuration the following formats are supported: + +* MapInfo in TAB format +* MapInfo in MIF format +* Un-styled KML +* CSV (without geometry data dumps) + +The list might be shorter if ogr2ogr has not been built with support for the above formats. + +Once installed in GeoServer four new GetFeature output formats will be available, in particular, ``OGR-TAB``, ``OGR-MIF``, ``OGR-KML``, ``OGR-CSV``. + +ogr2ogr conversion abilities +---------------------------- + +The ogr2ogr utility is usually able to convert more formats than the default setup of this output format allows for, but the exact list depends on how the utility was built from sources. To get a full list of the formats available by your ogr2ogr build just run:: + + ogr2ogr --help + +and you'll get the full set of options usable by the program, along with the supported formats. For example, the above produces the following output using the FWTools 2.2.8 distribution (which includes ogr2ogr among other useful information and conversion tools):: + + Usage: ogr2ogr [--help-general] [-skipfailures] [-append] [-update] [-gt n] + [-select field_list] [-where restricted_where] + [-sql ] + [-spat xmin ymin xmax ymax] [-preserve_fid] [-fid FID] + [-a_srs srs_def] [-t_srs srs_def] [-s_srs srs_def] + [-f format_name] [-overwrite] [[-dsco NAME=VALUE] ...] + [-segmentize max_dist] + dst_datasource_name src_datasource_name + [-lco NAME=VALUE] [-nln name] [-nlt type] [layer [layer ...]] + + -f format_name: output file format name, possible values are: + -f "ESRI Shapefile" + -f "MapInfo File" + -f "TIGER" + -f "S57" + -f "DGN" + -f "Memory" + -f "BNA" + -f "CSV" + -f "GML" + -f "GPX" + -f "KML" + -f "GeoJSON" + -f "Interlis 1" + -f "Interlis 2" + -f "GMT" + -f "SQLite" + -f "ODBC" + -f "PostgreSQL" + -f "MySQL" + -f "Geoconcept" + -append: Append to existing layer instead of creating new if it exists + -overwrite: delete the output layer and recreate it empty + -update: Open existing output datasource in update mode + -select field_list: Comma-delimited list of fields from input layer to + copy to the new layer (defaults to all) + -where restricted_where: Attribute query (like SQL WHERE) + -sql statement: Execute given SQL statement and save result. + -skipfailures: skip features or layers that fail to convert + -gt n: group n features per transaction (default 200) + -spat xmin ymin xmax ymax: spatial query extents + -segmentize max_dist: maximum distance between 2 nodes. + Used to create intermediate points + -dsco NAME=VALUE: Dataset creation option (format specific) + -lco NAME=VALUE: Layer creation option (format specific) + -nln name: Assign an alternate name to the new layer + -nlt type: Force a geometry type for new layer. One of NONE, GEOMETRY, + POINT, LINESTRING, POLYGON, GEOMETRYCOLLECTION, MULTIPOINT, + MULTIPOLYGON, or MULTILINESTRING. Add "25D" for 3D layers. + Default is type of source layer. + -a_srs srs_def: Assign an output SRS + -t_srs srs_def: Reproject/transform to this SRS on output + -s_srs srs_def: Override source SRS + + Srs_def can be a full WKT definition (hard to escape properly), + or a well known definition (ie. EPSG:4326) or a file with a WKT + definition. + +The full list of formats that ogr2ogr is able to support is available on the `OGR site `_. Mind that this output format can handle only outputs that are file based and that do support creation. So, for example, you won't be able to use the Postgres output (since it's database based) or the ArcInfo binary coverage (creation not supported). + +Customisation +------------- + +If ogr2ogr is not available in the default path, the GDAL_DATA is not set, or if the output formats needs tweaking, a ``ogr2ogr.xml`` file can be put in the root of the GeoServer data directory to customize the output format. + +The default GeoServer configuration is equivalent to the following xml file: + +.. code-block:: xml + + + ogr2ogr + + + + MapInfo File + OGR-TAB + .tab + + + MapInfo File + OGR-MIF + .mif + + + + + CSV + OGR-CSV + .csv + true + text/csv + + + KML + OGR-KML + .kml + true + application/vnd.google-earth.kml + + + + +The file showcases all possible usage of the configuration elements: + +* ``ogr2ogrLocation`` can be just ogr2ogr if the command is in the path, otherwise it should be the full path to the executable. For example, on a Windows box with FWTools installed it might be:: + + c:\Programmi\FWTools2.2.8\bin\ogr2ogr.exe + +* ``gdalData`` must point to the GDAL data directory. For example, on a Windows box with FWTools installed it might be:: + + c:\Programmi\FWTools2.2.8\data + +* ``Format`` defines a single format, which is defined by the following tags: + + * ``ogrFormat``: the name of the format to be passed to ogr2ogr with the -f option (it's case sensitive). + * ``formatName``: is the name of the output format as advertised by GeoServer + * ``fileExtension``: is the extension of the file generated after the translation, if any (can be omitted) + * ``option``: can be used to add one or more options to the ogr2ogr command line. As you can see by the MIF example, each item must be contained in its own tag. You can get a full list of options by running ogr2ogr --help or by visiting the ogr2ogr web page. Also consider that each format supports specific creation options, listed in the description page for each format (for example, here is the MapInfo one). + * ``singleFile`` (since 2.0.3): if true the output of the conversion is supposed to be a single file that can be streamed directly back without the need to wrap it into a zip file + * ``mimeType`` (since 2.0.3): the mime type of the file returned when using ``singleFile``. If not specified ``application/octet-stream`` will be used as a default. + +OGR based WPS Output Format +=========================== + +The OGR based WPS output format provides the ability to turn feature collection (vector layer) output types into formats supported by OGR, +using the same configuration and same machinery provided by the OGR WFS output format (which should also be installed for the WPS portion to work). + +Unlike the WFS case the WPS output formats are receiving different treatment in WPS responses depending on whether they are binary, text, or xml, when the Execute response +style chosen by the client is "document": + +* Binary types need to be base64 encoded for XML embedding +* Text types need to be included inside a CDATA section +* XML types can be integrated in the response as-is + +In order to understand the nature of the output format a new optional configuration element, ````, can +be added to the ``ogr2ogr.xml`` configuration file in order to specify the output nature. +The possible values are ``binary``, ``text``, ``xml``, in case the value is missing, ``binary`` is assumed. +Here is an example showing all possible combinations: + +.. code-block:: xml + + + ogr2ogr + + + + MapInfo File + OGR-TAB + .tab + binary + + + MapInfo File + OGR-MIF + .mif + + + + + CSV + OGR-CSV + .csv + true + text/csv + + + text + + + KML + OGR-KML + .kml + true + application/vnd.google-earth.kml + xml + + + diff --git a/doc/en/user/source/extensions/params-extractor/usage.rst b/doc/en/user/source/extensions/params-extractor/usage.rst index de6e804093f..05b689d95e8 100644 --- a/doc/en/user/source/extensions/params-extractor/usage.rst +++ b/doc/en/user/source/extensions/params-extractor/usage.rst @@ -1,212 +1,212 @@ -.. _params_extractor_usage: - -Using the Parameters Extractor module -===================================== - -This module allow us to entering specific request parameters as URL path fragments instead of using the query string. -For example, we want to be able to apply a cql_filter using a URL in the following form:: - - /geoserver////ows?service=WMS&version=1.3.0&request=GetMap - -As a simple example of usage, if the is something like:: - - K_140M - -the URL would become:: - - /geoserver///K_140M/ows?service=WMS&version=1.3.0&request=GetMap - -and this module will translate the URL to this new one:: - - /geoserver///ows?service=WMS&version=1.3.0&request=GetMap&cql_filter=seq='K140M' - -This module is configured by a set of rules that will be applied to the incoming URLs. Note that a get capabilities result will include the original URL maintaining the extra filter. - -This module also gives the possibility to echo existing URL parameters to the result of a get capabilities result. As an example, by default the following get capabilities request (note the existing cql_filter parameter):: - - /geoserver/ows?service=wms&version=1.3.0&request=GetCapabilities&cql_filter=CFCC=%27D68%27 - -will return a get capabilities document were the URLs will be of the type:: - - /geoserver/ows?SERVICE=WMS& - -if this module is configured to echo an existing cql_filter parameter the result would be:: - - /geoserver/ows?SERVICE=WMS&CQL_FILTER=CFCC%3D%27D68%27& - -This module is configured using three types of rules: echo parameter rules, basic rules and advanced rules. All of them can be managed in this module UI which is integrated in GeoServer UI. - - -Echo Parameter Rules ------------------------------------ - -Echo parameter rules are very simple, they allow us to define that a certain existing URL parameter should be echoed to a get capabilities result. This type of rules only required one mandatory parameter which is the name of the existing URL parameter that should be echoed to a get capabilities result. - -Example of an echo parameter rule: - -.. figure:: images/echo_rule.png - :align: center - - *Example of a echo parameter rule defined in the UI* - -This rule will echo the cql_filter of this URL:: - - /geoserver/ows?service=wms&version=1.3.0&request=GetCapabilities&cql_filter=CFCC=%27D68%27 - -to the get capabilities result:: - - /geoserver/ows?SERVICE=WMS&CQL_FILTER=CFCC%3D%27D68%27& - -Basic Rules ------------------------------------ - -Basic rules allow us to handle simple uses cases where we only want to extract a parameter from the URL. - -A basic rule is defined by three mandatory attributes: - -.. list-table:: - :widths: 20 80 - - * - **Attribute** - - **Description** - * - ``Position`` - - The position of the URL base path element to be selected - * - ``Parameter`` - - The name of the parameter produced by this rule - * - ``Transform`` - - Expression that defines the value of the parameter, use {PARAMETER} as a placeholder for the selected path element - -For commodity is also possible when defining this type of rules to configure that an existing parameter in the URL should be echoed to a get capabilities result. - -Example of a basic rule: - -.. figure:: images/basic_rule.png - :align: center - - *Example of a basic rule defined in the UI* - -This rule will transform the URL:: - - /geoserver/tiger/wms/H11?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap - -in:: - - /geoserver/tiger/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&CQL_FILTER=CFCC%3D%27H11%27 - -Advanced Rules ------------------------------------ - -Advanced rules allow us to handle more complex uses cases where more flexibility is required. - -An advanced rule is defined by three mandatory attributes and four optional ones: - -.. list-table:: - :widths: 10 80 10 - - * - **Attribute** - - **Description** - - **Mandatory** - * - ``Match`` - - Regex match expression with groups, for example ^(?:/[^/]*){3}(/([^/]+)).*$ selects the URL base path third element - - Yes - * - ``Activation`` - - If defined this rule will only be applied to URLs that match this regex expression - - No - * - ``Parameter`` - - The name of the parameter produced by this rule - - Yes - * - ``Transform`` - - Expression that defines the value of the parameter, use $1 ... $n as placeholders for groups defined in the match expression - - Yes - * - ``Remove`` - - The match expression group to be removed from URL, by default 1 - - No - * - ``Combine`` - - Defines how to combine parameter existing value ($1 existing value, $2 new value), by default the value is overridden - - No - * - ``Repeat`` - - If defined, Combine is applied not only once, but for every layer included in the LAYERS parameter, this allows filling parameters that require a value for each layer (e.g. STYLES or CQL_FILTER) - - No - -For commodity is also possible when defining this type of rules to configure that an existing parameter in the URL should be echoed to a get capabilities result. - -Example of an advanced rule: - -.. figure:: images/advanced_rule.png - :align: center - - *Example of an advanced rule defined in the UI* - -This rule will transform the URL:: - - /geoserver/tiger/wms/H11?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&CQL_FILTER=CFCC%3D%27D68%27 - -in:: - - /geoserver/tiger/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&CQL_FILTER=CFCC%3D%27D68%27+or+CFCC%3D%27H11%27 - -No that this rule will also echo an existing cql_filter parameter to the get capabilities result. - -Example of an advanced rule with repeat: - -.. figure:: images/advanced_rule_repeat.png - :align: center - - *Example of an advanced rule with repeat defined in the UI* - -This rule will transform the URL:: - - /geoserver/wms/H11?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=tiger,other - -in:: - - /geoserver/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=tiger,otherCQL_FILTER=CFCC%3D%27D68%27%3BCFCC%3D%27H11%27 - -Rules Management ------------------------------ - -Rules can be managed and tested in the rules management UI. Besides the basic operations like add, remove and update is also possible to activate or deactivate rules. A deactivated rule will be ignored by this module. - -Follow a print screen of the rules management UI with all the rules previously defined: - -.. figure:: images/rules_management.png - :align: center - - *Rules management UI* - -Note that the first rule (the advanced one) is not active. - -REST API --------- - -The rules and echo parameters can also be managed by means of a REST API found at -``geoserver/rest/params-extractor``. Documentation for it is available in -:api:`Swagger format ` - -Intercepting the security filters chain ---------------------------------------- -By default, the params-extractor module does not interact with the security authentication filters. -This is because the params-extractor filter is called later in the GeoServer filters chain. - -If you want params-extractor to work before the security filter chain, you have to configure it as -a standard servlet filter in the GeoServer WEB-INF/web.xml file. - -This can be done adding the following to your current web.xml (immediately after the ``Set Character Encoding`` filter) and restarting GeoServer: - - .. code-block:: xml - - - - ... - - ExtractParams - org.geoserver.params.extractor.Filter - - ... - - ExtractParams - /* - - ... - +.. _params_extractor_usage: + +Using the Parameters Extractor module +===================================== + +This module allow us to entering specific request parameters as URL path fragments instead of using the query string. +For example, we want to be able to apply a cql_filter using a URL in the following form:: + + /geoserver////ows?service=WMS&version=1.3.0&request=GetMap + +As a simple example of usage, if the is something like:: + + K_140M + +the URL would become:: + + /geoserver///K_140M/ows?service=WMS&version=1.3.0&request=GetMap + +and this module will translate the URL to this new one:: + + /geoserver///ows?service=WMS&version=1.3.0&request=GetMap&cql_filter=seq='K140M' + +This module is configured by a set of rules that will be applied to the incoming URLs. Note that a get capabilities result will include the original URL maintaining the extra filter. + +This module also gives the possibility to echo existing URL parameters to the result of a get capabilities result. As an example, by default the following get capabilities request (note the existing cql_filter parameter):: + + /geoserver/ows?service=wms&version=1.3.0&request=GetCapabilities&cql_filter=CFCC=%27D68%27 + +will return a get capabilities document were the URLs will be of the type:: + + /geoserver/ows?SERVICE=WMS& + +if this module is configured to echo an existing cql_filter parameter the result would be:: + + /geoserver/ows?SERVICE=WMS&CQL_FILTER=CFCC%3D%27D68%27& + +This module is configured using three types of rules: echo parameter rules, basic rules and advanced rules. All of them can be managed in this module UI which is integrated in GeoServer UI. + + +Echo Parameter Rules +----------------------------------- + +Echo parameter rules are very simple, they allow us to define that a certain existing URL parameter should be echoed to a get capabilities result. This type of rules only required one mandatory parameter which is the name of the existing URL parameter that should be echoed to a get capabilities result. + +Example of an echo parameter rule: + +.. figure:: images/echo_rule.png + :align: center + + *Example of a echo parameter rule defined in the UI* + +This rule will echo the cql_filter of this URL:: + + /geoserver/ows?service=wms&version=1.3.0&request=GetCapabilities&cql_filter=CFCC=%27D68%27 + +to the get capabilities result:: + + /geoserver/ows?SERVICE=WMS&CQL_FILTER=CFCC%3D%27D68%27& + +Basic Rules +----------------------------------- + +Basic rules allow us to handle simple uses cases where we only want to extract a parameter from the URL. + +A basic rule is defined by three mandatory attributes: + +.. list-table:: + :widths: 20 80 + + * - **Attribute** + - **Description** + * - ``Position`` + - The position of the URL base path element to be selected + * - ``Parameter`` + - The name of the parameter produced by this rule + * - ``Transform`` + - Expression that defines the value of the parameter, use {PARAMETER} as a placeholder for the selected path element + +For commodity is also possible when defining this type of rules to configure that an existing parameter in the URL should be echoed to a get capabilities result. + +Example of a basic rule: + +.. figure:: images/basic_rule.png + :align: center + + *Example of a basic rule defined in the UI* + +This rule will transform the URL:: + + /geoserver/tiger/wms/H11?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap + +in:: + + /geoserver/tiger/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&CQL_FILTER=CFCC%3D%27H11%27 + +Advanced Rules +----------------------------------- + +Advanced rules allow us to handle more complex uses cases where more flexibility is required. + +An advanced rule is defined by three mandatory attributes and four optional ones: + +.. list-table:: + :widths: 10 80 10 + + * - **Attribute** + - **Description** + - **Mandatory** + * - ``Match`` + - Regex match expression with groups, for example ^(?:/[^/]*){3}(/([^/]+)).*$ selects the URL base path third element + - Yes + * - ``Activation`` + - If defined this rule will only be applied to URLs that match this regex expression + - No + * - ``Parameter`` + - The name of the parameter produced by this rule + - Yes + * - ``Transform`` + - Expression that defines the value of the parameter, use $1 ... $n as placeholders for groups defined in the match expression + - Yes + * - ``Remove`` + - The match expression group to be removed from URL, by default 1 + - No + * - ``Combine`` + - Defines how to combine parameter existing value ($1 existing value, $2 new value), by default the value is overridden + - No + * - ``Repeat`` + - If defined, Combine is applied not only once, but for every layer included in the LAYERS parameter, this allows filling parameters that require a value for each layer (e.g. STYLES or CQL_FILTER) + - No + +For commodity is also possible when defining this type of rules to configure that an existing parameter in the URL should be echoed to a get capabilities result. + +Example of an advanced rule: + +.. figure:: images/advanced_rule.png + :align: center + + *Example of an advanced rule defined in the UI* + +This rule will transform the URL:: + + /geoserver/tiger/wms/H11?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&CQL_FILTER=CFCC%3D%27D68%27 + +in:: + + /geoserver/tiger/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&CQL_FILTER=CFCC%3D%27D68%27+or+CFCC%3D%27H11%27 + +No that this rule will also echo an existing cql_filter parameter to the get capabilities result. + +Example of an advanced rule with repeat: + +.. figure:: images/advanced_rule_repeat.png + :align: center + + *Example of an advanced rule with repeat defined in the UI* + +This rule will transform the URL:: + + /geoserver/wms/H11?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=tiger,other + +in:: + + /geoserver/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=tiger,otherCQL_FILTER=CFCC%3D%27D68%27%3BCFCC%3D%27H11%27 + +Rules Management +----------------------------- + +Rules can be managed and tested in the rules management UI. Besides the basic operations like add, remove and update is also possible to activate or deactivate rules. A deactivated rule will be ignored by this module. + +Follow a print screen of the rules management UI with all the rules previously defined: + +.. figure:: images/rules_management.png + :align: center + + *Rules management UI* + +Note that the first rule (the advanced one) is not active. + +REST API +-------- + +The rules and echo parameters can also be managed by means of a REST API found at +``geoserver/rest/params-extractor``. Documentation for it is available in +:api:`Swagger format ` + +Intercepting the security filters chain +--------------------------------------- +By default, the params-extractor module does not interact with the security authentication filters. +This is because the params-extractor filter is called later in the GeoServer filters chain. + +If you want params-extractor to work before the security filter chain, you have to configure it as +a standard servlet filter in the GeoServer WEB-INF/web.xml file. + +This can be done adding the following to your current web.xml (immediately after the ``Set Character Encoding`` filter) and restarting GeoServer: + + .. code-block:: xml + + + + ... + + ExtractParams + org.geoserver.params.extractor.Filter + + ... + + ExtractParams + /* + + ... + \ No newline at end of file diff --git a/doc/en/user/source/extensions/wmts-multidimensional/usage.rst b/doc/en/user/source/extensions/wmts-multidimensional/usage.rst index 2d2e1d5d55b..5877c00bffe 100644 --- a/doc/en/user/source/extensions/wmts-multidimensional/usage.rst +++ b/doc/en/user/source/extensions/wmts-multidimensional/usage.rst @@ -1,531 +1,531 @@ -.. _wmts_multidminensional_usage: - -WMTS Multidimensional usage -=========================== - -All described operations including is optional parameters and other extensions were implemented, only the the REST interfaces for the domain discovery operations were not implemented. - -The ``GetFeature`` operation only supports the profile GML 3.1 as feature info format ("application/gml+xml; version=3.1") and the ``GetHistogram`` operation only supports ``text/xml`` as output format. - - -This module support well defined dimensions like elevation and time and also custom dimensions. - -GetCapabilities ---------------- - -The default behavior of WMTS is to list in the capabilities document all the values available in a certain dimension, something like this: - -.. code-block:: xml - - - elevation - 0.0 - 0.0 - 200.0 - 400.0 - 600.0 - 800.0 - 1000.0 - 1200.0 - 1400.0 - 1600.0 - 1800.0 - 2000.0 - 3000.0 - 4000.0 - 5000.0 - 6000.0 - 7000.0 - 8000.0 - 9000.0 - - -This module will instead take into account the presentation mode selected by the user: - -.. figure:: images/layer_dimensions.png - :align: center - - *Configuration of a layer dimensions.* - -With the presentation mode select to ``Continuous interval`` or ``Resolution and interval`` we will instead see something like this: - -.. code-block:: xml - - - elevation - 0.0 - 0.0--9000.0 - - -Descriptions for the new introduced operations and associated formats will also be added to the capabilities document. - -Operations ----------- - -This module adds three new operations to the WMTS service that are described in detail in this `document `_: - -.. list-table:: - :widths: 20 80 - :header-rows: 1 - - * - Operation - - Description - * - DescribeDomains - - Describes all the dimension domains in a compact document, along with the restricted bounding box of the two dimensional space intercepted by the request. - * - GetDomainValues - - Allows to page through domain values (supplements DescribeDomains in case the domain has too many values, and the client still wants to get all of them, one page at a time) - * - GetHistogram - - Given a scattered domain description and an interval, this operation divides the interval in regular buckets, and provides an item count for each bucket. - * - GetFeature - - Enumerate the actual dimension possible values combinations, returns a list of features along with dimension values using the same formats as the feature info operation ("application/gml+xml; version=3.1"). - -Note that currently there is no restful implementations of this operations. - -DescribeDomains -^^^^^^^^^^^^^^^ - -This operation is useful to understand which domains are available in our layer dimensions and how they relate to each other. The parameters available for this operation are: - -.. list-table:: - :widths: 20 10 70 - :header-rows: 1 - - * - Name - - Mandatory - - Description - * - Service=WMTS - - Yes - - Service type identifier - * - Request=DescribeDomains - - Yes - - Operation name - * - Version=1.0.0 - - Yes - - Standard and schema version for this operation - * - Layer - - Yes - - Layer identifier - * - TileMatrixSet - - Yes - - Tile matrix set identifier - * - bbox=minx,miny,maxx,maxy - - No - - Bounding box corners (lower left, upper right) in CRS units - * - DimensionIdentifier - - No - - At most one per dimension, a range described as min/max, restricting the domain of this dimension - * - Domains - - No - - A comma separated list of domain names to be returned, in case only a subset is required. The space domain is identified by "bbox". - * - ExpandLimit - - No - - A numerical value, greater or equal to zero. If the number of unique domain values is below ``ExpandLimit`` then the domain with be represented in full, as - a comma separated list of values, otherwise in compact form, as ``start--end``. The server assumes a built-in limit of 200 in case not specified, - and allows client to specify a value up to 10000, values can be tuned via the user interface, in the WMTS panel (server defaults) and on a layer - by layer basis. - -.. figure:: images/expandLimitConfig.png - :align: center - - *Configuration domain expansion limits.* - - - -The ``bbox`` parameter allows the client to restrict the ``DescribeDomains`` operation to a certain spatial area, by default the layer extent will be used. - -The ``DimensionIdentifier`` parameter can be used to restrict the domain values of a certain dimension, this is useful to answer questions like which elevations values are available in a specific day. - -A simple ``DescribeDomains`` request will look like this: - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?REQUEST=DescribeDomains&Version=1.0.0&Layer=some_layer&TileMatrixSet=EPSG:4326 - -and the result will be similar to this: - -.. code-block:: xml - - - - - - - elevation - 0.0,200.0,400.0,600.0,800.0,1000.0 - 6 - - - REFERENCE_TIME - 2016-02-23T00:00:00.000Z,2016-02-24T00:00:00.000Z - 2 - - - time - 2016-02-23T03:00:00.000Z,2016-02-23T06:00:00.000Z - 2 - - - -From the information above we can see that we have three dimensions ``time``, ``elevation`` and ``REFERENCE_TIME`` and the respective domains values. - -Now let's see how elevations relate to time dimension by asking which elevations under 500.0 meters are available at time 2016-02-23T03:00:00.000Z: - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?REQUEST=DescribeDomains&Version=1.0.0&Layer=some_layer&TileMatrixSet=EPSG:4326&elevation=0/500&time=2016-02-23T03:00:00.000Z - -the result will be similar to this: - -.. code-block:: xml - - - - - - - elevation - 200.0 - 1 - - - REFERENCE_TIME - 2016-02-23T00:00:00.000Z - 1 - - - time - 2016-02-23T03:00:00.000Z - 1 - - - -So for time 2016-02-23T03:00:00.000Z there is only values measured at 200.0 meters. - -In case only the space domain is of interest, the following request will do: - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?REQUEST=DescribeDomains&Version=1.0.0&Layer=some_layer&TileMatrixSet=EPSG:4326&elevation=0/500&time=2016-02-23T03:00:00.000Z&domains=bbox - -and the result will be similar to this: - -.. code-block:: xml - - - - - - - -GetDomainValues -^^^^^^^^^^^^^^^ - -This operation is useful to page through the values of a given domain, in case the "multidimensional" area of interest -is too large for DescribeDomain to return them in a single shot. - -.. list-table:: - :widths: 20 10 70 - :header-rows: 1 - - * - Name - - Mandatory - - Description - * - Service=WMTS - - Yes - - Service type identifier - * - Request=GetDomainValues - - Yes - - Operation name - * - Version=1.0.0 - - Yes - - Standard and schema version for this operation - * - Layer - - Yes - - Layer identifier - * - bbox=minx,miny,maxx,maxy - - No - - Bounding box corners (lower left, upper right) in CRS units - * - DimensionIdentifier - - No - - At most one per dimension, a range described as min/max, restricting the domain of this dimension - * - Domain - - Yes - - Name of the domain whose values will be returned (one cannot use "bbox", only single value dimensions can be enumerated by GetDomainValues, e.g., time, elevation). - * - FromValue - - No - - Sets the beginning of domain enumeration, for paging purposes. It's not included in the result - * - Sort - - No - - Can be "asc" or "desc", determines if the enumeration is from low to high, or from high to low - * - Limit - - No - - Maximum number of values returned by this call. The server assumes a built-in limit of 1000 in case not specified, - and allows client to specify a value up to 10000. - -For example, let's say a "elevation" domain has values 1,2,3 and 5, and that we are paging through -it by pages of 2 elements. The client will start without providing a "fromValue", and will then continue -using the last value of the previous page as a reference: - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2 - -.. code-block:: xml - - - elevation - 2 - asc - 1.0,2.0 - 2 - - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2&fromValue=2 - -.. code-block:: xml - - - elevation - 2 - asc - 2.0 - 3.0,5.0 - 2 - - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2&fromValue=5 - -.. code-block:: xml - - - elevation - 2 - asc - 5.0 - - 0 - - -For elevations it might not be uncommon to iterate backwards, from the top-most elevation down to the lowest value. The interaction -between client and server migth then look as follows: - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2&sort=desc - -.. code-block:: xml - - - elevation - 2 - asc - 5.0,3.0 - 2 - - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2&fromValue=3&sort=desc - -.. code-block:: xml - - - elevation - 2 - asc - 3.0 - 2.0,1.0 - 2 - - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2&fromValue=1&sort=desc - -.. code-block:: xml - - - elevation - 2 - asc - 1.0 - - 0 - - -The paging approach might seem odd for those used to using "limit" and "offset". The main reason it's done -this way it's performance, paging through unique values via limit and offset means that the data source -has to compute and collect the unique values that are not needed (the ones in previous pages) in order to -find the ones in the current page. With large domains (typical of time series) this quickly becomes too -slow for interactive usage, as one moves forward in the domain. - -By giving a starting point, the unneeded data points can be skipped via index and the distinct value -computation can be performed only on the current page data, stopping it as soon as the desired number -of results has been computed. With an index on the dimension being queries, this results in nearly -constant response times, regardless of the page being requested. - -GetHistogram -^^^^^^^^^^^^ - -This operation can be used to provide information about the data distribution between the minimum and maximum values of a certain dimension. - -The parameters available for this operation are: - -.. list-table:: - :widths: 20 10 70 - :header-rows: 1 - - * - Name - - Mandatory - - Description - * - Service=WMTS - - Yes - - Service type identifier - * - Request=GetHistogram - - Yes - - Operation name - * - Version=1.0.0 - - Yes - - Standard and schema version for this operation - * - Layer - - Yes - - Layer identifier - * - TileMatrixSet - - Yes - - Tile matrix set identifier - * - BBOX=minx,miny,maxx,maxy - - No - - Bounding box corners (lower left, upper right) in CRS units - * - DimensionIdentifier - - No - - At most one per dimension, a range described as min/max, restricting the domain of this dimension - * - Histogram - - Yes - - Name of the dimension for which the histogram will be computed - * - Resolution - - No - - Suggested size of the histogram bucket. Cannot be provided for enumerated dimensions, will use the period syntax for time (e.g. PT1H), a number for numeric dimensions, or auto to leave the decision to the server - * - Format - - No - - The desired output format, default is text/html. - -The parameters common to the ``DescribeDomains`` operation work as already described above. Currently only the ``text/xml`` output format is supported. - -The following example request the histogram for time dimension with a resolution of 8 hours restricting elevations between 500.0 and 1000.0 meters: - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?REQUEST=GetHistogram&Version=1.0.0&Layer=some_layer&TileMatrixSet=EPSG:4326&histogram=time&resolution=PT8H&elevation=500.0/1000.0 - -and the result will be similar to this: - -.. code-block:: xml - - - time - 2016-02-23T00:00:00.000Z/2016-02-25T00:00:00.000Z/PT8H - 240,0,240,0,0,240 - - -Looking at the result we can conclude that measurements between 500.0 and 1000.0 meters are typically done during the night. - -The bucket matching is setup so that each one contains its first value, but not its last value (which is contained in the next bucket instead). -This is important to understand the results. Say we have a dataset with regular elevations, from 0 to 100 with a step of 10, and the -request calls for elevations between 0 and 20. Then the results will look something like follows: - -.. code-block:: xml - - - elevation - 0/30/10 - 5,3,8 - - -That is, there values catch the intervals [0,10[, [10, 20[, and [20, 30[ (to have a bucket for the images/features -having elevation exactly matching 20). This will happen only if an extreme value if found, the same request -filtering on elevations between 0 and 15 will return this instead: - -.. code-block:: xml - - - elevation - 0/20/10 - 5,3 - - -GetFeature -^^^^^^^^^^ - -This operation is capable to enumerate the actual possible values combinations. The output of this operation is similar to the output of the ``WFS 2.0 GetFeature`` operation which is a list of features along with dimension values using the same formats as the feature info operation. This output can be used to draw the features on a map for example. - -The parameters available for this operation are: - -.. list-table:: - :widths: 20 10 70 - :header-rows: 1 - - * - Name - - Mandatory - - Description - * - Service=WMTS - - Yes - - Service type identifier - * - Request=GetFeature - - Yes - - Operation name - * - Version=1.0.0 - - Yes - - Standard and schema version for this operation - * - Layer - - Yes - - Layer identifier - * - TileMatrixSet - - Yes - - Tile matrix set identifier - * - BBOX=minx,miny,maxx,maxy - - No - - Bounding box corners (lower left, upper right) in CRS units - * - DimensionIdentifier - - No - - At most one per dimension, a range described as min/max, restricting the domain of this dimension - * - Format - - Yes - - The desired output format - -The parameters common to the ``DescribeDomains`` operation work as already described above. Currently only the ``application/gml+xml; version=3.1`` output format is supported. - -Using the same restrictions parameters we used for the second request used as an example for the ``DescribeDomains`` operation a ``GetFeature`` request will look like this: - -.. code-block:: guess - - http://localhost:8080/geoserver/gwc/service/wmts?REQUEST=GetFeature&Version=1.0.0&Layer=some_layer&TileMatrixSet=EPSG:4326&elevation=0/500&time=2016-02-23T03:00:00.000Z - -and the result will be similar to this: - -.. code-block:: xml - - - - - - - - -180.125 -90.125 -180.125 89.875 179.875 89.875 179.875 -90.125 -180.125 -90.125 - - - - - 200.0 - 2016-02-23T03:00:00.000Z - 2016-02-23T00:00:00.000Z - - - -Note how this result correlate with the correspondent ``DescribeDomains`` operation result. +.. _wmts_multidminensional_usage: + +WMTS Multidimensional usage +=========================== + +All described operations including is optional parameters and other extensions were implemented, only the the REST interfaces for the domain discovery operations were not implemented. + +The ``GetFeature`` operation only supports the profile GML 3.1 as feature info format ("application/gml+xml; version=3.1") and the ``GetHistogram`` operation only supports ``text/xml`` as output format. + + +This module support well defined dimensions like elevation and time and also custom dimensions. + +GetCapabilities +--------------- + +The default behavior of WMTS is to list in the capabilities document all the values available in a certain dimension, something like this: + +.. code-block:: xml + + + elevation + 0.0 + 0.0 + 200.0 + 400.0 + 600.0 + 800.0 + 1000.0 + 1200.0 + 1400.0 + 1600.0 + 1800.0 + 2000.0 + 3000.0 + 4000.0 + 5000.0 + 6000.0 + 7000.0 + 8000.0 + 9000.0 + + +This module will instead take into account the presentation mode selected by the user: + +.. figure:: images/layer_dimensions.png + :align: center + + *Configuration of a layer dimensions.* + +With the presentation mode select to ``Continuous interval`` or ``Resolution and interval`` we will instead see something like this: + +.. code-block:: xml + + + elevation + 0.0 + 0.0--9000.0 + + +Descriptions for the new introduced operations and associated formats will also be added to the capabilities document. + +Operations +---------- + +This module adds three new operations to the WMTS service that are described in detail in this `document `_: + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Operation + - Description + * - DescribeDomains + - Describes all the dimension domains in a compact document, along with the restricted bounding box of the two dimensional space intercepted by the request. + * - GetDomainValues + - Allows to page through domain values (supplements DescribeDomains in case the domain has too many values, and the client still wants to get all of them, one page at a time) + * - GetHistogram + - Given a scattered domain description and an interval, this operation divides the interval in regular buckets, and provides an item count for each bucket. + * - GetFeature + - Enumerate the actual dimension possible values combinations, returns a list of features along with dimension values using the same formats as the feature info operation ("application/gml+xml; version=3.1"). + +Note that currently there is no restful implementations of this operations. + +DescribeDomains +^^^^^^^^^^^^^^^ + +This operation is useful to understand which domains are available in our layer dimensions and how they relate to each other. The parameters available for this operation are: + +.. list-table:: + :widths: 20 10 70 + :header-rows: 1 + + * - Name + - Mandatory + - Description + * - Service=WMTS + - Yes + - Service type identifier + * - Request=DescribeDomains + - Yes + - Operation name + * - Version=1.0.0 + - Yes + - Standard and schema version for this operation + * - Layer + - Yes + - Layer identifier + * - TileMatrixSet + - Yes + - Tile matrix set identifier + * - bbox=minx,miny,maxx,maxy + - No + - Bounding box corners (lower left, upper right) in CRS units + * - DimensionIdentifier + - No + - At most one per dimension, a range described as min/max, restricting the domain of this dimension + * - Domains + - No + - A comma separated list of domain names to be returned, in case only a subset is required. The space domain is identified by "bbox". + * - ExpandLimit + - No + - A numerical value, greater or equal to zero. If the number of unique domain values is below ``ExpandLimit`` then the domain with be represented in full, as + a comma separated list of values, otherwise in compact form, as ``start--end``. The server assumes a built-in limit of 200 in case not specified, + and allows client to specify a value up to 10000, values can be tuned via the user interface, in the WMTS panel (server defaults) and on a layer + by layer basis. + +.. figure:: images/expandLimitConfig.png + :align: center + + *Configuration domain expansion limits.* + + + +The ``bbox`` parameter allows the client to restrict the ``DescribeDomains`` operation to a certain spatial area, by default the layer extent will be used. + +The ``DimensionIdentifier`` parameter can be used to restrict the domain values of a certain dimension, this is useful to answer questions like which elevations values are available in a specific day. + +A simple ``DescribeDomains`` request will look like this: + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?REQUEST=DescribeDomains&Version=1.0.0&Layer=some_layer&TileMatrixSet=EPSG:4326 + +and the result will be similar to this: + +.. code-block:: xml + + + + + + + elevation + 0.0,200.0,400.0,600.0,800.0,1000.0 + 6 + + + REFERENCE_TIME + 2016-02-23T00:00:00.000Z,2016-02-24T00:00:00.000Z + 2 + + + time + 2016-02-23T03:00:00.000Z,2016-02-23T06:00:00.000Z + 2 + + + +From the information above we can see that we have three dimensions ``time``, ``elevation`` and ``REFERENCE_TIME`` and the respective domains values. + +Now let's see how elevations relate to time dimension by asking which elevations under 500.0 meters are available at time 2016-02-23T03:00:00.000Z: + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?REQUEST=DescribeDomains&Version=1.0.0&Layer=some_layer&TileMatrixSet=EPSG:4326&elevation=0/500&time=2016-02-23T03:00:00.000Z + +the result will be similar to this: + +.. code-block:: xml + + + + + + + elevation + 200.0 + 1 + + + REFERENCE_TIME + 2016-02-23T00:00:00.000Z + 1 + + + time + 2016-02-23T03:00:00.000Z + 1 + + + +So for time 2016-02-23T03:00:00.000Z there is only values measured at 200.0 meters. + +In case only the space domain is of interest, the following request will do: + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?REQUEST=DescribeDomains&Version=1.0.0&Layer=some_layer&TileMatrixSet=EPSG:4326&elevation=0/500&time=2016-02-23T03:00:00.000Z&domains=bbox + +and the result will be similar to this: + +.. code-block:: xml + + + + + + + +GetDomainValues +^^^^^^^^^^^^^^^ + +This operation is useful to page through the values of a given domain, in case the "multidimensional" area of interest +is too large for DescribeDomain to return them in a single shot. + +.. list-table:: + :widths: 20 10 70 + :header-rows: 1 + + * - Name + - Mandatory + - Description + * - Service=WMTS + - Yes + - Service type identifier + * - Request=GetDomainValues + - Yes + - Operation name + * - Version=1.0.0 + - Yes + - Standard and schema version for this operation + * - Layer + - Yes + - Layer identifier + * - bbox=minx,miny,maxx,maxy + - No + - Bounding box corners (lower left, upper right) in CRS units + * - DimensionIdentifier + - No + - At most one per dimension, a range described as min/max, restricting the domain of this dimension + * - Domain + - Yes + - Name of the domain whose values will be returned (one cannot use "bbox", only single value dimensions can be enumerated by GetDomainValues, e.g., time, elevation). + * - FromValue + - No + - Sets the beginning of domain enumeration, for paging purposes. It's not included in the result + * - Sort + - No + - Can be "asc" or "desc", determines if the enumeration is from low to high, or from high to low + * - Limit + - No + - Maximum number of values returned by this call. The server assumes a built-in limit of 1000 in case not specified, + and allows client to specify a value up to 10000. + +For example, let's say a "elevation" domain has values 1,2,3 and 5, and that we are paging through +it by pages of 2 elements. The client will start without providing a "fromValue", and will then continue +using the last value of the previous page as a reference: + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2 + +.. code-block:: xml + + + elevation + 2 + asc + 1.0,2.0 + 2 + + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2&fromValue=2 + +.. code-block:: xml + + + elevation + 2 + asc + 2.0 + 3.0,5.0 + 2 + + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2&fromValue=5 + +.. code-block:: xml + + + elevation + 2 + asc + 5.0 + + 0 + + +For elevations it might not be uncommon to iterate backwards, from the top-most elevation down to the lowest value. The interaction +between client and server migth then look as follows: + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2&sort=desc + +.. code-block:: xml + + + elevation + 2 + asc + 5.0,3.0 + 2 + + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2&fromValue=3&sort=desc + +.. code-block:: xml + + + elevation + 2 + asc + 3.0 + 2.0,1.0 + 2 + + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?request=GetDomainValues&Version=1.0.0&Layer=sampleLayer&domain=elevation&limit=2&fromValue=1&sort=desc + +.. code-block:: xml + + + elevation + 2 + asc + 1.0 + + 0 + + +The paging approach might seem odd for those used to using "limit" and "offset". The main reason it's done +this way it's performance, paging through unique values via limit and offset means that the data source +has to compute and collect the unique values that are not needed (the ones in previous pages) in order to +find the ones in the current page. With large domains (typical of time series) this quickly becomes too +slow for interactive usage, as one moves forward in the domain. + +By giving a starting point, the unneeded data points can be skipped via index and the distinct value +computation can be performed only on the current page data, stopping it as soon as the desired number +of results has been computed. With an index on the dimension being queries, this results in nearly +constant response times, regardless of the page being requested. + +GetHistogram +^^^^^^^^^^^^ + +This operation can be used to provide information about the data distribution between the minimum and maximum values of a certain dimension. + +The parameters available for this operation are: + +.. list-table:: + :widths: 20 10 70 + :header-rows: 1 + + * - Name + - Mandatory + - Description + * - Service=WMTS + - Yes + - Service type identifier + * - Request=GetHistogram + - Yes + - Operation name + * - Version=1.0.0 + - Yes + - Standard and schema version for this operation + * - Layer + - Yes + - Layer identifier + * - TileMatrixSet + - Yes + - Tile matrix set identifier + * - BBOX=minx,miny,maxx,maxy + - No + - Bounding box corners (lower left, upper right) in CRS units + * - DimensionIdentifier + - No + - At most one per dimension, a range described as min/max, restricting the domain of this dimension + * - Histogram + - Yes + - Name of the dimension for which the histogram will be computed + * - Resolution + - No + - Suggested size of the histogram bucket. Cannot be provided for enumerated dimensions, will use the period syntax for time (e.g. PT1H), a number for numeric dimensions, or auto to leave the decision to the server + * - Format + - No + - The desired output format, default is text/html. + +The parameters common to the ``DescribeDomains`` operation work as already described above. Currently only the ``text/xml`` output format is supported. + +The following example request the histogram for time dimension with a resolution of 8 hours restricting elevations between 500.0 and 1000.0 meters: + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?REQUEST=GetHistogram&Version=1.0.0&Layer=some_layer&TileMatrixSet=EPSG:4326&histogram=time&resolution=PT8H&elevation=500.0/1000.0 + +and the result will be similar to this: + +.. code-block:: xml + + + time + 2016-02-23T00:00:00.000Z/2016-02-25T00:00:00.000Z/PT8H + 240,0,240,0,0,240 + + +Looking at the result we can conclude that measurements between 500.0 and 1000.0 meters are typically done during the night. + +The bucket matching is setup so that each one contains its first value, but not its last value (which is contained in the next bucket instead). +This is important to understand the results. Say we have a dataset with regular elevations, from 0 to 100 with a step of 10, and the +request calls for elevations between 0 and 20. Then the results will look something like follows: + +.. code-block:: xml + + + elevation + 0/30/10 + 5,3,8 + + +That is, there values catch the intervals [0,10[, [10, 20[, and [20, 30[ (to have a bucket for the images/features +having elevation exactly matching 20). This will happen only if an extreme value if found, the same request +filtering on elevations between 0 and 15 will return this instead: + +.. code-block:: xml + + + elevation + 0/20/10 + 5,3 + + +GetFeature +^^^^^^^^^^ + +This operation is capable to enumerate the actual possible values combinations. The output of this operation is similar to the output of the ``WFS 2.0 GetFeature`` operation which is a list of features along with dimension values using the same formats as the feature info operation. This output can be used to draw the features on a map for example. + +The parameters available for this operation are: + +.. list-table:: + :widths: 20 10 70 + :header-rows: 1 + + * - Name + - Mandatory + - Description + * - Service=WMTS + - Yes + - Service type identifier + * - Request=GetFeature + - Yes + - Operation name + * - Version=1.0.0 + - Yes + - Standard and schema version for this operation + * - Layer + - Yes + - Layer identifier + * - TileMatrixSet + - Yes + - Tile matrix set identifier + * - BBOX=minx,miny,maxx,maxy + - No + - Bounding box corners (lower left, upper right) in CRS units + * - DimensionIdentifier + - No + - At most one per dimension, a range described as min/max, restricting the domain of this dimension + * - Format + - Yes + - The desired output format + +The parameters common to the ``DescribeDomains`` operation work as already described above. Currently only the ``application/gml+xml; version=3.1`` output format is supported. + +Using the same restrictions parameters we used for the second request used as an example for the ``DescribeDomains`` operation a ``GetFeature`` request will look like this: + +.. code-block:: guess + + http://localhost:8080/geoserver/gwc/service/wmts?REQUEST=GetFeature&Version=1.0.0&Layer=some_layer&TileMatrixSet=EPSG:4326&elevation=0/500&time=2016-02-23T03:00:00.000Z + +and the result will be similar to this: + +.. code-block:: xml + + + + + + + + -180.125 -90.125 -180.125 89.875 179.875 89.875 179.875 -90.125 -180.125 -90.125 + + + + + 200.0 + 2016-02-23T03:00:00.000Z + 2016-02-23T00:00:00.000Z + + + +Note how this result correlate with the correspondent ``DescribeDomains`` operation result. diff --git a/doc/en/user/source/filter/filter_reference.rst b/doc/en/user/source/filter/filter_reference.rst index b2715dea770..10efedefa10 100644 --- a/doc/en/user/source/filter/filter_reference.rst +++ b/doc/en/user/source/filter/filter_reference.rst @@ -1,405 +1,405 @@ -.. _filter_fe_reference: - -Filter Encoding Reference -========================= - -This is a reference for the **Filter Encoding** language -implemented in GeoServer. -The Filter Encoding language uses an XML-based syntax. -It is defined by the `OGC Filter Encoding standard `_. - -Filters are used to select features or other objects from the context in which they are evaluated. -They are similar in functionality to the SQL "WHERE" clause. -A filter is specified using a **condition**. - -.. _filter_condition: - -Condition ---------- - -A condition is a single :ref:`filter_predicate` element, -or a combination of conditions by :ref:`filter_logical`. - -.. _filter_predicate: - -Predicate ---------- - -Predicates are boolean-valued expressions which compute relationships between values. -A predicate is specified by using a **comparison operator** or a **spatial operator**. -The operators are used to compare properties of the features being filtered -to other feature properties or to literal data. - -Comparison operators -^^^^^^^^^^^^^^^^^^^^ - -Comparison operators are used to specify conditions on non-spatial attributes. - -Binary Comparison operators -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The **binary comparison operators** are: - - * ```` - * ```` - * ```` - * ```` - * ```` - * ```` - -They contain the elements: - -.. list-table:: - :widths: 25 15 60 - - * - **Element** - - **Required?** - - **Description** - * - :ref:`filter_expression` - - Yes - - The first value to compare. - Often a ````. - * - :ref:`filter_expression` - - Yes - - The second value to compare - -Binary comparison operator elements may include an optional ``matchCase`` attribute, -with the value ``true`` or ``false``. -If this attribute is ``true`` (the default), string comparisons are case-sensitive. -If the attribute is ``false`` strings comparisons do not check case. - -PropertyIsLike operator -~~~~~~~~~~~~~~~~~~~~~~~ - -The ```` operator matches a string property value against a text **pattern**. -It contains the elements: - -.. list-table:: - :widths: 25 15 60 - - * - **Element** - - **Required?** - - **Description** - * - ```` - - Yes - - Contains a string specifying the name of the property to test - * - ```` - - Yes - - Contains a pattern string to be matched - -The pattern is specified by a sequence of regular characters and -three special pattern characters. -The pattern characters are defined by the following *required* attributes of the ```` element: - - * ``wildCard`` specifies the pattern character which matches any sequence of zero or more string characters - * ``singleChar`` specifies the pattern character which matches any single string character - * ``escapeChar`` specifies the escape character which can be used to escape the pattern characters - -PropertyIsNull operator -~~~~~~~~~~~~~~~~~~~~~~~ - -The ```` operator tests whether a property value is null. -It contains the element: - -.. list-table:: - :widths: 25 15 60 - - * - **Element** - - **Required?** - - **Description** - * - ```` - - Yes - - contains a string specifying the name of the property to be tested - -PropertyIsBetweeen operator -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ```` operator tests whether an expression value lies within a range -given by a lower and upper bound (inclusive). -It contains the elements: - -.. list-table:: - :widths: 25 15 60 - - * - **Element** - - **Required?** - - **Description** - * - :ref:`filter_expression` - - Yes - - The value to test - * - ```` - - Yes - - Contains an :ref:`filter_expression` giving the lower bound of the range - * - ```` - - Yes - - Contains an :ref:`filter_expression` giving the upper bound of the range - - -Spatial operators -^^^^^^^^^^^^^^^^^ - -Spatial operators are used to specify conditions on the geometric attributes of a feature. -The following spatial operators are available: - -Topological operators -~~~~~~~~~~~~~~~~~~~~~ - -These operators test topological spatial relationships using the standard OGC Simple Features predicates: - - * ```` - Tests whether two geometries intersect - * ```` - Tests whether two geometries are disjoint (do not interact) - * ```` - Tests whether a geometry contains another one - * ```` - Tests whether a geometry is within another one - * ```` - Tests whether two geometries touch - * ```` - Tests whether two geometries cross - * ```` - Tests whether two geometries overlap - * ```` - Tests whether two geometries are topologically equal - -These contains the elements: - -.. list-table:: - :widths: 25 15 60 - - * - **Element** - - **Required?** - - **Description** - * - ```` - - Yes - - Contains a string specifying the name of the geometry-valued property to be tested. - * - *GML Geometry* - - Yes - - A GML literal value specifying the geometry to test against - -Distance operators -~~~~~~~~~~~~~~~~~~ - -These operators test distance relationships between a geometry property and a geometry literal: - - * ```` - * ```` - -They contain the elements: - -.. list-table:: - :widths: 25 15 60 - - * - **Element** - - **Required?** - - **Description** - * - ```` - - Yes - - Contains a string specifying the name of the property to be tested. - If omitted, the *default geometry attribute* is assumed. - * - *GML Geometry* - - Yes - - A literal value specifying a geometry to compute the distance to. - This may be either a geometry or an envelope in GML 3 format - * - ```` - - Yes - - Contains the numeric value for the distance tolerance. - The element may include an optional ``units`` attribute. - - -Bounding Box operator -~~~~~~~~~~~~~~~~~~~~~ - -The ```` operator tests whether a geometry-valued property intersects a fixed bounding box. -It contains the elements: - -.. list-table:: - :widths: 25 15 60 - - * - **Element** - - **Required?** - - **Description** - * - ```` - - No - - Contains a string specifying the name of the property to be tested. - If omitted, the *default geometry attribute* is assumed. - * - ```` - - Yes - - A GML Box literal value specifying the bounding box to test against - - -Examples -~~~~~~~~ - -* This filter selects features with a geometry that intersects the point (1,1). - -.. code-block:: xml - - - GEOMETRY - - 1 1 - - - -* This filter selects features with a geometry that overlaps a polygon. - -.. code-block:: xml - - - Geometry - - - - ... - - - - - -* This filter selects features with a geometry that intersects - the geographic extent [-10,0 : 10,10]. - -.. code-block:: xml - - - GEOMETRY - - - -10 0 - - - 10 10 - - - - - -.. _filter_logical: - -Logical operators ------------------ - -Logical operators are used to specify -logical combinations of :ref:`filter_condition` elements -(which may be either :ref:`filter_predicate` elements or other **logical operators**). -They may be nested to any depth. - -The following logical operators are available: - - * ```` - computes the logical conjunction of the operands - * ```` - computes the logical disjunction of the operands - -The content for ```` and ```` is two operands given by :ref:`filter_condition` elements. - - * ```` - computes the logical negation of the operand - -The content for ```` is a single operand given by a :ref:`filter_condition` element. - -Examples -^^^^^^^^ - -* This filter uses ```` to combine a comparison predicate and a spatial predicate: - -.. code-block:: xml - - - - NAME - New York - - - GEOMETRY - - - 1 1 - - - - - - -.. _filter_expression: - -Expression ----------- - -**Filter expressions** specify constant, variable or computed data values. -An expression is formed from one of the following elements -(some of which contain sub-expressions, -meaning that expressions may be of arbitrary depth): - -Arithmetic operators -^^^^^^^^^^^^^^^^^^^^ - -The **arithmetic operator** elements compute arithmetic operations on numeric values. - - * ```` - adds the two operands - * ```` - subtracts the second operand from the first - * ```` - multiplies the two operands - * ``
`` - divides the first operand by the second - -Each arithmetic operator element contains two :ref:`filter_expression` elements -providing the operands. - -Function -^^^^^^^^ - -The ```` element specifies a filter function to be evaluated. -The required ``name`` attribute gives the function name. -The element contains a sequence of zero or more -:ref:`filter_expression` elements providing the values of the function arguments. - -See the :ref:`filter_function_reference` for details of the functions provided by GeoServer. - -Property Value -^^^^^^^^^^^^^^ - -The ```` element refers to the value of a feature attribute. -It contains a **string** or an **XPath expression** specifying the attribute name. - -Literal -^^^^^^^ - -The ```` element specifies a constant value. -It contains data of one of the following types: - -.. list-table:: - :widths: 25 75 - - * - **Type** - - **Description** - * - Numeric - - A string representing a numeric value (integer or decimal). - * - Boolean - - A boolean value of ``true`` or ``false``. - * - String - - A string value. - XML-incompatible text may be included by using - **character entities** or ```` delimiters. - * - Date - - A string representing a date. - * - Geometry - - An element specifying a geometry in GML3 format. - -WFS 2.0 namespaces ------------------- - -WFS 2.0 does not depend on any one GML version and thus requires an explicit namespace and schemaLocation for GML. -In a GET request, namespaces can be placed on a Filter element (that is, ``filter=`` the block below, URL-encoded): - -.. code-block:: xml - - - - - sf:the_geom - - - - 590431 4915204 590430 - 4915205 590429 4915204 590430 - 4915203 590431 4915204 - - - - - - +.. _filter_fe_reference: + +Filter Encoding Reference +========================= + +This is a reference for the **Filter Encoding** language +implemented in GeoServer. +The Filter Encoding language uses an XML-based syntax. +It is defined by the `OGC Filter Encoding standard `_. + +Filters are used to select features or other objects from the context in which they are evaluated. +They are similar in functionality to the SQL "WHERE" clause. +A filter is specified using a **condition**. + +.. _filter_condition: + +Condition +--------- + +A condition is a single :ref:`filter_predicate` element, +or a combination of conditions by :ref:`filter_logical`. + +.. _filter_predicate: + +Predicate +--------- + +Predicates are boolean-valued expressions which compute relationships between values. +A predicate is specified by using a **comparison operator** or a **spatial operator**. +The operators are used to compare properties of the features being filtered +to other feature properties or to literal data. + +Comparison operators +^^^^^^^^^^^^^^^^^^^^ + +Comparison operators are used to specify conditions on non-spatial attributes. + +Binary Comparison operators +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The **binary comparison operators** are: + + * ```` + * ```` + * ```` + * ```` + * ```` + * ```` + +They contain the elements: + +.. list-table:: + :widths: 25 15 60 + + * - **Element** + - **Required?** + - **Description** + * - :ref:`filter_expression` + - Yes + - The first value to compare. + Often a ````. + * - :ref:`filter_expression` + - Yes + - The second value to compare + +Binary comparison operator elements may include an optional ``matchCase`` attribute, +with the value ``true`` or ``false``. +If this attribute is ``true`` (the default), string comparisons are case-sensitive. +If the attribute is ``false`` strings comparisons do not check case. + +PropertyIsLike operator +~~~~~~~~~~~~~~~~~~~~~~~ + +The ```` operator matches a string property value against a text **pattern**. +It contains the elements: + +.. list-table:: + :widths: 25 15 60 + + * - **Element** + - **Required?** + - **Description** + * - ```` + - Yes + - Contains a string specifying the name of the property to test + * - ```` + - Yes + - Contains a pattern string to be matched + +The pattern is specified by a sequence of regular characters and +three special pattern characters. +The pattern characters are defined by the following *required* attributes of the ```` element: + + * ``wildCard`` specifies the pattern character which matches any sequence of zero or more string characters + * ``singleChar`` specifies the pattern character which matches any single string character + * ``escapeChar`` specifies the escape character which can be used to escape the pattern characters + +PropertyIsNull operator +~~~~~~~~~~~~~~~~~~~~~~~ + +The ```` operator tests whether a property value is null. +It contains the element: + +.. list-table:: + :widths: 25 15 60 + + * - **Element** + - **Required?** + - **Description** + * - ```` + - Yes + - contains a string specifying the name of the property to be tested + +PropertyIsBetweeen operator +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ```` operator tests whether an expression value lies within a range +given by a lower and upper bound (inclusive). +It contains the elements: + +.. list-table:: + :widths: 25 15 60 + + * - **Element** + - **Required?** + - **Description** + * - :ref:`filter_expression` + - Yes + - The value to test + * - ```` + - Yes + - Contains an :ref:`filter_expression` giving the lower bound of the range + * - ```` + - Yes + - Contains an :ref:`filter_expression` giving the upper bound of the range + + +Spatial operators +^^^^^^^^^^^^^^^^^ + +Spatial operators are used to specify conditions on the geometric attributes of a feature. +The following spatial operators are available: + +Topological operators +~~~~~~~~~~~~~~~~~~~~~ + +These operators test topological spatial relationships using the standard OGC Simple Features predicates: + + * ```` - Tests whether two geometries intersect + * ```` - Tests whether two geometries are disjoint (do not interact) + * ```` - Tests whether a geometry contains another one + * ```` - Tests whether a geometry is within another one + * ```` - Tests whether two geometries touch + * ```` - Tests whether two geometries cross + * ```` - Tests whether two geometries overlap + * ```` - Tests whether two geometries are topologically equal + +These contains the elements: + +.. list-table:: + :widths: 25 15 60 + + * - **Element** + - **Required?** + - **Description** + * - ```` + - Yes + - Contains a string specifying the name of the geometry-valued property to be tested. + * - *GML Geometry* + - Yes + - A GML literal value specifying the geometry to test against + +Distance operators +~~~~~~~~~~~~~~~~~~ + +These operators test distance relationships between a geometry property and a geometry literal: + + * ```` + * ```` + +They contain the elements: + +.. list-table:: + :widths: 25 15 60 + + * - **Element** + - **Required?** + - **Description** + * - ```` + - Yes + - Contains a string specifying the name of the property to be tested. + If omitted, the *default geometry attribute* is assumed. + * - *GML Geometry* + - Yes + - A literal value specifying a geometry to compute the distance to. + This may be either a geometry or an envelope in GML 3 format + * - ```` + - Yes + - Contains the numeric value for the distance tolerance. + The element may include an optional ``units`` attribute. + + +Bounding Box operator +~~~~~~~~~~~~~~~~~~~~~ + +The ```` operator tests whether a geometry-valued property intersects a fixed bounding box. +It contains the elements: + +.. list-table:: + :widths: 25 15 60 + + * - **Element** + - **Required?** + - **Description** + * - ```` + - No + - Contains a string specifying the name of the property to be tested. + If omitted, the *default geometry attribute* is assumed. + * - ```` + - Yes + - A GML Box literal value specifying the bounding box to test against + + +Examples +~~~~~~~~ + +* This filter selects features with a geometry that intersects the point (1,1). + +.. code-block:: xml + + + GEOMETRY + + 1 1 + + + +* This filter selects features with a geometry that overlaps a polygon. + +.. code-block:: xml + + + Geometry + + + + ... + + + + + +* This filter selects features with a geometry that intersects + the geographic extent [-10,0 : 10,10]. + +.. code-block:: xml + + + GEOMETRY + + + -10 0 + + + 10 10 + + + + + +.. _filter_logical: + +Logical operators +----------------- + +Logical operators are used to specify +logical combinations of :ref:`filter_condition` elements +(which may be either :ref:`filter_predicate` elements or other **logical operators**). +They may be nested to any depth. + +The following logical operators are available: + + * ```` - computes the logical conjunction of the operands + * ```` - computes the logical disjunction of the operands + +The content for ```` and ```` is two operands given by :ref:`filter_condition` elements. + + * ```` - computes the logical negation of the operand + +The content for ```` is a single operand given by a :ref:`filter_condition` element. + +Examples +^^^^^^^^ + +* This filter uses ```` to combine a comparison predicate and a spatial predicate: + +.. code-block:: xml + + + + NAME + New York + + + GEOMETRY + + + 1 1 + + + + + + +.. _filter_expression: + +Expression +---------- + +**Filter expressions** specify constant, variable or computed data values. +An expression is formed from one of the following elements +(some of which contain sub-expressions, +meaning that expressions may be of arbitrary depth): + +Arithmetic operators +^^^^^^^^^^^^^^^^^^^^ + +The **arithmetic operator** elements compute arithmetic operations on numeric values. + + * ```` - adds the two operands + * ```` - subtracts the second operand from the first + * ```` - multiplies the two operands + * ``
`` - divides the first operand by the second + +Each arithmetic operator element contains two :ref:`filter_expression` elements +providing the operands. + +Function +^^^^^^^^ + +The ```` element specifies a filter function to be evaluated. +The required ``name`` attribute gives the function name. +The element contains a sequence of zero or more +:ref:`filter_expression` elements providing the values of the function arguments. + +See the :ref:`filter_function_reference` for details of the functions provided by GeoServer. + +Property Value +^^^^^^^^^^^^^^ + +The ```` element refers to the value of a feature attribute. +It contains a **string** or an **XPath expression** specifying the attribute name. + +Literal +^^^^^^^ + +The ```` element specifies a constant value. +It contains data of one of the following types: + +.. list-table:: + :widths: 25 75 + + * - **Type** + - **Description** + * - Numeric + - A string representing a numeric value (integer or decimal). + * - Boolean + - A boolean value of ``true`` or ``false``. + * - String + - A string value. + XML-incompatible text may be included by using + **character entities** or ```` delimiters. + * - Date + - A string representing a date. + * - Geometry + - An element specifying a geometry in GML3 format. + +WFS 2.0 namespaces +------------------ + +WFS 2.0 does not depend on any one GML version and thus requires an explicit namespace and schemaLocation for GML. +In a GET request, namespaces can be placed on a Filter element (that is, ``filter=`` the block below, URL-encoded): + +.. code-block:: xml + + + + + sf:the_geom + + + + 590431 4915204 590430 + 4915205 590429 4915204 590430 + 4915203 590431 4915204 + + + + + + diff --git a/doc/en/user/source/geowebcache/troubleshooting.rst b/doc/en/user/source/geowebcache/troubleshooting.rst index 3eb9063c122..52d312827d7 100644 --- a/doc/en/user/source/geowebcache/troubleshooting.rst +++ b/doc/en/user/source/geowebcache/troubleshooting.rst @@ -1,157 +1,157 @@ -.. _gwc_troubleshooting: - -Troubleshooting -=============== - -This section will discuss some common issues with the integrated GeoWebCache and their solutions. - -Grid misalignment ------------------ - -Sometimes errors will occur when requesting data from GeoWebCache endpoints. The error displayed might say that the "resolution is not supported" or the "bounds do not align." This is due to the client making WMS requests that do not align with the grid of tiles that GeoWebCache has created, such as differing map bounds or layer bounds, or an unsupported resolution. If you are using OpenLayers as a client, looking at the source code of the included demos may provide more clues to matching up the grid. - -An alternative workaround is to enable direct WMS integration with the GeoServer WMS. You can set this on the :ref:`gwc_webadmin_defaults` page. - - -Direct WMS integration ----------------------- - -Direct integration allows WMS requests served through GeoServer to be cached as if they were received and processed by GeoWebCache. With Direct WMS Integration, a request may either be handled by the GeoServer WMS or GeoWebCache WMS. - -Sometimes requests that should go to GeoWebCache will instead be passed through to GeoServer, resulting in no tiles saved. That said, it is possible to determine why a request was not handled by GeoWebCache when intended. This is done by using the command-line utility `cURL `_ and inspecting the response headers. - -First, obtain a sample request. This can easily be done by going to the Layer Preview for a given layer, setting the :guilabel:`Tiled` parameter to :guilabel:`Tiled`, then right-clicking on an area of the map and copy the full path to the image location. If done correctly, the result will be a GET request that looks something like this:: - - http://localhost:8090/geoserver/nurc/wms?LAYERS=nurc%3AArc_Sample&STYLES=&FORMAT=image%2Fjpeg&TILED=true&TILESORIGIN=-180%2C-90&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG%3A4326&BBOX=-45,-45,0,0&WIDTH=256&HEIGHT=256 - -You can then paste this URL into a curl request: - -.. code-block:: console - - curl -v "URL" - -For example: - -.. code-block:: console - - curl -v "http://localhost:8090/geoserver/nurc/wms?LAYERS=nurc%3AArc_Sample&STYLES=&FORMAT=image%2Fjpeg&TILED=true&TILESORIGIN=-180%2C-90&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG%3A4326&BBOX=-45,-45,0,0&WIDTH=256&HEIGHT=256" - -.. note:: To omit the raw image output to the terminal, pipe the output to your system's null. On Linux / OS X, append ``> /dev/null`` to these requests, and on Windows, append ``> nul``. - -If the request doesn't go through GeoWebCache's WMS, a reason will be given in a custom response header. Look for the following response headers: - -* ``geowebcache-cache-result``: Will say ``HIT`` if the GeoWebCache WMS processed the request, and ``MISS`` otherwise. -* ``geowebcache-miss-reason``: If the above shows as ``MISS``, this will generated a short description of why the request wasn't handled by the GeoWebCache WMS. - - -The following are some example requests made along with the responses. These responses have been truncated to show only the information relevant for troubleshooting. - -Successful request -~~~~~~~~~~~~~~~~~~ - -This request was successfully handled by the GeoWebCache WMS. - -Request: - -.. code-block:: console - - curl -v "http://localhost:8080/geoserver/topp/wms?TILED=true&LAYERS=states&FORMAT=image/png&REQUEST=GetMap&STYLES=&SRS=EPSG:4326&BBOX=-135,45,-112.5,67.5&WIDTH=256&HEIGHT=256" - -Response:: - - < HTTP/1.1 200 OK - < Content-Type: image/png - < geowebcache-crs: EPSG:4326 - ... - < geowebcache-layer: topp:states - < geowebcache-gridset: EPSG:4326 - < geowebcache-tile-index: [2, 6, 3] - ... - < geowebcache-cache-result: HIT - < geowebcache-tile-bounds: -135.0,45.0,-112.5,67.5 - ... - -Wrong height parameter -~~~~~~~~~~~~~~~~~~~~~~ - -The following request is not handled by the GeoWebCache WMS because the image requested (256x257) does not conform to the expected 256x256 tile size. - -Request: - -.. code-block:: console - - curl -v "http://localhost:8080/geoserver/topp/wms?TILED=true&LAYERS=states&FORMAT=image/png&REQUEST=GetMap&STYLES=&SRS=EPSG:4326&BBOX=-135,45,-112.5,67.5&WIDTH=256&HEIGHT=257" - -Response:: - - < HTTP/1.1 200 OK - < Content-Type: image/png - < geowebcache-miss-reason: request does not align to grid(s) 'EPSG:4326' - ... - -No tile layer associated -~~~~~~~~~~~~~~~~~~~~~~~~ - -The following request is not handled by the GeoWebCache WMS because the layer requested has no tile layer configured. - -Request: - -.. code-block:: console - - curl -v "http://localhost:8080/geoserver/topp/wms?TILED=true&LAYERS=tasmania_roads&FORMAT=image/png&REQUEST=GetMap&STYLES=&SRS=EPSG:4326&BBOX=-135,45,-112.5,67.5&WIDTH=256&HEIGHT=256" - -Response:: - - < HTTP/1.1 200 OK - < Content-Type: image/png - < geowebcache-miss-reason: not a tile layer - ... - -Missing parameter filter -~~~~~~~~~~~~~~~~~~~~~~~~ - -The following request is not handled by the GeoWebCache WMS because the request contains a parameter filter (BGCOLOR) that is not configured for this layer. - -Request: - -.. code-block:: console - - curl -v "http://localhost:8080/geoserver/topp/wms?BGCOLOR=0xAAAAAA&TILED=true&LAYERS=states&FORMAT=image/png&REQUEST=GetMap&STYLES=&SRS=EPSG:4326&BBOX=-135,45,-112.5,67.5&WIDTH=256&HEIGHT=256" - -Response:: - - < HTTP/1.1 200 OK - < Content-Type: image/png - < geowebcache-miss-reason: no parameter filter exists for BGCOLOR - ... - - -CRS not defined -~~~~~~~~~~~~~~~ - -The following request is not handled by the GeoWebCache WMS because the request references a CRS (EPSG:26986) that does not match any of the tile layer gridsets: - -Request: - -.. code-block:: console - - curl -v "http://localhost:8080/geoserver/topp/wms?TILED=true&LAYERS=states&FORMAT=image/png&REQUEST=GetMap&STYLES=&SRS=EPSG:26986&BBOX=-135,45,-112.5,67.5&WIDTH=256&HEIGHT=256" - -Response:: - - < HTTP/1.1 200 OK - < Content-Type: image/png - < geowebcache-miss-reason: no cache exists for requested CRS - ... - - -Workspace Styles -~~~~~~~~~~~~~~~~ - -If a cached layer uses a style which is tied to a workspace, the layer needs to be viewed in the context of that workspace in order for the style to be visible. Trying to cache such a layer will result in an error. - -By default, the embeded GeoWebCache uses the global workspace. This can be overridden using a ``WORKSPACE`` parameter. To enable this, create a List of Strings Parameter filter for the layer named ``WORKSPACE``. Set the default to the name of the workspace containing the style. Setting the other values will not be useful in most cases. - -Moving the style to a new workspace will require updating the filter. - -This parameter only applies to integrated tile layers. If you are adding a GeoServer layer on a remote GeoServer directly to GWC, then specify the workspace as part of the path as you would normally. +.. _gwc_troubleshooting: + +Troubleshooting +=============== + +This section will discuss some common issues with the integrated GeoWebCache and their solutions. + +Grid misalignment +----------------- + +Sometimes errors will occur when requesting data from GeoWebCache endpoints. The error displayed might say that the "resolution is not supported" or the "bounds do not align." This is due to the client making WMS requests that do not align with the grid of tiles that GeoWebCache has created, such as differing map bounds or layer bounds, or an unsupported resolution. If you are using OpenLayers as a client, looking at the source code of the included demos may provide more clues to matching up the grid. + +An alternative workaround is to enable direct WMS integration with the GeoServer WMS. You can set this on the :ref:`gwc_webadmin_defaults` page. + + +Direct WMS integration +---------------------- + +Direct integration allows WMS requests served through GeoServer to be cached as if they were received and processed by GeoWebCache. With Direct WMS Integration, a request may either be handled by the GeoServer WMS or GeoWebCache WMS. + +Sometimes requests that should go to GeoWebCache will instead be passed through to GeoServer, resulting in no tiles saved. That said, it is possible to determine why a request was not handled by GeoWebCache when intended. This is done by using the command-line utility `cURL `_ and inspecting the response headers. + +First, obtain a sample request. This can easily be done by going to the Layer Preview for a given layer, setting the :guilabel:`Tiled` parameter to :guilabel:`Tiled`, then right-clicking on an area of the map and copy the full path to the image location. If done correctly, the result will be a GET request that looks something like this:: + + http://localhost:8090/geoserver/nurc/wms?LAYERS=nurc%3AArc_Sample&STYLES=&FORMAT=image%2Fjpeg&TILED=true&TILESORIGIN=-180%2C-90&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG%3A4326&BBOX=-45,-45,0,0&WIDTH=256&HEIGHT=256 + +You can then paste this URL into a curl request: + +.. code-block:: console + + curl -v "URL" + +For example: + +.. code-block:: console + + curl -v "http://localhost:8090/geoserver/nurc/wms?LAYERS=nurc%3AArc_Sample&STYLES=&FORMAT=image%2Fjpeg&TILED=true&TILESORIGIN=-180%2C-90&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG%3A4326&BBOX=-45,-45,0,0&WIDTH=256&HEIGHT=256" + +.. note:: To omit the raw image output to the terminal, pipe the output to your system's null. On Linux / OS X, append ``> /dev/null`` to these requests, and on Windows, append ``> nul``. + +If the request doesn't go through GeoWebCache's WMS, a reason will be given in a custom response header. Look for the following response headers: + +* ``geowebcache-cache-result``: Will say ``HIT`` if the GeoWebCache WMS processed the request, and ``MISS`` otherwise. +* ``geowebcache-miss-reason``: If the above shows as ``MISS``, this will generated a short description of why the request wasn't handled by the GeoWebCache WMS. + + +The following are some example requests made along with the responses. These responses have been truncated to show only the information relevant for troubleshooting. + +Successful request +~~~~~~~~~~~~~~~~~~ + +This request was successfully handled by the GeoWebCache WMS. + +Request: + +.. code-block:: console + + curl -v "http://localhost:8080/geoserver/topp/wms?TILED=true&LAYERS=states&FORMAT=image/png&REQUEST=GetMap&STYLES=&SRS=EPSG:4326&BBOX=-135,45,-112.5,67.5&WIDTH=256&HEIGHT=256" + +Response:: + + < HTTP/1.1 200 OK + < Content-Type: image/png + < geowebcache-crs: EPSG:4326 + ... + < geowebcache-layer: topp:states + < geowebcache-gridset: EPSG:4326 + < geowebcache-tile-index: [2, 6, 3] + ... + < geowebcache-cache-result: HIT + < geowebcache-tile-bounds: -135.0,45.0,-112.5,67.5 + ... + +Wrong height parameter +~~~~~~~~~~~~~~~~~~~~~~ + +The following request is not handled by the GeoWebCache WMS because the image requested (256x257) does not conform to the expected 256x256 tile size. + +Request: + +.. code-block:: console + + curl -v "http://localhost:8080/geoserver/topp/wms?TILED=true&LAYERS=states&FORMAT=image/png&REQUEST=GetMap&STYLES=&SRS=EPSG:4326&BBOX=-135,45,-112.5,67.5&WIDTH=256&HEIGHT=257" + +Response:: + + < HTTP/1.1 200 OK + < Content-Type: image/png + < geowebcache-miss-reason: request does not align to grid(s) 'EPSG:4326' + ... + +No tile layer associated +~~~~~~~~~~~~~~~~~~~~~~~~ + +The following request is not handled by the GeoWebCache WMS because the layer requested has no tile layer configured. + +Request: + +.. code-block:: console + + curl -v "http://localhost:8080/geoserver/topp/wms?TILED=true&LAYERS=tasmania_roads&FORMAT=image/png&REQUEST=GetMap&STYLES=&SRS=EPSG:4326&BBOX=-135,45,-112.5,67.5&WIDTH=256&HEIGHT=256" + +Response:: + + < HTTP/1.1 200 OK + < Content-Type: image/png + < geowebcache-miss-reason: not a tile layer + ... + +Missing parameter filter +~~~~~~~~~~~~~~~~~~~~~~~~ + +The following request is not handled by the GeoWebCache WMS because the request contains a parameter filter (BGCOLOR) that is not configured for this layer. + +Request: + +.. code-block:: console + + curl -v "http://localhost:8080/geoserver/topp/wms?BGCOLOR=0xAAAAAA&TILED=true&LAYERS=states&FORMAT=image/png&REQUEST=GetMap&STYLES=&SRS=EPSG:4326&BBOX=-135,45,-112.5,67.5&WIDTH=256&HEIGHT=256" + +Response:: + + < HTTP/1.1 200 OK + < Content-Type: image/png + < geowebcache-miss-reason: no parameter filter exists for BGCOLOR + ... + + +CRS not defined +~~~~~~~~~~~~~~~ + +The following request is not handled by the GeoWebCache WMS because the request references a CRS (EPSG:26986) that does not match any of the tile layer gridsets: + +Request: + +.. code-block:: console + + curl -v "http://localhost:8080/geoserver/topp/wms?TILED=true&LAYERS=states&FORMAT=image/png&REQUEST=GetMap&STYLES=&SRS=EPSG:26986&BBOX=-135,45,-112.5,67.5&WIDTH=256&HEIGHT=256" + +Response:: + + < HTTP/1.1 200 OK + < Content-Type: image/png + < geowebcache-miss-reason: no cache exists for requested CRS + ... + + +Workspace Styles +~~~~~~~~~~~~~~~~ + +If a cached layer uses a style which is tied to a workspace, the layer needs to be viewed in the context of that workspace in order for the style to be visible. Trying to cache such a layer will result in an error. + +By default, the embeded GeoWebCache uses the global workspace. This can be overridden using a ``WORKSPACE`` parameter. To enable this, create a List of Strings Parameter filter for the layer named ``WORKSPACE``. Set the default to the name of the workspace containing the style. Setting the other values will not be useful in most cases. + +Moving the style to a new workspace will require updating the filter. + +This parameter only applies to integrated tile layers. If you are adding a GeoServer layer on a remote GeoServer directly to GWC, then specify the workspace as part of the path as you would normally. diff --git a/doc/en/user/source/geowebcache/webadmin/defaults.rst b/doc/en/user/source/geowebcache/webadmin/defaults.rst index fd8c3743d5d..322c0c9ede4 100644 --- a/doc/en/user/source/geowebcache/webadmin/defaults.rst +++ b/doc/en/user/source/geowebcache/webadmin/defaults.rst @@ -1,251 +1,251 @@ -.. _gwc_webadmin_defaults: - -Caching defaults -================ - -The Caching Defaults page shows the global configuration options for the tile caching functionality in GeoServer, an embedded GeoWebCache. - -GWC Provided Services ---------------------- - -In addition to the GeoServer endpoints, GeoWebCache provides other endpoints for OGC services. For example, the GeoServer WMS endpoint is available at:: - - http://GEOSERVER_URL/wms?... - -The GeoWebCache WMS endpoint is:: - - http://GEOSERVER_URL/gwc/service/wms?... - -.. figure:: img/defaults_services.png - - Provided services - -The following settings describe the different services that can be enabled with GeoWebCache. - -Enable direct integration with GeoServer WMS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Direct integration allows WMS requests served through GeoServer to be cached as if they were received and processed by GeoWebCache. This provides all the advantages of using a tile server while still employing the more-flexible GeoServer WMS as a fallback. See the section on :ref:`gwc_using` for more details about this feature. - -With direct integration, tile caching is enabled for all standard WMS requests that contain the ``tiled=true`` parameter and conform to all required parameters. - -This setting is disabled by default. When enabling this option, it is a good idea to also turn on :ref:`gwc_webadmin_diskquotas` as well, to prevent unbounded growth of the stored tiles. - -Explicitly require TILED Parameter -`````````````````````````````````` -When this parameter is checked direct WMS integration requires that the ``tiled=true`` parameter be set in all requests that will be cached. If this parameter is unchecked all incoming requests will be considered for caching, the request must still conform to all required parameters. - - - -Enable WMS-C Service -~~~~~~~~~~~~~~~~~~~~ - -Enables the Cached Web Map Service (WMS-C) service. When this setting is enabled, GeoWebCache will respond to its own WMS-C endpoint:: - - http://GEOSERVER_URL/gwc/service/wms?SERVICE=WMS&VERSION=1.1.1&TILED=true&... - -When the service is disabled, calls to the capabilities document will return a ``Service is disabled`` message. - -Enable TMS Service -~~~~~~~~~~~~~~~~~~ - -Enables the Tiled Map Service (TMS) endpoint in GeoWebCache. With the TMS service, GeoWebCache will respond to its own TMS endpoint:: - - http://GEOSERVER/URL/gwc/service/tms/1.0.0 - -When the service is disabled, calls to the capabilities document will return a ``Service is disabled`` message. - -Enable WMTS Service -~~~~~~~~~~~~~~~~~~~ - -Enables the Web Map Tiled Service (WMTS) endpoint in GeoWebCache. When this setting is enabled, GeoWebCache will respond to its own WMTS endpoint:: - - http://GEOSERVER/URL/gwc/service/wmts?... - -When the service is disabled, calls to the capabilities document will return a ``Service is disabled`` message. - -HTTP RESTful API is available through the existing GWC integration allowing clients to retrieve the following resources: - -* capabilities document -* tile -* feature info - -For more information read `GWC WMTS documentation `_. - -Enable Data Security -~~~~~~~~~~~~~~~~~~~~ - -Enables the :ref:`gwc_data_security` in the embedded GeoWebCache. - -Default Caching Options for GeoServer Layers --------------------------------------------- - -This section describes the configuration of the various defaults and other global options for the tile cache in GeoServer. - -.. figure:: img/defaults_options.png - - Default caching options - -Automatically configure a GeoWebCache layer for each new layer or layer group -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This setting, enabled by default, determines how layers in GeoServer are handled via the embedded GeoWebCache. When this setting is enabled, an entry in the GeoWebCache layer listing will be created whenever a new layer or layer group is published in GeoServer. Use this setting to keep the GeoWebCache catalog in sync. (This is enabled by default.) - -Automatically cache non-default styles -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, only requests using the default style for a given layer will be cached. When this setting is enabled, all requests for a given layer, even those that use a non-standard style will be cached. Disabling this may be useful in situations where disk space is an issue, or when only one default style is important. - -Default metatile size -~~~~~~~~~~~~~~~~~~~~~ - -A metatile is several tiles combined into a larger one. This larger metatile is generated and then subdivided before being served back (and cached) as standard tiles. The advantage of using metatiling is in situations where a label or geometry lies on a boundary of a tile, which may be truncated or altered. With metatiling, these tile edge issues are greatly reduced. - -Moreover, with metatiling, the overall time it takes to seed the cache is reduced in most cases, when compared with rendering a full map with single tiles. In fact, using larger metatiling factors is a good way to reduce the time spent in seeding the cache. - -The disadvantage of metatiling is that at large sizes, memory consumption can be an issue. - -The size of the default metatile can be adjusted here. By default, GeoServer sets a metatile size of **4x4**, which strikes a balance between performance, memory usage, and rendering accuracy. - -Default gutter size -~~~~~~~~~~~~~~~~~~~ - -The gutter size sets the amount of extra space (in pixels) used when generating a tile. Use this in conjunction with metatiles to reduce problems with labels and features not being rendered incorrectly due to being on a tile boundary. - -Default Cache Formats -~~~~~~~~~~~~~~~~~~~~~ - -This setting determines the default image formats that can be cached when tiled requests are made. There are four image formats that can be used when saving tiles: - -* PNG (24-bit PNG) -* PNG8 (8-bit PNG) -* JPEG -* GIF - -The default settings are subdivided into vector layers, raster layers, and layer groups. You may select any of the above four formats for each of the three types of layers. Any requests that fall outside of these layer/format combinations will not be cached if sent through GeoServer, and will return an error if sent to the GeoWebCache endpoints. - -These defaults can be overwritten on a per-layer basis when :ref:`editing the layer properties `. - -.. figure:: img/defaults_formats.png - - Default image formats - - -In Memory BlobStore Options -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -These options are used for enabling/disabling In Memory Caching for GeoWebCache. This feature can be used for saving GWC tiles directly in memory, for a fast data retrieval. - -Enable -`````` -This parameter allows to enable or disable in memory caching. By default it is disabled. - -Avoid Persistence -````````````````` -This parameter can be used to prevent the saving of any file in the file system, keeping all the GWC tiles only in memory. By default it is disabled. - -Available Caches -```````````````` -This parameter defines which Cache method can be used for In Memory Caching. By default the Guava Caching is used. Note that if a caching method -requires an immutable configuration at GeoServer startup like HazelCast, the *Hard Memory limit*, *Eviction Policy*, *Eviction Time* and *Concurrency Level* -parameters are disabled. - -More information on how to configure a new Cache object can be found in the GeoWebCache :ref:`gwc_config` page. - -Cache Hard Memory limit (Mb) -```````````````````````````` -Parameter for configuring in memory cache size in MB. - -Cache Eviction Policy -````````````````````` -Parameter for configuring in memory cache eviction policy, it may be: LRU, LFU, EXPIRE_AFTER_WRITE, EXPIRE_AFTER_ACCESS, NULL - -This eviction policies may not be supported by all caches implementations. For example, Guava Caching only supports the eviction policies: EXPIRE_AFTER_WRITE, EXPIRE_AFTER_ACCESS and NULL. - -Note, only the eviction policies accepted by the selected cache will be shown on the UI. - -Cache Eviction Time (in Seconds) -```````````````````````````````` -Parameter for configuring in memory cache eviction time. It is in seconds. - -.. note:: Note that this parameter is also used for configuring an internal thread which performs a periodical cache cleanup. - -Cache Concurrency Level -``````````````````````` -Parameter for configuring in memory cache concurrency. - -Clear In Memory Cache -````````````````````` -Button for clearing all the tiles in the in memory cache. - -Cache Statistics -```````````````` -Various statistics parameters associated with the in memory cache. - -Update Cache Statistics -``````````````````````` -Button for updating cache statistics seen above. The statistics are always related to the local cached entries, even in case of distributed in memory caching - -.. note:: Note that some Caches do not provide all the statistics parameters, in that case the user will only see *"Unavailable"* for those parameters. - -.. figure:: img/blobstoreoptions.png - :align: center - - *In Memory BlobStore Options* - -.. note:: Note that in the *TileCaching* tab for each Layer, you may decide to disable in memory caching for the selected Layer by clicking on the **Enable In Memory Caching for this Layer** checkbox. This option is disabled for those caches which don't support this feature. - -Skip caching on dimension warnings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -WMS dimension handling can be complex, with ability to return tiles where the specified time -was not a match, or when the request contained no time at all. -This may not be a good match for tile caching, as it breaks the unique link between URL and tile content. - -The following settings allow to disable caching when a WMS dimension warning is issued: - - -.. figure:: img/skipCacheWarnings.png - :align: center - - *Skip caching on cache warnings* - -The best settings depend on the type of dataset and disk-quota configurations: - - * For **static datasets with dimensions**, the default value skip could be removed, as it's going to - generate at most one copy of the tiles. The nearest match and failed nearest - could be cached if there is a disk quota (to speed up clients that repeatedly fail to perform an exact time match), - but it's best not to cache it if there is no disk quota, as the mismatches can be potentially infinite, leading to - an uncontrolled growth of the cache. - * For a **datasets growing over time**, it's better to disable caching on the default value, as it's often - the "latest", that is, the most recently added to the dataset. This means the tiles contents - change based on when they are asked for. The considerations for nearest and failed matches - are the same as for the static datasets. - -Caution is advised if the data ingestion might happen to skip some time/elevation values, -to fill them only at a later time. In this case, nearest matches could cause the system to cache -a tile for a nearby time value, which would hide the actual values if they get ingested at a later time. - - -Default Cached Gridsets -~~~~~~~~~~~~~~~~~~~~~~~ - -This section shows the gridsets that will be automatically configured for cached layers. While there are some pre-configured gridsets available, only two are enabled by default. These correspond to the most common and universal cases: - -* EPSG:4326 (geographic) with 22 maximum zoom levels and 256x256 pixel tiles -* EPSG:900913 (spherical Mercator) with 31 maximum zoom levels and 256x256 pixel tiles - -.. figure:: img/defaults_gridsets.png - :align: center - - *Default gridsets* - - -To add a pre-existing grid set, select it from the :guilabel:`Add default grid set` menu, and click the Add icon (green circle with plus sign). - -.. figure:: img/addexistinggridset.png - :align: center - - *Adding an existing gridset to the list of defaults* - -These definitions are described in more detail on the :ref:`gwc_webadmin_gridsets` page. +.. _gwc_webadmin_defaults: + +Caching defaults +================ + +The Caching Defaults page shows the global configuration options for the tile caching functionality in GeoServer, an embedded GeoWebCache. + +GWC Provided Services +--------------------- + +In addition to the GeoServer endpoints, GeoWebCache provides other endpoints for OGC services. For example, the GeoServer WMS endpoint is available at:: + + http://GEOSERVER_URL/wms?... + +The GeoWebCache WMS endpoint is:: + + http://GEOSERVER_URL/gwc/service/wms?... + +.. figure:: img/defaults_services.png + + Provided services + +The following settings describe the different services that can be enabled with GeoWebCache. + +Enable direct integration with GeoServer WMS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Direct integration allows WMS requests served through GeoServer to be cached as if they were received and processed by GeoWebCache. This provides all the advantages of using a tile server while still employing the more-flexible GeoServer WMS as a fallback. See the section on :ref:`gwc_using` for more details about this feature. + +With direct integration, tile caching is enabled for all standard WMS requests that contain the ``tiled=true`` parameter and conform to all required parameters. + +This setting is disabled by default. When enabling this option, it is a good idea to also turn on :ref:`gwc_webadmin_diskquotas` as well, to prevent unbounded growth of the stored tiles. + +Explicitly require TILED Parameter +`````````````````````````````````` +When this parameter is checked direct WMS integration requires that the ``tiled=true`` parameter be set in all requests that will be cached. If this parameter is unchecked all incoming requests will be considered for caching, the request must still conform to all required parameters. + + + +Enable WMS-C Service +~~~~~~~~~~~~~~~~~~~~ + +Enables the Cached Web Map Service (WMS-C) service. When this setting is enabled, GeoWebCache will respond to its own WMS-C endpoint:: + + http://GEOSERVER_URL/gwc/service/wms?SERVICE=WMS&VERSION=1.1.1&TILED=true&... + +When the service is disabled, calls to the capabilities document will return a ``Service is disabled`` message. + +Enable TMS Service +~~~~~~~~~~~~~~~~~~ + +Enables the Tiled Map Service (TMS) endpoint in GeoWebCache. With the TMS service, GeoWebCache will respond to its own TMS endpoint:: + + http://GEOSERVER/URL/gwc/service/tms/1.0.0 + +When the service is disabled, calls to the capabilities document will return a ``Service is disabled`` message. + +Enable WMTS Service +~~~~~~~~~~~~~~~~~~~ + +Enables the Web Map Tiled Service (WMTS) endpoint in GeoWebCache. When this setting is enabled, GeoWebCache will respond to its own WMTS endpoint:: + + http://GEOSERVER/URL/gwc/service/wmts?... + +When the service is disabled, calls to the capabilities document will return a ``Service is disabled`` message. + +HTTP RESTful API is available through the existing GWC integration allowing clients to retrieve the following resources: + +* capabilities document +* tile +* feature info + +For more information read `GWC WMTS documentation `_. + +Enable Data Security +~~~~~~~~~~~~~~~~~~~~ + +Enables the :ref:`gwc_data_security` in the embedded GeoWebCache. + +Default Caching Options for GeoServer Layers +-------------------------------------------- + +This section describes the configuration of the various defaults and other global options for the tile cache in GeoServer. + +.. figure:: img/defaults_options.png + + Default caching options + +Automatically configure a GeoWebCache layer for each new layer or layer group +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This setting, enabled by default, determines how layers in GeoServer are handled via the embedded GeoWebCache. When this setting is enabled, an entry in the GeoWebCache layer listing will be created whenever a new layer or layer group is published in GeoServer. Use this setting to keep the GeoWebCache catalog in sync. (This is enabled by default.) + +Automatically cache non-default styles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, only requests using the default style for a given layer will be cached. When this setting is enabled, all requests for a given layer, even those that use a non-standard style will be cached. Disabling this may be useful in situations where disk space is an issue, or when only one default style is important. + +Default metatile size +~~~~~~~~~~~~~~~~~~~~~ + +A metatile is several tiles combined into a larger one. This larger metatile is generated and then subdivided before being served back (and cached) as standard tiles. The advantage of using metatiling is in situations where a label or geometry lies on a boundary of a tile, which may be truncated or altered. With metatiling, these tile edge issues are greatly reduced. + +Moreover, with metatiling, the overall time it takes to seed the cache is reduced in most cases, when compared with rendering a full map with single tiles. In fact, using larger metatiling factors is a good way to reduce the time spent in seeding the cache. + +The disadvantage of metatiling is that at large sizes, memory consumption can be an issue. + +The size of the default metatile can be adjusted here. By default, GeoServer sets a metatile size of **4x4**, which strikes a balance between performance, memory usage, and rendering accuracy. + +Default gutter size +~~~~~~~~~~~~~~~~~~~ + +The gutter size sets the amount of extra space (in pixels) used when generating a tile. Use this in conjunction with metatiles to reduce problems with labels and features not being rendered incorrectly due to being on a tile boundary. + +Default Cache Formats +~~~~~~~~~~~~~~~~~~~~~ + +This setting determines the default image formats that can be cached when tiled requests are made. There are four image formats that can be used when saving tiles: + +* PNG (24-bit PNG) +* PNG8 (8-bit PNG) +* JPEG +* GIF + +The default settings are subdivided into vector layers, raster layers, and layer groups. You may select any of the above four formats for each of the three types of layers. Any requests that fall outside of these layer/format combinations will not be cached if sent through GeoServer, and will return an error if sent to the GeoWebCache endpoints. + +These defaults can be overwritten on a per-layer basis when :ref:`editing the layer properties `. + +.. figure:: img/defaults_formats.png + + Default image formats + + +In Memory BlobStore Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These options are used for enabling/disabling In Memory Caching for GeoWebCache. This feature can be used for saving GWC tiles directly in memory, for a fast data retrieval. + +Enable +`````` +This parameter allows to enable or disable in memory caching. By default it is disabled. + +Avoid Persistence +````````````````` +This parameter can be used to prevent the saving of any file in the file system, keeping all the GWC tiles only in memory. By default it is disabled. + +Available Caches +```````````````` +This parameter defines which Cache method can be used for In Memory Caching. By default the Guava Caching is used. Note that if a caching method +requires an immutable configuration at GeoServer startup like HazelCast, the *Hard Memory limit*, *Eviction Policy*, *Eviction Time* and *Concurrency Level* +parameters are disabled. + +More information on how to configure a new Cache object can be found in the GeoWebCache :ref:`gwc_config` page. + +Cache Hard Memory limit (Mb) +```````````````````````````` +Parameter for configuring in memory cache size in MB. + +Cache Eviction Policy +````````````````````` +Parameter for configuring in memory cache eviction policy, it may be: LRU, LFU, EXPIRE_AFTER_WRITE, EXPIRE_AFTER_ACCESS, NULL + +This eviction policies may not be supported by all caches implementations. For example, Guava Caching only supports the eviction policies: EXPIRE_AFTER_WRITE, EXPIRE_AFTER_ACCESS and NULL. + +Note, only the eviction policies accepted by the selected cache will be shown on the UI. + +Cache Eviction Time (in Seconds) +```````````````````````````````` +Parameter for configuring in memory cache eviction time. It is in seconds. + +.. note:: Note that this parameter is also used for configuring an internal thread which performs a periodical cache cleanup. + +Cache Concurrency Level +``````````````````````` +Parameter for configuring in memory cache concurrency. + +Clear In Memory Cache +````````````````````` +Button for clearing all the tiles in the in memory cache. + +Cache Statistics +```````````````` +Various statistics parameters associated with the in memory cache. + +Update Cache Statistics +``````````````````````` +Button for updating cache statistics seen above. The statistics are always related to the local cached entries, even in case of distributed in memory caching + +.. note:: Note that some Caches do not provide all the statistics parameters, in that case the user will only see *"Unavailable"* for those parameters. + +.. figure:: img/blobstoreoptions.png + :align: center + + *In Memory BlobStore Options* + +.. note:: Note that in the *TileCaching* tab for each Layer, you may decide to disable in memory caching for the selected Layer by clicking on the **Enable In Memory Caching for this Layer** checkbox. This option is disabled for those caches which don't support this feature. + +Skip caching on dimension warnings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +WMS dimension handling can be complex, with ability to return tiles where the specified time +was not a match, or when the request contained no time at all. +This may not be a good match for tile caching, as it breaks the unique link between URL and tile content. + +The following settings allow to disable caching when a WMS dimension warning is issued: + + +.. figure:: img/skipCacheWarnings.png + :align: center + + *Skip caching on cache warnings* + +The best settings depend on the type of dataset and disk-quota configurations: + + * For **static datasets with dimensions**, the default value skip could be removed, as it's going to + generate at most one copy of the tiles. The nearest match and failed nearest + could be cached if there is a disk quota (to speed up clients that repeatedly fail to perform an exact time match), + but it's best not to cache it if there is no disk quota, as the mismatches can be potentially infinite, leading to + an uncontrolled growth of the cache. + * For a **datasets growing over time**, it's better to disable caching on the default value, as it's often + the "latest", that is, the most recently added to the dataset. This means the tiles contents + change based on when they are asked for. The considerations for nearest and failed matches + are the same as for the static datasets. + +Caution is advised if the data ingestion might happen to skip some time/elevation values, +to fill them only at a later time. In this case, nearest matches could cause the system to cache +a tile for a nearby time value, which would hide the actual values if they get ingested at a later time. + + +Default Cached Gridsets +~~~~~~~~~~~~~~~~~~~~~~~ + +This section shows the gridsets that will be automatically configured for cached layers. While there are some pre-configured gridsets available, only two are enabled by default. These correspond to the most common and universal cases: + +* EPSG:4326 (geographic) with 22 maximum zoom levels and 256x256 pixel tiles +* EPSG:900913 (spherical Mercator) with 31 maximum zoom levels and 256x256 pixel tiles + +.. figure:: img/defaults_gridsets.png + :align: center + + *Default gridsets* + + +To add a pre-existing grid set, select it from the :guilabel:`Add default grid set` menu, and click the Add icon (green circle with plus sign). + +.. figure:: img/addexistinggridset.png + :align: center + + *Adding an existing gridset to the list of defaults* + +These definitions are described in more detail on the :ref:`gwc_webadmin_gridsets` page. diff --git a/doc/en/user/source/installation/osx_jaierror.txt b/doc/en/user/source/installation/osx_jaierror.txt index 41160f6101e..8ed41ec8750 100644 --- a/doc/en/user/source/installation/osx_jaierror.txt +++ b/doc/en/user/source/installation/osx_jaierror.txt @@ -1,15 +1,15 @@ -.. warning:: If you encounter the following error during startup, you may have some invalid JAI jars from the default Mac Java install: - - .. code-block:: bash - - java.lang.NoClassDefFoundError: Could not initialize class javax.media.jai.JAI - - To fix this error, locate your Java extensions folder (Usually ``/System/Library/Java/Extensions`` and/or ``~/Library/Java/Extensions``), and delete the following jars: - - .. code-block:: bash - - jai_codec-1.1.3.jar - jai_core-1.1.3.jar - jai_imageio-1.1.jar - +.. warning:: If you encounter the following error during startup, you may have some invalid JAI jars from the default Mac Java install: + + .. code-block:: bash + + java.lang.NoClassDefFoundError: Could not initialize class javax.media.jai.JAI + + To fix this error, locate your Java extensions folder (Usually ``/System/Library/Java/Extensions`` and/or ``~/Library/Java/Extensions``), and delete the following jars: + + .. code-block:: bash + + jai_codec-1.1.3.jar + jai_core-1.1.3.jar + jai_imageio-1.1.jar + If you have upgraded your OS from an older version, you may not have permission to delete these jars. In this case, you will first need to `disable System Integrity Protection `_. \ No newline at end of file diff --git a/doc/en/user/source/installation/war.rst b/doc/en/user/source/installation/war.rst index 88470077082..2156b1c4f07 100644 --- a/doc/en/user/source/installation/war.rst +++ b/doc/en/user/source/installation/war.rst @@ -1,117 +1,117 @@ -.. _installation_war: - -Web archive -=========== - -GeoServer is packaged as a standalone servlet for use with existing application servers such as `Apache Tomcat `_ and `Jetty `_. - -.. note:: GeoServer has been mostly tested using Tomcat, and so is the recommended application server. GeoServer requires a newer version of Tomcat (7.0.65 or later) that implements Servlet 3 and annotation processing. Other application servers have been known to work, but are not guaranteed. - -Installation ------------- - -#. Make sure you have a Java Runtime Environment (JRE) installed on your system. GeoServer requires a **Java 8** or **Java 11** environment, available from `OpenJDK `__, `AdoptOpenJDK `__ for Windows and macOS installers, or provided by your OS distribution. - - - .. note:: For more information about Java and GeoServer, please see the section on :ref:`production_java`. - -#. Navigate to the `GeoServer Download page `_. - -#. Select :guilabel:`Web Archive` on the download page. - -#. Download and unpack the archive. - -#. Deploy the web archive as you would normally. Often, all that is necessary is to copy the :file:`geoserver.war` file to the application server's ``webapps`` directory, and the application will be deployed. - - .. note:: A restart of your application server may be necessary. - -Tomcat Hardening ----------------- -Hide the Tomcat version in error responses and its error details. - -To remove the Tomcat version, create following file with emtpy parameters -:: - - cd $CATALINA_HOME (where Tomcat binaries are installed) - mkdir -p ./lib/org/apache/catalina/util/ - cat > ./lib/org/apache/catalina/util/ServerInfo.properties < - - ... - - - - - - - - - -Why, if security by obscurity does not work? - -Even though this is not the final solution, it at least mitigates the visible eye-catcher of outdated software packages. - -Let's take the attackers point of view. - -Response with just HTTP status: -:: - - HTTP Status 400 – Bad Request - -Ok, it looks like a Tomcat is installed. - -Default full response: -:: - - HTTP Status 400 – Bad Request - Type Status Report - Message Invalid URI - Description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). - Apache Tomcat/7.0.67 - -Ahh, great, the software ist not really maintained. Tomcat is far outdated from Dec. 2015 (6 years old as of today Jan. 2022) with a lot of unfixed vulnerabilities. - -Notice: For support reason, the local output of version.sh still outputs the current version -:: - - $CATALINA_HOME/bin/version.sh - ... - Server number: 7.0.67 - ... - - -Running -------- - -Use your container application's method of starting and stopping webapps to run GeoServer. - -To access the :ref:`web_admin`, open a browser and navigate to ``http://SERVER/geoserver`` . For example, with Tomcat running on port 8080 on localhost, the URL would be ``http://localhost:8080/geoserver``. - -Update ------- - -Update regularly at least the container application! And repeat the hardening. - -There are a lot of geoserver installations visible with outdated Tomcat versions. - -Uninstallation --------------- - -#. Stop the container application. - -#. Remove the GeoServer webapp from the container application's ``webapps`` directory. This will usually include the :file:`geoserver.war` file as well as a ``geoserver`` directory. +.. _installation_war: + +Web archive +=========== + +GeoServer is packaged as a standalone servlet for use with existing application servers such as `Apache Tomcat `_ and `Jetty `_. + +.. note:: GeoServer has been mostly tested using Tomcat, and so is the recommended application server. GeoServer requires a newer version of Tomcat (7.0.65 or later) that implements Servlet 3 and annotation processing. Other application servers have been known to work, but are not guaranteed. + +Installation +------------ + +#. Make sure you have a Java Runtime Environment (JRE) installed on your system. GeoServer requires a **Java 8** or **Java 11** environment, available from `OpenJDK `__, `AdoptOpenJDK `__ for Windows and macOS installers, or provided by your OS distribution. + + + .. note:: For more information about Java and GeoServer, please see the section on :ref:`production_java`. + +#. Navigate to the `GeoServer Download page `_. + +#. Select :guilabel:`Web Archive` on the download page. + +#. Download and unpack the archive. + +#. Deploy the web archive as you would normally. Often, all that is necessary is to copy the :file:`geoserver.war` file to the application server's ``webapps`` directory, and the application will be deployed. + + .. note:: A restart of your application server may be necessary. + +Tomcat Hardening +---------------- +Hide the Tomcat version in error responses and its error details. + +To remove the Tomcat version, create following file with emtpy parameters +:: + + cd $CATALINA_HOME (where Tomcat binaries are installed) + mkdir -p ./lib/org/apache/catalina/util/ + cat > ./lib/org/apache/catalina/util/ServerInfo.properties < + + ... + + + + + + + + + +Why, if security by obscurity does not work? + +Even though this is not the final solution, it at least mitigates the visible eye-catcher of outdated software packages. + +Let's take the attackers point of view. + +Response with just HTTP status: +:: + + HTTP Status 400 – Bad Request + +Ok, it looks like a Tomcat is installed. + +Default full response: +:: + + HTTP Status 400 – Bad Request + Type Status Report + Message Invalid URI + Description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). + Apache Tomcat/7.0.67 + +Ahh, great, the software ist not really maintained. Tomcat is far outdated from Dec. 2015 (6 years old as of today Jan. 2022) with a lot of unfixed vulnerabilities. + +Notice: For support reason, the local output of version.sh still outputs the current version +:: + + $CATALINA_HOME/bin/version.sh + ... + Server number: 7.0.67 + ... + + +Running +------- + +Use your container application's method of starting and stopping webapps to run GeoServer. + +To access the :ref:`web_admin`, open a browser and navigate to ``http://SERVER/geoserver`` . For example, with Tomcat running on port 8080 on localhost, the URL would be ``http://localhost:8080/geoserver``. + +Update +------ + +Update regularly at least the container application! And repeat the hardening. + +There are a lot of geoserver installations visible with outdated Tomcat versions. + +Uninstallation +-------------- + +#. Stop the container application. + +#. Remove the GeoServer webapp from the container application's ``webapps`` directory. This will usually include the :file:`geoserver.war` file as well as a ``geoserver`` directory. diff --git a/doc/en/user/source/installation/win_binary.rst b/doc/en/user/source/installation/win_binary.rst index d2346c927b8..914f0c33e88 100644 --- a/doc/en/user/source/installation/win_binary.rst +++ b/doc/en/user/source/installation/win_binary.rst @@ -1,70 +1,70 @@ -.. _installation_windows_bin: - -Windows binary -============== - -.. note:: For installing on Windows with an existing application server such as Tomcat, please see the :ref:`installation_war` section. - -The other way of installing GeoServer on Windows is to use the platform-independent binary. This version is a GeoServer web application bundled inside `Jetty `_, a lightweight and portable application server. It has the advantages of working very similarly across all operating systems and is very simple to set up. - -Installation ------------- - -#. Make sure you have a Java Runtime Environment (JRE) installed on your system. GeoServer requires a **Java 8** or **Java 11** environment, as provided by `AdoptOpenJDK `__ Windows installers. - - - .. note:: For more information about Java and GeoServer, please see the section on :ref:`production_java`. - -#. Navigate to the `GeoServer Download page `_. - -#. Select the version of GeoServer that you wish to download. If you're not sure, select `Stable `_. - -#. Select :guilabel:`Platform Independent Binary` on the download page. - -#. Download the archive and unpack to the directory where you would like the program to be located. - - .. note:: A suggested location would be :file:`C:\\Program Files\\GeoServer`. - -Setting environment variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You will need to set the ``JAVA_HOME`` environment variable if it is not already set. This is the path to your JRE such that :file:`%JAVA_HOME%\\bin\\java.exe` exists. - -#. Navigate to :menuselection:`Control Panel --> System --> Advanced --> Environment Variables`. - -#. Under :guilabel:`System variables` click :guilabel:`New`. - -#. For :guilabel:`Variable name` enter ``JAVA_HOME``. For :guilabel:`Variable value` enter the path to your JDK/JRE. - -#. Click OK three times. - -.. note:: You may also want to set the ``GEOSERVER_HOME`` variable, which is the directory where GeoServer is installed, and the ``GEOSERVER_DATA_DIR`` variable, which is the location of the GeoServer data directory (which by default is :file:`%GEOSERVER_HOME\\data_dir`). The latter is mandatory if you wish to use a data directory other than the default location. The procedure for setting these variables is identical to setting the ``JAVA_HOME`` variable. - -Running -------- - -.. note:: This can be done either via Windows Explorer or the command line. - -#. Navigate to the :file:`bin` directory inside the location where GeoServer is installed. - -#. Run :file:`startup.bat`. A command-line window will appear and persist. This window contains diagnostic and troubleshooting information. This window must be left open, otherwise GeoServer will shut down. - -#. Navigate to ``http://localhost:8080/geoserver`` (or wherever you installed GeoServer) to access the GeoServer :ref:`web_admin`. - -If you see the GeoServer logo, then GeoServer is successfully installed. - - .. figure:: images/success.png - - GeoServer installed and running successfully - -Stopping --------- - -To shut down GeoServer, either close the persistent command-line window, or run the :file:`shutdown.bat` file inside the :file:`bin` directory. - -Uninstallation --------------- - -#. Stop GeoServer (if it is running). - -#. Delete the directory where GeoServer is installed. +.. _installation_windows_bin: + +Windows binary +============== + +.. note:: For installing on Windows with an existing application server such as Tomcat, please see the :ref:`installation_war` section. + +The other way of installing GeoServer on Windows is to use the platform-independent binary. This version is a GeoServer web application bundled inside `Jetty `_, a lightweight and portable application server. It has the advantages of working very similarly across all operating systems and is very simple to set up. + +Installation +------------ + +#. Make sure you have a Java Runtime Environment (JRE) installed on your system. GeoServer requires a **Java 8** or **Java 11** environment, as provided by `AdoptOpenJDK `__ Windows installers. + + + .. note:: For more information about Java and GeoServer, please see the section on :ref:`production_java`. + +#. Navigate to the `GeoServer Download page `_. + +#. Select the version of GeoServer that you wish to download. If you're not sure, select `Stable `_. + +#. Select :guilabel:`Platform Independent Binary` on the download page. + +#. Download the archive and unpack to the directory where you would like the program to be located. + + .. note:: A suggested location would be :file:`C:\\Program Files\\GeoServer`. + +Setting environment variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You will need to set the ``JAVA_HOME`` environment variable if it is not already set. This is the path to your JRE such that :file:`%JAVA_HOME%\\bin\\java.exe` exists. + +#. Navigate to :menuselection:`Control Panel --> System --> Advanced --> Environment Variables`. + +#. Under :guilabel:`System variables` click :guilabel:`New`. + +#. For :guilabel:`Variable name` enter ``JAVA_HOME``. For :guilabel:`Variable value` enter the path to your JDK/JRE. + +#. Click OK three times. + +.. note:: You may also want to set the ``GEOSERVER_HOME`` variable, which is the directory where GeoServer is installed, and the ``GEOSERVER_DATA_DIR`` variable, which is the location of the GeoServer data directory (which by default is :file:`%GEOSERVER_HOME\\data_dir`). The latter is mandatory if you wish to use a data directory other than the default location. The procedure for setting these variables is identical to setting the ``JAVA_HOME`` variable. + +Running +------- + +.. note:: This can be done either via Windows Explorer or the command line. + +#. Navigate to the :file:`bin` directory inside the location where GeoServer is installed. + +#. Run :file:`startup.bat`. A command-line window will appear and persist. This window contains diagnostic and troubleshooting information. This window must be left open, otherwise GeoServer will shut down. + +#. Navigate to ``http://localhost:8080/geoserver`` (or wherever you installed GeoServer) to access the GeoServer :ref:`web_admin`. + +If you see the GeoServer logo, then GeoServer is successfully installed. + + .. figure:: images/success.png + + GeoServer installed and running successfully + +Stopping +-------- + +To shut down GeoServer, either close the persistent command-line window, or run the :file:`shutdown.bat` file inside the :file:`bin` directory. + +Uninstallation +-------------- + +#. Stop GeoServer (if it is running). + +#. Delete the directory where GeoServer is installed. diff --git a/doc/en/user/source/production/index.rst b/doc/en/user/source/production/index.rst index 137174ed6aa..db916489f2d 100644 --- a/doc/en/user/source/production/index.rst +++ b/doc/en/user/source/production/index.rst @@ -1,18 +1,18 @@ -.. _production: - -Running in a production environment -=================================== - -GeoServer is geared towards many different uses, from a simple test server to the enterprise-level data server. While many optimizations for GeoServer are set by default, here are some extra considerations to keep in mind when running GeoServer in a production environment. - -.. toctree:: - :maxdepth: 2 - - java - container - config - data - linuxscript - misc - troubleshooting - identify +.. _production: + +Running in a production environment +=================================== + +GeoServer is geared towards many different uses, from a simple test server to the enterprise-level data server. While many optimizations for GeoServer are set by default, here are some extra considerations to keep in mind when running GeoServer in a production environment. + +.. toctree:: + :maxdepth: 2 + + java + container + config + data + linuxscript + misc + troubleshooting + identify diff --git a/doc/en/user/source/rest/index.rst b/doc/en/user/source/rest/index.rst index a13e4f31d34..0cd3d04fb01 100644 --- a/doc/en/user/source/rest/index.rst +++ b/doc/en/user/source/rest/index.rst @@ -1,106 +1,106 @@ -.. _rest: - -REST -==== - -GeoServer provides a `RESTful `_ interface through which clients can retrieve information about an instance and make configuration changes. Using the REST interface's simple HTTP calls, clients can configure GeoServer without needing to use the :ref:`web_admin`. - -REST is an acronym for "`REpresentational State Transfer `_". REST adopts a fixed set of operations on named resources, where the representation of each resource is the same for retrieving and setting information. In other words, you can retrieve (read) data in an XML format and also send data back to the server in similar XML format in order to set (write) changes to the system. - -Operations on resources are implemented with the standard primitives of HTTP: GET to read; and PUT, POST, and DELETE to write changes. Each resource is represented as a URL, such as ``http://GEOSERVER_HOME/rest/workspaces/topp``. - - -API ---- - -.. warning:: The API is documented as Swagger 2.0 files. However, these files have been written by hand back in 2017, and have not always been kept up to date with the evolution of the GeoServer configuration object structure. Also, they have not been tested for proper client generation, and will likely not work for that purpose. Take them only as a form of documentation. - -The following links provide direct access to the GeoServer REST API documentation, including definitions and examples of each endpoint: - -* :api:`/about/manifests ` -* :api:`/about/system-status ` -* :api:`/datastores ` -* :api:`/coverages ` -* :api:`/coveragestores ` -* :api:`/featuretypes ` -* :api:`/fonts ` -* :api:`/layergroups ` -* :api:`/layers ` -* :api:`/monitoring ` -* :api:`/namespaces ` -* :api:`/services/wms|wfs|wcs|wmts/settings ` -* :api:`/reload ` -* :api:`/resource ` -* :api:`/security ` -* :api:`/settings ` -* :api:`/structuredcoverages ` -* :api:`/styles ` -* :api:`/templates ` -* :api:`/transforms ` -* :api:`/wmslayers ` -* :api:`/wmsstores ` -* :api:`/wmtslayers ` -* :api:`/wmtsstores ` -* :api:`/workspaces ` -* :api:`/usergroup ` -* :api:`/roles ` - -* GeoWebCache: - - * :api:`/blobstores ` - * :api:`/bounds ` - * :api:`/diskquota ` - * :api:`/filterupdate ` - * :api:`/global ` - * :api:`/gridsets ` - * :api:`/index ` - * :api:`/layers ` - * :api:`/masstruncate ` - * :api:`/statistics ` - * :api:`/reload ` - * :api:`/seed ` - -* Importer extension: - - * :api:`/imports ` - * :api:`/imports (tasks) ` - * :api:`/imports (transforms) ` - * :api:`/imports (data) ` - -* Monitor extension: - - * :api:`/monitor ` - -* XSLT extension: - - * :api:`/services/wfs/transforms ` - -.. note:: You can also view the original :ref:`rest_api` section. - -Examples --------- - -This section contains a number of examples which illustrate some of the most common uses of the REST API. They are grouped by endpoint. - - -.. toctree:: - :maxdepth: 1 - - about - fonts - layergroups - layers - security - styles - workspaces - stores - imagemosaic - appschema - - - -.. toctree:: - :maxdepth: 1 - :hidden: - - api/index +.. _rest: + +REST +==== + +GeoServer provides a `RESTful `_ interface through which clients can retrieve information about an instance and make configuration changes. Using the REST interface's simple HTTP calls, clients can configure GeoServer without needing to use the :ref:`web_admin`. + +REST is an acronym for "`REpresentational State Transfer `_". REST adopts a fixed set of operations on named resources, where the representation of each resource is the same for retrieving and setting information. In other words, you can retrieve (read) data in an XML format and also send data back to the server in similar XML format in order to set (write) changes to the system. + +Operations on resources are implemented with the standard primitives of HTTP: GET to read; and PUT, POST, and DELETE to write changes. Each resource is represented as a URL, such as ``http://GEOSERVER_HOME/rest/workspaces/topp``. + + +API +--- + +.. warning:: The API is documented as Swagger 2.0 files. However, these files have been written by hand back in 2017, and have not always been kept up to date with the evolution of the GeoServer configuration object structure. Also, they have not been tested for proper client generation, and will likely not work for that purpose. Take them only as a form of documentation. + +The following links provide direct access to the GeoServer REST API documentation, including definitions and examples of each endpoint: + +* :api:`/about/manifests ` +* :api:`/about/system-status ` +* :api:`/datastores ` +* :api:`/coverages ` +* :api:`/coveragestores ` +* :api:`/featuretypes ` +* :api:`/fonts ` +* :api:`/layergroups ` +* :api:`/layers ` +* :api:`/monitoring ` +* :api:`/namespaces ` +* :api:`/services/wms|wfs|wcs|wmts/settings ` +* :api:`/reload ` +* :api:`/resource ` +* :api:`/security ` +* :api:`/settings ` +* :api:`/structuredcoverages ` +* :api:`/styles ` +* :api:`/templates ` +* :api:`/transforms ` +* :api:`/wmslayers ` +* :api:`/wmsstores ` +* :api:`/wmtslayers ` +* :api:`/wmtsstores ` +* :api:`/workspaces ` +* :api:`/usergroup ` +* :api:`/roles ` + +* GeoWebCache: + + * :api:`/blobstores ` + * :api:`/bounds ` + * :api:`/diskquota ` + * :api:`/filterupdate ` + * :api:`/global ` + * :api:`/gridsets ` + * :api:`/index ` + * :api:`/layers ` + * :api:`/masstruncate ` + * :api:`/statistics ` + * :api:`/reload ` + * :api:`/seed ` + +* Importer extension: + + * :api:`/imports ` + * :api:`/imports (tasks) ` + * :api:`/imports (transforms) ` + * :api:`/imports (data) ` + +* Monitor extension: + + * :api:`/monitor ` + +* XSLT extension: + + * :api:`/services/wfs/transforms ` + +.. note:: You can also view the original :ref:`rest_api` section. + +Examples +-------- + +This section contains a number of examples which illustrate some of the most common uses of the REST API. They are grouped by endpoint. + + +.. toctree:: + :maxdepth: 1 + + about + fonts + layergroups + layers + security + styles + workspaces + stores + imagemosaic + appschema + + + +.. toctree:: + :maxdepth: 1 + :hidden: + + api/index diff --git a/doc/en/user/source/services/csw/index.rst b/doc/en/user/source/services/csw/index.rst index 65fc18372dc..ecfb5917a91 100644 --- a/doc/en/user/source/services/csw/index.rst +++ b/doc/en/user/source/services/csw/index.rst @@ -1,17 +1,17 @@ -.. _csw: - -Catalog Services for the Web (CSW) -================================== - -This section discusses the Catalog Services for Web (CSW) optional extension. With this extension, GeoServer supports retrieving and displaying items from the GeoServer catalog using the CSW service. - -For more information on CSW, please refer to `OGC OpenGIS Implementation Specification 07-006r1 `__ and the `OGC tutorial on CSW `_. - -.. toctree:: - :maxdepth: 2 - - installing - features - directdownload - -See the :ref:`csw_iso_tutorial` for a tutorial on how to use the CSW Metadata Module. +.. _csw: + +Catalog Services for the Web (CSW) +================================== + +This section discusses the Catalog Services for Web (CSW) optional extension. With this extension, GeoServer supports retrieving and displaying items from the GeoServer catalog using the CSW service. + +For more information on CSW, please refer to `OGC OpenGIS Implementation Specification 07-006r1 `__ and the `OGC tutorial on CSW `_. + +.. toctree:: + :maxdepth: 2 + + installing + features + directdownload + +See the :ref:`csw_iso_tutorial` for a tutorial on how to use the CSW Metadata Module. diff --git a/doc/en/user/source/services/wms/googleearth/features/customizingplacemarks.rst b/doc/en/user/source/services/wms/googleearth/features/customizingplacemarks.rst index ee6a382f363..e4146f45278 100644 --- a/doc/en/user/source/services/wms/googleearth/features/customizingplacemarks.rst +++ b/doc/en/user/source/services/wms/googleearth/features/customizingplacemarks.rst @@ -1,36 +1,36 @@ -.. _ge_feature_customizing_placemarks: - -Customizing Placemarks -====================== - -KML output can leverage some powerful visualization abilities in Google Earth. **Titles** can be displayed on top of the features. **Descriptions** (custom HTML shown when clicking on a feature) can be added to customize the views of the attribute data. In addition, using Google Earth's time slider, **time**-based animations can be created. Finally, **height** of features can be set, as opposed to the default ground overlay. All of these can be accomplished by creating Freemarker templates. Freemarker templates are text files (with limited HTML code), saved in the :ref:`datadir`, that utilize variables that link to specific attributes in the data. - -Titles ------- - -Specifying labels via a template involves creating a special text file called ``title.ftl`` and placing it into the featuretypes directory inside the :ref:`datadir` for the dataset to be labeled. For instance, to create a template to label the ``states`` layer by state name, one would create the file: ``/workspaces/topp/states_shapefile/states/title.ftl``. The content of the file would be:: - - ${STATE_NAME.value} - -.. warning: Add SS: Using a Freemarker template to display the value of STATE_NAME - -Descriptions ------------- - -When working with KML, each feature is linked to a description, accessible when the feature is clicked on. By default, GeoServer creates a list of all the attributes and values for the particular feature. - -.. warning: Add SS: Default description for a feature - -It is possible to modify this default behavior. Much like with featuretype titles, which are edited by creating a ``title.ftl`` template, specifying descriptions via a template involves creating a special text file called ``description.ftl`` and placing it into the featuretypes directory inside the :ref:`datadir` for the dataset to be labeled. For instance, a sample description template would be saved here: ``/workspaces/topp/states_shapefile/states/description.ftl``. The content of the file could be:: - - This is the state of ${STATE_NAME.value}. - -The resulting description will look like this: - -.. warning:: Add SS: A custom description - -It is also possible to create one description template for all layers in a given namespace. To do this, create a ``description.ftl`` file as above, and save it here:: - - /templates//description.ftl. - -Please note that if a description template is created for a specific layer that also has an associated namespace description template, the layer template (i.e. the most specific template) will take priority. +.. _ge_feature_customizing_placemarks: + +Customizing Placemarks +====================== + +KML output can leverage some powerful visualization abilities in Google Earth. **Titles** can be displayed on top of the features. **Descriptions** (custom HTML shown when clicking on a feature) can be added to customize the views of the attribute data. In addition, using Google Earth's time slider, **time**-based animations can be created. Finally, **height** of features can be set, as opposed to the default ground overlay. All of these can be accomplished by creating Freemarker templates. Freemarker templates are text files (with limited HTML code), saved in the :ref:`datadir`, that utilize variables that link to specific attributes in the data. + +Titles +------ + +Specifying labels via a template involves creating a special text file called ``title.ftl`` and placing it into the featuretypes directory inside the :ref:`datadir` for the dataset to be labeled. For instance, to create a template to label the ``states`` layer by state name, one would create the file: ``/workspaces/topp/states_shapefile/states/title.ftl``. The content of the file would be:: + + ${STATE_NAME.value} + +.. warning: Add SS: Using a Freemarker template to display the value of STATE_NAME + +Descriptions +------------ + +When working with KML, each feature is linked to a description, accessible when the feature is clicked on. By default, GeoServer creates a list of all the attributes and values for the particular feature. + +.. warning: Add SS: Default description for a feature + +It is possible to modify this default behavior. Much like with featuretype titles, which are edited by creating a ``title.ftl`` template, specifying descriptions via a template involves creating a special text file called ``description.ftl`` and placing it into the featuretypes directory inside the :ref:`datadir` for the dataset to be labeled. For instance, a sample description template would be saved here: ``/workspaces/topp/states_shapefile/states/description.ftl``. The content of the file could be:: + + This is the state of ${STATE_NAME.value}. + +The resulting description will look like this: + +.. warning:: Add SS: A custom description + +It is also possible to create one description template for all layers in a given namespace. To do this, create a ``description.ftl`` file as above, and save it here:: + + /templates//description.ftl. + +Please note that if a description template is created for a specific layer that also has an associated namespace description template, the layer template (i.e. the most specific template) will take priority. diff --git a/doc/en/user/source/services/wms/googleearth/features/filters.rst b/doc/en/user/source/services/wms/googleearth/features/filters.rst index ccf80320d1c..f4e45c42c1c 100644 --- a/doc/en/user/source/services/wms/googleearth/features/filters.rst +++ b/doc/en/user/source/services/wms/googleearth/features/filters.rst @@ -1,36 +1,36 @@ -.. _ge_feature_filters: - -Filters -======= - -Though not specific to Google Earth, GeoServer has the ability to filter data returned from the :ref:`wms`. The KML Reflector will pass through any WMS ``filter`` or ``cql_filter`` parameter to GeoServer to constrain the response. - -.. note:: Filters are basically a translation of a SQL "WHERE" statement into web form. Though limited to a single table, this allows users to do logical filters like "AND" and "OR" to make very complex queries, leveraging numerical and string comparisons, geometric operations ("bbox", "touches", "intersects", "disjoint"), "LIKE" statements, nulls, and more. - -Filter ------- - -There simplest filter is very easy to include. It is called the ``featureid`` filter, and it lets you filter to a single feature by its ID. The syntax is:: - - featureid= - -where is the feature and its ID. An example would be:: - - http://localhost:8080/geoserver/wms/kml?layers=topp:states&featureid=states.5 - -This request will output only the state of Maryland. The feature IDs of your data are most easily found by doing WFS or KML requests and examining the resulting output. - - -CQL Filter ----------- - -Using filters in a URL can be very unwieldy, as one needs to include URL-encoded XML:: - - http:/localhost:8080/geoserver/wms/kml?layers=topp:states&FILTER=%3CFilter%3E%3CPropertyIsBetween%3E%3CPropertyName%3Etopp:LAND_KM%3C/PropertyName%3E%3CLowerBoundary%3E%3CLiteral%3E100000%3C/Literal%3E%3C/LowerBoundary%3E%3CUpperBoundary%3E%3CLiteral%3E150000%3C/Literal%3E%3C/UpperBoundary%3E%3C/PropertyIsBetween%3E%3C/Filter%3E - -Instead, one can use Common Query Language (CQL), which allows one to specify the same statement more succinctly:: - - http://localhost:8080/geoserver/wms/kml?layers=topp:states&CQL_FILTER=LAND_KM+BETWEEN+100000+AND+150000 - -This query will return all the states in the US with areas between 100,000 and 150,000 km^2. - +.. _ge_feature_filters: + +Filters +======= + +Though not specific to Google Earth, GeoServer has the ability to filter data returned from the :ref:`wms`. The KML Reflector will pass through any WMS ``filter`` or ``cql_filter`` parameter to GeoServer to constrain the response. + +.. note:: Filters are basically a translation of a SQL "WHERE" statement into web form. Though limited to a single table, this allows users to do logical filters like "AND" and "OR" to make very complex queries, leveraging numerical and string comparisons, geometric operations ("bbox", "touches", "intersects", "disjoint"), "LIKE" statements, nulls, and more. + +Filter +------ + +There simplest filter is very easy to include. It is called the ``featureid`` filter, and it lets you filter to a single feature by its ID. The syntax is:: + + featureid= + +where is the feature and its ID. An example would be:: + + http://localhost:8080/geoserver/wms/kml?layers=topp:states&featureid=states.5 + +This request will output only the state of Maryland. The feature IDs of your data are most easily found by doing WFS or KML requests and examining the resulting output. + + +CQL Filter +---------- + +Using filters in a URL can be very unwieldy, as one needs to include URL-encoded XML:: + + http:/localhost:8080/geoserver/wms/kml?layers=topp:states&FILTER=%3CFilter%3E%3CPropertyIsBetween%3E%3CPropertyName%3Etopp:LAND_KM%3C/PropertyName%3E%3CLowerBoundary%3E%3CLiteral%3E100000%3C/Literal%3E%3C/LowerBoundary%3E%3CUpperBoundary%3E%3CLiteral%3E150000%3C/Literal%3E%3C/UpperBoundary%3E%3C/PropertyIsBetween%3E%3C/Filter%3E + +Instead, one can use Common Query Language (CQL), which allows one to specify the same statement more succinctly:: + + http://localhost:8080/geoserver/wms/kml?layers=topp:states&CQL_FILTER=LAND_KM+BETWEEN+100000+AND+150000 + +This query will return all the states in the US with areas between 100,000 and 150,000 km^2. + diff --git a/doc/en/user/source/services/wms/googleearth/features/index.rst b/doc/en/user/source/services/wms/googleearth/features/index.rst index 62a47c9499d..6934829e911 100644 --- a/doc/en/user/source/services/wms/googleearth/features/index.rst +++ b/doc/en/user/source/services/wms/googleearth/features/index.rst @@ -1,21 +1,21 @@ -.. _google-earth-features: - -Features -======== - -This section delves into greater detail about the various functionality and options possible with KML output and Google Earth. - - -.. toctree:: - :maxdepth: 2 - - kmlreflector.rst - togglingplacemarks.rst - customizingplacemarks.rst - kmlcentroids.rst - kmlheighttime.rst - kmllegends.rst - filters.rst - kmlsuperoverlays.rst - kmlregionation.rst +.. _google-earth-features: + +Features +======== + +This section delves into greater detail about the various functionality and options possible with KML output and Google Earth. + + +.. toctree:: + :maxdepth: 2 + + kmlreflector.rst + togglingplacemarks.rst + customizingplacemarks.rst + kmlcentroids.rst + kmlheighttime.rst + kmllegends.rst + filters.rst + kmlsuperoverlays.rst + kmlregionation.rst kmlscoring.rst \ No newline at end of file diff --git a/doc/en/user/source/services/wms/googleearth/features/kmlheighttime.rst b/doc/en/user/source/services/wms/googleearth/features/kmlheighttime.rst index 823ec7d211d..828f2cf5a27 100644 --- a/doc/en/user/source/services/wms/googleearth/features/kmlheighttime.rst +++ b/doc/en/user/source/services/wms/googleearth/features/kmlheighttime.rst @@ -1,42 +1,42 @@ -.. _ge_feature_kml_height_time: - -KML Height and Time -=================== - -Height ------- - -GeoServer by default creates two dimensional overlays in Google Earth. However, GeoServer can output features with -height information (also called "KML extrudes") if desired. This can have the effect of having features "float" above -the ground, or create bar graph style structures in the shape of the features. The height of features can be linked to -an attribute of the data. - -Setting the height of features is determined by using a KML Freemarker template. Create a file called ``height.ftl``, -and save it in the same directory as the featuretype in your :ref:`datadir`. For example, to create a height -template for the ``states`` layer, the file should be saved in -``/workspaces/topp/states_shapefile/states/height.ftl``. - -To set the height based on an attribute, the syntax is:: - - ${ATTRIBUTE.value} - -Replace the word ``ATTRIBUTE`` with the name of the height attribute in your data set. For a complete tutorial on -working with the height templates see :ref:`tutorials_heights`. - -Time ----- - -Google Earth also contains a "time slider", which can allow animations of data, and show changes over time. As with -height, time can be linked to an attribute of the data, as long as the data set has a date/time attribute. Linking this -date/time attribute to the time slider in Google Earth is accomplished by creating a Freemarker template. Create a file -called ``time.ftl``, and save it in the same directory that contains your data's ``info.xml``. - -To set the time based on an attribute the syntax is:: - - ${DATETIME_ATTRIBUTE.value} - -Replace the word ``DATETIME_ATTRIBUTE`` with the name of the date/time attribute. When creating KML, GeoServer will -automatically link the data to the time element in Google Earth. If set successfully, the time slider will -automatically appear. - -For a full tutorial on using GeoServer with Google Earth's time slider see :ref:`tutorials_time` +.. _ge_feature_kml_height_time: + +KML Height and Time +=================== + +Height +------ + +GeoServer by default creates two dimensional overlays in Google Earth. However, GeoServer can output features with +height information (also called "KML extrudes") if desired. This can have the effect of having features "float" above +the ground, or create bar graph style structures in the shape of the features. The height of features can be linked to +an attribute of the data. + +Setting the height of features is determined by using a KML Freemarker template. Create a file called ``height.ftl``, +and save it in the same directory as the featuretype in your :ref:`datadir`. For example, to create a height +template for the ``states`` layer, the file should be saved in +``/workspaces/topp/states_shapefile/states/height.ftl``. + +To set the height based on an attribute, the syntax is:: + + ${ATTRIBUTE.value} + +Replace the word ``ATTRIBUTE`` with the name of the height attribute in your data set. For a complete tutorial on +working with the height templates see :ref:`tutorials_heights`. + +Time +---- + +Google Earth also contains a "time slider", which can allow animations of data, and show changes over time. As with +height, time can be linked to an attribute of the data, as long as the data set has a date/time attribute. Linking this +date/time attribute to the time slider in Google Earth is accomplished by creating a Freemarker template. Create a file +called ``time.ftl``, and save it in the same directory that contains your data's ``info.xml``. + +To set the time based on an attribute the syntax is:: + + ${DATETIME_ATTRIBUTE.value} + +Replace the word ``DATETIME_ATTRIBUTE`` with the name of the date/time attribute. When creating KML, GeoServer will +automatically link the data to the time element in Google Earth. If set successfully, the time slider will +automatically appear. + +For a full tutorial on using GeoServer with Google Earth's time slider see :ref:`tutorials_time` diff --git a/doc/en/user/source/services/wms/googleearth/features/kmllegends.rst b/doc/en/user/source/services/wms/googleearth/features/kmllegends.rst index 1a846bdab26..df9ac789d9e 100644 --- a/doc/en/user/source/services/wms/googleearth/features/kmllegends.rst +++ b/doc/en/user/source/services/wms/googleearth/features/kmllegends.rst @@ -1,15 +1,15 @@ -.. _ge_feature_kml_legends: - -KML Legends -=========== - -WMS includes a ``GetLegendGraphic`` operation which allows a WMS client to obtain a legend graphic from the server for a particular layer. Combining the legend with KML overlays allows the legend to be viewed inside Google Earth. - -To get GeoServer to include a legend with the KML output, append ``legend=true`` to the KML reflector request. For example:: - - http://localhost:8080/geoserver/wms/kml?layers=topp:states&legend=true - -The resulting Google Earth output looks like this: - -.. figure:: images/legend.png +.. _ge_feature_kml_legends: + +KML Legends +=========== + +WMS includes a ``GetLegendGraphic`` operation which allows a WMS client to obtain a legend graphic from the server for a particular layer. Combining the legend with KML overlays allows the legend to be viewed inside Google Earth. + +To get GeoServer to include a legend with the KML output, append ``legend=true`` to the KML reflector request. For example:: + + http://localhost:8080/geoserver/wms/kml?layers=topp:states&legend=true + +The resulting Google Earth output looks like this: + +.. figure:: images/legend.png :align: center \ No newline at end of file diff --git a/doc/en/user/source/services/wms/googleearth/features/kmlreflector.rst b/doc/en/user/source/services/wms/googleearth/features/kmlreflector.rst index f704eb01c3c..25fc8f79083 100644 --- a/doc/en/user/source/services/wms/googleearth/features/kmlreflector.rst +++ b/doc/en/user/source/services/wms/googleearth/features/kmlreflector.rst @@ -1,108 +1,108 @@ -.. _ge_feature_kml_reflector: - -KML Reflector -============= - -Standard WMS requests can be quite long and cumbersome. The following is an example of a request for KML output from GeoServer:: - - http://localhost:8080/geoserver/ows?service=WMS&request=GetMap&version=1.1.1&format=application/vnd.google-earth.kml+XML&width=1024&height=1024&srs=EPSG:4326&layers=topp:states&styles=population&bbox=-180,-90,180,90 - -GeoServer includes an alternate way of requesting KML, and that is to use the **KML reflector**. The KML reflector is a simpler URL-encoded request that uses sensible defaults for many of the parameters in a standard WMS request. Using the KML reflector one can shorten the above request to:: - - http://localhost:8080/geoserver/wms/kml?layers=topp:states - -Using the KML reflector ------------------------ - -The only mandatory parameter is the ``layers`` parameter. The syntax is as follows:: - - http://GEOSERVER_URL/wms/kml?layers= - -where ``GEOSERVER_URL`` is the URL of your GeoServer instance, and ```` is the name of the featuretype to be served. - -The following table lists the default assumptions: - -.. list-table:: - :widths: 20 80 - - * - **Key** - - **Value** - * - ``request`` - - ``GetMap`` - * - ``service`` - - ``wms`` - * - ``version`` - - ``1.1.1`` - * - ``srs`` - - ``EPSG:4326`` - * - ``format`` - - ``application/vnd.google-earth.kml+xml`` - * - ``width`` - - ``2048`` - * - ``height`` - - ``2048`` - * - ``bbox`` - - ```` - * - ``kmattr`` - - ``true`` - * - ``kmplacemark`` - - ``false`` - * - ``kmscore`` - - ``40`` - * - ``styles`` - - [default style for the featuretype] - -Any of these defaults can be changed when specifying the request. For instance, to specify a particular style, one can append ``styles=population`` to the request:: - - http://localhost:8080/geoserver/wms/kml?layers=topp:states&styles=population - -To specify a different bounding box, append the parameter to the request:: - - http://localhost:8080/geoserver/wms/kml?layers=topp:states&bbox=-124.73,24.96,-66.97,49.37 - -Reflector modes ---------------- - -The KML reflector can operate in one of three modes: **refresh**, **superoverlay**, and **download**. - -The mode is set by appending the following parameter to the URL:: - - mode= - -where ```` is one of the three reflector modes. The details for each mode are as follows: - -.. list-table:: - :widths: 20 80 - - * - **Mode** - - **Description** - * - ``refresh`` - - (*default for all versions except 1.7.1 through 1.7.5*) Returns dynamic KML that can be refreshed/updated by the Google Earth client. Data is refreshed and new data/imagery is downloaded when zooming/panning stops. This mode can return either vector or raster (placemark or overlay) The decision to return either vector or raster data is determined by the value of ``kmscore``. Please see the section on :ref:`ge_feature_kml_scoring` for more information. - * - ``superoverlay`` - - (*default for versions 1.7.1 through 1.7.5*) Returns KML as a super-overlay. A super-overlay is a form of KML in which data is broken up into regions. Please see the section on :ref:`ge_feature_kml_super_overlays` for more information. - * - ``download`` - - Returns KML which contains the entire data set. In the case of a vector layer, this will include a series of KML placemarks. With raster layers, this will include a single KML ground overlay. This is the only mode that doesn't dynamically request new data from the server, and thus is self-contained KML. - -More about the "superoverlay" mode ----------------------------------- - -When requesting KML using the ``superoverlay`` mode, there are four additional submodes available regarding how and when data is requested. These options are set by appending the following parameter to the KML reflector request:: - - superoverlay_mode= - -where ```` is one of the following options: - -.. list-table:: - :widths: 20 80 - - * - **Submode** - - **Description** - * - ``auto`` - - (*default*) Always returns vector features if the original data is in vector form, and returns raster imagery if the original data is in raster form. This can sometimes be less than optimal if the geometry of the features are very complicated, which can slow down Google Earth. - * - ``raster`` - - Always returns raster imagery, regardless of the original data. This is almost always faster, but all vector information is lost in this view. - * - ``overview`` - - Displays either vector or raster data depending on the view. At higher zoom levels, raster imagery will be displayed, and at lower zoom levels, vector features will be displayed. The determination for when to switch between vector and raster is made by the regionation parameters set on the server. See the section on :ref:`ge_feature_kml_regionation` for more information. - * - ``hybrid`` - - Displays both raster and vector data at all times. - +.. _ge_feature_kml_reflector: + +KML Reflector +============= + +Standard WMS requests can be quite long and cumbersome. The following is an example of a request for KML output from GeoServer:: + + http://localhost:8080/geoserver/ows?service=WMS&request=GetMap&version=1.1.1&format=application/vnd.google-earth.kml+XML&width=1024&height=1024&srs=EPSG:4326&layers=topp:states&styles=population&bbox=-180,-90,180,90 + +GeoServer includes an alternate way of requesting KML, and that is to use the **KML reflector**. The KML reflector is a simpler URL-encoded request that uses sensible defaults for many of the parameters in a standard WMS request. Using the KML reflector one can shorten the above request to:: + + http://localhost:8080/geoserver/wms/kml?layers=topp:states + +Using the KML reflector +----------------------- + +The only mandatory parameter is the ``layers`` parameter. The syntax is as follows:: + + http://GEOSERVER_URL/wms/kml?layers= + +where ``GEOSERVER_URL`` is the URL of your GeoServer instance, and ```` is the name of the featuretype to be served. + +The following table lists the default assumptions: + +.. list-table:: + :widths: 20 80 + + * - **Key** + - **Value** + * - ``request`` + - ``GetMap`` + * - ``service`` + - ``wms`` + * - ``version`` + - ``1.1.1`` + * - ``srs`` + - ``EPSG:4326`` + * - ``format`` + - ``application/vnd.google-earth.kml+xml`` + * - ``width`` + - ``2048`` + * - ``height`` + - ``2048`` + * - ``bbox`` + - ```` + * - ``kmattr`` + - ``true`` + * - ``kmplacemark`` + - ``false`` + * - ``kmscore`` + - ``40`` + * - ``styles`` + - [default style for the featuretype] + +Any of these defaults can be changed when specifying the request. For instance, to specify a particular style, one can append ``styles=population`` to the request:: + + http://localhost:8080/geoserver/wms/kml?layers=topp:states&styles=population + +To specify a different bounding box, append the parameter to the request:: + + http://localhost:8080/geoserver/wms/kml?layers=topp:states&bbox=-124.73,24.96,-66.97,49.37 + +Reflector modes +--------------- + +The KML reflector can operate in one of three modes: **refresh**, **superoverlay**, and **download**. + +The mode is set by appending the following parameter to the URL:: + + mode= + +where ```` is one of the three reflector modes. The details for each mode are as follows: + +.. list-table:: + :widths: 20 80 + + * - **Mode** + - **Description** + * - ``refresh`` + - (*default for all versions except 1.7.1 through 1.7.5*) Returns dynamic KML that can be refreshed/updated by the Google Earth client. Data is refreshed and new data/imagery is downloaded when zooming/panning stops. This mode can return either vector or raster (placemark or overlay) The decision to return either vector or raster data is determined by the value of ``kmscore``. Please see the section on :ref:`ge_feature_kml_scoring` for more information. + * - ``superoverlay`` + - (*default for versions 1.7.1 through 1.7.5*) Returns KML as a super-overlay. A super-overlay is a form of KML in which data is broken up into regions. Please see the section on :ref:`ge_feature_kml_super_overlays` for more information. + * - ``download`` + - Returns KML which contains the entire data set. In the case of a vector layer, this will include a series of KML placemarks. With raster layers, this will include a single KML ground overlay. This is the only mode that doesn't dynamically request new data from the server, and thus is self-contained KML. + +More about the "superoverlay" mode +---------------------------------- + +When requesting KML using the ``superoverlay`` mode, there are four additional submodes available regarding how and when data is requested. These options are set by appending the following parameter to the KML reflector request:: + + superoverlay_mode= + +where ```` is one of the following options: + +.. list-table:: + :widths: 20 80 + + * - **Submode** + - **Description** + * - ``auto`` + - (*default*) Always returns vector features if the original data is in vector form, and returns raster imagery if the original data is in raster form. This can sometimes be less than optimal if the geometry of the features are very complicated, which can slow down Google Earth. + * - ``raster`` + - Always returns raster imagery, regardless of the original data. This is almost always faster, but all vector information is lost in this view. + * - ``overview`` + - Displays either vector or raster data depending on the view. At higher zoom levels, raster imagery will be displayed, and at lower zoom levels, vector features will be displayed. The determination for when to switch between vector and raster is made by the regionation parameters set on the server. See the section on :ref:`ge_feature_kml_regionation` for more information. + * - ``hybrid`` + - Displays both raster and vector data at all times. + diff --git a/doc/en/user/source/services/wms/googleearth/features/kmlregionation.rst b/doc/en/user/source/services/wms/googleearth/features/kmlregionation.rst index c6cd297a3cb..c872d23f16a 100644 --- a/doc/en/user/source/services/wms/googleearth/features/kmlregionation.rst +++ b/doc/en/user/source/services/wms/googleearth/features/kmlregionation.rst @@ -1,42 +1,42 @@ -.. _ge_feature_kml_regionation: - -KML Regionation -=============== - -Displaying vector features on Google Earth is a very powerful way of creating nicely-styled maps. However, it is not always optimal to display all features at all times. Displaying too many features can create an unsightly map, and can adversely affect Google Earth's performance. To combat this, GeoServer's KML output includes the ability to limit features based on certain criteria. This process is known as **regionation**. Regionation is active by default when using the superoverlay KML reflector mode. - - -Regionation Attributes ----------------------- - -The most important aspect of regionation is to decide how to determine which features show up more prominently than others. This can be done either **by geometry**, or **by attribute**. One should choose the option that best exemplifies the relative "importance" of the feature. When choosing to regionate by geometry, only the larger lines and polygons will be displayed at higher zoom levels, with smaller ones being displayed when zooming in. When regionating by an attribute, the higher value of this attribute will make those features show up at higher zoom levels. (Choosing an attribute with a non-numeric value will be ignored, and will instead default to regionation by geometry.) - - -Regionation Strategies ----------------------- - -Regionation strategies sets how to determine which features should be shown at any given time or zoom level. There are five types of regionation strategies: - -.. list-table:: - :widths: 20 80 - - * - **Strategy** - - **Description** - * - ``best_guess`` - - (*default*) The actual strategy is determined by the type of data being operated on. If the data consists of points, the ``random`` strategy is used. If the data consists of lines or polygons, the ``geometry`` strategy is used. - * - ``external-sorting`` - - Creates a temporary auxiliary database within GeoServer. It takes slightly extra time to build the index upon first request. - * - ``native-sorting`` - - Uses the default sorting algorithm of the backend where the data is hosted. It is faster than external-sorting, but will only work with PostGIS datastores. - * - ``geometry`` - - Externally sorts by length (if lines) or area (if polygons). - * - ``random`` - - Uses the existing order of the data and does not sort. - -In most cases, the **best_guess** strategy is sufficient. - - -Setting Regionation Parameters ------------------------------- - -Regionation strategies and attributes are featuretype-specific, and therefore are set in the :ref:`data_webadmin_layers` editing page of the :ref:`web_admin`. This can be navigated to by selecting 'Layers' on the left sidebar. +.. _ge_feature_kml_regionation: + +KML Regionation +=============== + +Displaying vector features on Google Earth is a very powerful way of creating nicely-styled maps. However, it is not always optimal to display all features at all times. Displaying too many features can create an unsightly map, and can adversely affect Google Earth's performance. To combat this, GeoServer's KML output includes the ability to limit features based on certain criteria. This process is known as **regionation**. Regionation is active by default when using the superoverlay KML reflector mode. + + +Regionation Attributes +---------------------- + +The most important aspect of regionation is to decide how to determine which features show up more prominently than others. This can be done either **by geometry**, or **by attribute**. One should choose the option that best exemplifies the relative "importance" of the feature. When choosing to regionate by geometry, only the larger lines and polygons will be displayed at higher zoom levels, with smaller ones being displayed when zooming in. When regionating by an attribute, the higher value of this attribute will make those features show up at higher zoom levels. (Choosing an attribute with a non-numeric value will be ignored, and will instead default to regionation by geometry.) + + +Regionation Strategies +---------------------- + +Regionation strategies sets how to determine which features should be shown at any given time or zoom level. There are five types of regionation strategies: + +.. list-table:: + :widths: 20 80 + + * - **Strategy** + - **Description** + * - ``best_guess`` + - (*default*) The actual strategy is determined by the type of data being operated on. If the data consists of points, the ``random`` strategy is used. If the data consists of lines or polygons, the ``geometry`` strategy is used. + * - ``external-sorting`` + - Creates a temporary auxiliary database within GeoServer. It takes slightly extra time to build the index upon first request. + * - ``native-sorting`` + - Uses the default sorting algorithm of the backend where the data is hosted. It is faster than external-sorting, but will only work with PostGIS datastores. + * - ``geometry`` + - Externally sorts by length (if lines) or area (if polygons). + * - ``random`` + - Uses the existing order of the data and does not sort. + +In most cases, the **best_guess** strategy is sufficient. + + +Setting Regionation Parameters +------------------------------ + +Regionation strategies and attributes are featuretype-specific, and therefore are set in the :ref:`data_webadmin_layers` editing page of the :ref:`web_admin`. This can be navigated to by selecting 'Layers' on the left sidebar. diff --git a/doc/en/user/source/services/wms/googleearth/features/kmlscoring.rst b/doc/en/user/source/services/wms/googleearth/features/kmlscoring.rst index 8fd954f2c8d..eefab2ea525 100644 --- a/doc/en/user/source/services/wms/googleearth/features/kmlscoring.rst +++ b/doc/en/user/source/services/wms/googleearth/features/kmlscoring.rst @@ -1,70 +1,70 @@ -.. _ge_feature_kml_scoring: - -KML Scoring -=========== - -.. note:: KML scoring only applies when using the super-overlay mode ``refresh``. See :ref:`ge_feature_kml_super_overlays` for more information. - -GeoServer can return KML in one of two forms. The first is as a number of placemark elements (vectors). Each placemark corresponds to a feature in the underlying dataset. This form only applies to vector datasets. - -The second form is as an overlay (image). In this form the rendering is done by the GeoServer WMS and only the resulting graphic is sent to Google Earth. This is the only form available for raster datasets, but can be applied to vector datasets as well. - -There are advantages to and disadvantages to each output mode when rendering vector data. Placemarks look nicer, but there can be performance problems with Google Earth if the data set is large. Overlays put less of a strain on Google Earth, but aren't as nice looking. - -The following shows the same dataset rendered in Placemark form on the top and Overlay form on the bottom. - -.. figure:: images/vector.png - :align: center - -.. figure:: images/raster.png - :align: center - -KML scoring is the process of determing whether to render features as rasters or as vectors. - -The kmscore attribute ---------------------- - -GeoServer makes the determination on whether to render a layer as raster or vector based on how many features are in the data set and an attribute called ``kmscore``. The ``kmscore`` attribute determines the maximum amount of vector features rendered. It is calculated by this formula:: - - maximum number of features = 10^(kmscore/15) - -The following table shows the values of this threashold for various values of the ``kmscore`` parameter: - -.. list-table:: - :widths: 20 80 - - * - **kmscore** - - **Maximum # of features** - * - 0 - - Force overlay/raster output - * - 10 - - 4 - * - 20 - - 21 - * - 30 - - 100 - * - 40 - - Approx. 450 - * - 50 - - (*default*) Approx. 2150 - * - 60 - - Approx. 10,000 - * - 70 - - Approx. 45,000 - * - 80 - - Approx. 200,000 - * - 90 - - Approx. 1,000,000 - * - 100 - - Force placemark/vector output - -The syntax for specifying ``kmscore`` is:: - - kmscore= - -where ```` is an integer between 0 and 100. For example:: - - http://localhost:8080/geoserver/wms/kml?layers=topp:states&mode=refresh&kmscore=20 - -The ``kmscore`` attribute will be ignored if using a reflector mode other than ``refresh``. - +.. _ge_feature_kml_scoring: + +KML Scoring +=========== + +.. note:: KML scoring only applies when using the super-overlay mode ``refresh``. See :ref:`ge_feature_kml_super_overlays` for more information. + +GeoServer can return KML in one of two forms. The first is as a number of placemark elements (vectors). Each placemark corresponds to a feature in the underlying dataset. This form only applies to vector datasets. + +The second form is as an overlay (image). In this form the rendering is done by the GeoServer WMS and only the resulting graphic is sent to Google Earth. This is the only form available for raster datasets, but can be applied to vector datasets as well. + +There are advantages to and disadvantages to each output mode when rendering vector data. Placemarks look nicer, but there can be performance problems with Google Earth if the data set is large. Overlays put less of a strain on Google Earth, but aren't as nice looking. + +The following shows the same dataset rendered in Placemark form on the top and Overlay form on the bottom. + +.. figure:: images/vector.png + :align: center + +.. figure:: images/raster.png + :align: center + +KML scoring is the process of determing whether to render features as rasters or as vectors. + +The kmscore attribute +--------------------- + +GeoServer makes the determination on whether to render a layer as raster or vector based on how many features are in the data set and an attribute called ``kmscore``. The ``kmscore`` attribute determines the maximum amount of vector features rendered. It is calculated by this formula:: + + maximum number of features = 10^(kmscore/15) + +The following table shows the values of this threashold for various values of the ``kmscore`` parameter: + +.. list-table:: + :widths: 20 80 + + * - **kmscore** + - **Maximum # of features** + * - 0 + - Force overlay/raster output + * - 10 + - 4 + * - 20 + - 21 + * - 30 + - 100 + * - 40 + - Approx. 450 + * - 50 + - (*default*) Approx. 2150 + * - 60 + - Approx. 10,000 + * - 70 + - Approx. 45,000 + * - 80 + - Approx. 200,000 + * - 90 + - Approx. 1,000,000 + * - 100 + - Force placemark/vector output + +The syntax for specifying ``kmscore`` is:: + + kmscore= + +where ```` is an integer between 0 and 100. For example:: + + http://localhost:8080/geoserver/wms/kml?layers=topp:states&mode=refresh&kmscore=20 + +The ``kmscore`` attribute will be ignored if using a reflector mode other than ``refresh``. + diff --git a/doc/en/user/source/services/wms/googleearth/features/kmlsuperoverlays.rst b/doc/en/user/source/services/wms/googleearth/features/kmlsuperoverlays.rst index e7fe20329bf..c5491662de4 100644 --- a/doc/en/user/source/services/wms/googleearth/features/kmlsuperoverlays.rst +++ b/doc/en/user/source/services/wms/googleearth/features/kmlsuperoverlays.rst @@ -1,58 +1,58 @@ -.. _ge_feature_kml_super_overlays: - -KML Super-Overlays -================== - -Super-overlays are a form of KML in which data is broken up into regions. This allows Google Earth to refresh/request only particular regions of the map when the view area changes. Super-overlays are used to efficiently publish large sets of data. (Please see `Google's page on super-overlays `_ for more information.) - -GeoServer supports two types of super-overlays: **raster** and **vector**. With raster super-overlays, GeoServer intelligently produces imagery appropriate to the current zoom level and dynamically outputs new imagery when the zoom level changes. With vector super-overlays, feature data is requested for only the visible features and new features are dynamically loaded as necessary. Raster super-overlays require less resources on the client, but vector super-overlays have a higher output quality. - -When using the :ref:`ge_feature_kml_reflector`, super-overlays are enabled by default, whether the data in question is raster or vector. For more information on the various options for KML super-overlay output, please see the page on the :ref:`ge_feature_kml_reflector`. - -Raster Super-Overlays ---------------------- - -Consider this image, which is generated from GeoServer. When zoomed out, the data is at a small size. - -.. figure:: images/tile0small.png - :align: center - -When zooming in, the image grows larger, but since the image is at low resolution (orignially designed to be viewed small), the quality degrades. - -.. figure:: images/tile0.png - :align: center - -However, in a super-overlay, the KML document requests a new image from GeoServer of a higher resolution for that zoom level. As the new image is downloaded, the old image is replaced by the new image. - -.. figure:: images/tile4.png - :align: center - -Raster Super-Overlays and GeoWebCache -------------------------------------- - -GeoServer implements super-overlays in a way that is compatible with the WMS Tiling Client Recommendation. Super-overlays are generated such that the tiles of the super-overlay are the same tiles that a WMS tiling client would request. One can therefore use existing tile caching mechanisms and reap a potentially large performance benefit. - -The easiest way to tile cache a raster super overlay is to use GeoWebCache which is built into GeoServer:: - - http://GEOSERVER_URL/gwc/service/kml/..kmz - -where ``GEOSERVER_URL`` is the URL of your GeoServer instance. - -Vector Super-Overlays ---------------------- - -GeoServer can include the feature information directly in the KML document. This has lots of benefits. It allows the user to select (click on) features to see descriptions, toggle the display of individual features, as well as have better rendering, regardless of zoom level. For large datasets, however, the feature information can take a long time to download and use a lot of client-side resources. Vector super-overlays allow the client to only download part of a dataset, and request more features as necessary. - -Vector super-overlays can use the process of :ref:`ge_feature_kml_regionation` to organize features into a hierarchy. The regionation process can operate in a variety of modes. Most of the modes require a "regionation attribute" which is used to determine which features should be visible at a particular zoom level. Please see the :ref:`ge_feature_kml_regionation` page for more details. - -Vector Super-Overlays and GeoWebCache -------------------------------------- - -As with raster super-overlays, it is possible to cache vector super-overlays using GeoWebCache. Below is the syntax for generating a vector super-overlay KML document via GeoWebCache:: - - http://GEOSERVER_URL/gwc/service/kml/.kml.kmz - -where ``GEOSERVER_URL`` is the URL of your GeoServer instance. - -Unlike generating a super-overlay with the standard :ref:`ge_feature_kml_reflector`, it is not possible to specify the regionation properties as part of the URL. These parameters must be set in the :ref:`data_webadmin_layers` configuration which can be navigated to by clicking on 'Layers' in the left hand sidebar and then selecting your vector layer. - +.. _ge_feature_kml_super_overlays: + +KML Super-Overlays +================== + +Super-overlays are a form of KML in which data is broken up into regions. This allows Google Earth to refresh/request only particular regions of the map when the view area changes. Super-overlays are used to efficiently publish large sets of data. (Please see `Google's page on super-overlays `_ for more information.) + +GeoServer supports two types of super-overlays: **raster** and **vector**. With raster super-overlays, GeoServer intelligently produces imagery appropriate to the current zoom level and dynamically outputs new imagery when the zoom level changes. With vector super-overlays, feature data is requested for only the visible features and new features are dynamically loaded as necessary. Raster super-overlays require less resources on the client, but vector super-overlays have a higher output quality. + +When using the :ref:`ge_feature_kml_reflector`, super-overlays are enabled by default, whether the data in question is raster or vector. For more information on the various options for KML super-overlay output, please see the page on the :ref:`ge_feature_kml_reflector`. + +Raster Super-Overlays +--------------------- + +Consider this image, which is generated from GeoServer. When zoomed out, the data is at a small size. + +.. figure:: images/tile0small.png + :align: center + +When zooming in, the image grows larger, but since the image is at low resolution (orignially designed to be viewed small), the quality degrades. + +.. figure:: images/tile0.png + :align: center + +However, in a super-overlay, the KML document requests a new image from GeoServer of a higher resolution for that zoom level. As the new image is downloaded, the old image is replaced by the new image. + +.. figure:: images/tile4.png + :align: center + +Raster Super-Overlays and GeoWebCache +------------------------------------- + +GeoServer implements super-overlays in a way that is compatible with the WMS Tiling Client Recommendation. Super-overlays are generated such that the tiles of the super-overlay are the same tiles that a WMS tiling client would request. One can therefore use existing tile caching mechanisms and reap a potentially large performance benefit. + +The easiest way to tile cache a raster super overlay is to use GeoWebCache which is built into GeoServer:: + + http://GEOSERVER_URL/gwc/service/kml/..kmz + +where ``GEOSERVER_URL`` is the URL of your GeoServer instance. + +Vector Super-Overlays +--------------------- + +GeoServer can include the feature information directly in the KML document. This has lots of benefits. It allows the user to select (click on) features to see descriptions, toggle the display of individual features, as well as have better rendering, regardless of zoom level. For large datasets, however, the feature information can take a long time to download and use a lot of client-side resources. Vector super-overlays allow the client to only download part of a dataset, and request more features as necessary. + +Vector super-overlays can use the process of :ref:`ge_feature_kml_regionation` to organize features into a hierarchy. The regionation process can operate in a variety of modes. Most of the modes require a "regionation attribute" which is used to determine which features should be visible at a particular zoom level. Please see the :ref:`ge_feature_kml_regionation` page for more details. + +Vector Super-Overlays and GeoWebCache +------------------------------------- + +As with raster super-overlays, it is possible to cache vector super-overlays using GeoWebCache. Below is the syntax for generating a vector super-overlay KML document via GeoWebCache:: + + http://GEOSERVER_URL/gwc/service/kml/.kml.kmz + +where ``GEOSERVER_URL`` is the URL of your GeoServer instance. + +Unlike generating a super-overlay with the standard :ref:`ge_feature_kml_reflector`, it is not possible to specify the regionation properties as part of the URL. These parameters must be set in the :ref:`data_webadmin_layers` configuration which can be navigated to by clicking on 'Layers' in the left hand sidebar and then selecting your vector layer. + diff --git a/doc/en/user/source/services/wms/googleearth/features/togglingplacemarks.rst b/doc/en/user/source/services/wms/googleearth/features/togglingplacemarks.rst index 364e091f874..9627e57aabf 100644 --- a/doc/en/user/source/services/wms/googleearth/features/togglingplacemarks.rst +++ b/doc/en/user/source/services/wms/googleearth/features/togglingplacemarks.rst @@ -1,30 +1,30 @@ -.. _ge_feature_toggling_placemarks: - -Toggling Placemarks -=================== - -Vector Placemarks ------------------ - -When GeoServer generates KML for a vector dataset, it attaches information from the data to each feature that is created. When clicking on a vector feature, a pop-up window is displayed. This is called a **placemark**. By default this is a simple list which displays attribute data, although this information can be customized using Freemarker templates. - -If you would like this information not to be shown when a feature is clicked (either for security reasons, or simply to have a cleaner user interface), it is possible to disable this functionality. To do so, use the ``kmattr`` parameter in a KML request to turn off attribution. - -The syntax for ``kmattr`` is as follows:: - - format_options=kmattr:[true|false] - -Note that ``kmattr`` is a "format option", so the syntax is slightly different from the usual key-value pair. For example:: - - http://localhost:8080/geoserver/wms/kml?layers=topp:states&format_options=kmattr:false - -Raster Placemarks ------------------ - -Unlike vector features, where the placemark is enabled by default, placemarks are disabled by default with raster images of features. To enable this feature, you can use the ``kmplacemark`` format option in your KML request. The syntax is similar to the ``kmattr`` format option specified above:: - - format_options=kmplacemark:[true|false] - -For example, using the KML reflector, the syntax would be:: - +.. _ge_feature_toggling_placemarks: + +Toggling Placemarks +=================== + +Vector Placemarks +----------------- + +When GeoServer generates KML for a vector dataset, it attaches information from the data to each feature that is created. When clicking on a vector feature, a pop-up window is displayed. This is called a **placemark**. By default this is a simple list which displays attribute data, although this information can be customized using Freemarker templates. + +If you would like this information not to be shown when a feature is clicked (either for security reasons, or simply to have a cleaner user interface), it is possible to disable this functionality. To do so, use the ``kmattr`` parameter in a KML request to turn off attribution. + +The syntax for ``kmattr`` is as follows:: + + format_options=kmattr:[true|false] + +Note that ``kmattr`` is a "format option", so the syntax is slightly different from the usual key-value pair. For example:: + + http://localhost:8080/geoserver/wms/kml?layers=topp:states&format_options=kmattr:false + +Raster Placemarks +----------------- + +Unlike vector features, where the placemark is enabled by default, placemarks are disabled by default with raster images of features. To enable this feature, you can use the ``kmplacemark`` format option in your KML request. The syntax is similar to the ``kmattr`` format option specified above:: + + format_options=kmplacemark:[true|false] + +For example, using the KML reflector, the syntax would be:: + http://localhost:8080/geoserver/wms/kml?layers=topp:states&format_options=kmplacemark:true \ No newline at end of file diff --git a/doc/en/user/source/services/wms/googleearth/kmlstyling.rst b/doc/en/user/source/services/wms/googleearth/kmlstyling.rst index 5f5ff9d9ba7..397505ee710 100644 --- a/doc/en/user/source/services/wms/googleearth/kmlstyling.rst +++ b/doc/en/user/source/services/wms/googleearth/kmlstyling.rst @@ -1,485 +1,485 @@ -.. _google-earth-kml-styling: - -KML Styling -=========== - -Introduction ------------- - -Keyhole Markup Langauge (KML), when created and output by GeoServer, is styled using `Styled Layer Descriptors `_ (SLD). This is the same approach used to style standard WMS output formats, but is a bit different from how Google Earth is normally styled, behaving more like Cascading Style Sheets (CSS). The style of the map is specified in the SLD file as a series of rules, and then the data matching those rules is styled appropriately in the KML output. For those unfamiliar with SLD, a good place to start is the :ref:`sld_intro`. The remainder of this guide contains information about how to construct SLD documents in order to impact the look of KML produced by GeoServer. - -Contents -```````` - - :ref:`kml-styling-basic` - - :ref:`kml-styling-sld-hand` - - :ref:`kml-styling-sld-structure` - - :ref:`kml-styling-points` - - :ref:`kml-styling-lines` - - :ref:`kml-styling-polygons` - - :ref:`kml-styling-text-labels` - - :ref:`kml-styling-descriptions` - - -.. _kml-styling-basic: - -SLD Generation from CSS ------------------------ - -The CSS extension provides the facility to generate SLD files using a lightweight "Cascading Style Sheet" syntax. The CSS GUI provides a live map preview as you are editing your style in addition to an attribute reference for the current layer. - -The generated styles will work seamlessly with KML output from GeoServer. - - -.. _kml-styling-sld-hand: - -Creating SLD by hand --------------------- - -One can edit the SLD files directly instead of using the CSS extension. For the most complete exploration of editing SLDs see the :ref:`styling` section. The examples below show how some of the basic styles show up in Google Earth. - - -.. _kml-styling-sld-structure: - -SLD Structure -------------- - - - -The following is a skeleton of a SLD document. It can be used as a base on which to expand upon to create more interesting and complicated styles. - -.. code-block:: xml - - - - Default Line - - My Style - A style - - - - - - - - - - - -*Figure 3: Basic SLD structure* - -In order to test the code snippets in this document, create an SLD with the content as shown in Figure 3, and then add the specific code you wish to test in the space that says ````. To view, edit, or add SLD files to GeoServer, navigate to **Config** -> **Data** -> **Styles**. - -.. _kml-styling-points: - -Points ------- - -In SLD, styles for points are specified via a PointSymbolizer. An empty PointSymbolizer element will result in a default KML style: - -.. code-block:: xml - - - - -.. figure:: pointDefault.png - :align: center - - *Figure 4: Default point* - -Three aspects of points that can be specified are *color*, *opacity*, and the *icon*. - -Point Color -``````````` - -The color of a point is specified with a ``CssParameter`` element and a ``fill`` attribute. The color is specified as a six digit hexadecimal code. - -.. code-block:: xml - - - - - - #ff0000 - - - - - -.. figure:: pointColor.png - :align: center - - *Figure 5: Setting the point color (#ff0000 = 100% red)* - -Point Opacity -````````````` - -The opacity of a point is specified with a CssParameter element and a ``fill-opacity`` attribute. The opacity is specified as a floating point number between **0** and **1**, with 0 being completely transparent, and 1 being completely opaque. - -.. code-block:: xml - - - - - - 0.5 - - - - - -.. figure:: pointOpacity.png - :align: center - - *Figure 6: Setting the point opacity (0.5 = 50% opaque)* - -Point Icon -`````````` - -An icon different from the default can be specified with the ``ExternalGraphic`` element: - -.. code-block:: xml - - - - - - image/png - - - - -.. figure:: pointCustomIcon.png - :align: center - - *Figure 7: A custom icon for points* - -In Figure 7, the custom icon is specified as a remote URL. It is also possible to place the graphic in the GeoServer ``styles`` directory, and then specify the filename only: - -.. code-block:: xml - - - - - - image/png - - - - -*Figure 8: Specifying a local file for a graphic point* - -.. _kml-styling-lines: - -Lines ------ - -Styles for lines are specified via a ``LineSymbolizer``. An empty ``LineSymbolizer`` element will result in a default KML style: - -.. code-block:: xml - - - - -.. figure:: lineDefault.png - :align: center - - *Figure 9: Default line* - -The aspects of the resulting line which can be specified via a ``LineSymbolizer`` are *color*, *width*, and *opacity*. - -Line Color -`````````` - -The color of a line is specified with a ``CssParameter`` element and a ``stroke`` attribute. The color is specified as a six digit hexadecimal code. - -.. code-block:: xml - - - - #ff0000 - - - -.. figure:: lineColor.png - :align: center - - *Figure 10: Line rendered with color #ff0000 (100% red)* - -Line Width -`````````` - -The width of a line is specified with a ``CssParameter`` element and a ``stroke-width`` attribute. The width is specified as an integer (in pixels): - -.. code-block:: xml - - - - 5 - - - -.. figure:: lineWidth.png - :align: center - - *Figure 11: Line rendered with a width of five (5) pixels* - -Line Opacity -```````````` - -The opacity of a line is specified with a ``CssParameter`` element and a ``fill-opacity`` attribute. The opacity is specified as a floating point number between **0** and **1**, with 0 being completely transparent, and 1 being completely opaque. - -.. code-block:: xml - - - - 0.5 - - - -.. figure:: lineOpacity.png - :align: center - - *Figure 12: A line rendered with 50% opacity* - -.. _kml-styling-polygons: - -Polygons --------- - -Styles for polygons are specified via a ``PolygonSymbolizer``. An empty ``PolygonSymbolizer`` element will result in a default KML style: - -.. code-block:: xml - - - - -Polygons have more options for styling than points and lines, as polygons have both an inside ("fill") and an outline ("stroke"). The aspects of polygons that can be specified via a ``PolygonSymbolizer`` are *stroke color*, *stroke width*, *stroke opacity*, *fill color*, and *fill opacity*. - -Polygon Stroke Color -```````````````````` - -The outline color of a polygon is specified with a ``CssParameter`` element and ``stroke`` attribute inside of a ``Stroke`` element. The color is specified as a 6 digit hexadecimal code: - -.. code-block:: xml - - - - #0000FF - - - -.. figure:: polygonOutlineColor.png - :align: center - - *Figure 13: Outline of a polygon (#0000FF or 100% blue)* - -Polygon Stroke Width -```````````````````` - -The outline width of a polygon is specified with a ``CssParameter`` element and ``stroke-width`` attribute inside of a ``Stroke`` element. The width is specified as an integer. - -.. code-block:: xml - - - - 5 - - - -.. figure:: polygonOutlineWidth.png - :align: center - -*Figure 14: Polygon with stroke width of five (5) pixels* - -Polygon Stroke Opacity -`````````````````````` - -The stroke opacity of a polygon is specified with a ``CssParameter`` element and ``stroke`` attribute inside of a ``Stroke`` element. The opacity is specified as a floating point number between **0** and **1**, with 0 being completely transparent, and 1 being completely opaque. - -.. code-block:: xml - - - - 0.5 - - - -.. figure:: polygonOutlineOpacity.png - :align: center - - *Figure 15: Polygon stroke opacity of 0.5 (50% opaque)* - -Polygon Fill Color -`````````````````` - -The fill color of a polygon is specified with a ``CssParameter`` element and ``fill`` attribute inside of a ``Fill`` element. The color is specified as a six digit hexadecimal code: - -.. code-block:: xml - - - - #0000FF - - - -.. figure:: polygonFillColor.png - :align: center - - *Figure 16: Polygon fill color of #0000FF (100% blue)* - -Polygon Fill Opacity -```````````````````` - -The fill opacity of a polygon is specified with a ``CssParameter`` element and ``fill-opacity`` attribute inside of a ``Fill`` element. The opacity is specified as a floating point number between **0** and **1**, with 0 being completely transparent, and 1 being completely opaque. - -.. code-block:: xml - - - - 0.5 - - - -.. figure:: polygonFillOpacity.png - :align: center - - *Figure 17: Polygon fill opacity of 0.5 (50% opaque)* - -.. _kml-styling-text-labels: - -Text Labels ------------ - -There are two ways to specify a label for a feature in Google Earth. The first is with Freemarker templates (LINK?), and the second is with a ``TextSymbolizer``. Templates take precedence over symbolizers. - -Freemarker Templates -```````````````````` - -Specifying labels via a Freemarker template involves creating a special text file called ``title.ftl`` and placing it into the ``workspaces///`` directory (inside the GeoServer data directory) for the dataset to be labeled. For example, to create a template to label the ``states`` dataset by state name one would create the file here: ``/workspaces/topp/states_shapefile/states/title.ftl``. The content of the file would be: - -.. code-block:: none - - ${STATE_NAME.value} - -.. figure:: labelTemplate.png - :align: center - - *Figure 18: Using a Freemarker template to display the value of STATE_NAME* - -For more information on Placemark Templates, please see our full tutorial (LINK FORTHCOMING). - -TextSymbolizer -`````````````` - -In SLD labels are specified with the Label element of a ``TextSymbolizer``. (Note the ``ogc:`` prefix on the ``PropertyName`` element.) - -.. code-block:: xml - - - - - -.. figure:: labelSymbolizer.png - :align: center - - *Figure 19: Using a TextSymbolizer to display the value of STATE_NAME* - -The aspects of the resulting label which can be specified via a ``TextSymbolizer`` are *color* and *opacity*. - -TextSymbolizer Color -```````````````````` - -The color of a label is specified with a ``CssParameter`` element and ``fill`` attribute inside of a ``Fill`` element. The color is specified as a six digit hexadecimal code: - -.. code-block:: xml - - - - - #000000 - - - -.. figure:: labelColor.png - :align: center - - *Figure 20: TextSymbolizer with black text color (#000000)* - -TextSymbolizer Opacity -`````````````````````` - -The opacity of a label is specified with a ``CssParameter`` element and ``fill-opacity`` attribute inside of a ``Fill`` element. The opacity is specified as a floating point number between **0** and **1**, with 0 being completely transparent, and 1 being completely opaque. - -.. code-block:: xml - - - - - 0.5 - - - -.. figure:: labelOpacity.png - :align: center - - *Figure 21: TextSymbolizer with opacity 0.5 (50% opaque)* - -.. _kml-styling-descriptions: - -Descriptions ------------- - -When working with KML, each feature is linked to a description, accessible when the feature is clicked on. By default, GeoServer creates a list of all the attributes and values for the particular feature. - -.. figure:: descriptionDefault.png - :align: center - - *Figure 22: Default description for a feature* - -It is possible to modify this default behavior. Much like with featureType titles, which are edited by creating a ``title.ftl`` template, a custom description can be used by creating template called ``description.ftl`` and placing it into the feature type directory (inside the GeoServer data directory) for the dataset. For instance, to create a template to provide a description for the states dataset, one would create the file: ``/workspaces/topp/states_shapefile/states/description.ftl``. As an example, if the content of the description template is: - -.. code-block:: none - - This is the state of ${STATE_NAME.value}. - -The resultant description will look like this: - -.. figure:: descriptionTemplate.png - :align: center - - *Figure 23: A custom description* - -It is also possible to create one description template for all featureTypes in a given namespace. To do this, create a ``description.ftl`` file as above, and save it as ``/templates//description.ftl``. Please note that if a description template is created for a specific featureType that also has an associated namespace description template, the featureType template (i.e. the most specific template) will take priority. - -One can also create more complex descriptions using a combination of HTML and the attributes of the data. A full tutorial on how to use templates to create descriptions is available in our page on KML Placemark Templates. (LINK?) - - - -:ref:`kml-styling-basic` -:ref:`kml-styling-sld-structure` -:ref:`kml-styling-points` -:ref:`kml-styling-lines` -:ref:`kml-styling-polygons` -:ref:`kml-styling-text-labels` -:ref:`kml-styling-descriptions` +.. _google-earth-kml-styling: + +KML Styling +=========== + +Introduction +------------ + +Keyhole Markup Langauge (KML), when created and output by GeoServer, is styled using `Styled Layer Descriptors `_ (SLD). This is the same approach used to style standard WMS output formats, but is a bit different from how Google Earth is normally styled, behaving more like Cascading Style Sheets (CSS). The style of the map is specified in the SLD file as a series of rules, and then the data matching those rules is styled appropriately in the KML output. For those unfamiliar with SLD, a good place to start is the :ref:`sld_intro`. The remainder of this guide contains information about how to construct SLD documents in order to impact the look of KML produced by GeoServer. + +Contents +```````` + + :ref:`kml-styling-basic` + + :ref:`kml-styling-sld-hand` + + :ref:`kml-styling-sld-structure` + + :ref:`kml-styling-points` + + :ref:`kml-styling-lines` + + :ref:`kml-styling-polygons` + + :ref:`kml-styling-text-labels` + + :ref:`kml-styling-descriptions` + + +.. _kml-styling-basic: + +SLD Generation from CSS +----------------------- + +The CSS extension provides the facility to generate SLD files using a lightweight "Cascading Style Sheet" syntax. The CSS GUI provides a live map preview as you are editing your style in addition to an attribute reference for the current layer. + +The generated styles will work seamlessly with KML output from GeoServer. + + +.. _kml-styling-sld-hand: + +Creating SLD by hand +-------------------- + +One can edit the SLD files directly instead of using the CSS extension. For the most complete exploration of editing SLDs see the :ref:`styling` section. The examples below show how some of the basic styles show up in Google Earth. + + +.. _kml-styling-sld-structure: + +SLD Structure +------------- + + + +The following is a skeleton of a SLD document. It can be used as a base on which to expand upon to create more interesting and complicated styles. + +.. code-block:: xml + + + + Default Line + + My Style + A style + + + + + + + + + + + +*Figure 3: Basic SLD structure* + +In order to test the code snippets in this document, create an SLD with the content as shown in Figure 3, and then add the specific code you wish to test in the space that says ````. To view, edit, or add SLD files to GeoServer, navigate to **Config** -> **Data** -> **Styles**. + +.. _kml-styling-points: + +Points +------ + +In SLD, styles for points are specified via a PointSymbolizer. An empty PointSymbolizer element will result in a default KML style: + +.. code-block:: xml + + + + +.. figure:: pointDefault.png + :align: center + + *Figure 4: Default point* + +Three aspects of points that can be specified are *color*, *opacity*, and the *icon*. + +Point Color +``````````` + +The color of a point is specified with a ``CssParameter`` element and a ``fill`` attribute. The color is specified as a six digit hexadecimal code. + +.. code-block:: xml + + + + + + #ff0000 + + + + + +.. figure:: pointColor.png + :align: center + + *Figure 5: Setting the point color (#ff0000 = 100% red)* + +Point Opacity +````````````` + +The opacity of a point is specified with a CssParameter element and a ``fill-opacity`` attribute. The opacity is specified as a floating point number between **0** and **1**, with 0 being completely transparent, and 1 being completely opaque. + +.. code-block:: xml + + + + + + 0.5 + + + + + +.. figure:: pointOpacity.png + :align: center + + *Figure 6: Setting the point opacity (0.5 = 50% opaque)* + +Point Icon +`````````` + +An icon different from the default can be specified with the ``ExternalGraphic`` element: + +.. code-block:: xml + + + + + + image/png + + + + +.. figure:: pointCustomIcon.png + :align: center + + *Figure 7: A custom icon for points* + +In Figure 7, the custom icon is specified as a remote URL. It is also possible to place the graphic in the GeoServer ``styles`` directory, and then specify the filename only: + +.. code-block:: xml + + + + + + image/png + + + + +*Figure 8: Specifying a local file for a graphic point* + +.. _kml-styling-lines: + +Lines +----- + +Styles for lines are specified via a ``LineSymbolizer``. An empty ``LineSymbolizer`` element will result in a default KML style: + +.. code-block:: xml + + + + +.. figure:: lineDefault.png + :align: center + + *Figure 9: Default line* + +The aspects of the resulting line which can be specified via a ``LineSymbolizer`` are *color*, *width*, and *opacity*. + +Line Color +`````````` + +The color of a line is specified with a ``CssParameter`` element and a ``stroke`` attribute. The color is specified as a six digit hexadecimal code. + +.. code-block:: xml + + + + #ff0000 + + + +.. figure:: lineColor.png + :align: center + + *Figure 10: Line rendered with color #ff0000 (100% red)* + +Line Width +`````````` + +The width of a line is specified with a ``CssParameter`` element and a ``stroke-width`` attribute. The width is specified as an integer (in pixels): + +.. code-block:: xml + + + + 5 + + + +.. figure:: lineWidth.png + :align: center + + *Figure 11: Line rendered with a width of five (5) pixels* + +Line Opacity +```````````` + +The opacity of a line is specified with a ``CssParameter`` element and a ``fill-opacity`` attribute. The opacity is specified as a floating point number between **0** and **1**, with 0 being completely transparent, and 1 being completely opaque. + +.. code-block:: xml + + + + 0.5 + + + +.. figure:: lineOpacity.png + :align: center + + *Figure 12: A line rendered with 50% opacity* + +.. _kml-styling-polygons: + +Polygons +-------- + +Styles for polygons are specified via a ``PolygonSymbolizer``. An empty ``PolygonSymbolizer`` element will result in a default KML style: + +.. code-block:: xml + + + + +Polygons have more options for styling than points and lines, as polygons have both an inside ("fill") and an outline ("stroke"). The aspects of polygons that can be specified via a ``PolygonSymbolizer`` are *stroke color*, *stroke width*, *stroke opacity*, *fill color*, and *fill opacity*. + +Polygon Stroke Color +```````````````````` + +The outline color of a polygon is specified with a ``CssParameter`` element and ``stroke`` attribute inside of a ``Stroke`` element. The color is specified as a 6 digit hexadecimal code: + +.. code-block:: xml + + + + #0000FF + + + +.. figure:: polygonOutlineColor.png + :align: center + + *Figure 13: Outline of a polygon (#0000FF or 100% blue)* + +Polygon Stroke Width +```````````````````` + +The outline width of a polygon is specified with a ``CssParameter`` element and ``stroke-width`` attribute inside of a ``Stroke`` element. The width is specified as an integer. + +.. code-block:: xml + + + + 5 + + + +.. figure:: polygonOutlineWidth.png + :align: center + +*Figure 14: Polygon with stroke width of five (5) pixels* + +Polygon Stroke Opacity +`````````````````````` + +The stroke opacity of a polygon is specified with a ``CssParameter`` element and ``stroke`` attribute inside of a ``Stroke`` element. The opacity is specified as a floating point number between **0** and **1**, with 0 being completely transparent, and 1 being completely opaque. + +.. code-block:: xml + + + + 0.5 + + + +.. figure:: polygonOutlineOpacity.png + :align: center + + *Figure 15: Polygon stroke opacity of 0.5 (50% opaque)* + +Polygon Fill Color +`````````````````` + +The fill color of a polygon is specified with a ``CssParameter`` element and ``fill`` attribute inside of a ``Fill`` element. The color is specified as a six digit hexadecimal code: + +.. code-block:: xml + + + + #0000FF + + + +.. figure:: polygonFillColor.png + :align: center + + *Figure 16: Polygon fill color of #0000FF (100% blue)* + +Polygon Fill Opacity +```````````````````` + +The fill opacity of a polygon is specified with a ``CssParameter`` element and ``fill-opacity`` attribute inside of a ``Fill`` element. The opacity is specified as a floating point number between **0** and **1**, with 0 being completely transparent, and 1 being completely opaque. + +.. code-block:: xml + + + + 0.5 + + + +.. figure:: polygonFillOpacity.png + :align: center + + *Figure 17: Polygon fill opacity of 0.5 (50% opaque)* + +.. _kml-styling-text-labels: + +Text Labels +----------- + +There are two ways to specify a label for a feature in Google Earth. The first is with Freemarker templates (LINK?), and the second is with a ``TextSymbolizer``. Templates take precedence over symbolizers. + +Freemarker Templates +```````````````````` + +Specifying labels via a Freemarker template involves creating a special text file called ``title.ftl`` and placing it into the ``workspaces///`` directory (inside the GeoServer data directory) for the dataset to be labeled. For example, to create a template to label the ``states`` dataset by state name one would create the file here: ``/workspaces/topp/states_shapefile/states/title.ftl``. The content of the file would be: + +.. code-block:: none + + ${STATE_NAME.value} + +.. figure:: labelTemplate.png + :align: center + + *Figure 18: Using a Freemarker template to display the value of STATE_NAME* + +For more information on Placemark Templates, please see our full tutorial (LINK FORTHCOMING). + +TextSymbolizer +`````````````` + +In SLD labels are specified with the Label element of a ``TextSymbolizer``. (Note the ``ogc:`` prefix on the ``PropertyName`` element.) + +.. code-block:: xml + + + + + +.. figure:: labelSymbolizer.png + :align: center + + *Figure 19: Using a TextSymbolizer to display the value of STATE_NAME* + +The aspects of the resulting label which can be specified via a ``TextSymbolizer`` are *color* and *opacity*. + +TextSymbolizer Color +```````````````````` + +The color of a label is specified with a ``CssParameter`` element and ``fill`` attribute inside of a ``Fill`` element. The color is specified as a six digit hexadecimal code: + +.. code-block:: xml + + + + + #000000 + + + +.. figure:: labelColor.png + :align: center + + *Figure 20: TextSymbolizer with black text color (#000000)* + +TextSymbolizer Opacity +`````````````````````` + +The opacity of a label is specified with a ``CssParameter`` element and ``fill-opacity`` attribute inside of a ``Fill`` element. The opacity is specified as a floating point number between **0** and **1**, with 0 being completely transparent, and 1 being completely opaque. + +.. code-block:: xml + + + + + 0.5 + + + +.. figure:: labelOpacity.png + :align: center + + *Figure 21: TextSymbolizer with opacity 0.5 (50% opaque)* + +.. _kml-styling-descriptions: + +Descriptions +------------ + +When working with KML, each feature is linked to a description, accessible when the feature is clicked on. By default, GeoServer creates a list of all the attributes and values for the particular feature. + +.. figure:: descriptionDefault.png + :align: center + + *Figure 22: Default description for a feature* + +It is possible to modify this default behavior. Much like with featureType titles, which are edited by creating a ``title.ftl`` template, a custom description can be used by creating template called ``description.ftl`` and placing it into the feature type directory (inside the GeoServer data directory) for the dataset. For instance, to create a template to provide a description for the states dataset, one would create the file: ``/workspaces/topp/states_shapefile/states/description.ftl``. As an example, if the content of the description template is: + +.. code-block:: none + + This is the state of ${STATE_NAME.value}. + +The resultant description will look like this: + +.. figure:: descriptionTemplate.png + :align: center + + *Figure 23: A custom description* + +It is also possible to create one description template for all featureTypes in a given namespace. To do this, create a ``description.ftl`` file as above, and save it as ``/templates//description.ftl``. Please note that if a description template is created for a specific featureType that also has an associated namespace description template, the featureType template (i.e. the most specific template) will take priority. + +One can also create more complex descriptions using a combination of HTML and the attributes of the data. A full tutorial on how to use templates to create descriptions is available in our page on KML Placemark Templates. (LINK?) + + + +:ref:`kml-styling-basic` +:ref:`kml-styling-sld-structure` +:ref:`kml-styling-points` +:ref:`kml-styling-lines` +:ref:`kml-styling-polygons` +:ref:`kml-styling-text-labels` +:ref:`kml-styling-descriptions` diff --git a/doc/en/user/source/services/wms/googleearth/quickstart.rst b/doc/en/user/source/services/wms/googleearth/quickstart.rst index a73a7f626d9..ccbb4437ea9 100644 --- a/doc/en/user/source/services/wms/googleearth/quickstart.rst +++ b/doc/en/user/source/services/wms/googleearth/quickstart.rst @@ -1,59 +1,59 @@ -.. _google_earth_quickstart: - -Quickstart -========== - -.. note:: If you are using GeoServer locally, the GEOSERVER_URL is usually ``http://localhost:8080/geoserver`` - -Viewing a layer ---------------- - -Once GeoServer is installed and running, open up a web browser and go to the web admin console (:ref:`web_admin`). Navigate to the :ref:`layerpreview` by clicking on the Layer Preview link at the bottom of the left sidebar. You will be presented with a list of the currently configured layers in your GeoServer instance. Find the row that says ``topp:states``. To the right of the layer click on the link that says **KML**. - - .. figure:: ../../../data/webadmin/img/preview_list.png - - The Map Preview page - -If Google Earth is correctly installed on your computer, you will see a dialog asking how to open the file. Select **Open with Google Earth**. - - .. figure:: openingkml.png - - Open with Google Earth - -When Google Earth is finished loading the result will be similar to below. - - .. figure:: googleearth.jpg - - The topp:states layer rendered in Google Earth - - -Direct access to KML --------------------- - -All of the configured FeatureTypes are available to be output as KML (and thus loaded into Google Earth). The URL structure for KMLs is:: - - http://GEOSERVER_URL/wms/kml?layers= - -For example, the topp:states layer URL is:: - - http://GEOSERVER_URL/wms/kml?layers=topp:states - - -Adding a Network Link ---------------------- - -An alternative to serving KML directly into Google Earth is to use a Network Link. A Network Link allows for better integration into Google Earth. For example, using a Network Link enables the user to refresh the data within Google Earth, without having to retype a URL, or click on links in the GeoServer Map Preview again. - -To add a Network Link, pull down the **Add** menu, and go to **Network Link**. The **New Network Link** dialog box will appear. -Name your layer in the **Name** field. (This will show up in **My Places** on the main Google Earth screen.) Set **Link** to:: - - http://GEOSERVER_URL/wms/kml?layers=topp:states - -(Don't forget to replace the GEOSERVER_URL.) Click **OK**. You can now save this layer in your **My Places**. - - .. figure:: networklink.png - - Adding a network link - -Check out the sections on :ref:`google-earth-tutorials` and the :ref:`google-earth-kml-styling` for more information. - +.. _google_earth_quickstart: + +Quickstart +========== + +.. note:: If you are using GeoServer locally, the GEOSERVER_URL is usually ``http://localhost:8080/geoserver`` + +Viewing a layer +--------------- + +Once GeoServer is installed and running, open up a web browser and go to the web admin console (:ref:`web_admin`). Navigate to the :ref:`layerpreview` by clicking on the Layer Preview link at the bottom of the left sidebar. You will be presented with a list of the currently configured layers in your GeoServer instance. Find the row that says ``topp:states``. To the right of the layer click on the link that says **KML**. + + .. figure:: ../../../data/webadmin/img/preview_list.png + + The Map Preview page + +If Google Earth is correctly installed on your computer, you will see a dialog asking how to open the file. Select **Open with Google Earth**. + + .. figure:: openingkml.png + + Open with Google Earth + +When Google Earth is finished loading the result will be similar to below. + + .. figure:: googleearth.jpg + + The topp:states layer rendered in Google Earth + + +Direct access to KML +-------------------- + +All of the configured FeatureTypes are available to be output as KML (and thus loaded into Google Earth). The URL structure for KMLs is:: + + http://GEOSERVER_URL/wms/kml?layers= + +For example, the topp:states layer URL is:: + + http://GEOSERVER_URL/wms/kml?layers=topp:states + + +Adding a Network Link +--------------------- + +An alternative to serving KML directly into Google Earth is to use a Network Link. A Network Link allows for better integration into Google Earth. For example, using a Network Link enables the user to refresh the data within Google Earth, without having to retype a URL, or click on links in the GeoServer Map Preview again. + +To add a Network Link, pull down the **Add** menu, and go to **Network Link**. The **New Network Link** dialog box will appear. +Name your layer in the **Name** field. (This will show up in **My Places** on the main Google Earth screen.) Set **Link** to:: + + http://GEOSERVER_URL/wms/kml?layers=topp:states + +(Don't forget to replace the GEOSERVER_URL.) Click **OK**. You can now save this layer in your **My Places**. + + .. figure:: networklink.png + + Adding a network link + +Check out the sections on :ref:`google-earth-tutorials` and the :ref:`google-earth-kml-styling` for more information. + diff --git a/doc/en/user/source/services/wms/googleearth/tutorials/index.rst b/doc/en/user/source/services/wms/googleearth/tutorials/index.rst index 27f2a54a5ba..e23e8d05bfa 100644 --- a/doc/en/user/source/services/wms/googleearth/tutorials/index.rst +++ b/doc/en/user/source/services/wms/googleearth/tutorials/index.rst @@ -1,13 +1,13 @@ -.. _google-earth-tutorials: - -Tutorials -========= - - -.. toctree:: - :maxdepth: 2 - - kmlplacemark/index - heights/heights.rst - time/time.rst - superoverlaysgwc.rst +.. _google-earth-tutorials: + +Tutorials +========= + + +.. toctree:: + :maxdepth: 2 + + kmlplacemark/index + heights/heights.rst + time/time.rst + superoverlaysgwc.rst diff --git a/doc/en/user/source/services/wms/googleearth/tutorials/superoverlaysgwc.rst b/doc/en/user/source/services/wms/googleearth/tutorials/superoverlaysgwc.rst index a6c354a2f07..4f6d474a6e3 100644 --- a/doc/en/user/source/services/wms/googleearth/tutorials/superoverlaysgwc.rst +++ b/doc/en/user/source/services/wms/googleearth/tutorials/superoverlaysgwc.rst @@ -1,28 +1,28 @@ -.. _ge-tutorial-superoverlays-gwc: - -Super-Overlays and GeoWebCache -============================== - -Overview --------- - -This tutorial explains how to use `GeoWebCache `_ (GWC) to enhance the performance of super-overlays in Google Earth. For more information please see the page on :ref:`ge_feature_kml_super_overlays` - -Conveniently GeoWebCache can generate super-overlays automatically. With the standalone GeoWebCache it takes minimal amount of configuration. Please see the `GeoWebCache documentation `_ for more information on the standalone version of GeoWebCache. - -We are going to use the plug in version of GeoWebCache where there is no configuration need. For this tutorial we are also using the topp:states layer. -Using the GeoWebCache plug in with super-overlays - - -To access GWC from GeoServer go to http://localhost:8080/geoserver/gwc/demo/. This should return a layer list of similar to below. - -.. figure:: ../../../../geowebcache/webadmin/img/demopage.png - -To use a super-overlay in GeoWebCache select the KML (vector) option display for each layer. Lets select topp:states.The url would be http://localhost:8080/geoserver/gwc/service/kml/topp:states.kml.kmz -After doing so you will be presented with a open option dialog, choose Google Earth. - -.. figure:: images/openingkmz.png - -When Google Earth finishes loading you should be viewing a the topp:states layers. - -.. figure:: ../googleearth.jpg +.. _ge-tutorial-superoverlays-gwc: + +Super-Overlays and GeoWebCache +============================== + +Overview +-------- + +This tutorial explains how to use `GeoWebCache `_ (GWC) to enhance the performance of super-overlays in Google Earth. For more information please see the page on :ref:`ge_feature_kml_super_overlays` + +Conveniently GeoWebCache can generate super-overlays automatically. With the standalone GeoWebCache it takes minimal amount of configuration. Please see the `GeoWebCache documentation `_ for more information on the standalone version of GeoWebCache. + +We are going to use the plug in version of GeoWebCache where there is no configuration need. For this tutorial we are also using the topp:states layer. +Using the GeoWebCache plug in with super-overlays + + +To access GWC from GeoServer go to http://localhost:8080/geoserver/gwc/demo/. This should return a layer list of similar to below. + +.. figure:: ../../../../geowebcache/webadmin/img/demopage.png + +To use a super-overlay in GeoWebCache select the KML (vector) option display for each layer. Lets select topp:states.The url would be http://localhost:8080/geoserver/gwc/service/kml/topp:states.kml.kmz +After doing so you will be presented with a open option dialog, choose Google Earth. + +.. figure:: images/openingkmz.png + +When Google Earth finishes loading you should be viewing a the topp:states layers. + +.. figure:: ../googleearth.jpg diff --git a/doc/en/user/source/services/wms/googleearth/tutorials/time/inet_weu.sld b/doc/en/user/source/services/wms/googleearth/tutorials/time/inet_weu.sld index 4d5cb977b2c..7f94866fc56 100644 --- a/doc/en/user/source/services/wms/googleearth/tutorials/time/inet_weu.sld +++ b/doc/en/user/source/services/wms/googleearth/tutorials/time/inet_weu.sld @@ -1,163 +1,163 @@ - - - - - Internet Users - - - Internet Users - Internet Users Per 100 People - - - n/a - - - INET_P100 - 0 - - - - - #C1C1C1 - 0.5 - - - - - 0 - 10 - - - INET_P100 - - 0 - - - 10 - - - - - - #FF0000 - 0.7 - - - - - 10 - 20 - - - INET_P100 - - 10 - - - 20 - - - - - - #00FF00 - 0.7 - - - - - 20 - 30 - - - INET_P100 - - 20 - - - 30 - - - - - - #0000FF - 0.7 - - - - - 30 - 40 - - - INET_P100 - - 30 - - - 40 - - - - - - #FF00FF - 0.7 - - - - - 40 - 50 - - - INET_P100 - - 40 - - - 50 - - - - - - #FFFF00 - 0.7 - - - - - > 50 - - - INET_P100 - 50 - - - - - #00FFFF - 0.7 - - - - - Border - - - - - - - Times New Roman - Normal - 14 - - - #000000 - - - - - - - + + + + + Internet Users + + + Internet Users + Internet Users Per 100 People + + + n/a + + + INET_P100 + 0 + + + + + #C1C1C1 + 0.5 + + + + + 0 - 10 + + + INET_P100 + + 0 + + + 10 + + + + + + #FF0000 + 0.7 + + + + + 10 - 20 + + + INET_P100 + + 10 + + + 20 + + + + + + #00FF00 + 0.7 + + + + + 20 - 30 + + + INET_P100 + + 20 + + + 30 + + + + + + #0000FF + 0.7 + + + + + 30 - 40 + + + INET_P100 + + 30 + + + 40 + + + + + + #FF00FF + 0.7 + + + + + 40 - 50 + + + INET_P100 + + 40 + + + 50 + + + + + + #FFFF00 + 0.7 + + + + + > 50 + + + INET_P100 + 50 + + + + + #00FFFF + 0.7 + + + + + Border + + + + + + + Times New Roman + Normal + 14 + + + #000000 + + + + + + + diff --git a/doc/en/user/source/services/wms/index.rst b/doc/en/user/source/services/wms/index.rst index bfc675f9b36..4dffc21d61a 100644 --- a/doc/en/user/source/services/wms/index.rst +++ b/doc/en/user/source/services/wms/index.rst @@ -1,22 +1,22 @@ -.. _wms: - -Web Map Service (WMS) -===================== - -This section describes the Web Map Service (WMS). - -.. toctree:: - :maxdepth: 2 - - webadmin - basics - reference - time - outputformats - vendor - nonstandardautonamespace - configuration - global - get_legend_graphic/index - decoration +.. _wms: + +Web Map Service (WMS) +===================== + +This section describes the Web Map Service (WMS). + +.. toctree:: + :maxdepth: 2 + + webadmin + basics + reference + time + outputformats + vendor + nonstandardautonamespace + configuration + global + get_legend_graphic/index + decoration googleearth/index \ No newline at end of file diff --git a/doc/en/user/source/services/wps/hazelcast-clustering.rst b/doc/en/user/source/services/wps/hazelcast-clustering.rst index 18ac426302f..49e96128ccb 100644 --- a/doc/en/user/source/services/wps/hazelcast-clustering.rst +++ b/doc/en/user/source/services/wps/hazelcast-clustering.rst @@ -1,99 +1,99 @@ -.. _hazelcast_clustering: - -Hazelcast based process status clustering -========================================= - -Starting with version 2.7.0 GeoServer has a new WPS extension point allowing GeoServer nodes -in the same cluster to share the status of current WPS requests. -This is particularly important for asynchronous ones, as the client polling for the progress/results -might not be hitting the same node that's currently running the requests. - -The Hazelcast based status sharing module leverages the Hazelcast library to share the information -about the current process status using a replicated map. - -Installation ------------- - -The installation of the module follows the usual process for most extensions: - -* Stop GeoServer -* Unpack the contents of gs-wps-hazelcast-status.zip into the ``geoserver/WEB-INF/lib`` folder -* Restart GeoServer - -Configuration -------------- - -The module does not require any configuration in case the default behavior is suitable for the -deploy enviroment. - -By default, the module will use multicast messages to locate other nodes in the same cluster -and will automatically start sharing information about the process status with them. - -In case this is not satisfactory, a ``hazelcast.xml`` file can be created/edited in the -root of the GeoServer data directory to modify the network connection methods. - -The file is not using a GeoServer specific syntax, it's instead a regular -`Hazelcast configuration `_ -file with a simple distributed map declaration: - -.. code-block:: xml - - - - - - geoserver - geoserver - - - - - log4j - - - - - 5701 - - - 224.2.2.3 - 54327 - - - 127.0.0.1 - - - my-access-key - my-secret-key - us-east-1 - - - - - - - - - - - executionId - completionTime - - - - -In case a TCP based configuration is desired, one just needs to disable the multicast one, -enable the tcp-ip one, and add a list of interface addresses in it that will form the core -of the cluster. -Not all nodes in the cluster need to be listed in said section, but a list long enough to ensure -that not all the nodes in the list might go down at the same time: as long as at least one +.. _hazelcast_clustering: + +Hazelcast based process status clustering +========================================= + +Starting with version 2.7.0 GeoServer has a new WPS extension point allowing GeoServer nodes +in the same cluster to share the status of current WPS requests. +This is particularly important for asynchronous ones, as the client polling for the progress/results +might not be hitting the same node that's currently running the requests. + +The Hazelcast based status sharing module leverages the Hazelcast library to share the information +about the current process status using a replicated map. + +Installation +------------ + +The installation of the module follows the usual process for most extensions: + +* Stop GeoServer +* Unpack the contents of gs-wps-hazelcast-status.zip into the ``geoserver/WEB-INF/lib`` folder +* Restart GeoServer + +Configuration +------------- + +The module does not require any configuration in case the default behavior is suitable for the +deploy enviroment. + +By default, the module will use multicast messages to locate other nodes in the same cluster +and will automatically start sharing information about the process status with them. + +In case this is not satisfactory, a ``hazelcast.xml`` file can be created/edited in the +root of the GeoServer data directory to modify the network connection methods. + +The file is not using a GeoServer specific syntax, it's instead a regular +`Hazelcast configuration `_ +file with a simple distributed map declaration: + +.. code-block:: xml + + + + + + geoserver + geoserver + + + + + log4j + + + + + 5701 + + + 224.2.2.3 + 54327 + + + 127.0.0.1 + + + my-access-key + my-secret-key + us-east-1 + + + + + + + + + + + executionId + completionTime + + + + +In case a TCP based configuration is desired, one just needs to disable the multicast one, +enable the tcp-ip one, and add a list of interface addresses in it that will form the core +of the cluster. +Not all nodes in the cluster need to be listed in said section, but a list long enough to ensure +that not all the nodes in the list might go down at the same time: as long as at least one of said nodes lives, the cluster will maintain its integrity. \ No newline at end of file diff --git a/doc/en/user/source/services/wps/index.rst b/doc/en/user/source/services/wps/index.rst index 42436691a3d..5efa6e96360 100644 --- a/doc/en/user/source/services/wps/index.rst +++ b/doc/en/user/source/services/wps/index.rst @@ -1,23 +1,23 @@ -.. _wps: - -Web Processing Service (WPS) -============================ - -Web Processing Service (WPS) is an OGC service for the publishing of geospatial processes, algorithms, and calculations. The WPS service is available as an extension for geoserver providing an execute operation for data processing and geospatial analysis. - -WPS is not a part of GeoServer by default, but is available as an extension. - -The main advantage of GeoServer WPS over a standalone WPS is **direct integration** with other GeoServer services and the data catalog. This means that it is possible to create processes based on data served in GeoServer, as opposed to sending the entire data source in the request. It is also possible for the results of a process to be stored as a new layer in the GeoServer catalog. In this way, WPS acts as a full remote geospatial analysis tool, capable of reading and writing data from and to GeoServer. - -For the official WPS specification, see `OGC Web Processing Service 05-007r7 `__. - -.. toctree:: - :maxdepth: 2 - - install - operations - administration - security - requestbuilder - processes/index - hazelcast-clustering +.. _wps: + +Web Processing Service (WPS) +============================ + +Web Processing Service (WPS) is an OGC service for the publishing of geospatial processes, algorithms, and calculations. The WPS service is available as an extension for geoserver providing an execute operation for data processing and geospatial analysis. + +WPS is not a part of GeoServer by default, but is available as an extension. + +The main advantage of GeoServer WPS over a standalone WPS is **direct integration** with other GeoServer services and the data catalog. This means that it is possible to create processes based on data served in GeoServer, as opposed to sending the entire data source in the request. It is also possible for the results of a process to be stored as a new layer in the GeoServer catalog. In this way, WPS acts as a full remote geospatial analysis tool, capable of reading and writing data from and to GeoServer. + +For the official WPS specification, see `OGC Web Processing Service 05-007r7 `__. + +.. toctree:: + :maxdepth: 2 + + install + operations + administration + security + requestbuilder + processes/index + hazelcast-clustering diff --git a/doc/en/user/source/services/wps/install.rst b/doc/en/user/source/services/wps/install.rst index 823e1259911..a9ec5e9ae27 100644 --- a/doc/en/user/source/services/wps/install.rst +++ b/doc/en/user/source/services/wps/install.rst @@ -1,35 +1,35 @@ -.. _wps_install: - -Installing the WPS extension -============================ - -The WPS module is not a part of GeoServer core, but instead must be installed as an extension. To install WPS: - -#. Navigate to the `GeoServer download page `_ - -#. Find the page that matches the exact version of GeoServer you are running. - - .. warning:: Be sure to match the version of the extension with that of GeoServer, otherwise errors will occur. - -#. Download the WPS extension. The download link for :guilabel:`WPS` will be in the :guilabel:`Extensions` section under :guilabel:`Other`. - -#. Extract the files in this archive to the :file:`WEB-INF/lib` directory of your GeoServer installation. - -#. Restart GeoServer. - -After restarting, load the :ref:`web_admin`. If the extension loaded properly, you should see an extra entry for WPS in the :guilabel:`Service Capabilities` column. If you don't see this entry, check the logs for errors. - -.. figure:: images/wpscapslink.png - :align: center - - *A link for the WPS capabilities document will display if installed properly* - -Configuring WPS ---------------- - -WPS processes are subject to the same feature limit as the WFS service. -The limit applies to process **input**, so even processes which summarize data -and return few results will be affected if applied to very large datasets. -The limit is set on the :ref:`services_webadmin_wfs` Admin page. - +.. _wps_install: + +Installing the WPS extension +============================ + +The WPS module is not a part of GeoServer core, but instead must be installed as an extension. To install WPS: + +#. Navigate to the `GeoServer download page `_ + +#. Find the page that matches the exact version of GeoServer you are running. + + .. warning:: Be sure to match the version of the extension with that of GeoServer, otherwise errors will occur. + +#. Download the WPS extension. The download link for :guilabel:`WPS` will be in the :guilabel:`Extensions` section under :guilabel:`Other`. + +#. Extract the files in this archive to the :file:`WEB-INF/lib` directory of your GeoServer installation. + +#. Restart GeoServer. + +After restarting, load the :ref:`web_admin`. If the extension loaded properly, you should see an extra entry for WPS in the :guilabel:`Service Capabilities` column. If you don't see this entry, check the logs for errors. + +.. figure:: images/wpscapslink.png + :align: center + + *A link for the WPS capabilities document will display if installed properly* + +Configuring WPS +--------------- + +WPS processes are subject to the same feature limit as the WFS service. +The limit applies to process **input**, so even processes which summarize data +and return few results will be affected if applied to very large datasets. +The limit is set on the :ref:`services_webadmin_wfs` Admin page. + .. warning:: If the limit is encountered during process execution, no error is given. Any results computed by the process may be incomplete \ No newline at end of file diff --git a/doc/en/user/source/services/wps/operations.rst b/doc/en/user/source/services/wps/operations.rst index d662568694a..470ad9e59f4 100644 --- a/doc/en/user/source/services/wps/operations.rst +++ b/doc/en/user/source/services/wps/operations.rst @@ -1,374 +1,374 @@ -.. _wps_operations: - -WPS Operations -============== - -WPS defines three operations for the discovery and execution of geospatial processes. -The operations are: - -* GetCapabilities -* DescribeProcess -* Execute - -.. _wps_getcaps: - -GetCapabilities ---------------- - -The **GetCapabilities** operation requests details of the service offering, -including service metadata and metadata describing the available processes. -The response is an XML document called the **capabilities document**. - -The required parameters, as in all OGC GetCapabilities requests, are ``service=WPS``, ``version=1.0.0`` and ``request=GetCapabilities``. - -An example of a GetCapabilities request is:: - - http://localhost:8080/geoserver/ows? - service=WPS& - version=1.0.0& - request=GetCapabilities - - -DescribeProcess ----------------- - -The **DescribeProcess** operation requests a description of a WPS process available through the service. - -The parameter ``identifier`` specifies the process to describe. -Multiple processes can be requested, separated by commas (for example, ``identifier=JTS:buffer,gs:Clip``). -At least one process must be specified. - -.. note:: As with all OGC parameters, the keys (``request``, ``version``, etc) are case-insensitive, and the values (``GetCapabilities``, ``JTS:buffer``, etc.) are case-sensitive. GeoServer is generally more relaxed about case, but it is best to follow the specification. - -The response is an XML document containing metadata about each requested process, including the following: - -* Process name, title and abstract -* For each input and output parameter: identifier, title, abstract, multiplicity, and supported datatype and format - -An example request for the process ``JTS:buffer`` is:: - - http://localhost:8080/geoserver/ows? - service=WPS& - version=1.0.0& - request=DescribeProcess& - identifier=JTS:buffer - -The response XML document contains the following information: - -.. list-table:: - :widths: 20 80 - - * - **Title** - - "Buffers a geometry using a certain distance" - * - **Inputs** - - **geom**: "The geometry to be buffered" *(geometry, mandatory)* - - **distance**: "The distance (same unit of measure as the geometry)" *(double, mandatory)* - - **quadrant segments**: "Number of quadrant segments. Use > 0 for round joins, 0 for flat joins, < 0 for mitred joins" *(integer, optional)* - - **capstyle**: "The buffer cap style, round, flat, square" *(literal value, optional)* - * - **Output formats** - - One of GML 3.1.1, GML 2.1.2, or WKT - - - -Execute -------- - -The **Execute** operation is a request to perform the process -with specified input values and required output data items. -The request may be made as either a GET URL, or a POST with an XML request document. -Because the request has a complex structure, the POST form is more typically used. - -The inputs and outputs required for the request depend on the process being executed. -GeoServer provides a wide variety of processes to process geometry, features, and coverage data. -For more information see the section :ref:`wps_processes`. - -Below is an example of a ``Execute`` POST request. -The example process (``JTS:buffer``) takes as input -a geometry ``geom`` (in this case the point ``POINT(0 0)``), -a ``distance`` (with the value ``10``), -a quantization factor ``quadrantSegments`` (here set to be 1), -and a ``capStyle`` (specified as ``flat``). -The ```` element specifies the format for the single output ``result`` to be GML 3.1.1. - -.. code-block:: xml - - - - JTS:buffer - - - geom - - - - - - distance - - 10 - - - - quadrantSegments - - 1 - - - - capStyle - - flat - - - - - - result - - - - -The process performs a buffer operation using the supplied inputs, -and returns the outputs as specified. -The response from the request is (with numbers rounded for clarity): - -.. code-block:: xml - - - - - - - 10.0 0.0 - 0.0 -10.0 - -10.0 0.0 - 0.0 10.0 - 10.0 0.0 - - - - - -For help in generating WPS requests you can use the built-in interactive :ref:`wps_request_builder`. - -Dismiss -------- - -According to the WPS specification, an asynchronous process execution returns a back link to a status -location that the client can ping to get progress report about the process, and eventually retrieve -its final results. - -In GeoServer this link is implemented as a pseudo-operation called ``GetExecutionStatus``, and the link -has the following structure:: - - http://host:port/geoserver/ows?service=WPS&version=1.0.0&request=GetExecutionStatus&executionId=397e8cbd-7d51-48c5-ad72-b0fcbe7cfbdb - -The ``executionId`` identifies the running request, and can be used in a the ``Dismiss`` vendor -operation in order to cancel the execution of the process: - - http://host:port/geoserver/ows?service=WPS&version=1.0.0&request=Dismiss&executionId=397e8cbd-7d51-48c5-ad72-b0fcbe7cfbdb - -Upon receipt GeoServer will do its best to stop the running process, and subsequent calls to ``Dismiss`` -or ``GetExecutionStatus`` will report that the executionId is not known anymore. -Internally, GeoServer will stop any process that attempts to report progress, and poison input and -outputs to break the execution of the process, but the execution of processes that already got their -inputs, and are not reporting their progress back, will continue until its natural end. - -For example, let's consider the "geo:Buffer" process, possibly working against a very large input -GML geometry, to be fetched from another host. The process itself does a single call to a JTS function, -which cannot report progress. Here are three possible scenarios, depending on when the Dismiss operation is invoked: - -* Dismiss is invoked while the GML is being retrieved, in this case the execution will stop immediately -* Dismiss is invoked while the process is doing the buffering, in this case, the execution will stop as soon as the buffering is completed -* Dismiss is invoked while the output GML is being encoded, also in this case the execution will stop immediately - -GetExecutions -------------- - -.. note:: This is an extension of the GeoServer WPS Service. This operation is specific to this GeoServer instance. - -This specific operation allows a client to recognize the list of WPS Executions. - -.. figure:: images/getExecutions_001.png - :align: center - -The client makes a simple “GetExecutions” request to the WPS Server, in order to get back an XML document containing the list of current Execution Statuses. - -It is also possible to filter the “GetExecutions” request along with simple parameters, in order to refine the output and get back only the executions status we are looking for. - -Adding a bit more to this, AUTHORIZATION headers must be sent along with the “GetExecutions” request; the WPS Server will be able, if the security subsystem is available and enable on the latter, to prove the list resources to the client itself. - -The operation will return only the list of available Executions the logged in user has started, except in the case it is an Administrator. In that case he will be able to get the whole list. - -If the “lineage” option of the WPS Execute Request has been specified, the client will be able to retrieve the Execute Inputs values provided to the process Identifier. - -StatusInfo Document -^^^^^^^^^^^^^^^^^^^ - -Refers to http://docs.opengeospatial.org/is/14-065/14-065.html 9.5 and extends it. - -The StatusInfo document is used to provide identification and status information about jobs on a WPS server. The operation adds additional fields to the StatusInfo Document reporting also the WPS Process Identifier and other information on estimated execution and expiration time. - -.. figure:: images/getExecutions_002.png - :align: center - - -GetExecutionsOperation -^^^^^^^^^^^^^^^^^^^^^^ - -The GetExecutions Operation allows WPS clients to retrieve the list of available process jobs running on a WPS instance. The output is returned in the form of an XML document. - -The GetExecutions Operation returns only the list of available Executions the logged in user has started, except in the case it is an Administrator. In that case he will be able to get the whole list. - -.. figure:: images/getExecutions_003.png - :align: center - - -GetExecutionsRequest -^^^^^^^^^^^^^^^^^^^^ - -The GetExecutions Request is a common structure for synchronous execution. It inherits basic properties from the RequestBaseType and contains additional elements that allow to filter out, refine and order the list of available Process Jobs. - -.. figure:: images/getExecutions_004.png - :align: center - -.. figure:: images/getExecutions_005.png - :align: center - - -GetExecutionsResponse -^^^^^^^^^^^^^^^^^^^^^ - -The GetExecutionsResponse it is always in the form of an XML document. Except in case of Exception, the response document will contain a list of StatusInfo elements filtered, refined or ordered accordingly to the specified parameters. - -Response paging -^^^^^^^^^^^^^^^ - -Response paging is the ability of a client to scroll through a set of response values, N values at-a-time much like one scrolls through the response from a search engine one page at a time. - -Similarly to the WFS 2.0.0 response paging mechanism (see See section “7.7.4.4 Response paging” of the specification), the output will show to the client the following attributes as part of the response document. - -.. figure:: images/getExecutions_006.png - :align: center - - -GetExecutionsExceptions -^^^^^^^^^^^^^^^^^^^^^^^ - -When a WPS server encounters an error while performing an GetExecutionsResponse, it shall return an exception report as specified in clause 8 of [OGC 06-121r9]. If appropriate, the server shall use additional exception codes as defined in this section. - -.. figure:: images/getExecutions_007.png - :align: center - -Retrieve the WPS Execute Input values -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The GetExecutions Operations tries (best-effort) to retrieve the Input values specified from the Execute Request **iff** the ``lineage`` option has been provided to the Execute Request. - -Example requests with the ``lineage`` option active - -.. code-block:: xml - - - - JTS:convexHull - - - geom - - - - - - - result - - - - - -.. code-block:: xml - - - - gs:BufferFeatureCollection - - - features - - - - gs:CollectGeometries - - - features - - - - - - - - - - - - result - - - - - - - - distance - - 0.005 - - - - - - - result - - - - - -.. code-block:: xml - - - - gs:Clip - - - features - - - - - - - - - - clip - - - - - - - - - result - - - +.. _wps_operations: + +WPS Operations +============== + +WPS defines three operations for the discovery and execution of geospatial processes. +The operations are: + +* GetCapabilities +* DescribeProcess +* Execute + +.. _wps_getcaps: + +GetCapabilities +--------------- + +The **GetCapabilities** operation requests details of the service offering, +including service metadata and metadata describing the available processes. +The response is an XML document called the **capabilities document**. + +The required parameters, as in all OGC GetCapabilities requests, are ``service=WPS``, ``version=1.0.0`` and ``request=GetCapabilities``. + +An example of a GetCapabilities request is:: + + http://localhost:8080/geoserver/ows? + service=WPS& + version=1.0.0& + request=GetCapabilities + + +DescribeProcess +---------------- + +The **DescribeProcess** operation requests a description of a WPS process available through the service. + +The parameter ``identifier`` specifies the process to describe. +Multiple processes can be requested, separated by commas (for example, ``identifier=JTS:buffer,gs:Clip``). +At least one process must be specified. + +.. note:: As with all OGC parameters, the keys (``request``, ``version``, etc) are case-insensitive, and the values (``GetCapabilities``, ``JTS:buffer``, etc.) are case-sensitive. GeoServer is generally more relaxed about case, but it is best to follow the specification. + +The response is an XML document containing metadata about each requested process, including the following: + +* Process name, title and abstract +* For each input and output parameter: identifier, title, abstract, multiplicity, and supported datatype and format + +An example request for the process ``JTS:buffer`` is:: + + http://localhost:8080/geoserver/ows? + service=WPS& + version=1.0.0& + request=DescribeProcess& + identifier=JTS:buffer + +The response XML document contains the following information: + +.. list-table:: + :widths: 20 80 + + * - **Title** + - "Buffers a geometry using a certain distance" + * - **Inputs** + - **geom**: "The geometry to be buffered" *(geometry, mandatory)* + + **distance**: "The distance (same unit of measure as the geometry)" *(double, mandatory)* + + **quadrant segments**: "Number of quadrant segments. Use > 0 for round joins, 0 for flat joins, < 0 for mitred joins" *(integer, optional)* + + **capstyle**: "The buffer cap style, round, flat, square" *(literal value, optional)* + * - **Output formats** + - One of GML 3.1.1, GML 2.1.2, or WKT + + + +Execute +------- + +The **Execute** operation is a request to perform the process +with specified input values and required output data items. +The request may be made as either a GET URL, or a POST with an XML request document. +Because the request has a complex structure, the POST form is more typically used. + +The inputs and outputs required for the request depend on the process being executed. +GeoServer provides a wide variety of processes to process geometry, features, and coverage data. +For more information see the section :ref:`wps_processes`. + +Below is an example of a ``Execute`` POST request. +The example process (``JTS:buffer``) takes as input +a geometry ``geom`` (in this case the point ``POINT(0 0)``), +a ``distance`` (with the value ``10``), +a quantization factor ``quadrantSegments`` (here set to be 1), +and a ``capStyle`` (specified as ``flat``). +The ```` element specifies the format for the single output ``result`` to be GML 3.1.1. + +.. code-block:: xml + + + + JTS:buffer + + + geom + + + + + + distance + + 10 + + + + quadrantSegments + + 1 + + + + capStyle + + flat + + + + + + result + + + + +The process performs a buffer operation using the supplied inputs, +and returns the outputs as specified. +The response from the request is (with numbers rounded for clarity): + +.. code-block:: xml + + + + + + + 10.0 0.0 + 0.0 -10.0 + -10.0 0.0 + 0.0 10.0 + 10.0 0.0 + + + + + +For help in generating WPS requests you can use the built-in interactive :ref:`wps_request_builder`. + +Dismiss +------- + +According to the WPS specification, an asynchronous process execution returns a back link to a status +location that the client can ping to get progress report about the process, and eventually retrieve +its final results. + +In GeoServer this link is implemented as a pseudo-operation called ``GetExecutionStatus``, and the link +has the following structure:: + + http://host:port/geoserver/ows?service=WPS&version=1.0.0&request=GetExecutionStatus&executionId=397e8cbd-7d51-48c5-ad72-b0fcbe7cfbdb + +The ``executionId`` identifies the running request, and can be used in a the ``Dismiss`` vendor +operation in order to cancel the execution of the process: + + http://host:port/geoserver/ows?service=WPS&version=1.0.0&request=Dismiss&executionId=397e8cbd-7d51-48c5-ad72-b0fcbe7cfbdb + +Upon receipt GeoServer will do its best to stop the running process, and subsequent calls to ``Dismiss`` +or ``GetExecutionStatus`` will report that the executionId is not known anymore. +Internally, GeoServer will stop any process that attempts to report progress, and poison input and +outputs to break the execution of the process, but the execution of processes that already got their +inputs, and are not reporting their progress back, will continue until its natural end. + +For example, let's consider the "geo:Buffer" process, possibly working against a very large input +GML geometry, to be fetched from another host. The process itself does a single call to a JTS function, +which cannot report progress. Here are three possible scenarios, depending on when the Dismiss operation is invoked: + +* Dismiss is invoked while the GML is being retrieved, in this case the execution will stop immediately +* Dismiss is invoked while the process is doing the buffering, in this case, the execution will stop as soon as the buffering is completed +* Dismiss is invoked while the output GML is being encoded, also in this case the execution will stop immediately + +GetExecutions +------------- + +.. note:: This is an extension of the GeoServer WPS Service. This operation is specific to this GeoServer instance. + +This specific operation allows a client to recognize the list of WPS Executions. + +.. figure:: images/getExecutions_001.png + :align: center + +The client makes a simple “GetExecutions” request to the WPS Server, in order to get back an XML document containing the list of current Execution Statuses. + +It is also possible to filter the “GetExecutions” request along with simple parameters, in order to refine the output and get back only the executions status we are looking for. + +Adding a bit more to this, AUTHORIZATION headers must be sent along with the “GetExecutions” request; the WPS Server will be able, if the security subsystem is available and enable on the latter, to prove the list resources to the client itself. + +The operation will return only the list of available Executions the logged in user has started, except in the case it is an Administrator. In that case he will be able to get the whole list. + +If the “lineage” option of the WPS Execute Request has been specified, the client will be able to retrieve the Execute Inputs values provided to the process Identifier. + +StatusInfo Document +^^^^^^^^^^^^^^^^^^^ + +Refers to http://docs.opengeospatial.org/is/14-065/14-065.html 9.5 and extends it. + +The StatusInfo document is used to provide identification and status information about jobs on a WPS server. The operation adds additional fields to the StatusInfo Document reporting also the WPS Process Identifier and other information on estimated execution and expiration time. + +.. figure:: images/getExecutions_002.png + :align: center + + +GetExecutionsOperation +^^^^^^^^^^^^^^^^^^^^^^ + +The GetExecutions Operation allows WPS clients to retrieve the list of available process jobs running on a WPS instance. The output is returned in the form of an XML document. + +The GetExecutions Operation returns only the list of available Executions the logged in user has started, except in the case it is an Administrator. In that case he will be able to get the whole list. + +.. figure:: images/getExecutions_003.png + :align: center + + +GetExecutionsRequest +^^^^^^^^^^^^^^^^^^^^ + +The GetExecutions Request is a common structure for synchronous execution. It inherits basic properties from the RequestBaseType and contains additional elements that allow to filter out, refine and order the list of available Process Jobs. + +.. figure:: images/getExecutions_004.png + :align: center + +.. figure:: images/getExecutions_005.png + :align: center + + +GetExecutionsResponse +^^^^^^^^^^^^^^^^^^^^^ + +The GetExecutionsResponse it is always in the form of an XML document. Except in case of Exception, the response document will contain a list of StatusInfo elements filtered, refined or ordered accordingly to the specified parameters. + +Response paging +^^^^^^^^^^^^^^^ + +Response paging is the ability of a client to scroll through a set of response values, N values at-a-time much like one scrolls through the response from a search engine one page at a time. + +Similarly to the WFS 2.0.0 response paging mechanism (see See section “7.7.4.4 Response paging” of the specification), the output will show to the client the following attributes as part of the response document. + +.. figure:: images/getExecutions_006.png + :align: center + + +GetExecutionsExceptions +^^^^^^^^^^^^^^^^^^^^^^^ + +When a WPS server encounters an error while performing an GetExecutionsResponse, it shall return an exception report as specified in clause 8 of [OGC 06-121r9]. If appropriate, the server shall use additional exception codes as defined in this section. + +.. figure:: images/getExecutions_007.png + :align: center + +Retrieve the WPS Execute Input values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The GetExecutions Operations tries (best-effort) to retrieve the Input values specified from the Execute Request **iff** the ``lineage`` option has been provided to the Execute Request. + +Example requests with the ``lineage`` option active + +.. code-block:: xml + + + + JTS:convexHull + + + geom + + + + + + + result + + + + + +.. code-block:: xml + + + + gs:BufferFeatureCollection + + + features + + + + gs:CollectGeometries + + + features + + + + + + + + + + + + result + + + + + + + + distance + + 0.005 + + + + + + + result + + + + + +.. code-block:: xml + + + + gs:Clip + + + features + + + + + + + + + + clip + + + + + + + + + result + + + \ No newline at end of file diff --git a/doc/en/user/source/styling/css/cookbook/line.rst b/doc/en/user/source/styling/css/cookbook/line.rst index 3baca354a86..6198a4f6372 100644 --- a/doc/en/user/source/styling/css/cookbook/line.rst +++ b/doc/en/user/source/styling/css/cookbook/line.rst @@ -1,667 +1,667 @@ -.. _css_cookbook_lines: - -Lines -===== - -While lines can also seem to be simple shapes, having length but no width, there are many options and tricks for making -lines display nicely. - -.. _css_cookbook_lines_attributes: - -Example lines layer -------------------- - -The :download:`lines layer <../../sld/cookbook/artifacts/sld_cookbook_line.zip>` used in the examples below contains road information for a -fictional country. For reference, the attribute table for the points in this layer is included below. - -.. list-table:: - :widths: 30 40 30 - - * - **fid** (Feature ID) - - **name** (Road name) - - **type** (Road class) - * - line.1 - - Latway - - highway - * - line.2 - - Crescent Avenue - - secondary - * - line.3 - - Forest Avenue - - secondary - * - line.4 - - Longway - - highway - * - line.5 - - Saxer Avenue - - secondary - * - line.6 - - Ridge Avenue - - secondary - * - line.7 - - Holly Lane - - local-road - * - line.8 - - Mulberry Street - - local-road - * - line.9 - - Nathan Lane - - local-road - * - line.10 - - Central Street - - local-road - * - line.11 - - Lois Lane - - local-road - * - line.12 - - Rocky Road - - local-road - * - line.13 - - Fleet Street - - local-road - * - line.14 - - Diane Court - - local-road - * - line.15 - - Cedar Trail - - local-road - * - line.16 - - Victory Road - - local-road - * - line.17 - - Highland Road - - local-road - * - line.18 - - Easy Street - - local-road - * - line.19 - - Hill Street - - local-road - * - line.20 - - Country Road - - local-road - * - line.21 - - Main Street - - local-road - * - line.22 - - Jani Lane - - local-road - * - line.23 - - Shinbone Alley - - local-road - * - line.24 - - State Street - - local-road - * - line.25 - - River Road - - local-road - -:download:`Download the lines shapefile <../../sld/cookbook/artifacts/sld_cookbook_line.zip>` - -.. _css_cookbook_lines_simpleline: - -Simple line ------------ - -This example specifies lines be colored black with a thickness of 3 pixels. - -.. figure:: ../../sld/cookbook/images/line_simpleline.png - :align: center - - *Simple line* - -Code -~~~~ - -.. code-block:: css - :linenos: - - * { - stroke: black; - stroke-width: 3px; - } - -Details -~~~~~~~ - -The only rule asks for a black stroke (this attribute is mandatory to get strokes to actually show up), 3 pixels wide. - - -Line with border ----------------- - -This example shows how to draw lines with borders (sometimes called "cased lines"). -In this case the lines are drawn with a 3 pixel blue center and a 1 pixel wide gray border. - -.. figure:: ../../sld/cookbook/images/line_linewithborder.png - :align: center - - *Line with border* - -Code -~~~~ - -.. code-block:: css - :linenos: - - * { - stroke: #333333, #6699FF; - stroke-width: 5px, 3px; - stroke-linecap: round; - z-index: 0, 1; - } - -Details -~~~~~~~ - -Lines in CSS have no notion of a "fill", only "stroke". Thus, unlike points or polygons, it is not possible to style the -"edge" of the line geometry. It is, however, possible to achieve this effect by drawing each line twice: once with a -certain width and again with a slightly smaller width. This gives the illusion of fill and stroke by obscuring the -larger lines everywhere except along the edges of the smaller lines. - -The style uses the "multi-valued properties" CSS support by specifying two strokes and two stroke-widths. -This causes each feature to be painted twice, first with a dark gray (``#333333``) line 5 pixels wide, and then a thinner -blue (``#6699FF``) line 3 pixels wide. - -Since every line is drawn twice, the order of the rendering is *very* important. -Without the z-index indication, each feature would first draw the gray stroke and then the blue one, and then the rendering engine -would move to the next feature, and so on. This would result in ugly overlaps when lines do cross. -By using the z-index property (**Line 3**) instead, all gray lines will be painted first, and then all blue lines will painted on top, -thus making sure the blue lines visually connect. - -The "stroke-linecap" property is the only one having a single value, this is because the value is the same for both the gray and blue line. - -The result is a 3 pixel blue line with a 1 pixel gray border, since the 5 pixel gray line will display 1 pixel on each -side of the 3 pixel blue line. - -Dashed line ------------ - -This example alters the :ref:`css_cookbook_lines_simpleline` to create a dashed line consisting of 5 pixels of drawn -line alternating with 2 pixels of blank space. - -.. figure:: ../../sld/cookbook/images/line_dashedline.png - :align: center - - *Dashed line* - -Code -~~~~ - -.. code-block:: css - :linenos: - - * { - stroke: blue; - stroke-width: 3px; - stroke-dasharray: 5 2; - } - -Details -~~~~~~~ - -In this example the we create a blue line, 3 pixels wide, and specify a dash array with value "5 2", which creates a -repeating pattern of 5 pixels of drawn line, followed by 2 pixels of omitted line. - - -Railroad (hatching) -------------------- - -This example uses hatching to create a railroad style. Both the line and the hatches are black, with a 2 pixel -thickness for the main line and a 1 pixel width for the perpendicular hatches. - -.. figure:: ../../sld/cookbook/images/line_railroad.png - :align: center - - *Railroad (hatching)* - -Code -~~~~ - -.. code-block:: scss - :linenos: - - * { - stroke: #333333, symbol("shape://vertline"); - stroke-width: 3px; - :nth-stroke(2) { - size: 12; - stroke: #333333; - stroke-width: 1px; - } - } - -Details -~~~~~~~ - -In this example a multi-valued stroke is used: the fist value makes the renderer paint a dark gray line (3 pixels wide, according to the "stroke-width" attribute), -whilst the second value makes the line be painted by repeating the "shape://vertline" symbol over and over, creating the hatching effect. - -In order to specify how the symbol itself should be painted, the ":nth-stroke(2)" pseudo-selector is used at **Line 4** to specify the options for the repeated symbol: -in particular with are instructing the renderer to create a 12px wide symbol, with a dark gray stroke 1 pixel wide. - -Spaced graphic symbols ----------------------- - -This example uses a graphic stroke along with dash arrays to create a "dot and space" line type. -Adding the dash array specification allows to control the amount of space between one symbol and the next one. -Without using the dash array the lines would be densely populated with dots, each one touching the previous one. - -.. figure:: ../../sld/cookbook/images/line_dashspace.png - :align: center - - *Spaced symbols along a line* - -Code -~~~~ - -.. code-block:: scss - :linenos: - - * { - stroke: symbol(circle); - stroke-dasharray: 4 6; - :stroke { - size: 4; - fill: #666666; - stroke: #333333; - stroke-width: 1px; - } - } - - -Details -~~~~~~~ - -This example, like others before, uses ``symbol(circle)`` to place a graphic symbol along a line. - -The symbol details are specified in the nested rule at **Line 4** using -the ":stroke" pseudo-selector, creating a gray fill circle, 4 pixels wide, with a dark gray outline. - -The spacing between symbols is controlled with the ``stroke-dasharray`` at **line 3**, which specifies 4 pixels of pen-down (just enough to draw the circle) and 6 pixels of pen-up, -to provide the spacing. - - -.. _css_cookbook_lines_dashoffset: - -Alternating symbols with dash offsets -------------------------------------- - -This example shows how to create a complex line style which alternates a dashed line and a graphic symbol. -The code builds on features shown in the previous examples: - - * ``stroke-dasharray`` controls pen-down/pen-up behavior to generate dashed lines - * ``symbol(...)`` places symbols along a line combining the two allows control of symbol spacing - -This also shows the usage of a `dash offset`, which controls where rendering starts -in the dash array. -For example, with a dash array of ``5 10`` and a dash offset of ``7`` the -renderer starts drawing the pattern 7 pixels from the beginning. It skips the 5 pixels pen-down -section and 2 pixels of the pen-up section, then draws the remaining 8 pixels of pen-up, then 5 down, 10 up, and so on. - -The example shows how to use these features to create two synchronized sequences of dash arrays, -one drawing line segments and the other symbols. - -.. figure:: ../../sld/cookbook/images/line_dashdot.png - :align: center - - *Alternating dash and symbol* - -Code -~~~~ - - -.. code-block:: scss - :linenos: - - * { - stroke: blue, symbol(circle); - stroke-width: 1px; - stroke-dasharray: 10 10, 5 15; - stroke-dashoffset: 0, 7.5; - :nth-stroke(2) { - stroke: #000033; - stroke-width: 1px; - size: 5px; - } - } - -Details -~~~~~~~ - -| This example uses again multi-valued properties to create two subsequent strokes applied to the same lines. -| The first stroke is a solid blue line, 1 pixel wide, with a dash array of "10 10". -| The second one instead is a repeated circle, using a dash array of "5 15" and with a dash offset of 7.5. This makes the sequence start with 12.5 pixels of white space, then a circle (which is then centered between the two line segments of the other pattern), then 15 pixels of white space, and so on. - -The circle portrayal details are specified using the pseudo selector "nth-stroke(2)" at **line 6**, asking for circles that -are 5 pixels wide, not filled, and with a dark blue outline. - -.. _css_cookbook_lines_defaultlabel: - -Line with default label ------------------------ - -This example shows a text label on the simple line. This is how a label will be displayed in the absence of any other -customization. - -.. figure:: ../../sld/cookbook/images/line_linewithdefaultlabel.png - :align: center - - *Line with default label* - -Code -~~~~ - -.. code-block:: css - :linenos: - - * { - stroke: red; - label: [name]; - font-fill: black; - } - -Details -~~~~~~~ - -This example paints lines with a red stroke, and then adds horizontal black labels at the center of the line, using the "name" attribute to fill the label. - -_css_line_ - -.. _css_cookbook_lines_perpendicularlabel: - -Labels along line with perpendicular offset -------------------------------------------- - -This example shows a text label on the simple line, just like the previous example, but will force the label to be parallel to the lines, and will offset them a few pixels away. - -.. figure:: ../../sld/cookbook/images/line_labelwithoffset.png - :align: center - - *Line with default label* - -Code -~~~~ - -.. code-block:: css - :linenos: - - * { - stroke: red; - label: [name]; - label-offset: 7px; - font-fill: black; - } - -Details -~~~~~~~ - -This example is line by line identical to the previous one, but it add a new attribute "label-offset", which in the case of lines, when having a single value, is intepreted as a perpendicular -offset from the line. The label is painted along a straight line, parallel to the line orientation in the center point of the label. - -.. _css_cookbook_lines_labelfollowingline: - -Label following line --------------------- - -This example renders the text label to follow the contour of the lines. - -.. figure:: ../../sld/cookbook/images/line_labelfollowingline.png - :align: center - - *Label following line* - -Code -~~~~ - -.. code-block:: css - :linenos: - - * { - stroke: red; - label: [name]; - font-fill: black; - label-follow-line: true; - } - -Details -~~~~~~~ - -As the :ref:`css_cookbook_lines_defaultlabel` example showed, the default label behavior isn't optimal. - -This example is similar to the :ref:`css_cookbook_lines_defaultlabel` example with the exception of **line 5** where the -"label-follow-line" option is specified, which forces the labels to strickly follow the line. - -Not all labels are visible partly because of conflict resolution, and partly because the renderer cannot find a line -segment long and "straight" enough to paint the label (labels are not painted over sharp turns by default). - -.. _css_cookbook_lines_optimizedlabel: - -Optimized label placement -------------------------- - -This example optimizes label placement for lines such that the maximum number of labels are displayed. - -.. figure:: ../../sld/cookbook/images/line_optimizedlabel.png - :align: center - - *Optimized label* - -Code -~~~~ - -.. code-block:: css - :linenos: - - * { - stroke: red; - label: [name]; - font-fill: black; - label-follow-line: true; - label-max-angle-delta: 90; - label-max-displacement: 400; - label-repeat: 150; - } - -Details -~~~~~~~ - -This example is similar to the previous example, :ref:`css_cookbook_lines_labelfollowingline`. The only differences are contained in **lines 6-8**. **Line 6** sets the maximum angle that the label will follow. This sets the label to never bend more than 90 degrees to prevent the label from becoming illegible due to a pronounced curve or angle. **Line 7** sets the maximum displacement of the label to be 400 pixels. In order to resolve conflicts with overlapping labels, GeoServer will attempt to move the labels such that they are no longer overlapping. This value sets how far the label can be moved relative to its original placement. Finally, **line 8** sets the labels to be repeated every 150 pixels. A feature will typically receive only one label, but this can cause confusion for long lines. Setting the label to repeat ensures that the line is always labeled locally. - - - -.. _css_cookbook_lines_optimizedstyledlabel: - -Optimized and styled label --------------------------- - -This example improves the style of the labels from the :ref:`css_cookbook_lines_optimizedlabel` example. - -.. figure:: ../../sld/cookbook/images/line_optimizedstyledlabel_with_halo.png - :align: center - - *Optimized and styled label* - -Code -~~~~ - -.. code-block:: css - :linenos: - - * { - stroke: red; - label: [name]; - font-family: Arial; - font-weight: bold; - font-fill: black; - font-size: 10; - halo-color: white; - halo-radius: 1; - label-follow-line: true; - label-max-angle-delta: 90; - label-max-displacement: 400; - label-repeat: 150; - } - -Details -~~~~~~~ - -This example is similar to the :ref:`css_cookbook_lines_optimizedlabel`. The only differences are: - - * The font family and weight have been specified - * In order to make the labels easier to read, a white "halo" has been added. The halo draws a thin 1 pixel white border around the text, making it stand out from the background. - - -Attribute-based line --------------------- - -This example styles the lines differently based on the "type" (Road class) attribute. - -.. figure:: ../../sld/cookbook/images/line_attributebasedline.png - :align: center - - *Attribute-based line* - -Code -~~~~ - -.. code-block:: css - :linenos: - - [type = 'local-road'] { - stroke: #009933; - stroke-width: 2; - z-index: 0; - } - - [type = 'secondary'] { - stroke: #0055CC; - stroke-width: 3; - z-index: 1; - } - - [type = 'highway'] { - stroke: #FF0000; - stroke-width: 6; - z-index: 2; - } - -Details -~~~~~~~ - -.. note:: Refer to the :ref:`css_cookbook_lines_attributes` to see the attributes for the layer. This example has eschewed labels in order to simplify the style, but you can refer to the example :ref:`css_cookbook_lines_optimizedstyledlabel` to see which attributes correspond to which points. - -There are three types of road classes in our fictional country, ranging from back roads to high-speed freeways: -"highway", "secondary", and "local-road". In order to make sure the roads are rendered in the proper order of importance, a "z-index" attribute has been placed in each rule. - -The three rules are designed as follows: - -.. list-table:: - :widths: 20 30 30 20 - - * - **Rule order** - - **Rule name / type** - - **Color** - - **Size** - * - 1 - - local-road - - ``#009933`` (green) - - 2 - * - 2 - - secondary - - ``#0055CC`` (blue) - - 3 - * - 3 - - highway - - ``#FF0000`` (red) - - 6 - -**Lines 1-5** comprise the first rule, the filter matches all roads that the "type" attribute has a value of "local-road". If this condition is true for a particular line, the rule renders it dark green, 2 pixels wide. All these lines are rendered first, and thus sit at the bottom of the final map. - -**Lines 7-11** match the "secondary" roads, painting them dark blue, 3 pixels wide. Given the "z-index" is 1, they are rendered after the local roads, but below the highways. - -**Lines 13-17** match the "highway" roads, painting them red 6 pixels wide. These roads are pained last, thus, on top of all others. - - -Zoom-based line ---------------- - -This example alters the :ref:`css_cookbook_lines_simpleline` style at different zoom levels. - -.. figure:: ../../sld/cookbook/images/line_zoombasedlinelarge.png - :align: center - - *Zoom-based line: Zoomed in* - - -.. figure:: ../../sld/cookbook/images/line_zoombasedlinemedium.png - :align: center - - *Zoom-based line: Partially zoomed* - - -.. figure:: ../../sld/cookbook/images/line_zoombasedlinesmall.png - :align: center - - *Zoom-based line: Zoomed out* - -Code -~~~~ - -.. code-block:: css - :linenos: - - * { - stroke: #009933; - } - - [@sd < 180M] { - stroke-width: 6; - } - - [@sd > 180M] [@sd < 360M] { - stroke-width: 4; - } - - [@sd > 360M] { - stroke-width: 2; - } - -Details -~~~~~~~ - -It is often desirable to make shapes larger at higher zoom levels when creating a natural-looking map. This example -varies the thickness of the lines according to the zoom level (or more accurately, scale denominator). Scale -denominators refer to the scale of the map. A scale denominator of 10,000 means the map has a scale of 1:10,000 in the -units of the map projection. - -.. note:: Determining the appropriate scale denominators (zoom levels) to use is beyond the scope of this example. - -This style contains three rules. The three rules are designed as follows: - -.. list-table:: - :widths: 15 25 40 20 - - * - **Rule order** - - **Rule name** - - **Scale denominator** - - **Line width** - * - 1 - - Large - - 1:180,000,000 or less - - 6 - * - 2 - - Medium - - 1:180,000,000 to 1:360,000,000 - - 4 - * - 3 - - Small - - Greater than 1:360,000,000 - - 2 - -The order of these rules does not matter since the scales denominated in each rule do not overlap. - -The first rule provides the stroke color used at all zoom levels, dark gray, while the other three rules cascade over it applying the different stroke widths based on the current zoom level leveraging the "@sd" pseudo attribute. The "@sd" pseudo attribute can only be compared using the "<" and ">" operators, using any other operator will result in errors. - -The result of this style is that lines are drawn with larger widths as one zooms in and smaller widths as one zooms out. - +.. _css_cookbook_lines: + +Lines +===== + +While lines can also seem to be simple shapes, having length but no width, there are many options and tricks for making +lines display nicely. + +.. _css_cookbook_lines_attributes: + +Example lines layer +------------------- + +The :download:`lines layer <../../sld/cookbook/artifacts/sld_cookbook_line.zip>` used in the examples below contains road information for a +fictional country. For reference, the attribute table for the points in this layer is included below. + +.. list-table:: + :widths: 30 40 30 + + * - **fid** (Feature ID) + - **name** (Road name) + - **type** (Road class) + * - line.1 + - Latway + - highway + * - line.2 + - Crescent Avenue + - secondary + * - line.3 + - Forest Avenue + - secondary + * - line.4 + - Longway + - highway + * - line.5 + - Saxer Avenue + - secondary + * - line.6 + - Ridge Avenue + - secondary + * - line.7 + - Holly Lane + - local-road + * - line.8 + - Mulberry Street + - local-road + * - line.9 + - Nathan Lane + - local-road + * - line.10 + - Central Street + - local-road + * - line.11 + - Lois Lane + - local-road + * - line.12 + - Rocky Road + - local-road + * - line.13 + - Fleet Street + - local-road + * - line.14 + - Diane Court + - local-road + * - line.15 + - Cedar Trail + - local-road + * - line.16 + - Victory Road + - local-road + * - line.17 + - Highland Road + - local-road + * - line.18 + - Easy Street + - local-road + * - line.19 + - Hill Street + - local-road + * - line.20 + - Country Road + - local-road + * - line.21 + - Main Street + - local-road + * - line.22 + - Jani Lane + - local-road + * - line.23 + - Shinbone Alley + - local-road + * - line.24 + - State Street + - local-road + * - line.25 + - River Road + - local-road + +:download:`Download the lines shapefile <../../sld/cookbook/artifacts/sld_cookbook_line.zip>` + +.. _css_cookbook_lines_simpleline: + +Simple line +----------- + +This example specifies lines be colored black with a thickness of 3 pixels. + +.. figure:: ../../sld/cookbook/images/line_simpleline.png + :align: center + + *Simple line* + +Code +~~~~ + +.. code-block:: css + :linenos: + + * { + stroke: black; + stroke-width: 3px; + } + +Details +~~~~~~~ + +The only rule asks for a black stroke (this attribute is mandatory to get strokes to actually show up), 3 pixels wide. + + +Line with border +---------------- + +This example shows how to draw lines with borders (sometimes called "cased lines"). +In this case the lines are drawn with a 3 pixel blue center and a 1 pixel wide gray border. + +.. figure:: ../../sld/cookbook/images/line_linewithborder.png + :align: center + + *Line with border* + +Code +~~~~ + +.. code-block:: css + :linenos: + + * { + stroke: #333333, #6699FF; + stroke-width: 5px, 3px; + stroke-linecap: round; + z-index: 0, 1; + } + +Details +~~~~~~~ + +Lines in CSS have no notion of a "fill", only "stroke". Thus, unlike points or polygons, it is not possible to style the +"edge" of the line geometry. It is, however, possible to achieve this effect by drawing each line twice: once with a +certain width and again with a slightly smaller width. This gives the illusion of fill and stroke by obscuring the +larger lines everywhere except along the edges of the smaller lines. + +The style uses the "multi-valued properties" CSS support by specifying two strokes and two stroke-widths. +This causes each feature to be painted twice, first with a dark gray (``#333333``) line 5 pixels wide, and then a thinner +blue (``#6699FF``) line 3 pixels wide. + +Since every line is drawn twice, the order of the rendering is *very* important. +Without the z-index indication, each feature would first draw the gray stroke and then the blue one, and then the rendering engine +would move to the next feature, and so on. This would result in ugly overlaps when lines do cross. +By using the z-index property (**Line 3**) instead, all gray lines will be painted first, and then all blue lines will painted on top, +thus making sure the blue lines visually connect. + +The "stroke-linecap" property is the only one having a single value, this is because the value is the same for both the gray and blue line. + +The result is a 3 pixel blue line with a 1 pixel gray border, since the 5 pixel gray line will display 1 pixel on each +side of the 3 pixel blue line. + +Dashed line +----------- + +This example alters the :ref:`css_cookbook_lines_simpleline` to create a dashed line consisting of 5 pixels of drawn +line alternating with 2 pixels of blank space. + +.. figure:: ../../sld/cookbook/images/line_dashedline.png + :align: center + + *Dashed line* + +Code +~~~~ + +.. code-block:: css + :linenos: + + * { + stroke: blue; + stroke-width: 3px; + stroke-dasharray: 5 2; + } + +Details +~~~~~~~ + +In this example the we create a blue line, 3 pixels wide, and specify a dash array with value "5 2", which creates a +repeating pattern of 5 pixels of drawn line, followed by 2 pixels of omitted line. + + +Railroad (hatching) +------------------- + +This example uses hatching to create a railroad style. Both the line and the hatches are black, with a 2 pixel +thickness for the main line and a 1 pixel width for the perpendicular hatches. + +.. figure:: ../../sld/cookbook/images/line_railroad.png + :align: center + + *Railroad (hatching)* + +Code +~~~~ + +.. code-block:: scss + :linenos: + + * { + stroke: #333333, symbol("shape://vertline"); + stroke-width: 3px; + :nth-stroke(2) { + size: 12; + stroke: #333333; + stroke-width: 1px; + } + } + +Details +~~~~~~~ + +In this example a multi-valued stroke is used: the fist value makes the renderer paint a dark gray line (3 pixels wide, according to the "stroke-width" attribute), +whilst the second value makes the line be painted by repeating the "shape://vertline" symbol over and over, creating the hatching effect. + +In order to specify how the symbol itself should be painted, the ":nth-stroke(2)" pseudo-selector is used at **Line 4** to specify the options for the repeated symbol: +in particular with are instructing the renderer to create a 12px wide symbol, with a dark gray stroke 1 pixel wide. + +Spaced graphic symbols +---------------------- + +This example uses a graphic stroke along with dash arrays to create a "dot and space" line type. +Adding the dash array specification allows to control the amount of space between one symbol and the next one. +Without using the dash array the lines would be densely populated with dots, each one touching the previous one. + +.. figure:: ../../sld/cookbook/images/line_dashspace.png + :align: center + + *Spaced symbols along a line* + +Code +~~~~ + +.. code-block:: scss + :linenos: + + * { + stroke: symbol(circle); + stroke-dasharray: 4 6; + :stroke { + size: 4; + fill: #666666; + stroke: #333333; + stroke-width: 1px; + } + } + + +Details +~~~~~~~ + +This example, like others before, uses ``symbol(circle)`` to place a graphic symbol along a line. + +The symbol details are specified in the nested rule at **Line 4** using +the ":stroke" pseudo-selector, creating a gray fill circle, 4 pixels wide, with a dark gray outline. + +The spacing between symbols is controlled with the ``stroke-dasharray`` at **line 3**, which specifies 4 pixels of pen-down (just enough to draw the circle) and 6 pixels of pen-up, +to provide the spacing. + + +.. _css_cookbook_lines_dashoffset: + +Alternating symbols with dash offsets +------------------------------------- + +This example shows how to create a complex line style which alternates a dashed line and a graphic symbol. +The code builds on features shown in the previous examples: + + * ``stroke-dasharray`` controls pen-down/pen-up behavior to generate dashed lines + * ``symbol(...)`` places symbols along a line combining the two allows control of symbol spacing + +This also shows the usage of a `dash offset`, which controls where rendering starts +in the dash array. +For example, with a dash array of ``5 10`` and a dash offset of ``7`` the +renderer starts drawing the pattern 7 pixels from the beginning. It skips the 5 pixels pen-down +section and 2 pixels of the pen-up section, then draws the remaining 8 pixels of pen-up, then 5 down, 10 up, and so on. + +The example shows how to use these features to create two synchronized sequences of dash arrays, +one drawing line segments and the other symbols. + +.. figure:: ../../sld/cookbook/images/line_dashdot.png + :align: center + + *Alternating dash and symbol* + +Code +~~~~ + + +.. code-block:: scss + :linenos: + + * { + stroke: blue, symbol(circle); + stroke-width: 1px; + stroke-dasharray: 10 10, 5 15; + stroke-dashoffset: 0, 7.5; + :nth-stroke(2) { + stroke: #000033; + stroke-width: 1px; + size: 5px; + } + } + +Details +~~~~~~~ + +| This example uses again multi-valued properties to create two subsequent strokes applied to the same lines. +| The first stroke is a solid blue line, 1 pixel wide, with a dash array of "10 10". +| The second one instead is a repeated circle, using a dash array of "5 15" and with a dash offset of 7.5. This makes the sequence start with 12.5 pixels of white space, then a circle (which is then centered between the two line segments of the other pattern), then 15 pixels of white space, and so on. + +The circle portrayal details are specified using the pseudo selector "nth-stroke(2)" at **line 6**, asking for circles that +are 5 pixels wide, not filled, and with a dark blue outline. + +.. _css_cookbook_lines_defaultlabel: + +Line with default label +----------------------- + +This example shows a text label on the simple line. This is how a label will be displayed in the absence of any other +customization. + +.. figure:: ../../sld/cookbook/images/line_linewithdefaultlabel.png + :align: center + + *Line with default label* + +Code +~~~~ + +.. code-block:: css + :linenos: + + * { + stroke: red; + label: [name]; + font-fill: black; + } + +Details +~~~~~~~ + +This example paints lines with a red stroke, and then adds horizontal black labels at the center of the line, using the "name" attribute to fill the label. + +_css_line_ + +.. _css_cookbook_lines_perpendicularlabel: + +Labels along line with perpendicular offset +------------------------------------------- + +This example shows a text label on the simple line, just like the previous example, but will force the label to be parallel to the lines, and will offset them a few pixels away. + +.. figure:: ../../sld/cookbook/images/line_labelwithoffset.png + :align: center + + *Line with default label* + +Code +~~~~ + +.. code-block:: css + :linenos: + + * { + stroke: red; + label: [name]; + label-offset: 7px; + font-fill: black; + } + +Details +~~~~~~~ + +This example is line by line identical to the previous one, but it add a new attribute "label-offset", which in the case of lines, when having a single value, is intepreted as a perpendicular +offset from the line. The label is painted along a straight line, parallel to the line orientation in the center point of the label. + +.. _css_cookbook_lines_labelfollowingline: + +Label following line +-------------------- + +This example renders the text label to follow the contour of the lines. + +.. figure:: ../../sld/cookbook/images/line_labelfollowingline.png + :align: center + + *Label following line* + +Code +~~~~ + +.. code-block:: css + :linenos: + + * { + stroke: red; + label: [name]; + font-fill: black; + label-follow-line: true; + } + +Details +~~~~~~~ + +As the :ref:`css_cookbook_lines_defaultlabel` example showed, the default label behavior isn't optimal. + +This example is similar to the :ref:`css_cookbook_lines_defaultlabel` example with the exception of **line 5** where the +"label-follow-line" option is specified, which forces the labels to strickly follow the line. + +Not all labels are visible partly because of conflict resolution, and partly because the renderer cannot find a line +segment long and "straight" enough to paint the label (labels are not painted over sharp turns by default). + +.. _css_cookbook_lines_optimizedlabel: + +Optimized label placement +------------------------- + +This example optimizes label placement for lines such that the maximum number of labels are displayed. + +.. figure:: ../../sld/cookbook/images/line_optimizedlabel.png + :align: center + + *Optimized label* + +Code +~~~~ + +.. code-block:: css + :linenos: + + * { + stroke: red; + label: [name]; + font-fill: black; + label-follow-line: true; + label-max-angle-delta: 90; + label-max-displacement: 400; + label-repeat: 150; + } + +Details +~~~~~~~ + +This example is similar to the previous example, :ref:`css_cookbook_lines_labelfollowingline`. The only differences are contained in **lines 6-8**. **Line 6** sets the maximum angle that the label will follow. This sets the label to never bend more than 90 degrees to prevent the label from becoming illegible due to a pronounced curve or angle. **Line 7** sets the maximum displacement of the label to be 400 pixels. In order to resolve conflicts with overlapping labels, GeoServer will attempt to move the labels such that they are no longer overlapping. This value sets how far the label can be moved relative to its original placement. Finally, **line 8** sets the labels to be repeated every 150 pixels. A feature will typically receive only one label, but this can cause confusion for long lines. Setting the label to repeat ensures that the line is always labeled locally. + + + +.. _css_cookbook_lines_optimizedstyledlabel: + +Optimized and styled label +-------------------------- + +This example improves the style of the labels from the :ref:`css_cookbook_lines_optimizedlabel` example. + +.. figure:: ../../sld/cookbook/images/line_optimizedstyledlabel_with_halo.png + :align: center + + *Optimized and styled label* + +Code +~~~~ + +.. code-block:: css + :linenos: + + * { + stroke: red; + label: [name]; + font-family: Arial; + font-weight: bold; + font-fill: black; + font-size: 10; + halo-color: white; + halo-radius: 1; + label-follow-line: true; + label-max-angle-delta: 90; + label-max-displacement: 400; + label-repeat: 150; + } + +Details +~~~~~~~ + +This example is similar to the :ref:`css_cookbook_lines_optimizedlabel`. The only differences are: + + * The font family and weight have been specified + * In order to make the labels easier to read, a white "halo" has been added. The halo draws a thin 1 pixel white border around the text, making it stand out from the background. + + +Attribute-based line +-------------------- + +This example styles the lines differently based on the "type" (Road class) attribute. + +.. figure:: ../../sld/cookbook/images/line_attributebasedline.png + :align: center + + *Attribute-based line* + +Code +~~~~ + +.. code-block:: css + :linenos: + + [type = 'local-road'] { + stroke: #009933; + stroke-width: 2; + z-index: 0; + } + + [type = 'secondary'] { + stroke: #0055CC; + stroke-width: 3; + z-index: 1; + } + + [type = 'highway'] { + stroke: #FF0000; + stroke-width: 6; + z-index: 2; + } + +Details +~~~~~~~ + +.. note:: Refer to the :ref:`css_cookbook_lines_attributes` to see the attributes for the layer. This example has eschewed labels in order to simplify the style, but you can refer to the example :ref:`css_cookbook_lines_optimizedstyledlabel` to see which attributes correspond to which points. + +There are three types of road classes in our fictional country, ranging from back roads to high-speed freeways: +"highway", "secondary", and "local-road". In order to make sure the roads are rendered in the proper order of importance, a "z-index" attribute has been placed in each rule. + +The three rules are designed as follows: + +.. list-table:: + :widths: 20 30 30 20 + + * - **Rule order** + - **Rule name / type** + - **Color** + - **Size** + * - 1 + - local-road + - ``#009933`` (green) + - 2 + * - 2 + - secondary + - ``#0055CC`` (blue) + - 3 + * - 3 + - highway + - ``#FF0000`` (red) + - 6 + +**Lines 1-5** comprise the first rule, the filter matches all roads that the "type" attribute has a value of "local-road". If this condition is true for a particular line, the rule renders it dark green, 2 pixels wide. All these lines are rendered first, and thus sit at the bottom of the final map. + +**Lines 7-11** match the "secondary" roads, painting them dark blue, 3 pixels wide. Given the "z-index" is 1, they are rendered after the local roads, but below the highways. + +**Lines 13-17** match the "highway" roads, painting them red 6 pixels wide. These roads are pained last, thus, on top of all others. + + +Zoom-based line +--------------- + +This example alters the :ref:`css_cookbook_lines_simpleline` style at different zoom levels. + +.. figure:: ../../sld/cookbook/images/line_zoombasedlinelarge.png + :align: center + + *Zoom-based line: Zoomed in* + + +.. figure:: ../../sld/cookbook/images/line_zoombasedlinemedium.png + :align: center + + *Zoom-based line: Partially zoomed* + + +.. figure:: ../../sld/cookbook/images/line_zoombasedlinesmall.png + :align: center + + *Zoom-based line: Zoomed out* + +Code +~~~~ + +.. code-block:: css + :linenos: + + * { + stroke: #009933; + } + + [@sd < 180M] { + stroke-width: 6; + } + + [@sd > 180M] [@sd < 360M] { + stroke-width: 4; + } + + [@sd > 360M] { + stroke-width: 2; + } + +Details +~~~~~~~ + +It is often desirable to make shapes larger at higher zoom levels when creating a natural-looking map. This example +varies the thickness of the lines according to the zoom level (or more accurately, scale denominator). Scale +denominators refer to the scale of the map. A scale denominator of 10,000 means the map has a scale of 1:10,000 in the +units of the map projection. + +.. note:: Determining the appropriate scale denominators (zoom levels) to use is beyond the scope of this example. + +This style contains three rules. The three rules are designed as follows: + +.. list-table:: + :widths: 15 25 40 20 + + * - **Rule order** + - **Rule name** + - **Scale denominator** + - **Line width** + * - 1 + - Large + - 1:180,000,000 or less + - 6 + * - 2 + - Medium + - 1:180,000,000 to 1:360,000,000 + - 4 + * - 3 + - Small + - Greater than 1:360,000,000 + - 2 + +The order of these rules does not matter since the scales denominated in each rule do not overlap. + +The first rule provides the stroke color used at all zoom levels, dark gray, while the other three rules cascade over it applying the different stroke widths based on the current zoom level leveraging the "@sd" pseudo attribute. The "@sd" pseudo attribute can only be compared using the "<" and ">" operators, using any other operator will result in errors. + +The result of this style is that lines are drawn with larger widths as one zooms in and smaller widths as one zooms out. + diff --git a/doc/en/user/source/styling/index.rst b/doc/en/user/source/styling/index.rst index cb319a407e7..37ae245db7e 100644 --- a/doc/en/user/source/styling/index.rst +++ b/doc/en/user/source/styling/index.rst @@ -1,17 +1,17 @@ -.. _styling: - -Styling -======= - -This section discusses the styling of geospatial data served through GeoServer. - -.. toctree:: - :maxdepth: 2 - - webadmin/index - sld/index - qgis/index - css/index - ysld/index - mbstyle/index - workshop/index +.. _styling: + +Styling +======= + +This section discusses the styling of geospatial data served through GeoServer. + +.. toctree:: + :maxdepth: 2 + + webadmin/index + sld/index + qgis/index + css/index + ysld/index + mbstyle/index + workshop/index diff --git a/doc/en/user/source/styling/mbstyle/cookbook/index.rst b/doc/en/user/source/styling/mbstyle/cookbook/index.rst index d228cc5d85d..134fe676ddd 100644 --- a/doc/en/user/source/styling/mbstyle/cookbook/index.rst +++ b/doc/en/user/source/styling/mbstyle/cookbook/index.rst @@ -1,31 +1,31 @@ -.. _mbstyle_cookbook: - -MBStyle Cookbook -================ - -The MBStyle Cookbook is a collection of MBStyle "recipes" for creating various types of map styles. Wherever possible, each example is designed to show off a single MBStyle layer so that code can be copied from the examples and adapted when creating MBStyles of your own. While not an exhaustive reference like the :ref:`MBStyle reference ` the MBStyle cookbook is designed to be a practical reference, showing common style templates that are easy to understand. - -The MBStyle Cookbook is divided into four sections: the first three for each of the vector types (points, lines, and polygons) and the fourth section for rasters to come. Each example in every section contains a screenshot showing actual GeoServer WMS output, a snippet of the MBStyle code for reference, and a link to download the full MBStyle. - -Each section uses data created especially for the MBStyle Cookbook, with shapefiles for vector data and GeoTIFFs for raster data. - -.. list-table:: - :widths: 20 80 - :header-rows: 1 - - * - Data Type - - Shapefile - * - Point - - :download:`mbstyle_cookbook_point.zip ` - * - Line - - :download:`mbstyle_cookbook_line.zip ` - * - Polygon - - :download:`mbstyle_cookbook_polygon.zip ` - - -.. toctree:: - :maxdepth: 2 - - points - lines - polygons +.. _mbstyle_cookbook: + +MBStyle Cookbook +================ + +The MBStyle Cookbook is a collection of MBStyle "recipes" for creating various types of map styles. Wherever possible, each example is designed to show off a single MBStyle layer so that code can be copied from the examples and adapted when creating MBStyles of your own. While not an exhaustive reference like the :ref:`MBStyle reference ` the MBStyle cookbook is designed to be a practical reference, showing common style templates that are easy to understand. + +The MBStyle Cookbook is divided into four sections: the first three for each of the vector types (points, lines, and polygons) and the fourth section for rasters to come. Each example in every section contains a screenshot showing actual GeoServer WMS output, a snippet of the MBStyle code for reference, and a link to download the full MBStyle. + +Each section uses data created especially for the MBStyle Cookbook, with shapefiles for vector data and GeoTIFFs for raster data. + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Data Type + - Shapefile + * - Point + - :download:`mbstyle_cookbook_point.zip ` + * - Line + - :download:`mbstyle_cookbook_line.zip ` + * - Polygon + - :download:`mbstyle_cookbook_polygon.zip ` + + +.. toctree:: + :maxdepth: 2 + + points + lines + polygons diff --git a/doc/en/user/source/styling/mbstyle/cookbook/lines.rst b/doc/en/user/source/styling/mbstyle/cookbook/lines.rst index 29408fa47c7..a805132e1f3 100644 --- a/doc/en/user/source/styling/mbstyle/cookbook/lines.rst +++ b/doc/en/user/source/styling/mbstyle/cookbook/lines.rst @@ -1,294 +1,294 @@ -.. _mbstyle_cookbook.lines: - -Lines -===== - -While lines can also seem to be simple shapes, having length but no width, there are many options and tricks for making -lines display nicely. - -.. _mbstyle_cookbook_lines_attributes: - -Example lines layer -------------------- - -The :download:`lines layer ` used in the examples below contains road information for a -fictional country. For reference, the attribute table for the points in this layer is included below. - -.. list-table:: - :widths: 30 40 30 - :header-rows: 1 - - * - ``fid`` (Feature ID) - - ``name`` (Road name) - - ``type`` (Road class) - * - line.1 - - Latway - - highway - * - line.2 - - Crescent Avenue - - secondary - * - line.3 - - Forest Avenue - - secondary - * - line.4 - - Longway - - highway - * - line.5 - - Saxer Avenue - - secondary - * - line.6 - - Ridge Avenue - - secondary - * - line.7 - - Holly Lane - - local-road - * - line.8 - - Mulberry Street - - local-road - * - line.9 - - Nathan Lane - - local-road - * - line.10 - - Central Street - - local-road - * - line.11 - - Lois Lane - - local-road - * - line.12 - - Rocky Road - - local-road - * - line.13 - - Fleet Street - - local-road - * - line.14 - - Diane Court - - local-road - * - line.15 - - Cedar Trail - - local-road - * - line.16 - - Victory Road - - local-road - * - line.17 - - Highland Road - - local-road - * - line.18 - - Easy Street - - local-road - * - line.19 - - Hill Street - - local-road - * - line.20 - - Country Road - - local-road - * - line.21 - - Main Street - - local-road - * - line.22 - - Jani Lane - - local-road - * - line.23 - - Shinbone Alley - - local-road - * - line.24 - - State Street - - local-road - * - line.25 - - River Road - - local-road - -:download:`Download the lines shapefile ` - -.. _mbstyle_cookbook_lines_simpleline: - -Simple line ------------ - -This example specifies lines be colored black with a thickness of 3 pixels. - -.. figure:: ../../sld/cookbook/images/line_simpleline.png - - Simple line - -Code -~~~~ - -:download:`Download the "Simple line" MBStyle ` - -.. code-block:: json - :linenos: - - { - "version": 8, - "name": "simple-line", - "layers": [ - { - "id": "simple-line", - "type": "line", - "paint": { - "line-color": "#000000", - "line-width": 3 - } - } - ] - } - -Details -~~~~~~~ - -There is one layer style for this MBStyle, which is the simplest possible situation. Styling -lines is accomplished using the line layer. **Line 9** specifies the color of the line to be -black (``"#000000"``), while **line 10** specifies the width of the lines to be 3 pixels. - - -Line with border ----------------- - -This example shows how to draw lines with borders (sometimes called "cased lines"). -In this case the lines are drawn with a 3 pixel blue center and a 1 pixel wide gray border. - -.. figure:: ../../sld/cookbook/images/line_linewithborder.png - - Line with border - -Code -~~~~ - -:download:`Download the "Line with border" MBStyle ` - -.. code-block:: json - :linenos: - - { - "version": 8, - "name": "simple-borderedline", - "layers": [ - { - "id": "simple-borderedline", - "type": "line", - "layout": { - "line-cap": "round" - }, - "paint": { - "line-color": "#333333", - "line-width": 5 - } - }, - { - "id": "simple-line", - "type": "line", - "layout": { - "line-cap": "round" - }, - "paint": { - "line-color": "#6699FF", - "line-width": 3 - } - } - ] - } - - -Details -~~~~~~~ - -In this example we are drawing the lines twice to achieve the appearance of a line with a border. -Since every line is drawn twice, the order of the rendering is *very* important. -GeoServer renders ``layers`` in the order that they are presented in the MBStyle. -In this style, the gray border lines are drawn first via the first layer style, followed by the blue center lines in a second layer style. This ensures that the blue lines are not obscured by the gray lines, and also ensures proper rendering at intersections, so that the blue lines "connect". - -In this example, **lines 5-15** comprise the first layer style, which is the outer line (or "stroke"). -**Line 12** specifies the color of the line to be dark gray (``"#333333"``), **line 13** specifies the width of this line to be 5 pixels, and in the ``layout`` **line 9** a ``line-cap`` parameter of ``round`` -renders the ends of the line as rounded instead of flat. -(When working with bordered lines using a round line cap ensures that the border connects properly at the ends of the lines.) - -**Lines 16-26** comprise the second ``layer``, which is the the inner line (or "fill"). **Line 23** -specifies the color of the line to be a medium blue (``"#6699FF"``), **line 24** specifies the width of this line to be 3 pixels, and in the ``layout`` **line 20** again renders the edges of the line to be rounded instead of flat. - -The result is a 3 pixel blue line with a 1 pixel gray border, since the 5 pixel gray line will display 1 pixel on each side of the 3 pixel blue line. - -Dashed line ------------ - -This example alters the :ref:`mbstyle_cookbook_lines_simpleline` to create a dashed line consisting of 5 pixels of drawn -line alternating with 2 pixels of blank space. - -.. figure:: ../../sld/cookbook/images/line_dashedline.png - - Dashed line - -Code -~~~~ - -:download:`Download the "Dashed line" MBStyle ` - -.. code-block:: json - :linenos: - - { - "version": 8, - "name": "simple-dashedline", - "layers": [ - { - "id": "simple-dashedline", - "type": "line", - "paint": { - "line-color": "#0000FF", - "line-width": 3, - "line-dasharray": [5, 2] - } - } - ] - } - -Details -~~~~~~~ - -In this example, **line 9** sets the color of the lines to be blue (``"#0000FF"``) and **line 10** sets the width of the lines to be 3 pixels. **Line 11** determines the composition of the line dashes. The value of ``[5, 2]`` creates a repeating pattern of 5 pixels of drawn line, followed by 2 pixels of omitted line. - -Offset line ------------ - -This example alters the :ref:`mbstyle_cookbook_lines_simpleline` to add a perpendicular offset line on the left side of the line, at five pixels distance. - -.. figure:: ../../sld/cookbook/images/line_offset.png - - Dashed line - -Code -~~~~ - -:download:`Download the "Offset line" MBStlye ` - -.. code-block:: json - :linenos: - - { - "version": 8, - "name": "simple-offsetline", - "layers": [ - { - "id": "simple-line", - "type": "line", - "paint": { - "line-color": "#000000", - "line-width": 1 - } - }, - { - "id": "simple-offsetline", - "type": "line", - "paint": { - "line-color": "#FF0000", - "line-width": 1, - "line-dasharray": [5, 2], - "line-offset": 5 - } - } - ] - } - -Details -~~~~~~~ - -In this example, **lines 5-11** draw a simple black line like in the Simple line example. **Lines 13-21** draw a red dashed line like in the above Dashed line example. **Line 20** modifies the dashed line with a 5 pixel offset from the line geometry. +.. _mbstyle_cookbook.lines: + +Lines +===== + +While lines can also seem to be simple shapes, having length but no width, there are many options and tricks for making +lines display nicely. + +.. _mbstyle_cookbook_lines_attributes: + +Example lines layer +------------------- + +The :download:`lines layer ` used in the examples below contains road information for a +fictional country. For reference, the attribute table for the points in this layer is included below. + +.. list-table:: + :widths: 30 40 30 + :header-rows: 1 + + * - ``fid`` (Feature ID) + - ``name`` (Road name) + - ``type`` (Road class) + * - line.1 + - Latway + - highway + * - line.2 + - Crescent Avenue + - secondary + * - line.3 + - Forest Avenue + - secondary + * - line.4 + - Longway + - highway + * - line.5 + - Saxer Avenue + - secondary + * - line.6 + - Ridge Avenue + - secondary + * - line.7 + - Holly Lane + - local-road + * - line.8 + - Mulberry Street + - local-road + * - line.9 + - Nathan Lane + - local-road + * - line.10 + - Central Street + - local-road + * - line.11 + - Lois Lane + - local-road + * - line.12 + - Rocky Road + - local-road + * - line.13 + - Fleet Street + - local-road + * - line.14 + - Diane Court + - local-road + * - line.15 + - Cedar Trail + - local-road + * - line.16 + - Victory Road + - local-road + * - line.17 + - Highland Road + - local-road + * - line.18 + - Easy Street + - local-road + * - line.19 + - Hill Street + - local-road + * - line.20 + - Country Road + - local-road + * - line.21 + - Main Street + - local-road + * - line.22 + - Jani Lane + - local-road + * - line.23 + - Shinbone Alley + - local-road + * - line.24 + - State Street + - local-road + * - line.25 + - River Road + - local-road + +:download:`Download the lines shapefile ` + +.. _mbstyle_cookbook_lines_simpleline: + +Simple line +----------- + +This example specifies lines be colored black with a thickness of 3 pixels. + +.. figure:: ../../sld/cookbook/images/line_simpleline.png + + Simple line + +Code +~~~~ + +:download:`Download the "Simple line" MBStyle ` + +.. code-block:: json + :linenos: + + { + "version": 8, + "name": "simple-line", + "layers": [ + { + "id": "simple-line", + "type": "line", + "paint": { + "line-color": "#000000", + "line-width": 3 + } + } + ] + } + +Details +~~~~~~~ + +There is one layer style for this MBStyle, which is the simplest possible situation. Styling +lines is accomplished using the line layer. **Line 9** specifies the color of the line to be +black (``"#000000"``), while **line 10** specifies the width of the lines to be 3 pixels. + + +Line with border +---------------- + +This example shows how to draw lines with borders (sometimes called "cased lines"). +In this case the lines are drawn with a 3 pixel blue center and a 1 pixel wide gray border. + +.. figure:: ../../sld/cookbook/images/line_linewithborder.png + + Line with border + +Code +~~~~ + +:download:`Download the "Line with border" MBStyle ` + +.. code-block:: json + :linenos: + + { + "version": 8, + "name": "simple-borderedline", + "layers": [ + { + "id": "simple-borderedline", + "type": "line", + "layout": { + "line-cap": "round" + }, + "paint": { + "line-color": "#333333", + "line-width": 5 + } + }, + { + "id": "simple-line", + "type": "line", + "layout": { + "line-cap": "round" + }, + "paint": { + "line-color": "#6699FF", + "line-width": 3 + } + } + ] + } + + +Details +~~~~~~~ + +In this example we are drawing the lines twice to achieve the appearance of a line with a border. +Since every line is drawn twice, the order of the rendering is *very* important. +GeoServer renders ``layers`` in the order that they are presented in the MBStyle. +In this style, the gray border lines are drawn first via the first layer style, followed by the blue center lines in a second layer style. This ensures that the blue lines are not obscured by the gray lines, and also ensures proper rendering at intersections, so that the blue lines "connect". + +In this example, **lines 5-15** comprise the first layer style, which is the outer line (or "stroke"). +**Line 12** specifies the color of the line to be dark gray (``"#333333"``), **line 13** specifies the width of this line to be 5 pixels, and in the ``layout`` **line 9** a ``line-cap`` parameter of ``round`` +renders the ends of the line as rounded instead of flat. +(When working with bordered lines using a round line cap ensures that the border connects properly at the ends of the lines.) + +**Lines 16-26** comprise the second ``layer``, which is the the inner line (or "fill"). **Line 23** +specifies the color of the line to be a medium blue (``"#6699FF"``), **line 24** specifies the width of this line to be 3 pixels, and in the ``layout`` **line 20** again renders the edges of the line to be rounded instead of flat. + +The result is a 3 pixel blue line with a 1 pixel gray border, since the 5 pixel gray line will display 1 pixel on each side of the 3 pixel blue line. + +Dashed line +----------- + +This example alters the :ref:`mbstyle_cookbook_lines_simpleline` to create a dashed line consisting of 5 pixels of drawn +line alternating with 2 pixels of blank space. + +.. figure:: ../../sld/cookbook/images/line_dashedline.png + + Dashed line + +Code +~~~~ + +:download:`Download the "Dashed line" MBStyle ` + +.. code-block:: json + :linenos: + + { + "version": 8, + "name": "simple-dashedline", + "layers": [ + { + "id": "simple-dashedline", + "type": "line", + "paint": { + "line-color": "#0000FF", + "line-width": 3, + "line-dasharray": [5, 2] + } + } + ] + } + +Details +~~~~~~~ + +In this example, **line 9** sets the color of the lines to be blue (``"#0000FF"``) and **line 10** sets the width of the lines to be 3 pixels. **Line 11** determines the composition of the line dashes. The value of ``[5, 2]`` creates a repeating pattern of 5 pixels of drawn line, followed by 2 pixels of omitted line. + +Offset line +----------- + +This example alters the :ref:`mbstyle_cookbook_lines_simpleline` to add a perpendicular offset line on the left side of the line, at five pixels distance. + +.. figure:: ../../sld/cookbook/images/line_offset.png + + Dashed line + +Code +~~~~ + +:download:`Download the "Offset line" MBStlye ` + +.. code-block:: json + :linenos: + + { + "version": 8, + "name": "simple-offsetline", + "layers": [ + { + "id": "simple-line", + "type": "line", + "paint": { + "line-color": "#000000", + "line-width": 1 + } + }, + { + "id": "simple-offsetline", + "type": "line", + "paint": { + "line-color": "#FF0000", + "line-width": 1, + "line-dasharray": [5, 2], + "line-offset": 5 + } + } + ] + } + +Details +~~~~~~~ + +In this example, **lines 5-11** draw a simple black line like in the Simple line example. **Lines 13-21** draw a red dashed line like in the above Dashed line example. **Line 20** modifies the dashed line with a 5 pixel offset from the line geometry. diff --git a/doc/en/user/source/styling/mbstyle/cookbook/points.rst b/doc/en/user/source/styling/mbstyle/cookbook/points.rst index 29910ff1c25..f1c932049d9 100644 --- a/doc/en/user/source/styling/mbstyle/cookbook/points.rst +++ b/doc/en/user/source/styling/mbstyle/cookbook/points.rst @@ -1,128 +1,128 @@ -.. _mbstyle_cookbook.points: - -Points -====== - -Points are seemingly the simplest type of shape, possessing only position and no other dimensions. MBStyle has a ``circle`` type that can be styled to represent a point. - -.. _mbstyle_cookbook_points_attributes: - -Example points layer --------------------- - -The :download:`points layer ` used for the examples below contains name and population information for the major cities of a fictional country. For reference, the attribute table for the points in this layer is included below. - -.. list-table:: - :widths: 30 40 30 - :header-rows: 1 - - * - ``fid`` (Feature ID) - - ``name`` (City name) - - ``pop`` (Population) - * - point.1 - - Borfin - - 157860 - * - point.2 - - Supox City - - 578231 - * - point.3 - - Ruckis - - 98159 - * - point.4 - - Thisland - - 34879 - * - point.5 - - Synopolis - - 24567 - * - point.6 - - San Glissando - - 76024 - * - point.7 - - Detrania - - 205609 - -:download:`Download the points shapefile ` - -.. _mbstyle_cookbook_points_simplepoint: - -Simple point ------------- - -This example specifies points be styled as red circles with a diameter of 6 pixels. - -.. figure:: ../../sld/cookbook/images/point_simplepoint.png - - Simple point - -Code -~~~~ - -:download:`Download the "Simple point" MBStyle JSON ` - -.. code-block:: json - :linenos: - - { - "version": 8, - "name": "point-circle-test", - "layers": [ - { - "id": "point", - "type": "circle", - "paint": { - "circle-radius": 3, - "circle-color": "#FF0000", - "circle-pitch-scale": "map" - } - } - ] - } - -Details -~~~~~~~ - -There is one layer in this MBStyle, which is the simplest possible situation. The "version" must always be set to 8. Layers is required for any MBStyle as an array. "id" is required and is a unique name for that layer. For our examples we will be setting the "type" to "circle". - - -.. _mbstyle_cookbook_points_simplepointwithstroke: - -Simple point with stroke ------------------------- - -This example adds a stroke (or border) around the :ref:`mbstyle_cookbook_points_simplepoint`, with the stroke colored black and given a thickness of 2 pixels. - -.. figure:: ../../sld/cookbook/images/point_simplepointwithstroke.png - - Simple point with stroke - -Code -~~~~ - -:download:`Download the "Simple point with stroke" MBStyle JSON ` - -.. code-block:: json - :linenos: - - { - "version": 8, - "name": "point-circle-test", - "layers": [ - { - "id": "point", - "type": "circle", - "paint": { - "circle-radius": 3, - "circle-color": "#FF0000", - "circle-pitch-scale": "map", - "circle-stroke-color": "#000000", - "circle-stroke-width": 2 - } - } - ] - } - -Details -~~~~~~~ - -This example is similar to the :ref:`mbstyle_cookbook_points_simplepoint` example. **Lines 12-13** specify the stroke, -with **line 12** setting the color to black (``'#000000'``) and **line 13** setting the width to 2 pixels. +.. _mbstyle_cookbook.points: + +Points +====== + +Points are seemingly the simplest type of shape, possessing only position and no other dimensions. MBStyle has a ``circle`` type that can be styled to represent a point. + +.. _mbstyle_cookbook_points_attributes: + +Example points layer +-------------------- + +The :download:`points layer ` used for the examples below contains name and population information for the major cities of a fictional country. For reference, the attribute table for the points in this layer is included below. + +.. list-table:: + :widths: 30 40 30 + :header-rows: 1 + + * - ``fid`` (Feature ID) + - ``name`` (City name) + - ``pop`` (Population) + * - point.1 + - Borfin + - 157860 + * - point.2 + - Supox City + - 578231 + * - point.3 + - Ruckis + - 98159 + * - point.4 + - Thisland + - 34879 + * - point.5 + - Synopolis + - 24567 + * - point.6 + - San Glissando + - 76024 + * - point.7 + - Detrania + - 205609 + +:download:`Download the points shapefile ` + +.. _mbstyle_cookbook_points_simplepoint: + +Simple point +------------ + +This example specifies points be styled as red circles with a diameter of 6 pixels. + +.. figure:: ../../sld/cookbook/images/point_simplepoint.png + + Simple point + +Code +~~~~ + +:download:`Download the "Simple point" MBStyle JSON ` + +.. code-block:: json + :linenos: + + { + "version": 8, + "name": "point-circle-test", + "layers": [ + { + "id": "point", + "type": "circle", + "paint": { + "circle-radius": 3, + "circle-color": "#FF0000", + "circle-pitch-scale": "map" + } + } + ] + } + +Details +~~~~~~~ + +There is one layer in this MBStyle, which is the simplest possible situation. The "version" must always be set to 8. Layers is required for any MBStyle as an array. "id" is required and is a unique name for that layer. For our examples we will be setting the "type" to "circle". + + +.. _mbstyle_cookbook_points_simplepointwithstroke: + +Simple point with stroke +------------------------ + +This example adds a stroke (or border) around the :ref:`mbstyle_cookbook_points_simplepoint`, with the stroke colored black and given a thickness of 2 pixels. + +.. figure:: ../../sld/cookbook/images/point_simplepointwithstroke.png + + Simple point with stroke + +Code +~~~~ + +:download:`Download the "Simple point with stroke" MBStyle JSON ` + +.. code-block:: json + :linenos: + + { + "version": 8, + "name": "point-circle-test", + "layers": [ + { + "id": "point", + "type": "circle", + "paint": { + "circle-radius": 3, + "circle-color": "#FF0000", + "circle-pitch-scale": "map", + "circle-stroke-color": "#000000", + "circle-stroke-width": 2 + } + } + ] + } + +Details +~~~~~~~ + +This example is similar to the :ref:`mbstyle_cookbook_points_simplepoint` example. **Lines 12-13** specify the stroke, +with **line 12** setting the color to black (``'#000000'``) and **line 13** setting the width to 2 pixels. diff --git a/doc/en/user/source/styling/qgis/index.rst b/doc/en/user/source/styling/qgis/index.rst index d5a0a3596cb..b153dd0f652 100644 --- a/doc/en/user/source/styling/qgis/index.rst +++ b/doc/en/user/source/styling/qgis/index.rst @@ -1,194 +1,194 @@ -.. _qgis: - -Generating SLD styles with QGIS -=============================== - -QGIS includes a sophisticated style editor with many map rendering possibilities. Styles generated -with QGIS can then be exported (with limitations) to SLD for usage with GeoServer. - -QGIS style exporting abilities have been evolving over time, as a reference: - -* For vector data QGIS exports SLD 1.1 styles that can be read by GeoServer. In order to get - the suitable results it's important to use QGIS 3.0 or newer, and GeoServer 2.13.x or newer. -* Raster data styling export is new in QGIS 3.4.5 (yet to be released at the time of writing). - This new version exports SLD 1.0 styles with vendor extensions to support constrast streching that most recent GeoServer versions support properly. For older QGIS versions limited export functionality is available using the SLD4Raster plugin. - -For the export it is advised to use the :guilabel:`Save As` functionality available in the style dialog, -as indicated below in this guide. Other plugins exist that streamline the export process, but they -may ruin the style trying to adapt it to older GeoServer versions (e.g., translating it -down to SLD 1.0 by simple text processing means), or rewrite it entirely. - -.. warning:: Despite the progress in the last years, it is known that not all QGIS rendering - options are supported by SLD and/or by GeoServer (e.g. shapeburst symbology), - and that support for exporting some parts is simply missing (e.g.. expression based symbology is - supported in SLD, but QGIS won't export it). If you are interested, both projects would welcome - sponsoring to improve the situation. - - -Exporting vector symbology --------------------------- - -This is a step by step guide to style a GeoServer demo layer, ``sfdem``. - -#. Open :command:`QGIS` (minimum version 3.0) -#. Load the :file:`states.shp` dataset from the GeoServer data directory, :file:`/data/shapefiles/states.shp` -#. Double click the layer to open the :guilabel:`Properties` dialog and switch to the :guilabel:`Symbology` page. -#. Choose a `Graduated` rendering, on the ``PERSONS`` column, and click on :guilabel:`Classify` button to generate `1.5` standard deviations, select the `spectral` color ramp, switch mode to `Quantile` and finally and click on the ":guilabel:`Classify` button to generate a 5 classes map, as shown in figure. - - .. figure:: images/qgis-vector-style.png - :align: center - - QGIS vector styling - -#. Switch to the :guilabel:`Labels` page, choose `Single labels``, label with the ``STATE NAME`` attribute and choose your preferred text rendering options, as shown in figure - - .. figure:: images/qgis-label-style.png - :align: center - - QGIS labelling - -#. The layer renders as follows: - - .. figure:: images/qgis-vector-render.png - :align: center - - QGIS raster styling - -#. Go back At the :guilabel:`Properties` dialog, from the bottom of the :guilabel:`Styles` page, choose :menuselection:`Style --> Save Style`. - - .. figure:: images/qgis-vector-saveas.png - :align: center - - *Export using Save As...* - -#. Choose export in the SLD format, placing the file in the desired location. - - .. figure:: images/qgis-choose-format.png - :align: center - - Choosing export format... - -#. Go in GeoServer, create a new style, use the :guilabel:`Upload a new style` dialog to choose the exported file, and click on `upload` link. - - .. figure:: images/gs-vector-upload.png - :align: center - - Uploading style in GeoServer... - -#. Click on guilabel:`Apply`. - -#. Change to the :guilabel:`Layer preview` tab, click on the :guilabel:`Preview on Layer` link to choose ``topp:states`` to verify proper rendering. - - .. figure:: images/gs-vector-preview.png - :align: center - - Previewing style in GeoServer... - -#. Eventually switch to the :guilabel:`Publishing` tab, search for ``states``, and select :guilabel:`Default` or :guilabel:`Associated` checkbox to publish the layer to use the new style permanently. - - .. figure:: images/gs-vector-associate.png - :align: center - - Associating style in GeoServer... - -Exporting raster symbology --------------------------- -The following are a couple of examples on how to export raster layers' symbology in QGIS and how to use the resulting SLD to style layers in GeoServer. - -.. warning:: As mentioned above, this functionality has some limitations: - - * :guilabel:`Hillshading` vendor options are not fully supported by GeoServer so you can't choose the `Band` and the position of the sun (`Altitude` and `Azimuth`), the `Multidirectional` option is not supported too - * GeoServer is not able to interpret the :guilabel:`Color Rendering` options yet - -This is a step by step guide to style a GeoServer demo layer, ``sfdem``. - -#. Open QGIS (minimum version 3.4.5) -#. Load the :file:`sfdem.tif` raster from the GeoServer data directory, :file:`/data/sf/sfdem.tif` -#. Double click the layer to open the :guilabel:`Properties` dialog and switch to the :guilabel:`Symbology` page. -#. Choose a `Singleband pseudocolor` rendering, Generate :guilabel:`Min / Max Value Settings` using :guilabel:`Mean +/- standard deviation` with using ``1.5`` standard deviations. Generate a 5 classes :guilabel:`Linear` interpolated map, as shown in figure. - - .. figure:: images/qgis-raster-style.png - :align: center - - QGIS raster styling - -#. The layer renders as follows: - - .. figure:: images/qgis-raster-render.png - :align: center - - QGIS raster styling - -#. Return to the layer's :guilabel:`Properties` dialog :guilabel:`Symbology` page, at the bottom of the page choose :menuselection:`Style --> Save Style`. - - .. figure:: images/qgis-raster-saveas.png - :align: center - - Export using Save As... - -#. Choose export in the SLD format, placing the file in the desired location - - .. figure:: images/qgis-choose-format.png - :align: center - - Choosing export format... - -#. Go in GeoServer, create a new style, use the :guilabel:`Upload a new style` dialog to choose the exported file, and click on `upload` link. - - .. figure:: images/gs-raster-upload.png - :align: center - - Uploading style in GeoServer... - -#. Click on guilabel:`Apply` then change to the :guilabel:`Layer preview` tab. Click on the :guilabel:`Preview on Layer` link to choose ``sfdem`` to verify proper rendering. - - .. figure:: images/gs-raster-preview.png - :align: center - - Previewing style in GeoServer... - -#. Finally switch to the :guilabel:`Publishing` tab, search for ``sfdem`` layer, and select :guilabel:`Default` or :guilabel:`Associated` checkbox to publish ``sfdem`` with the new style. - - .. figure:: images/gs-raster-associate.png - :align: center - - Associating style in GeoServer... - -The next example shows how to style an aerial image instead. - -#. Download an aerial image (for example from `USGS Landsat image archives `_) if you do not already have one. Give it a name (``aerial`` in this example) and :guilabel:`save it as GeoTIFF` - - .. figure:: images/landsat_usgs_sentinel2.png - :align: center - - aerial.tiff - -#. Open GeoServer, :guilabel:`create a new Store` (see :ref:`Add a Store `), :guilabel:`add a GeoTIFF Raster Data Source` to the Store and :guilabel:`connect` it to your ``aerial.tif`` file -#. In GeoServer, :guilabel:`create a new Layer` (see :ref:`Add a Layer `) choosing the Store you have created in the previous step -#. Open QGIS (minimum version 3.4.5) -#. Load the ``aerial.tif`` raster -#. Double click the layer to open the :guilabel:`Properties` dialog and switch to the :guilabel:`Symbology` page -#. Choose a `Multiband color` rendering, set the :guilabel:`bands` (Red band == Band 1 (red), Green band == Band 2 (Green), Blue band == Band 3 (Blue)), generate :guilabel:`Min / Max Value Settings` using ``5,0 - 95,0 % range`` of :guilabel:`Cumulative count cut` and select ``Stretch to MinMax`` as :guilabel:`Contrast enhancement` option, as shown in the picture below - - .. figure:: images/qgis-sentinel2-raster-style.png - :align: center - - QGIS layer properties - Symbology - -#. The layer renders as follows: - - .. figure:: images/qgis-sentinel2-raster-rendering.png - :align: center - - QGIS layer rendering - -#. :guilabel:`Save the Style` as SLD - -#. Go in GeoServer, use the generated SLD to :guilabel:`create a new style`, choose the ``aerial`` layer through the :guilabel:`Preview on Layer` link and verify if the layer is properly rendered (see the previous example for further details) - - .. figure:: images/gs-sentinel2-raster-rendering.png - :align: center - - GeoServer layer rendering - -#. Finally :guilabel:`Publish` the ``aerial`` layer with the new style as described in the previous example. +.. _qgis: + +Generating SLD styles with QGIS +=============================== + +QGIS includes a sophisticated style editor with many map rendering possibilities. Styles generated +with QGIS can then be exported (with limitations) to SLD for usage with GeoServer. + +QGIS style exporting abilities have been evolving over time, as a reference: + +* For vector data QGIS exports SLD 1.1 styles that can be read by GeoServer. In order to get + the suitable results it's important to use QGIS 3.0 or newer, and GeoServer 2.13.x or newer. +* Raster data styling export is new in QGIS 3.4.5 (yet to be released at the time of writing). + This new version exports SLD 1.0 styles with vendor extensions to support constrast streching that most recent GeoServer versions support properly. For older QGIS versions limited export functionality is available using the SLD4Raster plugin. + +For the export it is advised to use the :guilabel:`Save As` functionality available in the style dialog, +as indicated below in this guide. Other plugins exist that streamline the export process, but they +may ruin the style trying to adapt it to older GeoServer versions (e.g., translating it +down to SLD 1.0 by simple text processing means), or rewrite it entirely. + +.. warning:: Despite the progress in the last years, it is known that not all QGIS rendering + options are supported by SLD and/or by GeoServer (e.g. shapeburst symbology), + and that support for exporting some parts is simply missing (e.g.. expression based symbology is + supported in SLD, but QGIS won't export it). If you are interested, both projects would welcome + sponsoring to improve the situation. + + +Exporting vector symbology +-------------------------- + +This is a step by step guide to style a GeoServer demo layer, ``sfdem``. + +#. Open :command:`QGIS` (minimum version 3.0) +#. Load the :file:`states.shp` dataset from the GeoServer data directory, :file:`/data/shapefiles/states.shp` +#. Double click the layer to open the :guilabel:`Properties` dialog and switch to the :guilabel:`Symbology` page. +#. Choose a `Graduated` rendering, on the ``PERSONS`` column, and click on :guilabel:`Classify` button to generate `1.5` standard deviations, select the `spectral` color ramp, switch mode to `Quantile` and finally and click on the ":guilabel:`Classify` button to generate a 5 classes map, as shown in figure. + + .. figure:: images/qgis-vector-style.png + :align: center + + QGIS vector styling + +#. Switch to the :guilabel:`Labels` page, choose `Single labels``, label with the ``STATE NAME`` attribute and choose your preferred text rendering options, as shown in figure + + .. figure:: images/qgis-label-style.png + :align: center + + QGIS labelling + +#. The layer renders as follows: + + .. figure:: images/qgis-vector-render.png + :align: center + + QGIS raster styling + +#. Go back At the :guilabel:`Properties` dialog, from the bottom of the :guilabel:`Styles` page, choose :menuselection:`Style --> Save Style`. + + .. figure:: images/qgis-vector-saveas.png + :align: center + + *Export using Save As...* + +#. Choose export in the SLD format, placing the file in the desired location. + + .. figure:: images/qgis-choose-format.png + :align: center + + Choosing export format... + +#. Go in GeoServer, create a new style, use the :guilabel:`Upload a new style` dialog to choose the exported file, and click on `upload` link. + + .. figure:: images/gs-vector-upload.png + :align: center + + Uploading style in GeoServer... + +#. Click on guilabel:`Apply`. + +#. Change to the :guilabel:`Layer preview` tab, click on the :guilabel:`Preview on Layer` link to choose ``topp:states`` to verify proper rendering. + + .. figure:: images/gs-vector-preview.png + :align: center + + Previewing style in GeoServer... + +#. Eventually switch to the :guilabel:`Publishing` tab, search for ``states``, and select :guilabel:`Default` or :guilabel:`Associated` checkbox to publish the layer to use the new style permanently. + + .. figure:: images/gs-vector-associate.png + :align: center + + Associating style in GeoServer... + +Exporting raster symbology +-------------------------- +The following are a couple of examples on how to export raster layers' symbology in QGIS and how to use the resulting SLD to style layers in GeoServer. + +.. warning:: As mentioned above, this functionality has some limitations: + + * :guilabel:`Hillshading` vendor options are not fully supported by GeoServer so you can't choose the `Band` and the position of the sun (`Altitude` and `Azimuth`), the `Multidirectional` option is not supported too + * GeoServer is not able to interpret the :guilabel:`Color Rendering` options yet + +This is a step by step guide to style a GeoServer demo layer, ``sfdem``. + +#. Open QGIS (minimum version 3.4.5) +#. Load the :file:`sfdem.tif` raster from the GeoServer data directory, :file:`/data/sf/sfdem.tif` +#. Double click the layer to open the :guilabel:`Properties` dialog and switch to the :guilabel:`Symbology` page. +#. Choose a `Singleband pseudocolor` rendering, Generate :guilabel:`Min / Max Value Settings` using :guilabel:`Mean +/- standard deviation` with using ``1.5`` standard deviations. Generate a 5 classes :guilabel:`Linear` interpolated map, as shown in figure. + + .. figure:: images/qgis-raster-style.png + :align: center + + QGIS raster styling + +#. The layer renders as follows: + + .. figure:: images/qgis-raster-render.png + :align: center + + QGIS raster styling + +#. Return to the layer's :guilabel:`Properties` dialog :guilabel:`Symbology` page, at the bottom of the page choose :menuselection:`Style --> Save Style`. + + .. figure:: images/qgis-raster-saveas.png + :align: center + + Export using Save As... + +#. Choose export in the SLD format, placing the file in the desired location + + .. figure:: images/qgis-choose-format.png + :align: center + + Choosing export format... + +#. Go in GeoServer, create a new style, use the :guilabel:`Upload a new style` dialog to choose the exported file, and click on `upload` link. + + .. figure:: images/gs-raster-upload.png + :align: center + + Uploading style in GeoServer... + +#. Click on guilabel:`Apply` then change to the :guilabel:`Layer preview` tab. Click on the :guilabel:`Preview on Layer` link to choose ``sfdem`` to verify proper rendering. + + .. figure:: images/gs-raster-preview.png + :align: center + + Previewing style in GeoServer... + +#. Finally switch to the :guilabel:`Publishing` tab, search for ``sfdem`` layer, and select :guilabel:`Default` or :guilabel:`Associated` checkbox to publish ``sfdem`` with the new style. + + .. figure:: images/gs-raster-associate.png + :align: center + + Associating style in GeoServer... + +The next example shows how to style an aerial image instead. + +#. Download an aerial image (for example from `USGS Landsat image archives `_) if you do not already have one. Give it a name (``aerial`` in this example) and :guilabel:`save it as GeoTIFF` + + .. figure:: images/landsat_usgs_sentinel2.png + :align: center + + aerial.tiff + +#. Open GeoServer, :guilabel:`create a new Store` (see :ref:`Add a Store `), :guilabel:`add a GeoTIFF Raster Data Source` to the Store and :guilabel:`connect` it to your ``aerial.tif`` file +#. In GeoServer, :guilabel:`create a new Layer` (see :ref:`Add a Layer `) choosing the Store you have created in the previous step +#. Open QGIS (minimum version 3.4.5) +#. Load the ``aerial.tif`` raster +#. Double click the layer to open the :guilabel:`Properties` dialog and switch to the :guilabel:`Symbology` page +#. Choose a `Multiband color` rendering, set the :guilabel:`bands` (Red band == Band 1 (red), Green band == Band 2 (Green), Blue band == Band 3 (Blue)), generate :guilabel:`Min / Max Value Settings` using ``5,0 - 95,0 % range`` of :guilabel:`Cumulative count cut` and select ``Stretch to MinMax`` as :guilabel:`Contrast enhancement` option, as shown in the picture below + + .. figure:: images/qgis-sentinel2-raster-style.png + :align: center + + QGIS layer properties - Symbology + +#. The layer renders as follows: + + .. figure:: images/qgis-sentinel2-raster-rendering.png + :align: center + + QGIS layer rendering + +#. :guilabel:`Save the Style` as SLD + +#. Go in GeoServer, use the generated SLD to :guilabel:`create a new style`, choose the ``aerial`` layer through the :guilabel:`Preview on Layer` link and verify if the layer is properly rendered (see the previous example for further details) + + .. figure:: images/gs-sentinel2-raster-rendering.png + :align: center + + GeoServer layer rendering + +#. Finally :guilabel:`Publish` the ``aerial`` layer with the new style as described in the previous example. diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/line_offset.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/line_offset.sld index 8c64be6c343..55843b16823 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/line_offset.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/line_offset.sld @@ -1,30 +1,30 @@ - - - - Dashed line - - SLD Cook Book: Offset line - - - - - #000000 - - - - - #FF0000 - 5 2 - - 5 - - - - - + + + + Dashed line + + SLD Cook Book: Offset line + + + + + #000000 + + + + + #FF0000 + 5 2 + + 5 + + + + + \ No newline at end of file diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/line_optimizedlabel.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/line_optimizedlabel.sld index 5cecb9408ac..23b98d5b25d 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/line_optimizedlabel.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/line_optimizedlabel.sld @@ -1,38 +1,38 @@ - - - - Optimized label placement - - SLD Cook Book: Optimized label placement - - - - - #FF0000 - - - - - - - - - #000000 - - true - 90 - 400 - 150 - - - - - - + + + + Optimized label placement + + SLD Cook Book: Optimized label placement + + + + + #FF0000 + + + + + + + + + #000000 + + true + 90 + 400 + 150 + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/line_optimizedstyledlabel.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/line_optimizedstyledlabel.sld index 858c5e6c5ce..c9442be3e60 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/line_optimizedstyledlabel.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/line_optimizedstyledlabel.sld @@ -1,44 +1,44 @@ - - - - Optimized and styled label - - SLD Cook Book: Optimized and styled label - - - - - #FF0000 - - - - - - Arial - 10 - normal - bold - - - - - - #000000 - - true - 90 - 400 - 150 - - - - - - + + + + Optimized and styled label + + SLD Cook Book: Optimized and styled label + + + + + #FF0000 + + + + + + Arial + 10 + normal + bold + + + + + + #000000 + + true + 90 + 400 + 150 + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/point_attribute.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/point_attribute.sld index 9350541120f..7756f706ed0 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/point_attribute.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/point_attribute.sld @@ -1,85 +1,85 @@ - - - - Attribute-based point - - GeoServer SLD Cook Book: Attribute-based point - - - SmallPop - 1 to 50000 - - - pop - 50000 - - - - - - circle - - #0033CC - - - 8 - - - - - MediumPop - 50000 to 100000 - - - - pop - 50000 - - - pop - 100000 - - - - - - - circle - - #0033CC - - - 12 - - - - - LargePop - Greater than 100000 - - - pop - 100000 - - - - - - circle - - #0033CC - - - 16 - - - - - - - + + + + Attribute-based point + + GeoServer SLD Cook Book: Attribute-based point + + + SmallPop + 1 to 50000 + + + pop + 50000 + + + + + + circle + + #0033CC + + + 8 + + + + + MediumPop + 50000 to 100000 + + + + pop + 50000 + + + pop + 100000 + + + + + + + circle + + #0033CC + + + 12 + + + + + LargePop + Greater than 100000 + + + pop + 100000 + + + + + + circle + + #0033CC + + + 16 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointasgraphic.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointasgraphic.sld index 3c3d911a972..3f47691d5ff 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointasgraphic.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointasgraphic.sld @@ -1,29 +1,29 @@ - - - - Point as graphic - - GeoServer SLD Cook Book: Point as graphic - - - - - - - image/png - - 32 - - - - - - - + + + + Point as graphic + + GeoServer SLD Cook Book: Point as graphic + + + + + + + image/png + + 32 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithdefaultlabel.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithdefaultlabel.sld index 6e50ed0e3dd..64a0cca735f 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithdefaultlabel.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithdefaultlabel.sld @@ -1,38 +1,38 @@ - - - - Point with default label - - GeoServer SLD Cook Book: Point with default label - - - - - - circle - - #FF0000 - - - 6 - - - - - - - #000000 - - - - - - - + + + + Point with default label + + GeoServer SLD Cook Book: Point with default label + + + + + + circle + + #FF0000 + + + 6 + + + + + + + #000000 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithrotatedlabel.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithrotatedlabel.sld index 9e461224511..6304f8688ea 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithrotatedlabel.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithrotatedlabel.sld @@ -1,56 +1,56 @@ - - - - Point with rotated label - - GeoServer SLD Cook Book: Point with rotated label - - - - - - circle - - #FF0000 - - - 6 - - - - - - Arial - 12 - normal - bold - - - - - 0.5 - 0.0 - - - 0 - 25 - - -45 - - - - #990099 - - - - - - - + + + + Point with rotated label + + GeoServer SLD Cook Book: Point with rotated label + + + + + + circle + + #FF0000 + + + 6 + + + + + + Arial + 12 + normal + bold + + + + + 0.5 + 0.0 + + + 0 + 25 + + -45 + + + + #990099 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithstyledlabel.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithstyledlabel.sld index b149779ebf5..c040b4d7bbb 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithstyledlabel.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/point_pointwithstyledlabel.sld @@ -1,55 +1,55 @@ - - - - Point with styled label - - GeoServer SLD Cook Book: Point with styled label - - - - - - circle - - #FF0000 - - - 6 - - - - - - Arial - 12 - normal - bold - - - - - 0.5 - 0.0 - - - 0 - 5 - - - - - #000000 - - - - - - - + + + + Point with styled label + + GeoServer SLD Cook Book: Point with styled label + + + + + + circle + + #FF0000 + + + 6 + + + + + + Arial + 12 + normal + bold + + + + + 0.5 + 0.0 + + + 0 + 5 + + + + + #000000 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/point_rotatedsquare.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/point_rotatedsquare.sld index cfc40a0b96f..45d0b410622 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/point_rotatedsquare.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/point_rotatedsquare.sld @@ -1,30 +1,30 @@ - - - - Rotated square - - GeoServer SLD Cook Book: Rotated square - - - - - - square - - #009900 - - - 12 - 45 - - - - - - - + + + + Rotated square + + GeoServer SLD Cook Book: Rotated square + + + + + + square + + #009900 + + + 12 + 45 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/point_simplepoint.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/point_simplepoint.sld index 7d59c34c30a..d3211e6b22d 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/point_simplepoint.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/point_simplepoint.sld @@ -1,29 +1,29 @@ - - - - Simple Point - - SLD Cook Book: Simple Point - - - - - - circle - - #FF0000 - - - 6 - - - - - - - + + + + Simple Point + + SLD Cook Book: Simple Point + + + + + + circle + + #FF0000 + + + 6 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/point_simplepointwithstroke.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/point_simplepointwithstroke.sld index d9a2aedc8bb..18a364c117f 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/point_simplepointwithstroke.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/point_simplepointwithstroke.sld @@ -1,33 +1,33 @@ - - - - Simple point with stroke - - GeoServer SLD Cook Book: Simple point with stroke - - - - - - circle - - #FF0000 - - - #000000 - 2 - - - 6 - - - - - - - + + + + Simple point with stroke + + GeoServer SLD Cook Book: Simple point with stroke + + + + + + circle + + #FF0000 + + + #000000 + 2 + + + 6 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/point_transparenttriangle.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/point_transparenttriangle.sld index 0dc2a9c984c..a8f59949f89 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/point_transparenttriangle.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/point_transparenttriangle.sld @@ -1,34 +1,34 @@ - - - - Transparent triangle - - GeoServer SLD Cook Book: Transparent triangle - - - - - - triangle - - #009900 - 0.2 - - - #000000 - 2 - - - 12 - - - - - - - + + + + Transparent triangle + + GeoServer SLD Cook Book: Transparent triangle + + + + + + triangle + + #009900 + 0.2 + + + #000000 + 2 + + + 12 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/point_zoom.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/point_zoom.sld index af83e3b507c..ec6ae6f55a6 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/point_zoom.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/point_zoom.sld @@ -1,62 +1,62 @@ - - - - Zoom-based point - - GeoServer SLD Cook Book: Zoom-based point - - - Large - 160000000 - - - - circle - - #CC3300 - - - 12 - - - - - Medium - 160000000 - 320000000 - - - - circle - - #CC3300 - - - 8 - - - - - Small - 320000000 - - - - circle - - #CC3300 - - - 4 - - - - - - - + + + + Zoom-based point + + GeoServer SLD Cook Book: Zoom-based point + + + Large + 160000000 + + + + circle + + #CC3300 + + + 12 + + + + + Medium + 160000000 + 320000000 + + + + circle + + #CC3300 + + + 8 + + + + + Small + 320000000 + + + + circle + + #CC3300 + + + 4 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_attributebasedpolygon.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_attributebasedpolygon.sld index 6040767603e..e2dcc3f0443 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_attributebasedpolygon.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_attributebasedpolygon.sld @@ -1,67 +1,67 @@ - - - - Attribute-based polygon - - SLD Cook Book: Attribute-based polygon - - - SmallPop - Less Than 200,000 - - - pop - 200000 - - - - - #66FF66 - - - - - MediumPop - 200,000 to 500,000 - - - - pop - 200000 - - - pop - 500000 - - - - - - #33CC33 - - - - - LargePop - Greater Than 500,000 - - - pop - 500000 - - - - - #009900 - - - - - - - + + + + Attribute-based polygon + + SLD Cook Book: Attribute-based polygon + + + SmallPop + Less Than 200,000 + + + pop + 200000 + + + + + #66FF66 + + + + + MediumPop + 200,000 to 500,000 + + + + pop + 200000 + + + pop + 500000 + + + + + + #33CC33 + + + + + LargePop + Greater Than 500,000 + + + pop + 500000 + + + + + #009900 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_graphicfill.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_graphicfill.sld index 29085abb163..2bfd0dbbe40 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_graphicfill.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_graphicfill.sld @@ -1,33 +1,33 @@ - - - - Graphic fill - - SLD Cook Book: Graphic fill - - - - - - - - - image/png - - 93 - - - - - - - - - + + + + Graphic fill + + SLD Cook Book: Graphic fill + + + + + + + + + image/png + + 93 + + + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_hatchingfill.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_hatchingfill.sld index 7b30bb13f61..714f33000c6 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_hatchingfill.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_hatchingfill.sld @@ -1,34 +1,34 @@ - - - - Hatching fill - - SLD Cook Book: Hatching fill - - - - - - - - shape://times - - #990099 - 1 - - - 16 - - - - - - - - - + + + + Hatching fill + + SLD Cook Book: Hatching fill + + + + + + + + shape://times + + #990099 + 1 + + + 16 + + + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_labelhalo.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_labelhalo.sld index 40f917e3ec7..2b89651b4db 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_labelhalo.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_labelhalo.sld @@ -1,38 +1,38 @@ - - - - Label halo - - SLD Cook Book: Label halo - - - - - #40FF40 - - - #FFFFFF - 2 - - - - - - 3 - - #FFFFFF - - - - - - - - + + + + Label halo + + SLD Cook Book: Label halo + + + + + #40FF40 + + + #FFFFFF + 2 + + + + + + 3 + + #FFFFFF + + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_offset.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_offset.sld index 587f29ff9a8..d30b7ed152e 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_offset.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_offset.sld @@ -1,31 +1,31 @@ - - - - Dashed line - - SLD Cook Book: Offset line - - - - - #000000 - 2 - - - - - #AAAAAA - 3 - - -2 - - - - - + + + + Dashed line + + SLD Cook Book: Offset line + + + + + #000000 + 2 + + + + + #AAAAAA + 3 + + -2 + + + + + \ No newline at end of file diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_polygonwithdefaultlabel.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_polygonwithdefaultlabel.sld index ec9cbccb222..e3e3f69ce2d 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_polygonwithdefaultlabel.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_polygonwithdefaultlabel.sld @@ -1,32 +1,32 @@ - - - - Polygon with default label - - SLD Cook Book: Polygon with default label - - - - - #40FF40 - - - #FFFFFF - 2 - - - - - - - - - - + + + + Polygon with default label + + SLD Cook Book: Polygon with default label + + + + + #40FF40 + + + #FFFFFF + 2 + + + + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_polygonwithstyledlabel.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_polygonwithstyledlabel.sld index db6168b33ef..38a3c6f4902 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_polygonwithstyledlabel.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_polygonwithstyledlabel.sld @@ -1,51 +1,51 @@ - - - - Polygon with styled label - - SLD Cook Book: Polygon with styled label - - - - - #40FF40 - - - #FFFFFF - 2 - - - - - - Arial - 11 - normal - bold - - - - - 0.5 - 0.5 - - - - - #000000 - - 60 - 150 - - - - - - + + + + Polygon with styled label + + SLD Cook Book: Polygon with styled label + + + + + #40FF40 + + + #FFFFFF + 2 + + + + + + Arial + 11 + normal + bold + + + + + 0.5 + 0.5 + + + + + #000000 + + 60 + 150 + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_simplepolygon.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_simplepolygon.sld index c834fd9e9ce..f24b1ff0a8a 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_simplepolygon.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_simplepolygon.sld @@ -1,23 +1,23 @@ - - - - Simple polygon - - SLD Cook Book: Simple polygon - - - - - #000080 - - - - - - - + + + + Simple polygon + + SLD Cook Book: Simple polygon + + + + + #000080 + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_simplepolygonwithstroke.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_simplepolygonwithstroke.sld index 5259a19ec5f..29343d91c3f 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_simplepolygonwithstroke.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_simplepolygonwithstroke.sld @@ -1,27 +1,27 @@ - - - - Simple polygon with stroke - - SLD Cook Book: Simple polygon with stroke - - - - - #000080 - - - #FFFFFF - 2 - - - - - - + + + + Simple polygon with stroke + + SLD Cook Book: Simple polygon with stroke + + + + + #000080 + + + #FFFFFF + 2 + + + + + + \ No newline at end of file diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_transparentpolygon.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_transparentpolygon.sld index b6c06e2090d..60d022e148c 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_transparentpolygon.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_transparentpolygon.sld @@ -1,28 +1,28 @@ - - - - Transparent polygon - - SLD Cook Book: Transparent polygon - - - - - #000080 - 0.5 - - - #FFFFFF - 2 - - - - - - + + + + Transparent polygon + + SLD Cook Book: Transparent polygon + + + + + #000080 + 0.5 + + + #FFFFFF + 2 + + + + + + \ No newline at end of file diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_zoombasedpolygon.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_zoombasedpolygon.sld index 2c7eaa23780..f4da4bd7ecb 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_zoombasedpolygon.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/polygon_zoombasedpolygon.sld @@ -1,78 +1,78 @@ - - - - Zoom-based polygon - - SLD Cook Book: Zoom-based polygon - - - Large - 100000000 - - - #0000CC - - - #000000 - 7 - - - - - - Arial - 14 - normal - bold - - - - - 0.5 - 0.5 - - - - - #FFFFFF - - - - - Medium - 100000000 - 200000000 - - - #0000CC - - - #000000 - 4 - - - - - Small - 200000000 - - - #0000CC - - - #000000 - 1 - - - - - - + + + + Zoom-based polygon + + SLD Cook Book: Zoom-based polygon + + + Large + 100000000 + + + #0000CC + + + #000000 + 7 + + + + + + Arial + 14 + normal + bold + + + + + 0.5 + 0.5 + + + + + #FFFFFF + + + + + Medium + 100000000 + 200000000 + + + #0000CC + + + #000000 + 4 + + + + + Small + 200000000 + + + #0000CC + + + #000000 + 1 + + + + + + \ No newline at end of file diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_alphachannel.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_alphachannel.sld index f0bf65ad0dd..d4464132a9f 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_alphachannel.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_alphachannel.sld @@ -1,24 +1,24 @@ - - - - Alpha channel - - SLD Cook Book: Alpha channel - - - - - - - - - - - - - + + + + Alpha channel + + SLD Cook Book: Alpha channel + + + + + + + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_brightnessandcontrast.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_brightnessandcontrast.sld index b017a47c30d..8924b8d5cf4 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_brightnessandcontrast.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_brightnessandcontrast.sld @@ -1,28 +1,28 @@ - - - - Brightness and contrast - - SLD Cook Book: Brightness and contrast - - - - - - 0.5 - - - - - - - - - - - + + + + Brightness and contrast + + SLD Cook Book: Brightness and contrast + + + + + + 0.5 + + + + + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_discretecolors.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_discretecolors.sld index 9aa54c1ec66..4adff11cc2b 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_discretecolors.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_discretecolors.sld @@ -1,24 +1,24 @@ - - - - Discrete colors - - SLD Cook Book: Discrete colors - - - - - - - - - - - - - + + + + Discrete colors + + SLD Cook Book: Discrete colors + + + + + + + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_manycolorgradient.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_manycolorgradient.sld index fd01581c7bd..a00b49c008b 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_manycolorgradient.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_manycolorgradient.sld @@ -1,30 +1,30 @@ - - - - Many color gradient - - SLD Cook Book: Many color gradient - - - - - - - - - - - - - - - - - - - + + + + Many color gradient + + SLD Cook Book: Many color gradient + + + + + + + + + + + + + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_threecolorgradient.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_threecolorgradient.sld index 352301f3412..b665a3acc48 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_threecolorgradient.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_threecolorgradient.sld @@ -1,25 +1,25 @@ - - - - Three color gradient - - SLD Cook Book: Three color gradient - - - - - - - - - - - - - - + + + + Three color gradient + + SLD Cook Book: Three color gradient + + + + + + + + + + + + + + diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_transparentgradient.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_transparentgradient.sld index c1e7d7d2531..5ba7c84d434 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_transparentgradient.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_transparentgradient.sld @@ -1,25 +1,25 @@ - - - - Transparent gradient - - SLD Cook Book: Transparent gradient - - - - 0.3 - - - - - - - - - + + + + Transparent gradient + + SLD Cook Book: Transparent gradient + + + + 0.3 + + + + + + + + + \ No newline at end of file diff --git a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_twocolorgradient.sld b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_twocolorgradient.sld index abe9e2fa538..1e5fe4b70f2 100644 --- a/doc/en/user/source/styling/sld/cookbook/artifacts/raster_twocolorgradient.sld +++ b/doc/en/user/source/styling/sld/cookbook/artifacts/raster_twocolorgradient.sld @@ -1,24 +1,24 @@ - - - - Two color gradient - - SLD Cook Book: Two color gradient - - - - - - - - - - - - + + + + Two color gradient + + SLD Cook Book: Two color gradient + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/en/user/source/styling/sld/cookbook/index.rst b/doc/en/user/source/styling/sld/cookbook/index.rst index cb0a5dc18e8..21101ddcee3 100644 --- a/doc/en/user/source/styling/sld/cookbook/index.rst +++ b/doc/en/user/source/styling/sld/cookbook/index.rst @@ -1,33 +1,33 @@ -.. _sld_cookbook: - -SLD Cookbook -============ - -The SLD Cookbook is a collection of SLD "recipes" for creating various types of map styles. Wherever possible, each example is designed to show off a single SLD feature so that code can be copied from the examples and adapted when creating SLDs of your own. While not an exhaustive reference like the :ref:`sld_reference` or the `OGC SLD 1.0 specification `_ the SLD Cookbook is designed to be a practical reference, showing common style templates that are easy to understand. - -The SLD Cookbook is divided into four sections: the first three for each of the vector types (points, lines, and polygons) and the fourth section for rasters. Each example in every section contains a screenshot showing actual GeoServer WMS output, a snippet of the SLD code for reference, and a link to download the full SLD. - -Each section uses data created especially for the SLD Cookbook, with shapefiles for vector data and GeoTIFFs for raster data. The projection for data is EPSG:4326. All files can be easily loaded into GeoServer in order to recreate the examples. - -.. list-table:: - :widths: 20 80 - - * - **Data Type** - - **Shapefile** - * - Point - - :download:`sld_cookbook_point.zip ` - * - Line - - :download:`sld_cookbook_line.zip ` - * - Polygon - - :download:`sld_cookbook_polygon.zip ` - * - Raster - - :download:`sld_cookbook_raster.zip ` - -.. toctree:: - :maxdepth: 2 - - points - lines - polygons - rasters - +.. _sld_cookbook: + +SLD Cookbook +============ + +The SLD Cookbook is a collection of SLD "recipes" for creating various types of map styles. Wherever possible, each example is designed to show off a single SLD feature so that code can be copied from the examples and adapted when creating SLDs of your own. While not an exhaustive reference like the :ref:`sld_reference` or the `OGC SLD 1.0 specification `_ the SLD Cookbook is designed to be a practical reference, showing common style templates that are easy to understand. + +The SLD Cookbook is divided into four sections: the first three for each of the vector types (points, lines, and polygons) and the fourth section for rasters. Each example in every section contains a screenshot showing actual GeoServer WMS output, a snippet of the SLD code for reference, and a link to download the full SLD. + +Each section uses data created especially for the SLD Cookbook, with shapefiles for vector data and GeoTIFFs for raster data. The projection for data is EPSG:4326. All files can be easily loaded into GeoServer in order to recreate the examples. + +.. list-table:: + :widths: 20 80 + + * - **Data Type** + - **Shapefile** + * - Point + - :download:`sld_cookbook_point.zip ` + * - Line + - :download:`sld_cookbook_line.zip ` + * - Polygon + - :download:`sld_cookbook_polygon.zip ` + * - Raster + - :download:`sld_cookbook_raster.zip ` + +.. toctree:: + :maxdepth: 2 + + points + lines + polygons + rasters + diff --git a/doc/en/user/source/styling/sld/cookbook/lines.rst b/doc/en/user/source/styling/sld/cookbook/lines.rst index 7d049ff520d..87006f736b3 100644 --- a/doc/en/user/source/styling/sld/cookbook/lines.rst +++ b/doc/en/user/source/styling/sld/cookbook/lines.rst @@ -1,964 +1,964 @@ -.. _sld_cookbook_lines: - -Lines -===== - -While lines can also seem to be simple shapes, having length but no width, there are many options and tricks for making -lines display nicely. - -.. warning:: The code examples shown on this page are **not the full SLD code**, as they omit the SLD header and footer information for the sake of brevity. Please use the links to download the full SLD for each example. - - -.. _sld_cookbook_lines_attributes: - -Example lines layer -------------------- - -The :download:`lines layer ` used in the examples below contains road information for a -fictional country. For reference, the attribute table for the points in this layer is included below. - -.. list-table:: - :widths: 30 40 30 - - * - **fid** (Feature ID) - - **name** (Road name) - - **type** (Road class) - * - line.1 - - Latway - - highway - * - line.2 - - Crescent Avenue - - secondary - * - line.3 - - Forest Avenue - - secondary - * - line.4 - - Longway - - highway - * - line.5 - - Saxer Avenue - - secondary - * - line.6 - - Ridge Avenue - - secondary - * - line.7 - - Holly Lane - - local-road - * - line.8 - - Mulberry Street - - local-road - * - line.9 - - Nathan Lane - - local-road - * - line.10 - - Central Street - - local-road - * - line.11 - - Lois Lane - - local-road - * - line.12 - - Rocky Road - - local-road - * - line.13 - - Fleet Street - - local-road - * - line.14 - - Diane Court - - local-road - * - line.15 - - Cedar Trail - - local-road - * - line.16 - - Victory Road - - local-road - * - line.17 - - Highland Road - - local-road - * - line.18 - - Easy Street - - local-road - * - line.19 - - Hill Street - - local-road - * - line.20 - - Country Road - - local-road - * - line.21 - - Main Street - - local-road - * - line.22 - - Jani Lane - - local-road - * - line.23 - - Shinbone Alley - - local-road - * - line.24 - - State Street - - local-road - * - line.25 - - River Road - - local-road - -:download:`Download the lines shapefile ` - -.. _sld_cookbook_lines_simpleline: - -Simple line ------------ - -This example specifies lines be colored black with a thickness of 3 pixels. - -.. figure:: images/line_simpleline.png - :align: center - - *Simple line* - -Code -~~~~ - -:download:`View and download the full "Simple line" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #000000 - 3 - - - - - -Details -~~~~~~~ - -There is one ```` in one ```` for this SLD, which is the simplest possible situation. (All -subsequent examples will contain one ```` and one ```` unless otherwise specified.) Styling -lines is accomplished via the ```` (**lines 3-8**). **Line 5** specifies the color of the line to be -black (``#000000``), while **line 6** specifies the width of the lines to be 3 pixels. - - -Line with border ----------------- - -This example shows how to draw lines with borders (sometimes called "cased lines"). -In this case the lines are drawn with a 3 pixel blue center and a 1 pixel wide gray border. - -.. figure:: images/line_linewithborder.png - :align: center - - *Line with border* - -Code -~~~~ - -:download:`View and download the full "Line with border" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #333333 - 5 - round - - - - - - - - - #6699FF - 3 - round - - - - - -Details -~~~~~~~ - -Lines in SLD have no notion of a "fill", only "stroke". Thus, unlike points or polygons, it is not possible to style the -"edge" of the line geometry. It is, however, possible to achieve this effect by drawing each line twice: once with a -certain width and again with a slightly smaller width. This gives the illusion of fill and stroke by obscuring the -larger lines everywhere except along the edges of the smaller lines. - -Since every line is drawn twice, the order of the rendering is *very* important. -GeoServer renders ````\ s in the order that they are presented in the SLD. -In this style, the gray border lines -are drawn first via the first ````, followed by the blue center lines in a second -````. This ensures that the blue lines are not obscured by the gray lines, -and also ensures proper rendering at intersections, so that the blue lines "connect". - -In this example, **lines 1-11** comprise the first ````, which is the outer line (or "stroke"). -**Line 5** specifies the color of the line to be dark gray (``#333333``), **line 6** specifies the width of this line -to be 5 pixels, and in **line 7** a ``stroke-linecap`` parameter of ``round`` -renders the ends of the line as rounded instead of flat. -(When working with bordered lines using a round line cap ensures that the border connects properly at the ends of the lines.) - -**Lines 12-22** comprise the second ````, which is the the inner line (or "fill"). **Line 16** -specifies the color of the line to be a medium blue (``#6699FF``), **line 17** specifies the width of this line to be 3 -pixels, and **line 18** again renders the edges of the line to be rounded instead of flat. - -The result is a 3 pixel blue line with a 1 pixel gray border, since the 5 pixel gray line will display 1 pixel on each -side of the 3 pixel blue line. - -Dashed line ------------ - -This example alters the :ref:`sld_cookbook_lines_simpleline` to create a dashed line consisting of 5 pixels of drawn -line alternating with 2 pixels of blank space. - -.. figure:: images/line_dashedline.png - :align: center - - *Dashed line* - -Code -~~~~ - -:download:`View and download the full "Dashed line" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #0000FF - 3 - 5 2 - - - - - -Details -~~~~~~~ - -In this example, **line 5** sets the color of the lines to be blue (``#0000FF``) and **line 6** sets the width of the -lines to be 3 pixels. **Line 7** determines the composition of the line dashes. The value of ``5 2`` creates a -repeating pattern of 5 pixels of drawn line, followed by 2 pixels of omitted line. - -Offset line ------------ - -This example alters the :ref:`sld_cookbook_lines_simpleline` to add a perpendicular offset line on the left side -of the line, at five pixels distance. - -.. figure:: images/line_offset.png - :align: center - - *Offset line* - -Code -~~~~ - -:download:`View and download the full "Dashed line" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #000000 - - - - - #FF0000 - 5 2 - - 5 - - - - -Details -~~~~~~~ - -In this example, the first line symbolizer just paints the lines black. -**line 8** begines a second lines symbolizer, sets the color of the lines to be red (``#FF0000``) at line 10 and -determines the composition of the line dashes at **Line 11**. -**Line 13** finally specifies a perpendicular offset of 5 pixels (positive, thus on the left side). - - -Railroad (hatching) -------------------- - -This example uses hatching to create a railroad style. Both the line and the hatches are black, with a 2 pixel -thickness for the main line and a 1 pixel width for the perpendicular hatches. - -.. note:: This example leverages an SLD extension in GeoServer. Hatching is not part of the standard SLD 1.0 specification. - -.. figure:: images/line_railroad.png - :align: center - - *Railroad (hatching)* - -Code -~~~~ - -:download:`View and download the full "Railroad (hatching)" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #333333 - 3 - - - - - - - - shape://vertline - - #333333 - 1 - - - 12 - - - - - - - -Details -~~~~~~~ - -In this example there are two ````\ s. -The first symbolizer, on **lines 3-8**, draws a standard line, with **line 5** drawing the lines as dark gray -(``#333333``) and **line 6** setting the width of the lines to be 2 pixels. - -The hatching is invoked in the second symbolizer, on **lines 9-24**. **Line 14** specifies that the symbolizer draw a vertical line -hatch (``shape://vertline``) perpendicular to the line geometry. **Lines 16-17** set the hatch color to dark gray -(``#333333``) and width to 1 pixel. Finally, **line 20** specifies both the length of the hatch and the distance -between each hatch to both be 12 pixels. - -Spaced graphic symbols ----------------------- - -This example uses a graphic stroke along with dash arrays to create a "dot and space" line type. -Adding the dash array specification allows to control the amount of space between one symbol and the next one. -Without using the dash -array the lines would be densely populated with dots, each one touching the previous one. - -.. note:: This example may not work in other systems using SLD, since they may not support combining the use of ``stroke-dasharray`` and ``GraphicStroke``. - While the SLD is spec-compliant, the SLD specification does not state what this combination is supposed to produce. - - -.. figure:: images/line_dashspace.png - :align: center - - *Spaced symbols along a line* - -Code -~~~~ - -:download:`View and download the full "Spaced symbols" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - - - circle - - #666666 - - - #333333 - 1 - - - 4 - - - 4 6 - - - - - -Details -~~~~~~~ -This example, like others before, uses a ``GraphicStroke`` to place a graphic symbol along a line. The symbol, defined -at **lines 7-16** is a 4 pixel gray circle with a dark gray outline. The spacing between symbols is controlled with -the ``stroke-dasharray`` at **line 20**, which specifies 4 pixels of pen-down (just enough to draw the circle) and 6 pixels of pen-up, -to provide the spacing. - - -.. _sld_cookbook_lines_defaultlabel: - -Alternating symbols with dash offsets -------------------------------------- - -This example shows how to create a complex line style which alternates a dashed line and a graphic symbol. -The code builds on features shown in the previous examples: - - * ``stroke-dasharray`` controls pen-down/pen-up behavior to generate dashed lines - * ``GraphicStroke`` places symbols along a line - * combining the two allows control of symbol spacing - -This also shows the usage of a `dash offset`, which controls where rendering starts -in the dash array. -For example, with a dash array of ``5 10`` and a dash offset of ``7`` the -renderer starts drawing the pattern 7 pixels from the beginning. It skips the 5 pixels pen-down -section and 2 pixels of the pen-up section, then draws the remaining 8 pixels of pen-up, then 5 down, 10 up, and so on. - -The example shows how to use these features to create two synchronized sequences of dash arrays, -one drawing line segments and the other symbols. - -.. note:: This example may not work in other systems using SLD, since they may not support combining the use of ``stroke-dasharray`` and ``GraphicStroke``. - While the SLD is spec-compliant, the SLD specification does not state what this combination is supposed to produce. - - -.. figure:: images/line_dashdot.png - :align: center - - *Alternating dash and symbol* - -Code -~~~~ - -:download:`View and download the full "Spaced symbols" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #0000FF - 1 - 10 10 - - - - - - - - circle - - #000033 - 1 - - - 5 - - - 5 15 - 7.5 - - - - - -Details -~~~~~~~ - -In this example two ``LineSymbolizer``\ s use ``stroke-dasharray`` and different symbology -to produce a sequence of alternating dashes and symbols. The first symbolizer -(**lines 3-9**) is a simple dashed line alternating 10 pixels of pen-down with 10 pixels of pen-up. -The second symbolizer (**lines 10-27**) alternates a 5 pixel empty circle with 15 pixels of white space. -The circle symbol is produced by a ``Mark`` element, with its symbology specified -by ``stroke`` parameters (**lines 17-18**). -The spacing between symbols is controlled with -the ``stroke-dasharray`` (**line 24**), which specifies 5 pixels of pen-down (just enough to draw the circle) and 15 pixels of pen-up. -In order to have the two sequences positioned correctly the second one uses a ``stroke-dashoffset`` of 7.5 (**line 25**). -This makes the sequence start with 12.5 -pixels of white space, then a circle (which is then centered between the two line segments of the other pattern), -then 15 pixels of white space, and so on. - - - -Line with default label ------------------------ - -This example shows a text label on the simple line. This is how a label will be displayed in the absence of any other -customization. - -.. figure:: images/line_linewithdefaultlabel.png - :align: center - - *Line with default label* - -Code -~~~~ - -:download:`View and download the full "Line with default label" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #FF0000 - - - - - - - - - #000000 - - - - - -Details -~~~~~~~ - -In this example, there is one rule with a ```` and a ````. The ```` -(**lines 3-7**) draws red lines (``#FF0000``). Since no width is specified, the default is set to 1 pixel. The -```` (**lines 8-15**) determines the labeling of the lines. **Lines 9-11** specify that the text of -the label will be determined by the value of the "name" attribute for each line. (Refer to the attribute table in the -:ref:`sld_cookbook_lines_attributes` section if necessary.) **Line 13** sets the text color to black. All other -details about the label are set to the renderer default, which here is Times New Roman font, font color black, and font -size of 10 pixels. - - -.. _sld_cookbook_lines_labelfollowingline: - -Label following line --------------------- - -This example renders the text label to follow the contour of the lines. - -.. note:: Labels following lines is an SLD extension specific to GeoServer. It is not part of the SLD 1.0 specification. - -.. figure:: images/line_labelfollowingline.png - :align: center - - *Label following line* - -Code -~~~~ - -:download:`View and download the full "Label following line" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #FF0000 - - - - - - - - - #000000 - - true - - - - -Details -~~~~~~~ - -As the :ref:`sld_cookbook_lines_defaultlabel` example showed, the default label behavior isn't optimal. The label -is displayed at a tangent to the line itself, leading to uncertainty as to which label corresponds to which line. - -This example is similar to the :ref:`sld_cookbook_lines_defaultlabel` example with the exception of **lines 12-18**. -**Line 18** sets the option to have the label follow the line, while **lines 12-14** specify that the label is placed -along a line. If ```` is not specified in an SLD, then ```` is assumed, which isn't -compatible with line-specific rendering options. - -.. note:: Not all labels are shown due to label conflict resolution. See the next section on :ref:`sld_cookbook_lines_optimizedlabel` for an example of how to maximize label display. - - -.. _sld_cookbook_lines_optimizedlabel: - -Optimized label placement -------------------------- - -This example optimizes label placement for lines such that the maximum number of labels are displayed. - -.. note:: This example uses options that are specific to GeoServer and are not part of the SLD 1.0 specification. - - -.. figure:: images/line_optimizedlabel.png - :align: center - - *Optimized label* - -Code -~~~~ - -:download:`View and download the full "Optimized label" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #FF0000 - - - - - - - - - #000000 - - true - 90 - 400 - 150 - - - - -Details -~~~~~~~ - -GeoServer uses "conflict resolution" to ensure that labels aren't drawn on top of other labels, obscuring them both. -This accounts for the reason why many lines don't have labels in the previous example, -:ref:`sld_cookbook_lines_labelfollowingline`. While this setting can be toggled, it is usually a good idea to leave it -on and use other label placement options to ensure that labels are drawn as often as desired and in the correct places. -This example does just that. - -This example is similar to the previous example, :ref:`sld_cookbook_lines_labelfollowingline`. The only differences are contained in **lines 18-21**. **Line 19** sets the maximum angle that the label will follow. This sets the label to never bend more than 90 degrees to prevent the label from becoming illegible due to a pronounced curve or angle. **Line 20** sets the maximum displacement of the label to be 400 pixels. In order to resolve conflicts with overlapping labels, GeoServer will attempt to move the labels such that they are no longer overlapping. This value sets how far the label can be moved relative to its original placement. Finally, **line 21** sets the labels to be repeated every 150 pixels. A feature will typically receive only one label, but this can cause confusion for long lines. Setting the label to repeat ensures that the line is always labeled locally. - - - -.. _sld_cookbook_lines_optimizedstyledlabel: - -Optimized and styled label --------------------------- - -This example improves the style of the labels from the :ref:`sld_cookbook_lines_optimizedlabel` example. - -.. figure:: images/line_optimizedstyledlabel.png - :align: center - - *Optimized and styled label* - -Code -~~~~ - -:download:`View and download the full "Optimized and styled label" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #FF0000 - - - - - - - - - #000000 - - - Arial - 10 - normal - bold - - true - 90 - 400 - 150 - - - - -Details -~~~~~~~ - -This example is similar to the :ref:`sld_cookbook_lines_optimizedlabel`. The only difference is in the font information, which is contained in **lines 18-23**. **Line 19** sets the font family to be "Arial", **line 20** sets the font size to 10, **line 21** sets the font style to "normal" (as opposed to "italic" or "oblique"), and **line 22** sets the font weight to "bold" (as opposed to "normal"). - - -Attribute-based line --------------------- - -This example styles the lines differently based on the "type" (Road class) attribute. - -.. figure:: images/line_attributebasedline.png - :align: center - - *Attribute-based line* - -Code -~~~~ - -:download:`View and download the full "Attribute-based line" SLD ` - -.. code-block:: xml - :linenos: - - - - local-road - - - type - local-road - - - - - #009933 - 2 - - - - - - - secondary - - - type - secondary - - - - - #0055CC - 3 - - - - - - - highway - - - type - highway - - - - - #FF0000 - 6 - - - - - - -Details -~~~~~~~ - -.. note:: Refer to the :ref:`sld_cookbook_lines_attributes` to see the attributes for the layer. This example has eschewed labels in order to simplify the style, but you can refer to the example :ref:`sld_cookbook_lines_optimizedstyledlabel` to see which attributes correspond to which points. - -There are three types of road classes in our fictional country, ranging from back roads to high-speed freeways: -"highway", "secondary", and "local-road". In order to handle each case separately, there is more than one -````, each containing a single rule. This ensures that each road type is rendered in order, as each -```` is drawn based on the order in which it appears in the SLD. - -The three rules are designed as follows: - -.. list-table:: - :widths: 20 30 30 20 - - * - **Rule order** - - **Rule name / type** - - **Color** - - **Size** - * - 1 - - local-road - - ``#009933`` (green) - - 2 - * - 2 - - secondary - - ``#0055CC`` (blue) - - 3 - * - 3 - - highway - - ``#FF0000`` (red) - - 6 - -**Lines 2-16** comprise the first ````. **Lines 4-9** set the filter for this rule, such that the "type" -attribute has a value of "local-road". If this condition is true for a particular line, the rule is rendered according -to the ```` which is on **lines 10-15**. **Lines 12-13** set the color of the line to be a dark green -(``#009933``) and the width to be 2 pixels. - -**Lines 19-33** comprise the second ````. **Lines 21-26** set the filter for this rule, such that the "type" -attribute has a value of "secondary". If this condition is true for a particular line, the rule is rendered according -to the ```` which is on **lines 27-32**. **Lines 29-30** set the color of the line to be a dark blue -(``#0055CC``) and the width to be 3 pixels, making the lines slightly thicker than the "local-road" lines and also a -different color. - -**Lines 36-50** comprise the third and final ````. **Lines 38-43** set the filter for this rule, such that the -"type" attribute has a value of "primary". If this condition is true for a particular line, the rule is rendered -according to the ```` which is on **lines 44-49**. **Lines 46-47** set the color of the line to be a -bright red (``#FF0000``) and the width to be 6 pixels, so that these lines are rendered on top of and thicker than the -other two road classes. In this way, the "primary" roads are given priority in the map rendering. - - -Zoom-based line ---------------- - -This example alters the :ref:`sld_cookbook_lines_simpleline` style at different zoom levels. - -.. figure:: images/line_zoombasedlinelarge.png - :align: center - - *Zoom-based line: Zoomed in* - - -.. figure:: images/line_zoombasedlinemedium.png - :align: center - - *Zoom-based line: Partially zoomed* - - -.. figure:: images/line_zoombasedlinesmall.png - :align: center - - *Zoom-based line: Zoomed out* - -Code -~~~~ - -:download:`View and download the full "Zoom-based line" SLD ` - -.. code-block:: xml - :linenos: - - - - Large - 180000000 - - - #009933 - 6 - - - - - Medium - 180000000 - 360000000 - - - #009933 - 4 - - - - - Small - 360000000 - - - #009933 - 2 - - - - - -Details -~~~~~~~ - -It is often desirable to make shapes larger at higher zoom levels when creating a natural-looking map. This example -varies the thickness of the lines according to the zoom level (or more accurately, scale denominator). Scale -denominators refer to the scale of the map. A scale denominator of 10,000 means the map has a scale of 1:10,000 in the -units of the map projection. - -.. note:: Determining the appropriate scale denominators (zoom levels) to use is beyond the scope of this example. - -This style contains three rules. The three rules are designed as follows: - -.. list-table:: - :widths: 15 25 40 20 - - * - **Rule order** - - **Rule name** - - **Scale denominator** - - **Line width** - * - 1 - - Large - - 1:180,000,000 or less - - 6 - * - 2 - - Medium - - 1:180,000,000 to 1:360,000,000 - - 4 - * - 3 - - Small - - Greater than 1:360,000,000 - - 2 - -The order of these rules does not matter since the scales denominated in each rule do not overlap. - -The first rule (**lines 2-11**) is the smallest scale denominator, corresponding to when the view is "zoomed in". The -scale rule is set on **line 4**, so that the rule will apply to any map with a scale denominator of 180,000,000 or -less. **Line 7-8** draws the line to be dark green (``#009933``) with a width of 6 pixels. - -The second rule (**lines 12-22**) is the intermediate scale denominator, corresponding to when the view is "partially -zoomed". **Lines 14-15** set the scale such that the rule will apply to any map with scale denominators between -180,000,000 and 360,000,000. (The ```` is inclusive and the ```` is -exclusive, so a zoom level of exactly 360,000,000 would *not* apply here.) Aside from the scale, the only difference -between this rule and the previous is the width of the lines, which is set to 4 pixels on **line 19**. - -The third rule (**lines 23-32**) is the largest scale denominator, corresponding to when the map is "zoomed out". The -scale rule is set on **line 25**, so that the rule will apply to any map with a scale denominator of 360,000,000 or -greater. Again, the only other difference between this rule and the others is the width of the lines, which is set to -2 pixels on **line 29**. - -The result of this style is that lines are drawn with larger widths as one zooms in and smaller widths as one zooms out. - +.. _sld_cookbook_lines: + +Lines +===== + +While lines can also seem to be simple shapes, having length but no width, there are many options and tricks for making +lines display nicely. + +.. warning:: The code examples shown on this page are **not the full SLD code**, as they omit the SLD header and footer information for the sake of brevity. Please use the links to download the full SLD for each example. + + +.. _sld_cookbook_lines_attributes: + +Example lines layer +------------------- + +The :download:`lines layer ` used in the examples below contains road information for a +fictional country. For reference, the attribute table for the points in this layer is included below. + +.. list-table:: + :widths: 30 40 30 + + * - **fid** (Feature ID) + - **name** (Road name) + - **type** (Road class) + * - line.1 + - Latway + - highway + * - line.2 + - Crescent Avenue + - secondary + * - line.3 + - Forest Avenue + - secondary + * - line.4 + - Longway + - highway + * - line.5 + - Saxer Avenue + - secondary + * - line.6 + - Ridge Avenue + - secondary + * - line.7 + - Holly Lane + - local-road + * - line.8 + - Mulberry Street + - local-road + * - line.9 + - Nathan Lane + - local-road + * - line.10 + - Central Street + - local-road + * - line.11 + - Lois Lane + - local-road + * - line.12 + - Rocky Road + - local-road + * - line.13 + - Fleet Street + - local-road + * - line.14 + - Diane Court + - local-road + * - line.15 + - Cedar Trail + - local-road + * - line.16 + - Victory Road + - local-road + * - line.17 + - Highland Road + - local-road + * - line.18 + - Easy Street + - local-road + * - line.19 + - Hill Street + - local-road + * - line.20 + - Country Road + - local-road + * - line.21 + - Main Street + - local-road + * - line.22 + - Jani Lane + - local-road + * - line.23 + - Shinbone Alley + - local-road + * - line.24 + - State Street + - local-road + * - line.25 + - River Road + - local-road + +:download:`Download the lines shapefile ` + +.. _sld_cookbook_lines_simpleline: + +Simple line +----------- + +This example specifies lines be colored black with a thickness of 3 pixels. + +.. figure:: images/line_simpleline.png + :align: center + + *Simple line* + +Code +~~~~ + +:download:`View and download the full "Simple line" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #000000 + 3 + + + + + +Details +~~~~~~~ + +There is one ```` in one ```` for this SLD, which is the simplest possible situation. (All +subsequent examples will contain one ```` and one ```` unless otherwise specified.) Styling +lines is accomplished via the ```` (**lines 3-8**). **Line 5** specifies the color of the line to be +black (``#000000``), while **line 6** specifies the width of the lines to be 3 pixels. + + +Line with border +---------------- + +This example shows how to draw lines with borders (sometimes called "cased lines"). +In this case the lines are drawn with a 3 pixel blue center and a 1 pixel wide gray border. + +.. figure:: images/line_linewithborder.png + :align: center + + *Line with border* + +Code +~~~~ + +:download:`View and download the full "Line with border" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #333333 + 5 + round + + + + + + + + + #6699FF + 3 + round + + + + + +Details +~~~~~~~ + +Lines in SLD have no notion of a "fill", only "stroke". Thus, unlike points or polygons, it is not possible to style the +"edge" of the line geometry. It is, however, possible to achieve this effect by drawing each line twice: once with a +certain width and again with a slightly smaller width. This gives the illusion of fill and stroke by obscuring the +larger lines everywhere except along the edges of the smaller lines. + +Since every line is drawn twice, the order of the rendering is *very* important. +GeoServer renders ````\ s in the order that they are presented in the SLD. +In this style, the gray border lines +are drawn first via the first ````, followed by the blue center lines in a second +````. This ensures that the blue lines are not obscured by the gray lines, +and also ensures proper rendering at intersections, so that the blue lines "connect". + +In this example, **lines 1-11** comprise the first ````, which is the outer line (or "stroke"). +**Line 5** specifies the color of the line to be dark gray (``#333333``), **line 6** specifies the width of this line +to be 5 pixels, and in **line 7** a ``stroke-linecap`` parameter of ``round`` +renders the ends of the line as rounded instead of flat. +(When working with bordered lines using a round line cap ensures that the border connects properly at the ends of the lines.) + +**Lines 12-22** comprise the second ````, which is the the inner line (or "fill"). **Line 16** +specifies the color of the line to be a medium blue (``#6699FF``), **line 17** specifies the width of this line to be 3 +pixels, and **line 18** again renders the edges of the line to be rounded instead of flat. + +The result is a 3 pixel blue line with a 1 pixel gray border, since the 5 pixel gray line will display 1 pixel on each +side of the 3 pixel blue line. + +Dashed line +----------- + +This example alters the :ref:`sld_cookbook_lines_simpleline` to create a dashed line consisting of 5 pixels of drawn +line alternating with 2 pixels of blank space. + +.. figure:: images/line_dashedline.png + :align: center + + *Dashed line* + +Code +~~~~ + +:download:`View and download the full "Dashed line" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #0000FF + 3 + 5 2 + + + + + +Details +~~~~~~~ + +In this example, **line 5** sets the color of the lines to be blue (``#0000FF``) and **line 6** sets the width of the +lines to be 3 pixels. **Line 7** determines the composition of the line dashes. The value of ``5 2`` creates a +repeating pattern of 5 pixels of drawn line, followed by 2 pixels of omitted line. + +Offset line +----------- + +This example alters the :ref:`sld_cookbook_lines_simpleline` to add a perpendicular offset line on the left side +of the line, at five pixels distance. + +.. figure:: images/line_offset.png + :align: center + + *Offset line* + +Code +~~~~ + +:download:`View and download the full "Dashed line" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #000000 + + + + + #FF0000 + 5 2 + + 5 + + + + +Details +~~~~~~~ + +In this example, the first line symbolizer just paints the lines black. +**line 8** begines a second lines symbolizer, sets the color of the lines to be red (``#FF0000``) at line 10 and +determines the composition of the line dashes at **Line 11**. +**Line 13** finally specifies a perpendicular offset of 5 pixels (positive, thus on the left side). + + +Railroad (hatching) +------------------- + +This example uses hatching to create a railroad style. Both the line and the hatches are black, with a 2 pixel +thickness for the main line and a 1 pixel width for the perpendicular hatches. + +.. note:: This example leverages an SLD extension in GeoServer. Hatching is not part of the standard SLD 1.0 specification. + +.. figure:: images/line_railroad.png + :align: center + + *Railroad (hatching)* + +Code +~~~~ + +:download:`View and download the full "Railroad (hatching)" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #333333 + 3 + + + + + + + + shape://vertline + + #333333 + 1 + + + 12 + + + + + + + +Details +~~~~~~~ + +In this example there are two ````\ s. +The first symbolizer, on **lines 3-8**, draws a standard line, with **line 5** drawing the lines as dark gray +(``#333333``) and **line 6** setting the width of the lines to be 2 pixels. + +The hatching is invoked in the second symbolizer, on **lines 9-24**. **Line 14** specifies that the symbolizer draw a vertical line +hatch (``shape://vertline``) perpendicular to the line geometry. **Lines 16-17** set the hatch color to dark gray +(``#333333``) and width to 1 pixel. Finally, **line 20** specifies both the length of the hatch and the distance +between each hatch to both be 12 pixels. + +Spaced graphic symbols +---------------------- + +This example uses a graphic stroke along with dash arrays to create a "dot and space" line type. +Adding the dash array specification allows to control the amount of space between one symbol and the next one. +Without using the dash +array the lines would be densely populated with dots, each one touching the previous one. + +.. note:: This example may not work in other systems using SLD, since they may not support combining the use of ``stroke-dasharray`` and ``GraphicStroke``. + While the SLD is spec-compliant, the SLD specification does not state what this combination is supposed to produce. + + +.. figure:: images/line_dashspace.png + :align: center + + *Spaced symbols along a line* + +Code +~~~~ + +:download:`View and download the full "Spaced symbols" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + + + circle + + #666666 + + + #333333 + 1 + + + 4 + + + 4 6 + + + + + +Details +~~~~~~~ +This example, like others before, uses a ``GraphicStroke`` to place a graphic symbol along a line. The symbol, defined +at **lines 7-16** is a 4 pixel gray circle with a dark gray outline. The spacing between symbols is controlled with +the ``stroke-dasharray`` at **line 20**, which specifies 4 pixels of pen-down (just enough to draw the circle) and 6 pixels of pen-up, +to provide the spacing. + + +.. _sld_cookbook_lines_defaultlabel: + +Alternating symbols with dash offsets +------------------------------------- + +This example shows how to create a complex line style which alternates a dashed line and a graphic symbol. +The code builds on features shown in the previous examples: + + * ``stroke-dasharray`` controls pen-down/pen-up behavior to generate dashed lines + * ``GraphicStroke`` places symbols along a line + * combining the two allows control of symbol spacing + +This also shows the usage of a `dash offset`, which controls where rendering starts +in the dash array. +For example, with a dash array of ``5 10`` and a dash offset of ``7`` the +renderer starts drawing the pattern 7 pixels from the beginning. It skips the 5 pixels pen-down +section and 2 pixels of the pen-up section, then draws the remaining 8 pixels of pen-up, then 5 down, 10 up, and so on. + +The example shows how to use these features to create two synchronized sequences of dash arrays, +one drawing line segments and the other symbols. + +.. note:: This example may not work in other systems using SLD, since they may not support combining the use of ``stroke-dasharray`` and ``GraphicStroke``. + While the SLD is spec-compliant, the SLD specification does not state what this combination is supposed to produce. + + +.. figure:: images/line_dashdot.png + :align: center + + *Alternating dash and symbol* + +Code +~~~~ + +:download:`View and download the full "Spaced symbols" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #0000FF + 1 + 10 10 + + + + + + + + circle + + #000033 + 1 + + + 5 + + + 5 15 + 7.5 + + + + + +Details +~~~~~~~ + +In this example two ``LineSymbolizer``\ s use ``stroke-dasharray`` and different symbology +to produce a sequence of alternating dashes and symbols. The first symbolizer +(**lines 3-9**) is a simple dashed line alternating 10 pixels of pen-down with 10 pixels of pen-up. +The second symbolizer (**lines 10-27**) alternates a 5 pixel empty circle with 15 pixels of white space. +The circle symbol is produced by a ``Mark`` element, with its symbology specified +by ``stroke`` parameters (**lines 17-18**). +The spacing between symbols is controlled with +the ``stroke-dasharray`` (**line 24**), which specifies 5 pixels of pen-down (just enough to draw the circle) and 15 pixels of pen-up. +In order to have the two sequences positioned correctly the second one uses a ``stroke-dashoffset`` of 7.5 (**line 25**). +This makes the sequence start with 12.5 +pixels of white space, then a circle (which is then centered between the two line segments of the other pattern), +then 15 pixels of white space, and so on. + + + +Line with default label +----------------------- + +This example shows a text label on the simple line. This is how a label will be displayed in the absence of any other +customization. + +.. figure:: images/line_linewithdefaultlabel.png + :align: center + + *Line with default label* + +Code +~~~~ + +:download:`View and download the full "Line with default label" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #FF0000 + + + + + + + + + #000000 + + + + + +Details +~~~~~~~ + +In this example, there is one rule with a ```` and a ````. The ```` +(**lines 3-7**) draws red lines (``#FF0000``). Since no width is specified, the default is set to 1 pixel. The +```` (**lines 8-15**) determines the labeling of the lines. **Lines 9-11** specify that the text of +the label will be determined by the value of the "name" attribute for each line. (Refer to the attribute table in the +:ref:`sld_cookbook_lines_attributes` section if necessary.) **Line 13** sets the text color to black. All other +details about the label are set to the renderer default, which here is Times New Roman font, font color black, and font +size of 10 pixels. + + +.. _sld_cookbook_lines_labelfollowingline: + +Label following line +-------------------- + +This example renders the text label to follow the contour of the lines. + +.. note:: Labels following lines is an SLD extension specific to GeoServer. It is not part of the SLD 1.0 specification. + +.. figure:: images/line_labelfollowingline.png + :align: center + + *Label following line* + +Code +~~~~ + +:download:`View and download the full "Label following line" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #FF0000 + + + + + + + + + #000000 + + true + + + + +Details +~~~~~~~ + +As the :ref:`sld_cookbook_lines_defaultlabel` example showed, the default label behavior isn't optimal. The label +is displayed at a tangent to the line itself, leading to uncertainty as to which label corresponds to which line. + +This example is similar to the :ref:`sld_cookbook_lines_defaultlabel` example with the exception of **lines 12-18**. +**Line 18** sets the option to have the label follow the line, while **lines 12-14** specify that the label is placed +along a line. If ```` is not specified in an SLD, then ```` is assumed, which isn't +compatible with line-specific rendering options. + +.. note:: Not all labels are shown due to label conflict resolution. See the next section on :ref:`sld_cookbook_lines_optimizedlabel` for an example of how to maximize label display. + + +.. _sld_cookbook_lines_optimizedlabel: + +Optimized label placement +------------------------- + +This example optimizes label placement for lines such that the maximum number of labels are displayed. + +.. note:: This example uses options that are specific to GeoServer and are not part of the SLD 1.0 specification. + + +.. figure:: images/line_optimizedlabel.png + :align: center + + *Optimized label* + +Code +~~~~ + +:download:`View and download the full "Optimized label" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #FF0000 + + + + + + + + + #000000 + + true + 90 + 400 + 150 + + + + +Details +~~~~~~~ + +GeoServer uses "conflict resolution" to ensure that labels aren't drawn on top of other labels, obscuring them both. +This accounts for the reason why many lines don't have labels in the previous example, +:ref:`sld_cookbook_lines_labelfollowingline`. While this setting can be toggled, it is usually a good idea to leave it +on and use other label placement options to ensure that labels are drawn as often as desired and in the correct places. +This example does just that. + +This example is similar to the previous example, :ref:`sld_cookbook_lines_labelfollowingline`. The only differences are contained in **lines 18-21**. **Line 19** sets the maximum angle that the label will follow. This sets the label to never bend more than 90 degrees to prevent the label from becoming illegible due to a pronounced curve or angle. **Line 20** sets the maximum displacement of the label to be 400 pixels. In order to resolve conflicts with overlapping labels, GeoServer will attempt to move the labels such that they are no longer overlapping. This value sets how far the label can be moved relative to its original placement. Finally, **line 21** sets the labels to be repeated every 150 pixels. A feature will typically receive only one label, but this can cause confusion for long lines. Setting the label to repeat ensures that the line is always labeled locally. + + + +.. _sld_cookbook_lines_optimizedstyledlabel: + +Optimized and styled label +-------------------------- + +This example improves the style of the labels from the :ref:`sld_cookbook_lines_optimizedlabel` example. + +.. figure:: images/line_optimizedstyledlabel.png + :align: center + + *Optimized and styled label* + +Code +~~~~ + +:download:`View and download the full "Optimized and styled label" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #FF0000 + + + + + + + + + #000000 + + + Arial + 10 + normal + bold + + true + 90 + 400 + 150 + + + + +Details +~~~~~~~ + +This example is similar to the :ref:`sld_cookbook_lines_optimizedlabel`. The only difference is in the font information, which is contained in **lines 18-23**. **Line 19** sets the font family to be "Arial", **line 20** sets the font size to 10, **line 21** sets the font style to "normal" (as opposed to "italic" or "oblique"), and **line 22** sets the font weight to "bold" (as opposed to "normal"). + + +Attribute-based line +-------------------- + +This example styles the lines differently based on the "type" (Road class) attribute. + +.. figure:: images/line_attributebasedline.png + :align: center + + *Attribute-based line* + +Code +~~~~ + +:download:`View and download the full "Attribute-based line" SLD ` + +.. code-block:: xml + :linenos: + + + + local-road + + + type + local-road + + + + + #009933 + 2 + + + + + + + secondary + + + type + secondary + + + + + #0055CC + 3 + + + + + + + highway + + + type + highway + + + + + #FF0000 + 6 + + + + + + +Details +~~~~~~~ + +.. note:: Refer to the :ref:`sld_cookbook_lines_attributes` to see the attributes for the layer. This example has eschewed labels in order to simplify the style, but you can refer to the example :ref:`sld_cookbook_lines_optimizedstyledlabel` to see which attributes correspond to which points. + +There are three types of road classes in our fictional country, ranging from back roads to high-speed freeways: +"highway", "secondary", and "local-road". In order to handle each case separately, there is more than one +````, each containing a single rule. This ensures that each road type is rendered in order, as each +```` is drawn based on the order in which it appears in the SLD. + +The three rules are designed as follows: + +.. list-table:: + :widths: 20 30 30 20 + + * - **Rule order** + - **Rule name / type** + - **Color** + - **Size** + * - 1 + - local-road + - ``#009933`` (green) + - 2 + * - 2 + - secondary + - ``#0055CC`` (blue) + - 3 + * - 3 + - highway + - ``#FF0000`` (red) + - 6 + +**Lines 2-16** comprise the first ````. **Lines 4-9** set the filter for this rule, such that the "type" +attribute has a value of "local-road". If this condition is true for a particular line, the rule is rendered according +to the ```` which is on **lines 10-15**. **Lines 12-13** set the color of the line to be a dark green +(``#009933``) and the width to be 2 pixels. + +**Lines 19-33** comprise the second ````. **Lines 21-26** set the filter for this rule, such that the "type" +attribute has a value of "secondary". If this condition is true for a particular line, the rule is rendered according +to the ```` which is on **lines 27-32**. **Lines 29-30** set the color of the line to be a dark blue +(``#0055CC``) and the width to be 3 pixels, making the lines slightly thicker than the "local-road" lines and also a +different color. + +**Lines 36-50** comprise the third and final ````. **Lines 38-43** set the filter for this rule, such that the +"type" attribute has a value of "primary". If this condition is true for a particular line, the rule is rendered +according to the ```` which is on **lines 44-49**. **Lines 46-47** set the color of the line to be a +bright red (``#FF0000``) and the width to be 6 pixels, so that these lines are rendered on top of and thicker than the +other two road classes. In this way, the "primary" roads are given priority in the map rendering. + + +Zoom-based line +--------------- + +This example alters the :ref:`sld_cookbook_lines_simpleline` style at different zoom levels. + +.. figure:: images/line_zoombasedlinelarge.png + :align: center + + *Zoom-based line: Zoomed in* + + +.. figure:: images/line_zoombasedlinemedium.png + :align: center + + *Zoom-based line: Partially zoomed* + + +.. figure:: images/line_zoombasedlinesmall.png + :align: center + + *Zoom-based line: Zoomed out* + +Code +~~~~ + +:download:`View and download the full "Zoom-based line" SLD ` + +.. code-block:: xml + :linenos: + + + + Large + 180000000 + + + #009933 + 6 + + + + + Medium + 180000000 + 360000000 + + + #009933 + 4 + + + + + Small + 360000000 + + + #009933 + 2 + + + + + +Details +~~~~~~~ + +It is often desirable to make shapes larger at higher zoom levels when creating a natural-looking map. This example +varies the thickness of the lines according to the zoom level (or more accurately, scale denominator). Scale +denominators refer to the scale of the map. A scale denominator of 10,000 means the map has a scale of 1:10,000 in the +units of the map projection. + +.. note:: Determining the appropriate scale denominators (zoom levels) to use is beyond the scope of this example. + +This style contains three rules. The three rules are designed as follows: + +.. list-table:: + :widths: 15 25 40 20 + + * - **Rule order** + - **Rule name** + - **Scale denominator** + - **Line width** + * - 1 + - Large + - 1:180,000,000 or less + - 6 + * - 2 + - Medium + - 1:180,000,000 to 1:360,000,000 + - 4 + * - 3 + - Small + - Greater than 1:360,000,000 + - 2 + +The order of these rules does not matter since the scales denominated in each rule do not overlap. + +The first rule (**lines 2-11**) is the smallest scale denominator, corresponding to when the view is "zoomed in". The +scale rule is set on **line 4**, so that the rule will apply to any map with a scale denominator of 180,000,000 or +less. **Line 7-8** draws the line to be dark green (``#009933``) with a width of 6 pixels. + +The second rule (**lines 12-22**) is the intermediate scale denominator, corresponding to when the view is "partially +zoomed". **Lines 14-15** set the scale such that the rule will apply to any map with scale denominators between +180,000,000 and 360,000,000. (The ```` is inclusive and the ```` is +exclusive, so a zoom level of exactly 360,000,000 would *not* apply here.) Aside from the scale, the only difference +between this rule and the previous is the width of the lines, which is set to 4 pixels on **line 19**. + +The third rule (**lines 23-32**) is the largest scale denominator, corresponding to when the map is "zoomed out". The +scale rule is set on **line 25**, so that the rule will apply to any map with a scale denominator of 360,000,000 or +greater. Again, the only other difference between this rule and the others is the width of the lines, which is set to +2 pixels on **line 29**. + +The result of this style is that lines are drawn with larger widths as one zooms in and smaller widths as one zooms out. + diff --git a/doc/en/user/source/styling/sld/cookbook/points.rst b/doc/en/user/source/styling/sld/cookbook/points.rst index 50e114a9689..13984adba53 100644 --- a/doc/en/user/source/styling/sld/cookbook/points.rst +++ b/doc/en/user/source/styling/sld/cookbook/points.rst @@ -1,718 +1,718 @@ -.. _sld_cookbook_points: - -Points -====== - -While points are seemingly the simplest type of shape, possessing only position and no other dimensions, there are many different ways that a point can be styled in SLD. - -.. warning:: The code examples shown on this page are **not the full SLD code**, as they omit the SLD header and footer information for the sake of brevity. Please use the links to download the full SLD for each example. - -.. _sld_cookbook_points_attributes: - -Example points layer --------------------- - -The :download:`points layer ` used for the examples below contains name and population information for the major cities of a fictional country. For reference, the attribute table for the points in this layer is included below. - -.. list-table:: - :widths: 30 40 30 - - * - **fid** (Feature ID) - - **name** (City name) - - **pop** (Population) - * - point.1 - - Borfin - - 157860 - * - point.2 - - Supox City - - 578231 - * - point.3 - - Ruckis - - 98159 - * - point.4 - - Thisland - - 34879 - * - point.5 - - Synopolis - - 24567 - * - point.6 - - San Glissando - - 76024 - * - point.7 - - Detrania - - 205609 - -:download:`Download the points shapefile ` - -.. _sld_cookbook_points_simplepoint: - -Simple point ------------- - -This example specifies points be styled as red circles with a diameter of 6 pixels. - -.. figure:: images/point_simplepoint.png - :align: center - - *Simple point* - -Code -~~~~ - -:download:`View and download the full "Simple point" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - circle - - #FF0000 - - - 6 - - - - - - - -Details -~~~~~~~ - -There is one ```` in one ```` for this SLD, which is the simplest possible situation. (All subsequent examples will contain one ```` and one ```` unless otherwise specified.) Styling points is accomplished via the ```` (**lines 3-13**). **Line 6** specifies the shape of the symbol to be a circle, with **line 8** determining the fill color to be red (``#FF0000``). **Line 11** sets the size (diameter) of the graphic to be 6 pixels. - - -.. _sld_cookbook_points_simplepointwithstroke: - -Simple point with stroke ------------------------- - -This example adds a stroke (or border) around the :ref:`sld_cookbook_points_simplepoint`, with the stroke colored black and given a thickness of 2 pixels. - -.. figure:: images/point_simplepointwithstroke.png - :align: center - - *Simple point with stroke* - -Code -~~~~ - -:download:`View and download the full "Simple point with stroke" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - circle - - #FF0000 - - - #000000 - 2 - - - 6 - - - - - -Details -~~~~~~~ - -This example is similar to the :ref:`sld_cookbook_points_simplepoint` example. **Lines 10-13** specify the stroke, with **line 11** setting the color to black (``#000000``) and **line 12** setting the width to 2 pixels. - - -Rotated square --------------- - -This example creates a square instead of a circle, colors it green, sizes it to 12 pixels, and rotates it by 45 degrees. - -.. figure:: images/point_rotatedsquare.png - :align: center - - *Rotated square* - -Code -~~~~ - -:download:`View and download the full "Rotated square" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - square - - #009900 - - - 12 - 45 - - - - - - - -Details -~~~~~~~ - -In this example, **line 6** sets the shape to be a square, with **line 8** setting the color to a dark green (``#009900``). **Line 11** sets the size of the square to be 12 pixels, and **line 12** set the rotation is to 45 degrees. - - -Transparent triangle --------------------- - -This example draws a triangle, creates a black stroke identical to the :ref:`sld_cookbook_points_simplepointwithstroke` example, and sets the fill of the triangle to 20% opacity (mostly transparent). - -.. figure:: images/point_transparenttriangle.png - :align: center - - *Transparent triangle* - -Code -~~~~ - -:download:`View and download the full "Transparent triangle" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - triangle - - #009900 - 0.2 - - - #000000 - 2 - - - 12 - - - - - - - -Details -~~~~~~~ - -In this example, **line 6** once again sets the shape, in this case to a triangle. **Line 8** sets the fill color to a dark green (``#009900``) and **line 9** sets the opacity to 0.2 (20% opaque). An opacity value of 1 means that the shape is drawn 100% opaque, while an opacity value of 0 means that the shape is drawn 0% opaque, or completely transparent. The value of 0.2 (20% opaque) means that the fill of the points partially takes on the color and style of whatever is drawn beneath it. In this example, since the background is white, the dark green looks lighter. Were the points imposed on a dark background, the resulting color would be darker. **Lines 12-13** set the stroke color to black (``#000000``) and width to 2 pixels. Finally, **line 16** sets the size of the point to be 12 pixels in diameter. - -Point as graphic ----------------- - -This example styles each point as a graphic instead of as a simple shape. - -.. figure:: images/point_pointasgraphic.png - :align: center - - *Point as graphic* - -Code -~~~~ - -:download:`View and download the full "Point as graphic" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - - image/png - - 32 - - - - - - - -Details -~~~~~~~ - -This style uses a graphic instead of a simple shape to render the points. In SLD, this is known as an ````, to distinguish it from the commonly-used shapes such as squares and circles that are "internal" to the renderer. **Lines 5-10** specify the details of this graphic. **Line 8** sets the path and file name of the graphic, while **line 9** indicates the format (MIME type) of the graphic (image/png). In this example, the graphic is contained in the same directory as the SLD, so no path information is necessary in **line 8**, although a full URL could be used if desired. **Line 11** determines the size of the displayed graphic; this can be set independently of the dimensions of the graphic itself, although in this case they are the same (32 pixels). Should a graphic be rectangular, the ```` value will apply to the *height* of the graphic only, with the width scaled proportionally. - -.. figure:: images/smileyface.png - :align: center - - *Graphic used for points* - -.. _sld_cookbook_points_pointwithdefaultlabel: - -Point with default label ------------------------- - -This example shows a text label on the :ref:`sld_cookbook_points_simplepoint` that displays the "name" attribute of the point. This is how a label will be displayed in the absence of any other customization. - -.. figure:: images/point_pointwithdefaultlabel.png - :align: center - - *Point with default label* - -Code -~~~~ - -:download:`View and download the full "Point with default label" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - circle - - #FF0000 - - - 6 - - - - - - #000000 - - - - - - - -Details -~~~~~~~ - -**Lines 3-13**, which contain the ````, are identical to the :ref:`sld_cookbook_points_simplepoint` example above. The label is set in the ```` on **lines 14-27**. **Lines 15-17** determine what text to display in the label, which in this case is the value of the "name" attribute. (Refer to the attribute table in the :ref:`sld_cookbook_points_attributes` section if necessary.) **Line 19** sets the text color. All other details about the label are set to the renderer default, which here is Times New Roman font, font color black, and font size of 10 pixels. The bottom left of the label is aligned with the center of the point. - - -.. _sld_cookbook_points_pointwithstyledlabel: - -Point with styled label ------------------------ - -This example improves the label style from the :ref:`sld_cookbook_points_pointwithdefaultlabel` example by centering the label above the point and providing a different font name and size. - -.. figure:: images/point_pointwithstyledlabel.png - :align: center - - *Point with styled label* - -Code -~~~~ - -:download:`View and download the full "Point with styled label" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - circle - - #FF0000 - - - 6 - - - - - - Arial - 12 - normal - bold - - - - - 0.5 - 0.0 - - - 0 - 5 - - - - - #000000 - - - - - - -Details -~~~~~~~ - -In this example, **lines 3-13** are identical to the :ref:`sld_cookbook_points_simplepoint` example above. The ```` on lines 14-39 contains many more details about the label styling than the previous example, :ref:`sld_cookbook_points_pointwithdefaultlabel`. **Lines 15-17** once again specify the "name" attribute as text to display. **Lines 18-23** set the font information: **line 19** sets the font family to be "Arial", **line 20** sets the font size to 12, **line 21** sets the font style to "normal" (as opposed to "italic" or "oblique"), and **line 22** sets the font weight to "bold" (as opposed to "normal"). **Lines 24-35** (````) determine the placement of the label relative to the point. The ```` (**lines 26-29**) sets the point of intersection between the label and point, which here (**line 27-28**) sets the point to be centered (0.5) horizontally axis and bottom aligned (0.0) vertically with the label. There is also ```` (**lines 30-33**), which sets the offset of the label relative to the line, which in this case is 0 pixels horizontally (**line 31**) and 5 pixels vertically (**line 32**). Finally, **line 37** sets the font color of the label to black (``#000000``). - -The result is a centered bold label placed slightly above each point. - - - -Point with rotated label ------------------------- - -This example builds on the previous example, :ref:`sld_cookbook_points_pointwithstyledlabel`, by rotating the label by 45 degrees, positioning the labels farther away from the points, and changing the color of the label to purple. - -.. figure:: images/point_pointwithrotatedlabel.png - :align: center - - *Point with rotated label* - -Code -~~~~ - -:download:`View and download the full "Point with rotated label" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - circle - - #FF0000 - - - 6 - - - - - - Arial - 12 - normal - bold - - - - - 0.5 - 0.0 - - - 0 - 25 - - -45 - - - - #990099 - - - - - - - -Details -~~~~~~~ - -This example is similar to the :ref:`sld_cookbook_points_pointwithstyledlabel`, but there are three important differences. **Line 32** specifies 25 pixels of vertical displacement. **Line 34** specifies a rotation of "-45" or 45 degrees counter-clockwise. (Rotation values increase clockwise, which is why the value is negative.) Finally, **line 38** sets the font color to be a shade of purple (``#99099``). - -Note that the displacement takes effect before the rotation during rendering, so in this example, the 25 pixel vertical displacement is itself rotated 45 degrees. - - -Attribute-based point ---------------------- - -This example alters the size of the symbol based on the value of the population ("pop") attribute. - -.. figure:: images/point_attributebasedpoint.png - :align: center - - *Attribute-based point* - -Code -~~~~ - -:download:`View and download the full "Attribute-based point" SLD ` - -.. code-block:: xml - :linenos: - - - - SmallPop - 1 to 50000 - - - pop - 50000 - - - - - - circle - - #0033CC - - - 8 - - - - - MediumPop - 50000 to 100000 - - - - pop - 50000 - - - pop - 100000 - - - - - - - circle - - #0033CC - - - 12 - - - - - LargePop - Greater than 100000 - - - pop - 100000 - - - - - - circle - - #0033CC - - - 16 - - - - - - - -Details -~~~~~~~ - -.. note:: Refer to the :ref:`sld_cookbook_points_attributes` to see the attributes for this data. This example has eschewed labels in order to simplify the style, but you can refer to the example :ref:`sld_cookbook_points_pointwithstyledlabel` to see which attributes correspond to which points. - -This style contains three rules. Each ```` varies the style based on the value of the population ("pop") attribute for each point, with smaller values yielding a smaller circle, and larger values yielding a larger circle. - -The three rules are designed as follows: - -.. list-table:: - :widths: 20 30 30 20 - - * - **Rule order** - - **Rule name** - - **Population** ("pop") - - **Size** - * - 1 - - SmallPop - - Less than 50,000 - - 8 - * - 2 - - MediumPop - - 50,000 to 100,000 - - 12 - * - 3 - - LargePop - - Greater than 100,000 - - 16 - -The order of the rules does not matter in this case, since each shape is only rendered by a single rule. - -The first rule, on **lines 2-22**, specifies the styling of those points whose population attribute is less than 50,000. **Lines 5-10** set this filter, with **lines 6-9** setting the "less than" filter, **line 7** denoting the attribute ("pop"), and **line 8** the value of 50,000. The symbol is a circle (**line 14**), the color is dark blue (``#0033CC``, on **line 16**), and the size is 8 pixels in diameter (**line 19**). - -The second rule, on **lines 23-49**, specifies a style for points whose population attribute is greater than or equal to 50,000 and less than 100,000. The population filter is set on **lines 26-37**. This filter is longer than in the first rule because two criteria need to be specified instead of one: a "greater than or equal to" and a "less than" filter. Notice the ``And`` on **line 27** and **line 36**. This mandates that both filters need to be true for the rule to be applicable. The size of the graphic is set to 12 pixels on **line 46**. All other styling directives are identical to the first rule. - -The third rule, on **lines 50-70**, specifies a style for points whose population attribute is greater than or equal to 100,000. The population filter is set on **lines 53-58**, and the only other difference is the size of the circle, which in this rule (**line 67**) is 16 pixels. - -The result of this style is that cities with larger populations have larger points. - - -Zoom-based point ----------------- - -This example alters the style of the points at different zoom levels. - -.. figure:: images/point_zoombasedpointlarge.png - :align: center - - *Zoom-based point: Zoomed in* - -.. figure:: images/point_zoombasedpointmedium.png - :align: center - - *Zoom-based point: Partially zoomed* - -.. figure:: images/point_zoombasedpointsmall.png - :align: center - - *Zoom-based point: Zoomed out* - - -Code -~~~~ - -:download:`View and download the full "Zoom-based point" SLD ` - -.. code-block:: xml - :linenos: - - - - Large - 160000000 - - - - circle - - #CC3300 - - - 12 - - - - - Medium - 160000000 - 320000000 - - - - circle - - #CC3300 - - - 8 - - - - - Small - 320000000 - - - - circle - - #CC3300 - - - 4 - - - - - - - - -Details -~~~~~~~ - -It is often desirable to make shapes larger at higher zoom levels when creating a natural-looking map. This example styles the points to vary in size based on the zoom level (or more accurately, scale denominator). Scale denominators refer to the scale of the map. A scale denominator of 10,000 means the map has a scale of 1:10,000 in the units of the map projection. - -.. note:: Determining the appropriate scale denominators (zoom levels) to use is beyond the scope of this example. - -This style contains three rules. The three rules are designed as follows: - -.. list-table:: - :widths: 25 25 25 25 - - * - **Rule order** - - **Rule name** - - **Scale denominator** - - **Point size** - * - 1 - - Large - - 1:160,000,000 or less - - 12 - * - 2 - - Medium - - 1:160,000,000 to 1:320,000,000 - - 8 - * - 3 - - Small - - Greater than 1:320,000,000 - - 4 - -The order of these rules does not matter since the scales denominated in each rule do not overlap. - -The first rule (**lines 2-16**) is for the smallest scale denominator, corresponding to when the view is "zoomed in". The scale rule is set on **line 4**, so that the rule will apply to any map with a scale denominator of 160,000,000 or less. The rule draws a circle (**line 8**), colored red (``#CC3300`` on **line 10**) with a size of 12 pixels (**line 13**). - -The second rule (**lines 17-32**) is the intermediate scale denominator, corresponding to when the view is "partially zoomed". The scale rules are set on **lines 19-20**, so that the rule will apply to any map with a scale denominator between 160,000,000 and 320,000,000. (The ```` is inclusive and the ```` is exclusive, so a zoom level of exactly 320,000,000 would *not* apply here.) Aside from the scale, the only difference between this rule and the first is the size of the symbol, which is set to 8 pixels on **line 29**. - -The third rule (**lines 33-47**) is the largest scale denominator, corresponding to when the map is "zoomed out". The scale rule is set on **line 35**, so that the rule will apply to any map with a scale denominator of 320,000,000 or more. Again, the only other difference between this rule and the others is the size of the symbol, which is set to 4 pixels on **line 44**. - -The result of this style is that points are drawn larger as one zooms in and smaller as one zooms out. - +.. _sld_cookbook_points: + +Points +====== + +While points are seemingly the simplest type of shape, possessing only position and no other dimensions, there are many different ways that a point can be styled in SLD. + +.. warning:: The code examples shown on this page are **not the full SLD code**, as they omit the SLD header and footer information for the sake of brevity. Please use the links to download the full SLD for each example. + +.. _sld_cookbook_points_attributes: + +Example points layer +-------------------- + +The :download:`points layer ` used for the examples below contains name and population information for the major cities of a fictional country. For reference, the attribute table for the points in this layer is included below. + +.. list-table:: + :widths: 30 40 30 + + * - **fid** (Feature ID) + - **name** (City name) + - **pop** (Population) + * - point.1 + - Borfin + - 157860 + * - point.2 + - Supox City + - 578231 + * - point.3 + - Ruckis + - 98159 + * - point.4 + - Thisland + - 34879 + * - point.5 + - Synopolis + - 24567 + * - point.6 + - San Glissando + - 76024 + * - point.7 + - Detrania + - 205609 + +:download:`Download the points shapefile ` + +.. _sld_cookbook_points_simplepoint: + +Simple point +------------ + +This example specifies points be styled as red circles with a diameter of 6 pixels. + +.. figure:: images/point_simplepoint.png + :align: center + + *Simple point* + +Code +~~~~ + +:download:`View and download the full "Simple point" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + circle + + #FF0000 + + + 6 + + + + + + + +Details +~~~~~~~ + +There is one ```` in one ```` for this SLD, which is the simplest possible situation. (All subsequent examples will contain one ```` and one ```` unless otherwise specified.) Styling points is accomplished via the ```` (**lines 3-13**). **Line 6** specifies the shape of the symbol to be a circle, with **line 8** determining the fill color to be red (``#FF0000``). **Line 11** sets the size (diameter) of the graphic to be 6 pixels. + + +.. _sld_cookbook_points_simplepointwithstroke: + +Simple point with stroke +------------------------ + +This example adds a stroke (or border) around the :ref:`sld_cookbook_points_simplepoint`, with the stroke colored black and given a thickness of 2 pixels. + +.. figure:: images/point_simplepointwithstroke.png + :align: center + + *Simple point with stroke* + +Code +~~~~ + +:download:`View and download the full "Simple point with stroke" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + circle + + #FF0000 + + + #000000 + 2 + + + 6 + + + + + +Details +~~~~~~~ + +This example is similar to the :ref:`sld_cookbook_points_simplepoint` example. **Lines 10-13** specify the stroke, with **line 11** setting the color to black (``#000000``) and **line 12** setting the width to 2 pixels. + + +Rotated square +-------------- + +This example creates a square instead of a circle, colors it green, sizes it to 12 pixels, and rotates it by 45 degrees. + +.. figure:: images/point_rotatedsquare.png + :align: center + + *Rotated square* + +Code +~~~~ + +:download:`View and download the full "Rotated square" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + square + + #009900 + + + 12 + 45 + + + + + + + +Details +~~~~~~~ + +In this example, **line 6** sets the shape to be a square, with **line 8** setting the color to a dark green (``#009900``). **Line 11** sets the size of the square to be 12 pixels, and **line 12** set the rotation is to 45 degrees. + + +Transparent triangle +-------------------- + +This example draws a triangle, creates a black stroke identical to the :ref:`sld_cookbook_points_simplepointwithstroke` example, and sets the fill of the triangle to 20% opacity (mostly transparent). + +.. figure:: images/point_transparenttriangle.png + :align: center + + *Transparent triangle* + +Code +~~~~ + +:download:`View and download the full "Transparent triangle" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + triangle + + #009900 + 0.2 + + + #000000 + 2 + + + 12 + + + + + + + +Details +~~~~~~~ + +In this example, **line 6** once again sets the shape, in this case to a triangle. **Line 8** sets the fill color to a dark green (``#009900``) and **line 9** sets the opacity to 0.2 (20% opaque). An opacity value of 1 means that the shape is drawn 100% opaque, while an opacity value of 0 means that the shape is drawn 0% opaque, or completely transparent. The value of 0.2 (20% opaque) means that the fill of the points partially takes on the color and style of whatever is drawn beneath it. In this example, since the background is white, the dark green looks lighter. Were the points imposed on a dark background, the resulting color would be darker. **Lines 12-13** set the stroke color to black (``#000000``) and width to 2 pixels. Finally, **line 16** sets the size of the point to be 12 pixels in diameter. + +Point as graphic +---------------- + +This example styles each point as a graphic instead of as a simple shape. + +.. figure:: images/point_pointasgraphic.png + :align: center + + *Point as graphic* + +Code +~~~~ + +:download:`View and download the full "Point as graphic" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + + image/png + + 32 + + + + + + + +Details +~~~~~~~ + +This style uses a graphic instead of a simple shape to render the points. In SLD, this is known as an ````, to distinguish it from the commonly-used shapes such as squares and circles that are "internal" to the renderer. **Lines 5-10** specify the details of this graphic. **Line 8** sets the path and file name of the graphic, while **line 9** indicates the format (MIME type) of the graphic (image/png). In this example, the graphic is contained in the same directory as the SLD, so no path information is necessary in **line 8**, although a full URL could be used if desired. **Line 11** determines the size of the displayed graphic; this can be set independently of the dimensions of the graphic itself, although in this case they are the same (32 pixels). Should a graphic be rectangular, the ```` value will apply to the *height* of the graphic only, with the width scaled proportionally. + +.. figure:: images/smileyface.png + :align: center + + *Graphic used for points* + +.. _sld_cookbook_points_pointwithdefaultlabel: + +Point with default label +------------------------ + +This example shows a text label on the :ref:`sld_cookbook_points_simplepoint` that displays the "name" attribute of the point. This is how a label will be displayed in the absence of any other customization. + +.. figure:: images/point_pointwithdefaultlabel.png + :align: center + + *Point with default label* + +Code +~~~~ + +:download:`View and download the full "Point with default label" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + circle + + #FF0000 + + + 6 + + + + + + #000000 + + + + + + + +Details +~~~~~~~ + +**Lines 3-13**, which contain the ````, are identical to the :ref:`sld_cookbook_points_simplepoint` example above. The label is set in the ```` on **lines 14-27**. **Lines 15-17** determine what text to display in the label, which in this case is the value of the "name" attribute. (Refer to the attribute table in the :ref:`sld_cookbook_points_attributes` section if necessary.) **Line 19** sets the text color. All other details about the label are set to the renderer default, which here is Times New Roman font, font color black, and font size of 10 pixels. The bottom left of the label is aligned with the center of the point. + + +.. _sld_cookbook_points_pointwithstyledlabel: + +Point with styled label +----------------------- + +This example improves the label style from the :ref:`sld_cookbook_points_pointwithdefaultlabel` example by centering the label above the point and providing a different font name and size. + +.. figure:: images/point_pointwithstyledlabel.png + :align: center + + *Point with styled label* + +Code +~~~~ + +:download:`View and download the full "Point with styled label" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + circle + + #FF0000 + + + 6 + + + + + + Arial + 12 + normal + bold + + + + + 0.5 + 0.0 + + + 0 + 5 + + + + + #000000 + + + + + + +Details +~~~~~~~ + +In this example, **lines 3-13** are identical to the :ref:`sld_cookbook_points_simplepoint` example above. The ```` on lines 14-39 contains many more details about the label styling than the previous example, :ref:`sld_cookbook_points_pointwithdefaultlabel`. **Lines 15-17** once again specify the "name" attribute as text to display. **Lines 18-23** set the font information: **line 19** sets the font family to be "Arial", **line 20** sets the font size to 12, **line 21** sets the font style to "normal" (as opposed to "italic" or "oblique"), and **line 22** sets the font weight to "bold" (as opposed to "normal"). **Lines 24-35** (````) determine the placement of the label relative to the point. The ```` (**lines 26-29**) sets the point of intersection between the label and point, which here (**line 27-28**) sets the point to be centered (0.5) horizontally axis and bottom aligned (0.0) vertically with the label. There is also ```` (**lines 30-33**), which sets the offset of the label relative to the line, which in this case is 0 pixels horizontally (**line 31**) and 5 pixels vertically (**line 32**). Finally, **line 37** sets the font color of the label to black (``#000000``). + +The result is a centered bold label placed slightly above each point. + + + +Point with rotated label +------------------------ + +This example builds on the previous example, :ref:`sld_cookbook_points_pointwithstyledlabel`, by rotating the label by 45 degrees, positioning the labels farther away from the points, and changing the color of the label to purple. + +.. figure:: images/point_pointwithrotatedlabel.png + :align: center + + *Point with rotated label* + +Code +~~~~ + +:download:`View and download the full "Point with rotated label" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + circle + + #FF0000 + + + 6 + + + + + + Arial + 12 + normal + bold + + + + + 0.5 + 0.0 + + + 0 + 25 + + -45 + + + + #990099 + + + + + + + +Details +~~~~~~~ + +This example is similar to the :ref:`sld_cookbook_points_pointwithstyledlabel`, but there are three important differences. **Line 32** specifies 25 pixels of vertical displacement. **Line 34** specifies a rotation of "-45" or 45 degrees counter-clockwise. (Rotation values increase clockwise, which is why the value is negative.) Finally, **line 38** sets the font color to be a shade of purple (``#99099``). + +Note that the displacement takes effect before the rotation during rendering, so in this example, the 25 pixel vertical displacement is itself rotated 45 degrees. + + +Attribute-based point +--------------------- + +This example alters the size of the symbol based on the value of the population ("pop") attribute. + +.. figure:: images/point_attributebasedpoint.png + :align: center + + *Attribute-based point* + +Code +~~~~ + +:download:`View and download the full "Attribute-based point" SLD ` + +.. code-block:: xml + :linenos: + + + + SmallPop + 1 to 50000 + + + pop + 50000 + + + + + + circle + + #0033CC + + + 8 + + + + + MediumPop + 50000 to 100000 + + + + pop + 50000 + + + pop + 100000 + + + + + + + circle + + #0033CC + + + 12 + + + + + LargePop + Greater than 100000 + + + pop + 100000 + + + + + + circle + + #0033CC + + + 16 + + + + + + + +Details +~~~~~~~ + +.. note:: Refer to the :ref:`sld_cookbook_points_attributes` to see the attributes for this data. This example has eschewed labels in order to simplify the style, but you can refer to the example :ref:`sld_cookbook_points_pointwithstyledlabel` to see which attributes correspond to which points. + +This style contains three rules. Each ```` varies the style based on the value of the population ("pop") attribute for each point, with smaller values yielding a smaller circle, and larger values yielding a larger circle. + +The three rules are designed as follows: + +.. list-table:: + :widths: 20 30 30 20 + + * - **Rule order** + - **Rule name** + - **Population** ("pop") + - **Size** + * - 1 + - SmallPop + - Less than 50,000 + - 8 + * - 2 + - MediumPop + - 50,000 to 100,000 + - 12 + * - 3 + - LargePop + - Greater than 100,000 + - 16 + +The order of the rules does not matter in this case, since each shape is only rendered by a single rule. + +The first rule, on **lines 2-22**, specifies the styling of those points whose population attribute is less than 50,000. **Lines 5-10** set this filter, with **lines 6-9** setting the "less than" filter, **line 7** denoting the attribute ("pop"), and **line 8** the value of 50,000. The symbol is a circle (**line 14**), the color is dark blue (``#0033CC``, on **line 16**), and the size is 8 pixels in diameter (**line 19**). + +The second rule, on **lines 23-49**, specifies a style for points whose population attribute is greater than or equal to 50,000 and less than 100,000. The population filter is set on **lines 26-37**. This filter is longer than in the first rule because two criteria need to be specified instead of one: a "greater than or equal to" and a "less than" filter. Notice the ``And`` on **line 27** and **line 36**. This mandates that both filters need to be true for the rule to be applicable. The size of the graphic is set to 12 pixels on **line 46**. All other styling directives are identical to the first rule. + +The third rule, on **lines 50-70**, specifies a style for points whose population attribute is greater than or equal to 100,000. The population filter is set on **lines 53-58**, and the only other difference is the size of the circle, which in this rule (**line 67**) is 16 pixels. + +The result of this style is that cities with larger populations have larger points. + + +Zoom-based point +---------------- + +This example alters the style of the points at different zoom levels. + +.. figure:: images/point_zoombasedpointlarge.png + :align: center + + *Zoom-based point: Zoomed in* + +.. figure:: images/point_zoombasedpointmedium.png + :align: center + + *Zoom-based point: Partially zoomed* + +.. figure:: images/point_zoombasedpointsmall.png + :align: center + + *Zoom-based point: Zoomed out* + + +Code +~~~~ + +:download:`View and download the full "Zoom-based point" SLD ` + +.. code-block:: xml + :linenos: + + + + Large + 160000000 + + + + circle + + #CC3300 + + + 12 + + + + + Medium + 160000000 + 320000000 + + + + circle + + #CC3300 + + + 8 + + + + + Small + 320000000 + + + + circle + + #CC3300 + + + 4 + + + + + + + + +Details +~~~~~~~ + +It is often desirable to make shapes larger at higher zoom levels when creating a natural-looking map. This example styles the points to vary in size based on the zoom level (or more accurately, scale denominator). Scale denominators refer to the scale of the map. A scale denominator of 10,000 means the map has a scale of 1:10,000 in the units of the map projection. + +.. note:: Determining the appropriate scale denominators (zoom levels) to use is beyond the scope of this example. + +This style contains three rules. The three rules are designed as follows: + +.. list-table:: + :widths: 25 25 25 25 + + * - **Rule order** + - **Rule name** + - **Scale denominator** + - **Point size** + * - 1 + - Large + - 1:160,000,000 or less + - 12 + * - 2 + - Medium + - 1:160,000,000 to 1:320,000,000 + - 8 + * - 3 + - Small + - Greater than 1:320,000,000 + - 4 + +The order of these rules does not matter since the scales denominated in each rule do not overlap. + +The first rule (**lines 2-16**) is for the smallest scale denominator, corresponding to when the view is "zoomed in". The scale rule is set on **line 4**, so that the rule will apply to any map with a scale denominator of 160,000,000 or less. The rule draws a circle (**line 8**), colored red (``#CC3300`` on **line 10**) with a size of 12 pixels (**line 13**). + +The second rule (**lines 17-32**) is the intermediate scale denominator, corresponding to when the view is "partially zoomed". The scale rules are set on **lines 19-20**, so that the rule will apply to any map with a scale denominator between 160,000,000 and 320,000,000. (The ```` is inclusive and the ```` is exclusive, so a zoom level of exactly 320,000,000 would *not* apply here.) Aside from the scale, the only difference between this rule and the first is the size of the symbol, which is set to 8 pixels on **line 29**. + +The third rule (**lines 33-47**) is the largest scale denominator, corresponding to when the map is "zoomed out". The scale rule is set on **line 35**, so that the rule will apply to any map with a scale denominator of 320,000,000 or more. Again, the only other difference between this rule and the others is the size of the symbol, which is set to 4 pixels on **line 44**. + +The result of this style is that points are drawn larger as one zooms in and smaller as one zooms out. + diff --git a/doc/en/user/source/styling/sld/cookbook/polygons.rst b/doc/en/user/source/styling/sld/cookbook/polygons.rst index 489031b64f8..b4bb9855443 100644 --- a/doc/en/user/source/styling/sld/cookbook/polygons.rst +++ b/doc/en/user/source/styling/sld/cookbook/polygons.rst @@ -1,724 +1,724 @@ -.. _sld_cookbook_polygons: - -Polygons -======== - -Polygons are two dimensional shapes that contain both an outer edge (or "stroke") and an inside (or "fill"). A polygon can be thought of as an irregularly-shaped point and is styled in similar ways to points. - -.. warning:: The code examples shown on this page are **not the full SLD code**, as they omit the SLD header and footer information for the sake of brevity. Please use the links to download the full SLD for each example. - -.. _sld_cookbook_polygons_attributes: - -Example polygons layer ----------------------- - -The :download:`polygons layer ` used below contains county information for a fictional country. For reference, the attribute table for the polygons is included below. - -.. list-table:: - :widths: 30 40 30 - - * - **fid** (Feature ID) - - **name** (County name) - - **pop** (Population) - * - polygon.1 - - Irony County - - 412234 - * - polygon.2 - - Tracker County - - 235421 - * - polygon.3 - - Dracula County - - 135022 - * - polygon.4 - - Poly County - - 1567879 - * - polygon.5 - - Bearing County - - 201989 - * - polygon.6 - - Monte Cristo County - - 152734 - * - polygon.7 - - Massive County - - 67123 - * - polygon.8 - - Rhombus County - - 198029 - -:download:`Download the polygons shapefile ` - - -.. _sld_cookbook_polygons_simplepolygon: - -Simple polygon --------------- - -This example shows a polygon filled in blue. - -.. figure:: images/polygon_simplepolygon.png - :align: center - - *Simple polygon* - -Code -~~~~ - -:download:`View and download the full "Simple polygon" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #000080 - - - - - -Details -~~~~~~~ - -There is one ```` in one ```` for this style, which is the simplest possible situation. (All subsequent examples will share this characteristic unless otherwise specified.) Styling polygons is accomplished via the ```` (**lines 3-7**). **Line 5** specifies dark blue (``#000080``) as the polygon's fill color. - -.. note:: The light-colored borders around the polygons in the figure are artifacts of the renderer caused by the polygons being adjacent. There is no border in this style. - -.. _sld_cookbook_polygons_simplepolygonwithstroke: - -Simple polygon with stroke --------------------------- - -This example adds a 2 pixel white stroke to the :ref:`sld_cookbook_polygons_simplepolygon` example. - -.. figure:: images/polygon_simplepolygonwithstroke.png - :align: center - - *Simple polygon with stroke* - -Code -~~~~ - -:download:`View and download the full "Simple polygon with stroke" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #000080 - - - #FFFFFF - 2 - - - - - -Details -~~~~~~~ - -This example is similar to the :ref:`sld_cookbook_polygons_simplepolygon` example above, with the addition of the ```` tag (**lines 7-10**). **Line 8** sets the color of stroke to white (``#FFFFFF``) and **line 9** sets the width of the stroke to 2 pixels. - - -Transparent polygon -------------------- - -This example builds on the :ref:`sld_cookbook_polygons_simplepolygonwithstroke` example and makes the fill partially transparent by setting the opacity to 50%. - -.. figure:: images/polygon_transparentpolygon.png - :align: center - - *Transparent polygon* - -Code -~~~~ - -:download:`View and download the full "Transparent polygon" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #000080 - 0.5 - - - #FFFFFF - 2 - - - - - -Details -~~~~~~~ - -This example is similar to the :ref:`sld_cookbook_polygons_simplepolygonwithstroke` example, save for defining the fill's opacity in **line 6**. The value of 0.5 results in partially transparent fill that is 50% opaque. An opacity value of 1 would draw the fill as 100% opaque, while an opacity value of 0 would result in a completely transparent (0% opaque) fill. In this example, since the background is white, the dark blue looks lighter. Were the points imposed on a dark background, the resulting color would be darker. - - -.. _sld_cookbook_polygons_offset: - -Offset inner lines ------------------- - -Shows how to draw inner buffer lines inside a polygon. - -.. figure:: images/polygon_offset.png - :align: center - - *Offset buffer* - -Code -~~~~ - -:download:`View and download the full "Inner offset lines" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #000000 - 2 - - - - - #AAAAAA - 3 - - -2 - - - - -Details -~~~~~~~ - -This example is similar to the :ref:`sld_cookbook_polygons_simplepolygonwithstroke` example, save -for defining adding a ``>`` at **line 9**, where a light gray (**line 11**) -3 pixels wide (**line 12**) line is drawn as a inner buffer inside the polygon. -**Line 14** controls the buffering distance, setting a inner buffer of 2 pixels. - - -.. _sld_cookbook_polygons_graphicfill: - -Graphic fill ------------- - -This example fills the polygons with a tiled graphic. - -.. figure:: images/polygon_graphicfill.png - :align: center - - *Graphic fill* - -Code -~~~~ - -:download:`View and download the full "Graphic fill" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - - - - image/png - - 93 - - - - - - - -Details -~~~~~~~ - -This style fills the polygon with a tiled graphic. This is known as an ```` in SLD, to distinguish it from commonly-used shapes such as squares and circles that are "internal" to the renderer. **Lines 7-12** specify details for the graphic, with **line 10** setting the path and file name of the graphic and **line 11** indicating the file format (MIME type) of the graphic (``image/png``). Although a full URL could be specified if desired, no path information is necessary in **line 11** because this graphic is contained in the same directory as the SLD. **Line 13** determines the height of the displayed graphic in pixels; if the value differs from the height of the graphic then it will be scaled accordingly while preserving the aspect ratio. - -.. figure:: images/colorblocks.png - :align: center - - *Graphic used for fill* - - -Hatching fill -------------- - -This example fills the polygons with a hatching pattern. - -.. note:: This example leverages an SLD extension in GeoServer. Hatching is not part of the standard SLD 1.0 specification. - -.. figure:: images/polygon_hatchingfill.png - :align: center - - *Hatching fill* - -Code -~~~~ - -:download:`View and download the full "Hatching fill" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - - - shape://times - - #990099 - 1 - - - 16 - - - - - - - -Details -~~~~~~~ - -In this example, there is a ```` tag as in the :ref:`sld_cookbook_polygons_graphicfill` example, but a ```` (**lines 7-13**) is used instead of an ````. **Line 8** specifies a "times" symbol (an "x") be tiled throughout the polygon. **Line 10** sets the color to purple (``#990099``), **line 11** sets the width of the hatches to 1 pixel, and **line 14** sets the size of the tile to 16 pixels. Because hatch tiles are always square, the ```` sets both the width and the height. - - -.. _sld_cookbook_polygons_polygonwithdefaultlabel: - -Polygon with default label --------------------------- - -This example shows a text label on the polygon. In the absence of any other customization, this is how a label will be displayed. - -.. figure:: images/polygon_polygonwithdefaultlabel.png - :align: center - - *Polygon with default label* - -Code -~~~~ - -:download:`View and download the full "Polygon with default label" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #40FF40 - - - #FFFFFF - 2 - - - - - - - - -Details -~~~~~~~ - -In this example there is a ```` and a ````. **Lines 3-11** comprise the ````. The fill of the polygon is set on **line 5** to a light green (``#40FF40``) while the stroke of the polygon is set on **lines 8-9** to white (``#FFFFFF``) with a thickness of 2 pixels. The label is set in the ```` on **lines 12-16**, with **line 14** determining what text to display, in this case the value of the "name" attribute. (Refer to the attribute table in the :ref:`sld_cookbook_polygons_attributes` section if necessary.) All other details about the label are set to the renderer default, which here is Times New Roman font, font color black, and font size of 10 pixels. - - -Label halo ----------- - -This example alters the look of the :ref:`sld_cookbook_polygons_polygonwithdefaultlabel` by adding a white halo to the label. - -.. figure:: images/polygon_labelhalo.png - :align: center - - *Label halo* - -Code -~~~~ - -:download:`View and download the full "Label halo" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #40FF40 - - - #FFFFFF - 2 - - - - - - 3 - - #FFFFFF - - - - - - -Details -~~~~~~~ - -This example is similar to the :ref:`sld_cookbook_polygons_polygonwithdefaultlabel`, with the addition of a halo around the labels on **lines 16-21**. A halo creates a color buffer around the label to improve label legibility. **Line 17** sets the radius of the halo, extending the halo 3 pixels around the edge of the label, and **line 19** sets the color of the halo to white (``#FFFFFF``). Since halos are most useful when set to a sharp contrast relative to the text color, this example uses a white halo around black text to ensure optimum readability. - - -.. _sld_cookbook_polygons_polygonwithstyledlabel: - -Polygon with styled label -------------------------- - -This example improves the label style from the :ref:`sld_cookbook_polygons_polygonwithdefaultlabel` example by centering the label on the polygon, specifying a different font name and size, and setting additional label placement optimizations. - -.. note:: The label placement optimizations discussed below (the ```` tags) are SLD extensions that are custom to GeoServer. They are not part of the SLD 1.0 specification. - -.. figure:: images/polygon_polygonwithstyledlabel.png - :align: center - - *Polygon with styled label* - -Code -~~~~ - -:download:`View and download the full "Polygon with styled label" SLD ` - -.. code-block:: xml - :linenos: - - - - - - #40FF40 - - - #FFFFFF - 2 - - - - - - Arial - 11 - normal - bold - - - - - 0.5 - 0.5 - - - - - #000000 - - 60 - 150 - - - - -Details -~~~~~~~ - -This example is similar to the :ref:`sld_cookbook_polygons_polygonwithdefaultlabel` example, with additional styling options within the ```` on lines **12-35**. **Lines 16-21** set the font styling. **Line 17** sets the font family to be Arial, **line 18** sets the font size to 11 pixels, **line 19** sets the font style to "normal" (as opposed to "italic" or "oblique"), and **line 20** sets the font weight to "bold" (as opposed to "normal"). - -The ```` tag on **lines 22-29** affects where the label is placed relative to the centroid of the polygon. **Line 21** centers the label by positioning it 50% (or 0.5) of the way horizontally along the centroid of the polygon. **Line 22** centers the label vertically in exactly the same way. - -Finally, there are two added touches for label placement optimization: **line 33** ensures that long labels are split across multiple lines by setting line wrapping on the labels to 60 pixels, and **line 34** allows the label to be displaced by up to 150 pixels. This ensures that labels are compacted and less likely to spill over polygon boundaries. Notice little Massive County in the corner, whose label is now displayed." - - -Attribute-based polygon ------------------------ - - -This example styles the polygons differently based on the "pop" (Population) attribute. - -.. figure:: images/polygon_attributebasedpolygon.png - :align: center - - *Attribute-based polygon* - -Code -~~~~ - -:download:`View and download the full "Attribute-based polygon" SLD ` - -.. code-block:: xml - :linenos: - - - - SmallPop - Less Than 200,000 - - - pop - 200000 - - - - - #66FF66 - - - - - MediumPop - 200,000 to 500,000 - - - - pop - 200000 - - - pop - 500000 - - - - - - #33CC33 - - - - - LargePop - Greater Than 500,000 - - - pop - 500000 - - - - - #009900 - - - - - - -Details -~~~~~~~ - -.. note:: Refer to the :ref:`sld_cookbook_polygons_attributes` to see the attributes for the layer. This example has eschewed labels in order to simplify the style, but you can refer to the example :ref:`sld_cookbook_polygons_polygonwithstyledlabel` to see which attributes correspond to which polygons. - -Each polygon in our fictional country has a population that is represented by the population ("pop") attribute. This style contains three rules that alter the fill based on the value of "pop" attribute, with smaller values yielding a lighter color and larger values yielding a darker color. - -The three rules are designed as follows: - -.. list-table:: - :widths: 20 20 30 30 - - * - **Rule order** - - **Rule name** - - **Population** ("pop") - - **Color** - * - 1 - - SmallPop - - Less than 200,000 - - ``#66FF66`` - * - 2 - - MediumPop - - 200,000 to 500,000 - - ``#33CC33`` - * - 3 - - LargePop - - Greater than 500,000 - - ``#009900`` - -The order of the rules does not matter in this case, since each shape is only rendered by a single rule. - -The first rule, on **lines 2-16**, specifies the styling of polygons whose population attribute is less than 200,000. **Lines 5-10** set this filter, with **lines 6-9** setting the "less than" filter, **line 7** denoting the attribute ("pop"), and **line 8** the value of 200,000. The color of the polygon fill is set to a light green (``#66FF66``) on **line 13**. - -The second rule, on **lines 17-37**, is similar, specifying a style for polygons whose population attribute is greater than or equal to 200,000 but less than 500,000. The filter is set on **lines 20-31**. This filter is longer than in the first rule because two criteria need to be specified instead of one: a "greater than or equal to" and a "less than" filter. Notice the ``And`` on **line 21** and **line 30**. This mandates that both filters need to be true for the rule to be applicable. The color of the polygon fill is set to a medium green on (``#33CC33``) on **line 34**. - -The third rule, on **lines 38-52**, specifies a style for polygons whose population attribute is greater than or equal to 500,000. The filter is set on **lines 41-46**. The color of the polygon fill is the only other difference in this rule, which is set to a dark green (``#009900``) on **line 49**. - - - -Zoom-based polygon ------------------- - -This example alters the style of the polygon at different zoom levels. - - -.. figure:: images/polygon_zoombasedpolygonlarge.png - :align: center - - *Zoom-based polygon: Zoomed in* - -.. figure:: images/polygon_zoombasedpolygonmedium.png - :align: center - - *Zoom-based polygon: Partially zoomed* - -.. figure:: images/polygon_zoombasedpolygonsmall.png - :align: center - - *Zoom-based polygon: Zoomed out* - -Code -~~~~ - -:download:`View and download the full "Zoom-based polygon" SLD ` - -.. code-block:: xml - :linenos: - - - - Large - 100000000 - - - #0000CC - - - #000000 - 7 - - - - - - Arial - 14 - normal - bold - - - - - 0.5 - 0.5 - - - - - #FFFFFF - - - - - Medium - 100000000 - 200000000 - - - #0000CC - - - #000000 - 4 - - - - - Small - 200000000 - - - #0000CC - - - #000000 - 1 - - - - - -Details -~~~~~~~ - -It is often desirable to make shapes larger at higher zoom levels when creating a natural-looking map. This example varies the thickness of the lines according to the zoom level. Polygons already do this by nature of being two dimensional, but another way to adjust styling of polygons based on zoom level is to adjust the thickness of the stroke (to be larger as the map is zoomed in) or to limit labels to only certain zoom levels. This is ensures that the size and quantity of strokes and labels remains legible and doesn't overshadow the polygons themselves. - -Zoom levels (or more accurately, scale denominators) refer to the scale of the map. A scale denominator of 10,000 means the map has a scale of 1:10,000 in the units of the map projection. - -.. note:: Determining the appropriate scale denominators (zoom levels) to use is beyond the scope of this example. - -This style contains three rules, defined as follows: - -.. list-table:: - :widths: 15 15 40 15 15 - - * - **Rule order** - - **Rule name** - - **Scale denominator** - - **Stroke width** - - **Label display?** - * - 1 - - Large - - 1:100,000,000 or less - - 7 - - Yes - * - 2 - - Medium - - 1:100,000,000 to 1:200,000,000 - - 4 - - No - * - 3 - - Small - - Greater than 1:200,000,000 - - 2 - - No - -The first rule, on **lines 2-36**, is for the smallest scale denominator, corresponding to when the view is "zoomed in". The scale rule is set on **line 40** such that the rule will apply only where the scale denominator is 100,000,000 or less. **Line 7** defines the fill as blue (``#0000CC``). Note that the fill is kept constant across all rules regardless of the scale denominator. As in the :ref:`sld_cookbook_polygons_polygonwithdefaultlabel` or :ref:`sld_cookbook_polygons_polygonwithstyledlabel` examples, the rule also contains a ```` at **lines 14-35** for drawing a text label on top of the polygon. **Lines 19-22** set the font information to be Arial, 14 pixels, and bold with no italics. The label is centered both horizontally and vertically along the centroid of the polygon on by setting ```` and ```` to both be 0.5 (or 50%) on **lines 27-28**. Finally, the color of the font is set to white (``#FFFFFF``) in **line 33**. - -The second rule, on **lines 37-50**, is for the intermediate scale denominators, corresponding to when the view is "partially zoomed". The scale rules on **lines 39-40** set the rule such that it will apply to any map with a scale denominator between 100,000,000 and 200,000,000. (The ```` is inclusive and the ```` is exclusive, so a zoom level of exactly 200,000,000 would *not* apply here.) Aside from the scale, there are two differences between this rule and the first: the width of the stroke is set to 4 pixels on **line 47** and a ```` is not present so that no labels will be displayed. - -The third rule, on **lines 51-63**, is for the largest scale denominator, corresponding to when the map is "zoomed out". The scale rule is set on **line 53** such that the rule will apply to any map with a scale denominator of 200,000,000 or greater. Again, the only differences between this rule and the others are the width of the lines, which is set to 1 pixel on **line 60**, and the absence of a ```` so that no labels will be displayed. - +.. _sld_cookbook_polygons: + +Polygons +======== + +Polygons are two dimensional shapes that contain both an outer edge (or "stroke") and an inside (or "fill"). A polygon can be thought of as an irregularly-shaped point and is styled in similar ways to points. + +.. warning:: The code examples shown on this page are **not the full SLD code**, as they omit the SLD header and footer information for the sake of brevity. Please use the links to download the full SLD for each example. + +.. _sld_cookbook_polygons_attributes: + +Example polygons layer +---------------------- + +The :download:`polygons layer ` used below contains county information for a fictional country. For reference, the attribute table for the polygons is included below. + +.. list-table:: + :widths: 30 40 30 + + * - **fid** (Feature ID) + - **name** (County name) + - **pop** (Population) + * - polygon.1 + - Irony County + - 412234 + * - polygon.2 + - Tracker County + - 235421 + * - polygon.3 + - Dracula County + - 135022 + * - polygon.4 + - Poly County + - 1567879 + * - polygon.5 + - Bearing County + - 201989 + * - polygon.6 + - Monte Cristo County + - 152734 + * - polygon.7 + - Massive County + - 67123 + * - polygon.8 + - Rhombus County + - 198029 + +:download:`Download the polygons shapefile ` + + +.. _sld_cookbook_polygons_simplepolygon: + +Simple polygon +-------------- + +This example shows a polygon filled in blue. + +.. figure:: images/polygon_simplepolygon.png + :align: center + + *Simple polygon* + +Code +~~~~ + +:download:`View and download the full "Simple polygon" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #000080 + + + + + +Details +~~~~~~~ + +There is one ```` in one ```` for this style, which is the simplest possible situation. (All subsequent examples will share this characteristic unless otherwise specified.) Styling polygons is accomplished via the ```` (**lines 3-7**). **Line 5** specifies dark blue (``#000080``) as the polygon's fill color. + +.. note:: The light-colored borders around the polygons in the figure are artifacts of the renderer caused by the polygons being adjacent. There is no border in this style. + +.. _sld_cookbook_polygons_simplepolygonwithstroke: + +Simple polygon with stroke +-------------------------- + +This example adds a 2 pixel white stroke to the :ref:`sld_cookbook_polygons_simplepolygon` example. + +.. figure:: images/polygon_simplepolygonwithstroke.png + :align: center + + *Simple polygon with stroke* + +Code +~~~~ + +:download:`View and download the full "Simple polygon with stroke" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #000080 + + + #FFFFFF + 2 + + + + + +Details +~~~~~~~ + +This example is similar to the :ref:`sld_cookbook_polygons_simplepolygon` example above, with the addition of the ```` tag (**lines 7-10**). **Line 8** sets the color of stroke to white (``#FFFFFF``) and **line 9** sets the width of the stroke to 2 pixels. + + +Transparent polygon +------------------- + +This example builds on the :ref:`sld_cookbook_polygons_simplepolygonwithstroke` example and makes the fill partially transparent by setting the opacity to 50%. + +.. figure:: images/polygon_transparentpolygon.png + :align: center + + *Transparent polygon* + +Code +~~~~ + +:download:`View and download the full "Transparent polygon" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #000080 + 0.5 + + + #FFFFFF + 2 + + + + + +Details +~~~~~~~ + +This example is similar to the :ref:`sld_cookbook_polygons_simplepolygonwithstroke` example, save for defining the fill's opacity in **line 6**. The value of 0.5 results in partially transparent fill that is 50% opaque. An opacity value of 1 would draw the fill as 100% opaque, while an opacity value of 0 would result in a completely transparent (0% opaque) fill. In this example, since the background is white, the dark blue looks lighter. Were the points imposed on a dark background, the resulting color would be darker. + + +.. _sld_cookbook_polygons_offset: + +Offset inner lines +------------------ + +Shows how to draw inner buffer lines inside a polygon. + +.. figure:: images/polygon_offset.png + :align: center + + *Offset buffer* + +Code +~~~~ + +:download:`View and download the full "Inner offset lines" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #000000 + 2 + + + + + #AAAAAA + 3 + + -2 + + + + +Details +~~~~~~~ + +This example is similar to the :ref:`sld_cookbook_polygons_simplepolygonwithstroke` example, save +for defining adding a ``>`` at **line 9**, where a light gray (**line 11**) +3 pixels wide (**line 12**) line is drawn as a inner buffer inside the polygon. +**Line 14** controls the buffering distance, setting a inner buffer of 2 pixels. + + +.. _sld_cookbook_polygons_graphicfill: + +Graphic fill +------------ + +This example fills the polygons with a tiled graphic. + +.. figure:: images/polygon_graphicfill.png + :align: center + + *Graphic fill* + +Code +~~~~ + +:download:`View and download the full "Graphic fill" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + + + + image/png + + 93 + + + + + + + +Details +~~~~~~~ + +This style fills the polygon with a tiled graphic. This is known as an ```` in SLD, to distinguish it from commonly-used shapes such as squares and circles that are "internal" to the renderer. **Lines 7-12** specify details for the graphic, with **line 10** setting the path and file name of the graphic and **line 11** indicating the file format (MIME type) of the graphic (``image/png``). Although a full URL could be specified if desired, no path information is necessary in **line 11** because this graphic is contained in the same directory as the SLD. **Line 13** determines the height of the displayed graphic in pixels; if the value differs from the height of the graphic then it will be scaled accordingly while preserving the aspect ratio. + +.. figure:: images/colorblocks.png + :align: center + + *Graphic used for fill* + + +Hatching fill +------------- + +This example fills the polygons with a hatching pattern. + +.. note:: This example leverages an SLD extension in GeoServer. Hatching is not part of the standard SLD 1.0 specification. + +.. figure:: images/polygon_hatchingfill.png + :align: center + + *Hatching fill* + +Code +~~~~ + +:download:`View and download the full "Hatching fill" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + + + shape://times + + #990099 + 1 + + + 16 + + + + + + + +Details +~~~~~~~ + +In this example, there is a ```` tag as in the :ref:`sld_cookbook_polygons_graphicfill` example, but a ```` (**lines 7-13**) is used instead of an ````. **Line 8** specifies a "times" symbol (an "x") be tiled throughout the polygon. **Line 10** sets the color to purple (``#990099``), **line 11** sets the width of the hatches to 1 pixel, and **line 14** sets the size of the tile to 16 pixels. Because hatch tiles are always square, the ```` sets both the width and the height. + + +.. _sld_cookbook_polygons_polygonwithdefaultlabel: + +Polygon with default label +-------------------------- + +This example shows a text label on the polygon. In the absence of any other customization, this is how a label will be displayed. + +.. figure:: images/polygon_polygonwithdefaultlabel.png + :align: center + + *Polygon with default label* + +Code +~~~~ + +:download:`View and download the full "Polygon with default label" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #40FF40 + + + #FFFFFF + 2 + + + + + + + + +Details +~~~~~~~ + +In this example there is a ```` and a ````. **Lines 3-11** comprise the ````. The fill of the polygon is set on **line 5** to a light green (``#40FF40``) while the stroke of the polygon is set on **lines 8-9** to white (``#FFFFFF``) with a thickness of 2 pixels. The label is set in the ```` on **lines 12-16**, with **line 14** determining what text to display, in this case the value of the "name" attribute. (Refer to the attribute table in the :ref:`sld_cookbook_polygons_attributes` section if necessary.) All other details about the label are set to the renderer default, which here is Times New Roman font, font color black, and font size of 10 pixels. + + +Label halo +---------- + +This example alters the look of the :ref:`sld_cookbook_polygons_polygonwithdefaultlabel` by adding a white halo to the label. + +.. figure:: images/polygon_labelhalo.png + :align: center + + *Label halo* + +Code +~~~~ + +:download:`View and download the full "Label halo" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #40FF40 + + + #FFFFFF + 2 + + + + + + 3 + + #FFFFFF + + + + + + +Details +~~~~~~~ + +This example is similar to the :ref:`sld_cookbook_polygons_polygonwithdefaultlabel`, with the addition of a halo around the labels on **lines 16-21**. A halo creates a color buffer around the label to improve label legibility. **Line 17** sets the radius of the halo, extending the halo 3 pixels around the edge of the label, and **line 19** sets the color of the halo to white (``#FFFFFF``). Since halos are most useful when set to a sharp contrast relative to the text color, this example uses a white halo around black text to ensure optimum readability. + + +.. _sld_cookbook_polygons_polygonwithstyledlabel: + +Polygon with styled label +------------------------- + +This example improves the label style from the :ref:`sld_cookbook_polygons_polygonwithdefaultlabel` example by centering the label on the polygon, specifying a different font name and size, and setting additional label placement optimizations. + +.. note:: The label placement optimizations discussed below (the ```` tags) are SLD extensions that are custom to GeoServer. They are not part of the SLD 1.0 specification. + +.. figure:: images/polygon_polygonwithstyledlabel.png + :align: center + + *Polygon with styled label* + +Code +~~~~ + +:download:`View and download the full "Polygon with styled label" SLD ` + +.. code-block:: xml + :linenos: + + + + + + #40FF40 + + + #FFFFFF + 2 + + + + + + Arial + 11 + normal + bold + + + + + 0.5 + 0.5 + + + + + #000000 + + 60 + 150 + + + + +Details +~~~~~~~ + +This example is similar to the :ref:`sld_cookbook_polygons_polygonwithdefaultlabel` example, with additional styling options within the ```` on lines **12-35**. **Lines 16-21** set the font styling. **Line 17** sets the font family to be Arial, **line 18** sets the font size to 11 pixels, **line 19** sets the font style to "normal" (as opposed to "italic" or "oblique"), and **line 20** sets the font weight to "bold" (as opposed to "normal"). + +The ```` tag on **lines 22-29** affects where the label is placed relative to the centroid of the polygon. **Line 21** centers the label by positioning it 50% (or 0.5) of the way horizontally along the centroid of the polygon. **Line 22** centers the label vertically in exactly the same way. + +Finally, there are two added touches for label placement optimization: **line 33** ensures that long labels are split across multiple lines by setting line wrapping on the labels to 60 pixels, and **line 34** allows the label to be displaced by up to 150 pixels. This ensures that labels are compacted and less likely to spill over polygon boundaries. Notice little Massive County in the corner, whose label is now displayed." + + +Attribute-based polygon +----------------------- + + +This example styles the polygons differently based on the "pop" (Population) attribute. + +.. figure:: images/polygon_attributebasedpolygon.png + :align: center + + *Attribute-based polygon* + +Code +~~~~ + +:download:`View and download the full "Attribute-based polygon" SLD ` + +.. code-block:: xml + :linenos: + + + + SmallPop + Less Than 200,000 + + + pop + 200000 + + + + + #66FF66 + + + + + MediumPop + 200,000 to 500,000 + + + + pop + 200000 + + + pop + 500000 + + + + + + #33CC33 + + + + + LargePop + Greater Than 500,000 + + + pop + 500000 + + + + + #009900 + + + + + + +Details +~~~~~~~ + +.. note:: Refer to the :ref:`sld_cookbook_polygons_attributes` to see the attributes for the layer. This example has eschewed labels in order to simplify the style, but you can refer to the example :ref:`sld_cookbook_polygons_polygonwithstyledlabel` to see which attributes correspond to which polygons. + +Each polygon in our fictional country has a population that is represented by the population ("pop") attribute. This style contains three rules that alter the fill based on the value of "pop" attribute, with smaller values yielding a lighter color and larger values yielding a darker color. + +The three rules are designed as follows: + +.. list-table:: + :widths: 20 20 30 30 + + * - **Rule order** + - **Rule name** + - **Population** ("pop") + - **Color** + * - 1 + - SmallPop + - Less than 200,000 + - ``#66FF66`` + * - 2 + - MediumPop + - 200,000 to 500,000 + - ``#33CC33`` + * - 3 + - LargePop + - Greater than 500,000 + - ``#009900`` + +The order of the rules does not matter in this case, since each shape is only rendered by a single rule. + +The first rule, on **lines 2-16**, specifies the styling of polygons whose population attribute is less than 200,000. **Lines 5-10** set this filter, with **lines 6-9** setting the "less than" filter, **line 7** denoting the attribute ("pop"), and **line 8** the value of 200,000. The color of the polygon fill is set to a light green (``#66FF66``) on **line 13**. + +The second rule, on **lines 17-37**, is similar, specifying a style for polygons whose population attribute is greater than or equal to 200,000 but less than 500,000. The filter is set on **lines 20-31**. This filter is longer than in the first rule because two criteria need to be specified instead of one: a "greater than or equal to" and a "less than" filter. Notice the ``And`` on **line 21** and **line 30**. This mandates that both filters need to be true for the rule to be applicable. The color of the polygon fill is set to a medium green on (``#33CC33``) on **line 34**. + +The third rule, on **lines 38-52**, specifies a style for polygons whose population attribute is greater than or equal to 500,000. The filter is set on **lines 41-46**. The color of the polygon fill is the only other difference in this rule, which is set to a dark green (``#009900``) on **line 49**. + + + +Zoom-based polygon +------------------ + +This example alters the style of the polygon at different zoom levels. + + +.. figure:: images/polygon_zoombasedpolygonlarge.png + :align: center + + *Zoom-based polygon: Zoomed in* + +.. figure:: images/polygon_zoombasedpolygonmedium.png + :align: center + + *Zoom-based polygon: Partially zoomed* + +.. figure:: images/polygon_zoombasedpolygonsmall.png + :align: center + + *Zoom-based polygon: Zoomed out* + +Code +~~~~ + +:download:`View and download the full "Zoom-based polygon" SLD ` + +.. code-block:: xml + :linenos: + + + + Large + 100000000 + + + #0000CC + + + #000000 + 7 + + + + + + Arial + 14 + normal + bold + + + + + 0.5 + 0.5 + + + + + #FFFFFF + + + + + Medium + 100000000 + 200000000 + + + #0000CC + + + #000000 + 4 + + + + + Small + 200000000 + + + #0000CC + + + #000000 + 1 + + + + + +Details +~~~~~~~ + +It is often desirable to make shapes larger at higher zoom levels when creating a natural-looking map. This example varies the thickness of the lines according to the zoom level. Polygons already do this by nature of being two dimensional, but another way to adjust styling of polygons based on zoom level is to adjust the thickness of the stroke (to be larger as the map is zoomed in) or to limit labels to only certain zoom levels. This is ensures that the size and quantity of strokes and labels remains legible and doesn't overshadow the polygons themselves. + +Zoom levels (or more accurately, scale denominators) refer to the scale of the map. A scale denominator of 10,000 means the map has a scale of 1:10,000 in the units of the map projection. + +.. note:: Determining the appropriate scale denominators (zoom levels) to use is beyond the scope of this example. + +This style contains three rules, defined as follows: + +.. list-table:: + :widths: 15 15 40 15 15 + + * - **Rule order** + - **Rule name** + - **Scale denominator** + - **Stroke width** + - **Label display?** + * - 1 + - Large + - 1:100,000,000 or less + - 7 + - Yes + * - 2 + - Medium + - 1:100,000,000 to 1:200,000,000 + - 4 + - No + * - 3 + - Small + - Greater than 1:200,000,000 + - 2 + - No + +The first rule, on **lines 2-36**, is for the smallest scale denominator, corresponding to when the view is "zoomed in". The scale rule is set on **line 40** such that the rule will apply only where the scale denominator is 100,000,000 or less. **Line 7** defines the fill as blue (``#0000CC``). Note that the fill is kept constant across all rules regardless of the scale denominator. As in the :ref:`sld_cookbook_polygons_polygonwithdefaultlabel` or :ref:`sld_cookbook_polygons_polygonwithstyledlabel` examples, the rule also contains a ```` at **lines 14-35** for drawing a text label on top of the polygon. **Lines 19-22** set the font information to be Arial, 14 pixels, and bold with no italics. The label is centered both horizontally and vertically along the centroid of the polygon on by setting ```` and ```` to both be 0.5 (or 50%) on **lines 27-28**. Finally, the color of the font is set to white (``#FFFFFF``) in **line 33**. + +The second rule, on **lines 37-50**, is for the intermediate scale denominators, corresponding to when the view is "partially zoomed". The scale rules on **lines 39-40** set the rule such that it will apply to any map with a scale denominator between 100,000,000 and 200,000,000. (The ```` is inclusive and the ```` is exclusive, so a zoom level of exactly 200,000,000 would *not* apply here.) Aside from the scale, there are two differences between this rule and the first: the width of the stroke is set to 4 pixels on **line 47** and a ```` is not present so that no labels will be displayed. + +The third rule, on **lines 51-63**, is for the largest scale denominator, corresponding to when the map is "zoomed out". The scale rule is set on **line 53** such that the rule will apply to any map with a scale denominator of 200,000,000 or greater. Again, the only differences between this rule and the others are the width of the lines, which is set to 1 pixel on **line 60**, and the absence of a ```` so that no labels will be displayed. + The resulting style produces a polygon stroke that gets larger as one zooms in and labels that only display when zoomed in to a sufficient level. \ No newline at end of file diff --git a/doc/en/user/source/styling/sld/cookbook/rasters.rst b/doc/en/user/source/styling/sld/cookbook/rasters.rst index 678fb4fbf0a..883276d0a61 100644 --- a/doc/en/user/source/styling/sld/cookbook/rasters.rst +++ b/doc/en/user/source/styling/sld/cookbook/rasters.rst @@ -1,336 +1,336 @@ -.. _sld_cookbook_rasters: - -Rasters -======= - -Rasters are geographic data displayed in a grid. They are similar to image files such as PNG files, except that instead of each point containing visual information, each point contains geographic information in numerical form. Rasters can be thought of as a georeferenced table of numerical values. - -One example of a raster is a Digital Elevation Model (DEM) layer, which has elevation data encoded numerically at each georeferenced data point. - -.. warning:: The code examples shown on this page are **not the full SLD code**, as they omit the SLD header and footer information for the sake of brevity. Please use the links to download the full SLD for each example. - - -Example raster --------------- - -The :download:`raster layer ` that is used in the examples below contains elevation data for a fictional world. The data is stored in EPSG:4326 (longitude/latitude) and has a data range from 70 to 256. If rendered in grayscale, where minimum values are colored black and maximum values are colored white, the raster would look like this: - -.. figure:: images/raster.png - :align: center - - *Raster file as rendered in grayscale* - -:download:`Download the raster shapefile ` - -.. _sld_cookbook_raster_twocolorgradient: - - -Two-color gradient ------------------- - -This example shows a two-color style with green at lower elevations and brown at higher elevations. - -.. figure:: images/raster_twocolorgradient.png - :align: center - - *Two-color gradient* - -Code -~~~~ - -:download:`View and download the full "Two-color gradient" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - - - - - - -Details -~~~~~~~ - -There is one ```` in one ```` for this example, which is the simplest possible situation. All subsequent examples will share this characteristic. Styling of rasters is done via the ```` tag (**lines 3-8**). - -This example creates a smooth gradient between two colors corresponding to two elevation values. The gradient is created via the ```` on **lines 4-7**. Each entry in the ```` represents one entry or anchor in the gradient. **Line 5** sets the lower value of 70 via the ``quantity`` parameter, which is styled a dark green (``#008000``). **Line 6** sets the upper value of 256 via the ``quantity`` parameter again, which is styled a dark brown (``#663333``). All data values in between these two quantities will be linearly interpolated: a value of 163 (the midpoint between 70 and 256) will be colored as the midpoint between the two colors (in this case approximately ``#335717``, a muddy green). - -Transparent gradient --------------------- - -This example creates the same two-color gradient as in the :ref:`sld_cookbook_raster_twocolorgradient` as in the example above but makes the entire layer mostly transparent by setting a 30% opacity. - -.. figure:: images/raster_transparentgradient.png - :align: center - - *Transparent gradient* - -Code -~~~~ - -:download:`View and download the full "Transparent gradient" SLD ` - -.. code-block:: xml - :linenos: - - - - - 0.3 - - - - - - - - -Details -~~~~~~~ - - -This example is similar to the :ref:`sld_cookbook_raster_twocolorgradient` example save for the addition of **line 4**, which sets the opacity of the layer to 0.3 (or 30% opaque). An opacity value of 1 means that the shape is drawn 100% opaque, while an opacity value of 0 means that the shape is rendered as completely transparent. The value of 0.3 means that the the raster partially takes on the color and style of whatever is drawn beneath it. Since the background is white in this example, the colors generated from the ```` look lighter, but were the raster imposed on a dark background the resulting colors would be darker. - - -Brightness and contrast ------------------------ - -This example normalizes the color output and then increases the brightness by a factor of 2. - -.. figure:: images/raster_brightnessandcontrast.png - :align: center - - *Brightness and contrast* - -Code -~~~~ - -:download:`View and download the full "Brightness and contrast" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - 0.5 - - - - - - - - - -Details -~~~~~~~ - -This example is similar to the :ref:`sld_cookbook_raster_twocolorgradient`, save for the addition of the ```` tag on **lines 4-7**. **Line 5** normalizes the output by increasing the contrast to its maximum extent. **Line 6** then adjusts the brightness by a factor of 0.5. Since values less than 1 make the output brighter, a value of 0.5 makes the output twice as bright. - -As with previous examples, **lines 8-11** determine the ````, with **line 9** setting the lower bound (70) to be colored dark green (``#008000``) and **line 10** setting the upper bound (256) to be colored dark brown (``#663333``). - - - -Three-color gradient --------------------- - -This example creates a three-color gradient in primary colors. - -.. figure:: images/raster_threecolorgradient.png - :align: center - - *Three-color gradient* - -Code -~~~~ - -:download:`View and download the full "Three-color gradient" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - - - - - - - -Details -~~~~~~~ - -This example creates a three-color gradient based on a ```` with three entries on **lines 4-8**: **line 5** specifies the lower bound (150) be styled in blue (``#0000FF``), **line 6** specifies an intermediate point (200) be styled in yellow (``#FFFF00``), and **line 7** specifies the upper bound (250) be styled in red (``#FF0000``). - -Since our data values run between 70 and 256, some data points are not accounted for in this style. Those values below the lowest entry in the color map (the range from 70 to 149) are styled the same color as the lower bound, in this case blue. Values above the upper bound in the color map (the range from 251 to 256) are styled the same color as the upper bound, in this case red. - - -Alpha channel -------------- - -This example creates an "alpha channel" effect such that higher values are increasingly transparent. - -.. figure:: images/raster_alphachannel.png - :align: center - - *Alpha channel* - -Code -~~~~ - -:download:`View and download the full "Alpha channel" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - - - - - - -Details -~~~~~~~ - -An alpha channel is another way of referring to variable transparency. Much like how a gradient maps values to colors, each entry in a ```` can have a value for opacity (with the default being 1.0 or completely opaque). - -In this example, there is a ```` with two entries: **line 5** specifies the lower bound of 70 be colored dark green (``#008000``), while **line 6** specifies the upper bound of 256 also be colored dark green but with an opacity value of 0. This means that values of 256 will be rendered at 0% opacity (entirely transparent). Just like the gradient color, the opacity is also linearly interpolated such that a value of 163 (the midpoint between 70 and 256) is rendered at 50% opacity. - - -Discrete colors ---------------- - -This example shows a gradient that is not linearly interpolated but instead has values mapped precisely to one of three specific colors. - -.. note:: This example leverages an SLD extension in GeoServer. Discrete colors are not part of the standard SLD 1.0 specification. - -.. figure:: images/raster_discretecolors.png - :align: center - - *Discrete colors* - -Code -~~~~ - -:download:`View and download the full "Discrete colors" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - - - - - - -Details -~~~~~~~ - -Sometimes color bands in discrete steps are more appropriate than a color gradient. The ``type="intervals"`` parameter added to the ```` on **line 4** sets the display to output discrete colors instead of a gradient. The values in each entry correspond to the upper bound for the color -band such that colors are mapped to values less than the value of one entry but greater than or equal to the next lower entry. For example, **line 5** colors all values less than 150 to dark green (``#008000``) and line 6 colors all values less than 256 but greater than or equal to 150 to dark brown (``#663333``). - - -Many color gradient -------------------- - -This example shows a gradient interpolated across eight different colors. - -.. figure:: images/raster_manycolorgradient.png - :align: center - - *Many color gradient* - -Code -~~~~ - -:download:`View and download the full "Many color gradient" SLD ` - -.. code-block:: xml - :linenos: - - - - - - - - - - - - - - - - - - -Details -~~~~~~~ - -A ```` can include up to 255 ```` elements. -This example has eight entries (**lines 4-13**): - -.. list-table:: - :widths: 15 25 30 30 - - * - **Entry number** - - **Value** - - **Color** - - **RGB code** - * - 1 - - 95 - - Black - - ``#000000`` - * - 2 - - 110 - - Blue - - ``#0000FF`` - * - 3 - - 135 - - Green - - ``#00FF00`` - * - 4 - - 160 - - Red - - ``#FF0000`` - * - 5 - - 185 - - Purple - - ``#FF00FF`` - * - 6 - - 210 - - Yellow - - ``#FFFF00`` - * - 7 - - 235 - - Cyan - - ``#00FFFF`` - * - 8 - - 256 - - White - - ``#FFFFFF`` - +.. _sld_cookbook_rasters: + +Rasters +======= + +Rasters are geographic data displayed in a grid. They are similar to image files such as PNG files, except that instead of each point containing visual information, each point contains geographic information in numerical form. Rasters can be thought of as a georeferenced table of numerical values. + +One example of a raster is a Digital Elevation Model (DEM) layer, which has elevation data encoded numerically at each georeferenced data point. + +.. warning:: The code examples shown on this page are **not the full SLD code**, as they omit the SLD header and footer information for the sake of brevity. Please use the links to download the full SLD for each example. + + +Example raster +-------------- + +The :download:`raster layer ` that is used in the examples below contains elevation data for a fictional world. The data is stored in EPSG:4326 (longitude/latitude) and has a data range from 70 to 256. If rendered in grayscale, where minimum values are colored black and maximum values are colored white, the raster would look like this: + +.. figure:: images/raster.png + :align: center + + *Raster file as rendered in grayscale* + +:download:`Download the raster shapefile ` + +.. _sld_cookbook_raster_twocolorgradient: + + +Two-color gradient +------------------ + +This example shows a two-color style with green at lower elevations and brown at higher elevations. + +.. figure:: images/raster_twocolorgradient.png + :align: center + + *Two-color gradient* + +Code +~~~~ + +:download:`View and download the full "Two-color gradient" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + + + + + + +Details +~~~~~~~ + +There is one ```` in one ```` for this example, which is the simplest possible situation. All subsequent examples will share this characteristic. Styling of rasters is done via the ```` tag (**lines 3-8**). + +This example creates a smooth gradient between two colors corresponding to two elevation values. The gradient is created via the ```` on **lines 4-7**. Each entry in the ```` represents one entry or anchor in the gradient. **Line 5** sets the lower value of 70 via the ``quantity`` parameter, which is styled a dark green (``#008000``). **Line 6** sets the upper value of 256 via the ``quantity`` parameter again, which is styled a dark brown (``#663333``). All data values in between these two quantities will be linearly interpolated: a value of 163 (the midpoint between 70 and 256) will be colored as the midpoint between the two colors (in this case approximately ``#335717``, a muddy green). + +Transparent gradient +-------------------- + +This example creates the same two-color gradient as in the :ref:`sld_cookbook_raster_twocolorgradient` as in the example above but makes the entire layer mostly transparent by setting a 30% opacity. + +.. figure:: images/raster_transparentgradient.png + :align: center + + *Transparent gradient* + +Code +~~~~ + +:download:`View and download the full "Transparent gradient" SLD ` + +.. code-block:: xml + :linenos: + + + + + 0.3 + + + + + + + + +Details +~~~~~~~ + + +This example is similar to the :ref:`sld_cookbook_raster_twocolorgradient` example save for the addition of **line 4**, which sets the opacity of the layer to 0.3 (or 30% opaque). An opacity value of 1 means that the shape is drawn 100% opaque, while an opacity value of 0 means that the shape is rendered as completely transparent. The value of 0.3 means that the the raster partially takes on the color and style of whatever is drawn beneath it. Since the background is white in this example, the colors generated from the ```` look lighter, but were the raster imposed on a dark background the resulting colors would be darker. + + +Brightness and contrast +----------------------- + +This example normalizes the color output and then increases the brightness by a factor of 2. + +.. figure:: images/raster_brightnessandcontrast.png + :align: center + + *Brightness and contrast* + +Code +~~~~ + +:download:`View and download the full "Brightness and contrast" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + 0.5 + + + + + + + + + +Details +~~~~~~~ + +This example is similar to the :ref:`sld_cookbook_raster_twocolorgradient`, save for the addition of the ```` tag on **lines 4-7**. **Line 5** normalizes the output by increasing the contrast to its maximum extent. **Line 6** then adjusts the brightness by a factor of 0.5. Since values less than 1 make the output brighter, a value of 0.5 makes the output twice as bright. + +As with previous examples, **lines 8-11** determine the ````, with **line 9** setting the lower bound (70) to be colored dark green (``#008000``) and **line 10** setting the upper bound (256) to be colored dark brown (``#663333``). + + + +Three-color gradient +-------------------- + +This example creates a three-color gradient in primary colors. + +.. figure:: images/raster_threecolorgradient.png + :align: center + + *Three-color gradient* + +Code +~~~~ + +:download:`View and download the full "Three-color gradient" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + + + + + + + +Details +~~~~~~~ + +This example creates a three-color gradient based on a ```` with three entries on **lines 4-8**: **line 5** specifies the lower bound (150) be styled in blue (``#0000FF``), **line 6** specifies an intermediate point (200) be styled in yellow (``#FFFF00``), and **line 7** specifies the upper bound (250) be styled in red (``#FF0000``). + +Since our data values run between 70 and 256, some data points are not accounted for in this style. Those values below the lowest entry in the color map (the range from 70 to 149) are styled the same color as the lower bound, in this case blue. Values above the upper bound in the color map (the range from 251 to 256) are styled the same color as the upper bound, in this case red. + + +Alpha channel +------------- + +This example creates an "alpha channel" effect such that higher values are increasingly transparent. + +.. figure:: images/raster_alphachannel.png + :align: center + + *Alpha channel* + +Code +~~~~ + +:download:`View and download the full "Alpha channel" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + + + + + + +Details +~~~~~~~ + +An alpha channel is another way of referring to variable transparency. Much like how a gradient maps values to colors, each entry in a ```` can have a value for opacity (with the default being 1.0 or completely opaque). + +In this example, there is a ```` with two entries: **line 5** specifies the lower bound of 70 be colored dark green (``#008000``), while **line 6** specifies the upper bound of 256 also be colored dark green but with an opacity value of 0. This means that values of 256 will be rendered at 0% opacity (entirely transparent). Just like the gradient color, the opacity is also linearly interpolated such that a value of 163 (the midpoint between 70 and 256) is rendered at 50% opacity. + + +Discrete colors +--------------- + +This example shows a gradient that is not linearly interpolated but instead has values mapped precisely to one of three specific colors. + +.. note:: This example leverages an SLD extension in GeoServer. Discrete colors are not part of the standard SLD 1.0 specification. + +.. figure:: images/raster_discretecolors.png + :align: center + + *Discrete colors* + +Code +~~~~ + +:download:`View and download the full "Discrete colors" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + + + + + + +Details +~~~~~~~ + +Sometimes color bands in discrete steps are more appropriate than a color gradient. The ``type="intervals"`` parameter added to the ```` on **line 4** sets the display to output discrete colors instead of a gradient. The values in each entry correspond to the upper bound for the color +band such that colors are mapped to values less than the value of one entry but greater than or equal to the next lower entry. For example, **line 5** colors all values less than 150 to dark green (``#008000``) and line 6 colors all values less than 256 but greater than or equal to 150 to dark brown (``#663333``). + + +Many color gradient +------------------- + +This example shows a gradient interpolated across eight different colors. + +.. figure:: images/raster_manycolorgradient.png + :align: center + + *Many color gradient* + +Code +~~~~ + +:download:`View and download the full "Many color gradient" SLD ` + +.. code-block:: xml + :linenos: + + + + + + + + + + + + + + + + + + +Details +~~~~~~~ + +A ```` can include up to 255 ```` elements. +This example has eight entries (**lines 4-13**): + +.. list-table:: + :widths: 15 25 30 30 + + * - **Entry number** + - **Value** + - **Color** + - **RGB code** + * - 1 + - 95 + - Black + - ``#000000`` + * - 2 + - 110 + - Blue + - ``#0000FF`` + * - 3 + - 135 + - Green + - ``#00FF00`` + * - 4 + - 160 + - Red + - ``#FF0000`` + * - 5 + - 185 + - Purple + - ``#FF00FF`` + * - 6 + - 210 + - Yellow + - ``#FFFF00`` + * - 7 + - 235 + - Cyan + - ``#00FFFF`` + * - 8 + - 256 + - White + - ``#FFFFFF`` + diff --git a/doc/en/user/source/styling/sld/extensions/geometry-transformations.rst b/doc/en/user/source/styling/sld/extensions/geometry-transformations.rst index c711901ba14..d458c4d6797 100644 --- a/doc/en/user/source/styling/sld/extensions/geometry-transformations.rst +++ b/doc/en/user/source/styling/sld/extensions/geometry-transformations.rst @@ -1,163 +1,163 @@ -.. _geometry_transformations: - -Geometry transformations in SLD -=============================== - -SLD symbolizers may contain an optional ```` element, which allows specifying which geometry attribute is to be rendered. -In the common case of a featuretype with a single geometry attribute this element is usually omitted, -but it is useful when a featuretype has multiple geometry-valued attributes. - -SLD 1.0 requires the ```` content to be a ````. -GeoServer extends this to allow a general SLD expression to be used. -The expression can contain filter functions that manipulate geometries by transforming them into something different. -This facility is called SLD *geometry transformations*. - -GeoServer provides a number of filter functions that can transform geometry. -A full list is available in the :ref:`filter_function_reference`. -They can be used to do things such as extracting line vertices or endpoints, -offsetting polygons, or buffering geometries. - -Geometry transformations are computed in the geometry's original coordinate reference system, before any reprojection and rescaling to the output map is performed. -For this reason, transformation parameters must be expressed in the units of the geometry CRS. -This must be taken into account when using geometry transformations at different screen scales, -since the parameters will not change with scale. - -Examples --------- - -Let's look at some examples. - -Extracting vertices -^^^^^^^^^^^^^^^^^^^ - -Here is an example that allows one to extract all the vertices of a geometry, and make them visible in a map, using the ``vertices`` function: - -.. code-block:: xml - :linenos: - - - - - the_geom - - - - - square - - #FF0000 - - - 6 - - - -:download:`View the full "Vertices" SLD ` - -Applied to the sample `tasmania_roads` layer this will result in: - -.. figure:: images/vertices.png - :align: center - - *Extracting and showing the vertices out of a geometry* - - -Start and end point -^^^^^^^^^^^^^^^^^^^ - -The `startPoint` and `endPoint` functions can be used to extract the start and end point of a line. - -.. code-block:: xml - :linenos: - - - - - the_geom - - - - - square - - 0x00FF00 - 1.5 - - - 8 - - - - - - the_geom - - - - - circle - - 0xFF0000 - - - 4 - - - -:download:`View the full "StartEnd" SLD ` - -Applied to the sample `tasmania_roads` layer this will result in: - -.. figure:: images/startend.png - :align: center - - *Extracting start and end point of a line* - - -Drop shadow -^^^^^^^^^^^ - -The `offset` function can be used to create drop shadow effects below polygons. -Notice that the offset values reflect the fact that the data used in the example is in a geographic coordinate system. - -.. code-block:: xml - :linenos: - - - - - the_geom - 0.00004 - -0.00004 - - - - #555555 - - - -:download:`View the full "Shadow" SLD ` - -Applied to the sample `tasmania_roads` layer this will result in: - -.. figure:: images/shadow.png - :align: center - - *Dropping building shadows* - -Performance tips ----------------- - -GeoServer's filter functions contain a number of set-related or constructive geometric functions, -such as ``buffer``, ``intersection``, ``difference`` and others. -These can be used as geometry transformations, but they be can quite heavy in terms of CPU consumption so it is advisable to use them with care. -One strategy is to activate them only at higher zoom levels, so that fewer features are processed. - -Buffering can often be visually approximated by using very large strokes together with round line joins and line caps. -This avoids incurring the performance cost of a true geometric buffer transformation. - -Adding new transformations --------------------------- - -Additional filter functions can be developed in Java and then deployed in a JAR file as a GeoServer plugin. -A guide is not available at this time, but see the GeoTools ``main`` module for examples. +.. _geometry_transformations: + +Geometry transformations in SLD +=============================== + +SLD symbolizers may contain an optional ```` element, which allows specifying which geometry attribute is to be rendered. +In the common case of a featuretype with a single geometry attribute this element is usually omitted, +but it is useful when a featuretype has multiple geometry-valued attributes. + +SLD 1.0 requires the ```` content to be a ````. +GeoServer extends this to allow a general SLD expression to be used. +The expression can contain filter functions that manipulate geometries by transforming them into something different. +This facility is called SLD *geometry transformations*. + +GeoServer provides a number of filter functions that can transform geometry. +A full list is available in the :ref:`filter_function_reference`. +They can be used to do things such as extracting line vertices or endpoints, +offsetting polygons, or buffering geometries. + +Geometry transformations are computed in the geometry's original coordinate reference system, before any reprojection and rescaling to the output map is performed. +For this reason, transformation parameters must be expressed in the units of the geometry CRS. +This must be taken into account when using geometry transformations at different screen scales, +since the parameters will not change with scale. + +Examples +-------- + +Let's look at some examples. + +Extracting vertices +^^^^^^^^^^^^^^^^^^^ + +Here is an example that allows one to extract all the vertices of a geometry, and make them visible in a map, using the ``vertices`` function: + +.. code-block:: xml + :linenos: + + + + + the_geom + + + + + square + + #FF0000 + + + 6 + + + +:download:`View the full "Vertices" SLD ` + +Applied to the sample `tasmania_roads` layer this will result in: + +.. figure:: images/vertices.png + :align: center + + *Extracting and showing the vertices out of a geometry* + + +Start and end point +^^^^^^^^^^^^^^^^^^^ + +The `startPoint` and `endPoint` functions can be used to extract the start and end point of a line. + +.. code-block:: xml + :linenos: + + + + + the_geom + + + + + square + + 0x00FF00 + 1.5 + + + 8 + + + + + + the_geom + + + + + circle + + 0xFF0000 + + + 4 + + + +:download:`View the full "StartEnd" SLD ` + +Applied to the sample `tasmania_roads` layer this will result in: + +.. figure:: images/startend.png + :align: center + + *Extracting start and end point of a line* + + +Drop shadow +^^^^^^^^^^^ + +The `offset` function can be used to create drop shadow effects below polygons. +Notice that the offset values reflect the fact that the data used in the example is in a geographic coordinate system. + +.. code-block:: xml + :linenos: + + + + + the_geom + 0.00004 + -0.00004 + + + + #555555 + + + +:download:`View the full "Shadow" SLD ` + +Applied to the sample `tasmania_roads` layer this will result in: + +.. figure:: images/shadow.png + :align: center + + *Dropping building shadows* + +Performance tips +---------------- + +GeoServer's filter functions contain a number of set-related or constructive geometric functions, +such as ``buffer``, ``intersection``, ``difference`` and others. +These can be used as geometry transformations, but they be can quite heavy in terms of CPU consumption so it is advisable to use them with care. +One strategy is to activate them only at higher zoom levels, so that fewer features are processed. + +Buffering can often be visually approximated by using very large strokes together with round line joins and line caps. +This avoids incurring the performance cost of a true geometric buffer transformation. + +Adding new transformations +-------------------------- + +Additional filter functions can be developed in Java and then deployed in a JAR file as a GeoServer plugin. +A guide is not available at this time, but see the GeoTools ``main`` module for examples. diff --git a/doc/en/user/source/styling/sld/extensions/rendering-transform.rst b/doc/en/user/source/styling/sld/extensions/rendering-transform.rst index bd8f8e89118..2c3780295be 100644 --- a/doc/en/user/source/styling/sld/extensions/rendering-transform.rst +++ b/doc/en/user/source/styling/sld/extensions/rendering-transform.rst @@ -1,473 +1,473 @@ -.. _rendering_transform: - -Rendering Transformations -========================= - -**Rendering Transformations** allow processing to be carried out -on datasets within the GeoServer rendering pipeline. -A typical transformation computes a derived or aggregated result from the input data, -allowing various useful visualization effects to be obtained. -Transformations may transform data from one format into another -(i.e vector to raster or vice-versa), -to provide an appropriate format for display. - -The following table lists examples of various kinds of rendering transformations -available in GeoServer: - -.. list-table:: - :widths: 25 75 - - * - **Type** - - **Examples** - * - Raster-to-Vector - - **Contour** extracts contours from a DEM raster. - **RasterAsPointCollections** extracts a vector field from a multi-band raster - * - Vector-to-Raster - - **BarnesSurfaceInterpolation** computes a surface from scattered data points. - **Heatmap** computes a heatmap surface from weighted data points. - * - Vector-to-Vector - - **PointStacker** aggregates dense point data into clusters. - - -Rendering transformations are invoked within SLD styles. -Parameters may be supplied to control the appearance of the output. -The rendered output for the layer is produced -by applying the styling rules and symbolizers in the SLD to the result of transformation. - -Rendering transformations are implemented using the same mechanism as :ref:`wps_processes`. -They can thus also be executed via the WPS protocol, if required. -Conversely, any WPS process can be executed as a transformation, as long -as the input and output are appropriate for use within an SLD. - -This section is a general guide to rendering transformation usage in GeoServer. -For details of input, parameters, and output for any particular -rendering transformation, refer to its own documentation. - - -Installation ------------- - -Using Rendering Transformations requires the WPS extension to be installed. See :ref:`wps_install`. - -.. note:: - - The WPS service does not need to be **enabled** to use Rendering Transformations. - To avoid unwanted consumption of server resources - it may be desirable to disable the WPS service if it is not being used directly. - - -Usage ------ - -Rendering Transformations are invoked by adding the ```` element -to a ```` element in an SLD document. -This element specifies the name of the transformation process, -and usually includes parameter values controlling the operation of the transformation. - -The ```` element syntax leverages the OGC Filter function syntax. -The content of the element is a ```` with the name of the rendering transformation process. -Transformation processes may accept some number of parameters, -which may be either required (in which case they must be specified), -or optional (in which case they may be omitted if the default value is acceptable). -Parameters are supplied as name/value pairs. -Each parameter's name and value are supplied via another function ````. -The first argument to this function is an ```` containing the name of the parameter. -The optional following arguments provide the value for the parameter (if any). -Some parameters accept only a single value, while others may accept a list of values. -As with any filter function argument, values may be supplied in several ways: - -* As a literal value -* As a computed expression -* As an SLD environment variable, whose actual value is supplied in the WMS request - (see :ref:`sld_variable_substitution`). -* As a predefined SLD environment variable (which allows obtaining values - for the current request such as output image width and height). - -The order of the supplied parameters is not significant. - -Most rendering transformations take as input a dataset to be transformed. -This is supplied via a special named parameter which does not have a value specified. -The name of the parameter is determined by the particular transformation being used. -When the transformation is executed, the input dataset -is passed to it via this parameter. - -The input dataset is determined by the same query mechanism as used for all WMS requests, -and can thus be filtered in the request if required. - -In rendering transformations which take as input a featuretype (vector dataset) -and convert it to a raster dataset, in order to pass validation -the SLD needs to mention the geometry attribute of the input dataset -(even though it is not used). -This is done by specifying the attribute name in the symbolizer ```` element. - -The output of the rendering transformation is styled using symbolizers -appropriate to its format: -:ref:`sld_reference_pointsymbolizer`, :ref:`sld_reference_linesymbolizer`, :ref:`sld_reference_polygonsymbolizer`, -and :ref:`sld_reference_textsymbolizer` for vector data, -and :ref:`sld_reference_rastersymbolizer` for raster coverage data. - -If it is desired to display the input dataset in its orginal form, -or transformed in another way, there are two options: - -* Another ```` can be used in the same SLD -* Another SLD can be created, and the layer displayed twice using the different SLDs - -Notes -^^^^^ - -* Rendering transformations may not work correctly in tiled mode, - unless they have been specifically written to accomodate it. - -Examples --------- - -Contour extraction -^^^^^^^^^^^^^^^^^^ - -``ras:Contour`` is a **Raster-to-Vector** rendering transformation -which extracts contour lines at specified levels from a raster DEM. -The following SLD invokes the transformation -and styles the contours as black lines. - -.. code-block:: xml - :linenos: - - - - - contour_dem - - Contour DEM - Extracts contours from DEM - - - - - data - - - levels - 1100 - 1200 - 1300 - 1400 - 1500 - 1600 - 1700 - 1800 - - - - - rule1 - Contour Line - - - #000000 - 1 - - - - - - Arial - Normal - 10 - - - - - - - 2 - - - #FFFFFF - 0.6 - - - - #000000 - - 2000 - true - 100 - 50 - 30 - - - - - - - -Key aspects of the SLD are: - -* **Lines 14-15** define the rendering transformation, using the process ``ras:Contour``. -* **Lines 16-18** supply the input data parameter, named ``data`` in this process. -* **Lines 19-29** supply values for the process's ``levels`` parameter, - which specifies the elevation levels for the contours to extract. -* **Lines 35-40** specify a ``LineSymbolizer`` to style the contour lines. -* **Lines 41-70** specify a ``TextSymbolizer`` to show the contour levels along the lines. - - -The result of using this transformation is shown in the following map image -(which also shows the underlying DEM raster): - -.. figure:: images/transform_contour_sf_dem.png - :align: center - - -Heatmap generation -^^^^^^^^^^^^^^^^^^ - -``vec:Heatmap`` is a **Vector-to-Raster** rendering transformation -which generates a heatmap surface from weighted point data. -The following SLD invokes a Heatmap rendering transformation -on a featuretype with point geometries -and an attribute ``pop2000`` supplying the weight for the points -(in this example, a dataset of world urban areas is used). -The output is styled using a color ramp across the output data value range [0 .. 1]. - -.. code-block:: xml - :linenos: - - - - - Heatmap - - Heatmap - A heatmap surface showing population density - - - - - data - - - weightAttr - pop2000 - - - radiusPixels - - radius - 100 - - - - pixelsPerCell - 10 - - - outputBBOX - - wms_bbox - - - - outputWidth - - wms_width - - - - outputHeight - - wms_height - - - - - - - - - the_geom - 0.6 - - - - - - - - - - - - - - -Key aspects of the SLD are: - -* **Lines 14-15** define the rendering transformation, using the process ``vec:Heatmap``. -* **Lines 16-18** supply the input data parameter, named ``data`` in this process. -* **Lines 19-22** supply a value for the process's ``weightAttr`` parameter, - which specifies the input attribute providing a weight for each data point. -* **Lines 23-29** supply the value for the ``radiusPixels`` parameter, - which controls the "spread" of the heatmap around each point. - In this SLD the value of this parameter may be supplied by a SLD substitution variable - called ``radius``, with a default value of ``100`` pixels. -* **Lines 30-33** supply the ``pixelsPerCell`` parameter, - which controls the resolution at which the heatmap raster is computed. -* **Lines 34-38** supply the ``outputBBOX`` parameter, - which is given the value of the standard SLD environment variable ``wms_bbox``. -* **Lines 40-45** supply the ``outputWidth`` parameter, - which is given the value of the standard SLD environment variable ``wms_width``. -* **Lines 46-52** supply the ``outputHeight`` parameter, - which is given the value of the standard SLD environment variable ``wms_height``. -* **Lines 55-70** specify a ``RasterSymbolizer`` to style the computed raster surface. - The symbolizer contains a ramped color map for the data range [0..1]. -* **Line 58** specifies the geometry attribute of the input featuretype, - which is necessary to pass SLD validation. - - -This transformation styles a layer to produce a heatmap surface -for the data in the requested map extent, as shown in the image below. -(The map image also shows the original input data points -styled by another SLD, as well as a base map layer.) - -.. figure:: images/heatmap_urban_us_east.png - :align: center - -Running map algebra on the fly using Jiffle -------------------------------------------- - -The ``Jiffle`` rendering transformation allows to run map algebra on the bands of an input raster -layer using the `Jiffle language `_. -For example, the following style computes the NDVI index from a 13 bands Sentinel 2 image, in which -the red and NIR bands are the forth and eight bands (Jiffle band indexes are zero based), -and then displays the resulting index with a color map: - -.. code-block:: xml - :linenos: - - - - - Sentinel2 NDVI - - NDVI - - - - - coverage - - - script - - nir = src[7]; - vir = src[3]; - dest = (nir - vir) / (nir + vir); - - - - - - - 1.0 - - - - - - - - - - - - - - - -Here are a view of the area, using the visible color bands: - -.. figure:: images/s2-visible.png - :align: center - -and then the display of the NDVI index computed with the above style: - -.. figure:: images/s2-ndvi.png - :align: center - - -Group candidate selection -^^^^^^^^^^^^^^^^^^^^^^^^^ - -``vec:GroupCandidateSelection`` is a **Vector-to-Vector** rendering transformation -which filters a FeatureCollection according to the aggregate operation chosen (MIN or MAX) and the groups defined through attribute names. Given a feature collection, groups according to the defined grouping attributes, and returns the feature having the MIN or MAX value for the chosen attribute. One feature will be chosen for each group. -The following SLD invokes the transformation: - -.. code-block:: xml - - - - - - Default Styler - Default Styler - - - - - data - - - operationAttribute - st:numericAttribute - - - aggregation - MIN - - - groupingAttributes - st:inferredAttribute - st:inferredAttribute2 - - - - - Stations Selected Candidate - - - #000000 - - - - - - - - - -Where ``st:numericAttribute``, ``st:inferredAttribute`` and ``st:inferredAttribute2`` are attributes of the current layer being rendered, in this case, a layer based complex features, having the attributes used for rendering in the ``http://www.stations.org/1.0`` namespace. - -This vector process accepts four parameters: - -* ``data``: the data on which perform the computation. - -* ``aggregation``: the type of operation required to filter data (MIN or MAX). - -* ``operationAttribute``: the xpath to the attribute whose value will be used to perform the MIN or MAX operation. - -* ``groupingAttributes``: a lists of xpath pointing to the attirbutes defining the features' groups for which perform the filtering process. +.. _rendering_transform: + +Rendering Transformations +========================= + +**Rendering Transformations** allow processing to be carried out +on datasets within the GeoServer rendering pipeline. +A typical transformation computes a derived or aggregated result from the input data, +allowing various useful visualization effects to be obtained. +Transformations may transform data from one format into another +(i.e vector to raster or vice-versa), +to provide an appropriate format for display. + +The following table lists examples of various kinds of rendering transformations +available in GeoServer: + +.. list-table:: + :widths: 25 75 + + * - **Type** + - **Examples** + * - Raster-to-Vector + - **Contour** extracts contours from a DEM raster. + **RasterAsPointCollections** extracts a vector field from a multi-band raster + * - Vector-to-Raster + - **BarnesSurfaceInterpolation** computes a surface from scattered data points. + **Heatmap** computes a heatmap surface from weighted data points. + * - Vector-to-Vector + - **PointStacker** aggregates dense point data into clusters. + + +Rendering transformations are invoked within SLD styles. +Parameters may be supplied to control the appearance of the output. +The rendered output for the layer is produced +by applying the styling rules and symbolizers in the SLD to the result of transformation. + +Rendering transformations are implemented using the same mechanism as :ref:`wps_processes`. +They can thus also be executed via the WPS protocol, if required. +Conversely, any WPS process can be executed as a transformation, as long +as the input and output are appropriate for use within an SLD. + +This section is a general guide to rendering transformation usage in GeoServer. +For details of input, parameters, and output for any particular +rendering transformation, refer to its own documentation. + + +Installation +------------ + +Using Rendering Transformations requires the WPS extension to be installed. See :ref:`wps_install`. + +.. note:: + + The WPS service does not need to be **enabled** to use Rendering Transformations. + To avoid unwanted consumption of server resources + it may be desirable to disable the WPS service if it is not being used directly. + + +Usage +----- + +Rendering Transformations are invoked by adding the ```` element +to a ```` element in an SLD document. +This element specifies the name of the transformation process, +and usually includes parameter values controlling the operation of the transformation. + +The ```` element syntax leverages the OGC Filter function syntax. +The content of the element is a ```` with the name of the rendering transformation process. +Transformation processes may accept some number of parameters, +which may be either required (in which case they must be specified), +or optional (in which case they may be omitted if the default value is acceptable). +Parameters are supplied as name/value pairs. +Each parameter's name and value are supplied via another function ````. +The first argument to this function is an ```` containing the name of the parameter. +The optional following arguments provide the value for the parameter (if any). +Some parameters accept only a single value, while others may accept a list of values. +As with any filter function argument, values may be supplied in several ways: + +* As a literal value +* As a computed expression +* As an SLD environment variable, whose actual value is supplied in the WMS request + (see :ref:`sld_variable_substitution`). +* As a predefined SLD environment variable (which allows obtaining values + for the current request such as output image width and height). + +The order of the supplied parameters is not significant. + +Most rendering transformations take as input a dataset to be transformed. +This is supplied via a special named parameter which does not have a value specified. +The name of the parameter is determined by the particular transformation being used. +When the transformation is executed, the input dataset +is passed to it via this parameter. + +The input dataset is determined by the same query mechanism as used for all WMS requests, +and can thus be filtered in the request if required. + +In rendering transformations which take as input a featuretype (vector dataset) +and convert it to a raster dataset, in order to pass validation +the SLD needs to mention the geometry attribute of the input dataset +(even though it is not used). +This is done by specifying the attribute name in the symbolizer ```` element. + +The output of the rendering transformation is styled using symbolizers +appropriate to its format: +:ref:`sld_reference_pointsymbolizer`, :ref:`sld_reference_linesymbolizer`, :ref:`sld_reference_polygonsymbolizer`, +and :ref:`sld_reference_textsymbolizer` for vector data, +and :ref:`sld_reference_rastersymbolizer` for raster coverage data. + +If it is desired to display the input dataset in its orginal form, +or transformed in another way, there are two options: + +* Another ```` can be used in the same SLD +* Another SLD can be created, and the layer displayed twice using the different SLDs + +Notes +^^^^^ + +* Rendering transformations may not work correctly in tiled mode, + unless they have been specifically written to accomodate it. + +Examples +-------- + +Contour extraction +^^^^^^^^^^^^^^^^^^ + +``ras:Contour`` is a **Raster-to-Vector** rendering transformation +which extracts contour lines at specified levels from a raster DEM. +The following SLD invokes the transformation +and styles the contours as black lines. + +.. code-block:: xml + :linenos: + + + + + contour_dem + + Contour DEM + Extracts contours from DEM + + + + + data + + + levels + 1100 + 1200 + 1300 + 1400 + 1500 + 1600 + 1700 + 1800 + + + + + rule1 + Contour Line + + + #000000 + 1 + + + + + + Arial + Normal + 10 + + + + + + + 2 + + + #FFFFFF + 0.6 + + + + #000000 + + 2000 + true + 100 + 50 + 30 + + + + + + + +Key aspects of the SLD are: + +* **Lines 14-15** define the rendering transformation, using the process ``ras:Contour``. +* **Lines 16-18** supply the input data parameter, named ``data`` in this process. +* **Lines 19-29** supply values for the process's ``levels`` parameter, + which specifies the elevation levels for the contours to extract. +* **Lines 35-40** specify a ``LineSymbolizer`` to style the contour lines. +* **Lines 41-70** specify a ``TextSymbolizer`` to show the contour levels along the lines. + + +The result of using this transformation is shown in the following map image +(which also shows the underlying DEM raster): + +.. figure:: images/transform_contour_sf_dem.png + :align: center + + +Heatmap generation +^^^^^^^^^^^^^^^^^^ + +``vec:Heatmap`` is a **Vector-to-Raster** rendering transformation +which generates a heatmap surface from weighted point data. +The following SLD invokes a Heatmap rendering transformation +on a featuretype with point geometries +and an attribute ``pop2000`` supplying the weight for the points +(in this example, a dataset of world urban areas is used). +The output is styled using a color ramp across the output data value range [0 .. 1]. + +.. code-block:: xml + :linenos: + + + + + Heatmap + + Heatmap + A heatmap surface showing population density + + + + + data + + + weightAttr + pop2000 + + + radiusPixels + + radius + 100 + + + + pixelsPerCell + 10 + + + outputBBOX + + wms_bbox + + + + outputWidth + + wms_width + + + + outputHeight + + wms_height + + + + + + + + + the_geom + 0.6 + + + + + + + + + + + + + + +Key aspects of the SLD are: + +* **Lines 14-15** define the rendering transformation, using the process ``vec:Heatmap``. +* **Lines 16-18** supply the input data parameter, named ``data`` in this process. +* **Lines 19-22** supply a value for the process's ``weightAttr`` parameter, + which specifies the input attribute providing a weight for each data point. +* **Lines 23-29** supply the value for the ``radiusPixels`` parameter, + which controls the "spread" of the heatmap around each point. + In this SLD the value of this parameter may be supplied by a SLD substitution variable + called ``radius``, with a default value of ``100`` pixels. +* **Lines 30-33** supply the ``pixelsPerCell`` parameter, + which controls the resolution at which the heatmap raster is computed. +* **Lines 34-38** supply the ``outputBBOX`` parameter, + which is given the value of the standard SLD environment variable ``wms_bbox``. +* **Lines 40-45** supply the ``outputWidth`` parameter, + which is given the value of the standard SLD environment variable ``wms_width``. +* **Lines 46-52** supply the ``outputHeight`` parameter, + which is given the value of the standard SLD environment variable ``wms_height``. +* **Lines 55-70** specify a ``RasterSymbolizer`` to style the computed raster surface. + The symbolizer contains a ramped color map for the data range [0..1]. +* **Line 58** specifies the geometry attribute of the input featuretype, + which is necessary to pass SLD validation. + + +This transformation styles a layer to produce a heatmap surface +for the data in the requested map extent, as shown in the image below. +(The map image also shows the original input data points +styled by another SLD, as well as a base map layer.) + +.. figure:: images/heatmap_urban_us_east.png + :align: center + +Running map algebra on the fly using Jiffle +------------------------------------------- + +The ``Jiffle`` rendering transformation allows to run map algebra on the bands of an input raster +layer using the `Jiffle language `_. +For example, the following style computes the NDVI index from a 13 bands Sentinel 2 image, in which +the red and NIR bands are the forth and eight bands (Jiffle band indexes are zero based), +and then displays the resulting index with a color map: + +.. code-block:: xml + :linenos: + + + + + Sentinel2 NDVI + + NDVI + + + + + coverage + + + script + + nir = src[7]; + vir = src[3]; + dest = (nir - vir) / (nir + vir); + + + + + + + 1.0 + + + + + + + + + + + + + + + +Here are a view of the area, using the visible color bands: + +.. figure:: images/s2-visible.png + :align: center + +and then the display of the NDVI index computed with the above style: + +.. figure:: images/s2-ndvi.png + :align: center + + +Group candidate selection +^^^^^^^^^^^^^^^^^^^^^^^^^ + +``vec:GroupCandidateSelection`` is a **Vector-to-Vector** rendering transformation +which filters a FeatureCollection according to the aggregate operation chosen (MIN or MAX) and the groups defined through attribute names. Given a feature collection, groups according to the defined grouping attributes, and returns the feature having the MIN or MAX value for the chosen attribute. One feature will be chosen for each group. +The following SLD invokes the transformation: + +.. code-block:: xml + + + + + + Default Styler + Default Styler + + + + + data + + + operationAttribute + st:numericAttribute + + + aggregation + MIN + + + groupingAttributes + st:inferredAttribute + st:inferredAttribute2 + + + + + Stations Selected Candidate + + + #000000 + + + + + + + + + +Where ``st:numericAttribute``, ``st:inferredAttribute`` and ``st:inferredAttribute2`` are attributes of the current layer being rendered, in this case, a layer based complex features, having the attributes used for rendering in the ``http://www.stations.org/1.0`` namespace. + +This vector process accepts four parameters: + +* ``data``: the data on which perform the computation. + +* ``aggregation``: the type of operation required to filter data (MIN or MAX). + +* ``operationAttribute``: the xpath to the attribute whose value will be used to perform the MIN or MAX operation. + +* ``groupingAttributes``: a lists of xpath pointing to the attirbutes defining the features' groups for which perform the filtering process. diff --git a/doc/en/user/source/styling/sld/index.rst b/doc/en/user/source/styling/sld/index.rst index 37e0045c64f..162ae53be52 100644 --- a/doc/en/user/source/styling/sld/index.rst +++ b/doc/en/user/source/styling/sld/index.rst @@ -1,17 +1,17 @@ -.. _sld: - -SLD Styling -=========== - -This section discusses styling of geospatial data using "Style Layer Descriptor" XML files. - -.. toctree:: - :maxdepth: 2 - - introduction/ - working/ - cookbook/index - reference/index - extensions/index - tipstricks/index - language +.. _sld: + +SLD Styling +=========== + +This section discusses styling of geospatial data using "Style Layer Descriptor" XML files. + +.. toctree:: + :maxdepth: 2 + + introduction/ + working/ + cookbook/index + reference/index + extensions/index + tipstricks/index + language diff --git a/doc/en/user/source/styling/sld/reference/filters.rst b/doc/en/user/source/styling/sld/reference/filters.rst index b4edf35af78..7b1620a22fc 100644 --- a/doc/en/user/source/styling/sld/reference/filters.rst +++ b/doc/en/user/source/styling/sld/reference/filters.rst @@ -1,243 +1,243 @@ -.. _sld_reference_filters: - -Filters -======= - -A *filter* is the mechanism in SLD for specifying conditions. -They are similar in functionality to the SQL "WHERE" clause. -Filters are used within :ref:`sld_reference_rules` to determine which styles should be applied to which features in a data set. -The filter language used by SLD follows the `OGC Filter Encoding standard `_. -It is described in detail in the :ref:`filter_fe_reference`. - -A filter condition is specified by using a **comparison operator** or a **spatial operator**, -or two or more of these combined by **logical operators**. -The operators are usually used to compare properties of the features being filtered -to other properties or to literal data. - -Comparison operators --------------------- - -Comparison operators are used to specify conditions on the non-spatial attributes of a feature. -The following **binary comparison operators** are available: - - * ```` - * ```` - * ```` - * ```` - * ```` - * ```` - -These operators contain two :ref:`filter expressions ` to be compared. -The first operand is often a ````, -but both operands may be any expression, function or literal value. - -Binary comparison operators may include a ``matchCase`` attribute with the value ``true`` or ``false``. -If this attribute is ``true`` (which is the default), string comparisons are case-sensitive. -If the attribute is specified and has the value ``false`` strings comparisons do not check case. - -Other available **value comparison operators** are: - - * ```` - * ```` - * ```` - -```` matches a string property value against a text **pattern**. -It contains a ```` element -containing the name of the property containing the string to be matched -and a ```` element containing the pattern. -The pattern is specified by a sequence of regular characters and -three special pattern characters. -The pattern characters are defined by the following required attributes of the ```` element: - - * ``wildCard`` specifies a pattern character which matches any sequence of zero or more characters - * ``singleChar`` specifies a pattern character which matches any single character - * ``escapeChar`` specifies an escape character which can be used to escape these pattern characters - -```` tests whether a property value is null. -It contains a single ```` element containing the name of the property containing the value to be tested. - -```` tests whether an expression value lies within a range. -It contains a :ref:`filter expression ` providing the value to test, -followed by the elements ```` and ````, -each containing a :ref:`filter expression `. - -Examples -^^^^^^^^ - -* The following filter selects features whose ``NAME`` attribute has the value of "New York": - -.. code-block:: xml - - - NAME - New York - - -* The following filter selects features whose geometry area is greater than 1,000,000: - -.. code-block:: xml - - - - GEOMETRY - - 1000000 - - - -Spatial operators ------------------ - -Spatial operators are used to specify conditions on the geometric attributes of a feature. -The following spatial operators are available: - -**Topological Operators** - -These operators test topological spatial relationships using the standard OGC Simple Features predicates: - - * ```` - * ```` - * ```` - * ```` - * ```` - * ```` - * ```` - * ```` - * ```` - -The content for these operators is a ```` element -for a geometry-valued property -and a GML geometry literal. - -**Distance Operators** - -These operators compute distance relationships between geometries: - - * ```` - * ```` - -The content for these elements is a ```` element for a geometry-valued property, -a GML geometry literal, and a ```` element containing the value for the distance tolerance. -The ```` element may include an optional ``units`` attribute. - -**Bounding Box Operator** - -This operator tests whether a feature geometry attribute intersects a given bounding box: - - * ```` - -The content is an optional ```` element, and a GML envelope literal. -If the ``PropertyName`` is omitted the default geometry attribute is assumed. - -Examples -^^^^^^^^ - -* The following filter selects features with a geometry that intersects the point (1,1): - - -.. code-block:: xml - - - GEOMETRY - - - 1 1 - - - - - -* The following filter selects features with a geometry that intersects - the box [-10,0 : 10,10]: - -.. code-block:: xml - - - GEOMETRY - - - -10 0 - - - 10 10 - - - - - -Logical operators ------------------ - -Logical operators are used to create logical combinations of other filter operators. -They may be nested to any depth. -The following logical operators are available: - - * ```` - * ```` - * ```` - -The content for ```` and ```` is two filter operator elements. -The content for ```` is a single filter operator element. - -Examples -^^^^^^^^ - -* The following filter uses ```` to combine a comparison operator and a spatial operator: - -.. code-block:: xml - - - - NAME - New York - - - GEOMETRY - - - 1 1 - - - - - -.. _sld_filter_expression: - -Filter Expressions ------------------- - -Filter expressions allow performing computation on data values. -The following elements can be used to form expressions. - -**Arithmetic Operators** - -These operators perform arithmetic on numeric values. -Each contains two expressions as sub-elements. - - * ```` - * ```` - * ```` - * ``
`` - -**Functions** - -The ```` element specifies a filter function to be evaluated. -The ``name`` attribute gives the function name. -The element contains a sequence of zero or more -filter expressions providing the function arguments. -See the :ref:`filter_function_reference` for details of the functions provided by GeoServer. - -**Feature Property Values** - -The ```` element allows referring to the value of a given feature attribute. -It contains a string specifying the attribute name. - -**Literals** - -The ```` element allows specifying constant values -of numeric, boolean, string, date or geometry type. - - - - - +.. _sld_reference_filters: + +Filters +======= + +A *filter* is the mechanism in SLD for specifying conditions. +They are similar in functionality to the SQL "WHERE" clause. +Filters are used within :ref:`sld_reference_rules` to determine which styles should be applied to which features in a data set. +The filter language used by SLD follows the `OGC Filter Encoding standard `_. +It is described in detail in the :ref:`filter_fe_reference`. + +A filter condition is specified by using a **comparison operator** or a **spatial operator**, +or two or more of these combined by **logical operators**. +The operators are usually used to compare properties of the features being filtered +to other properties or to literal data. + +Comparison operators +-------------------- + +Comparison operators are used to specify conditions on the non-spatial attributes of a feature. +The following **binary comparison operators** are available: + + * ```` + * ```` + * ```` + * ```` + * ```` + * ```` + +These operators contain two :ref:`filter expressions ` to be compared. +The first operand is often a ````, +but both operands may be any expression, function or literal value. + +Binary comparison operators may include a ``matchCase`` attribute with the value ``true`` or ``false``. +If this attribute is ``true`` (which is the default), string comparisons are case-sensitive. +If the attribute is specified and has the value ``false`` strings comparisons do not check case. + +Other available **value comparison operators** are: + + * ```` + * ```` + * ```` + +```` matches a string property value against a text **pattern**. +It contains a ```` element +containing the name of the property containing the string to be matched +and a ```` element containing the pattern. +The pattern is specified by a sequence of regular characters and +three special pattern characters. +The pattern characters are defined by the following required attributes of the ```` element: + + * ``wildCard`` specifies a pattern character which matches any sequence of zero or more characters + * ``singleChar`` specifies a pattern character which matches any single character + * ``escapeChar`` specifies an escape character which can be used to escape these pattern characters + +```` tests whether a property value is null. +It contains a single ```` element containing the name of the property containing the value to be tested. + +```` tests whether an expression value lies within a range. +It contains a :ref:`filter expression ` providing the value to test, +followed by the elements ```` and ````, +each containing a :ref:`filter expression `. + +Examples +^^^^^^^^ + +* The following filter selects features whose ``NAME`` attribute has the value of "New York": + +.. code-block:: xml + + + NAME + New York + + +* The following filter selects features whose geometry area is greater than 1,000,000: + +.. code-block:: xml + + + + GEOMETRY + + 1000000 + + + +Spatial operators +----------------- + +Spatial operators are used to specify conditions on the geometric attributes of a feature. +The following spatial operators are available: + +**Topological Operators** + +These operators test topological spatial relationships using the standard OGC Simple Features predicates: + + * ```` + * ```` + * ```` + * ```` + * ```` + * ```` + * ```` + * ```` + * ```` + +The content for these operators is a ```` element +for a geometry-valued property +and a GML geometry literal. + +**Distance Operators** + +These operators compute distance relationships between geometries: + + * ```` + * ```` + +The content for these elements is a ```` element for a geometry-valued property, +a GML geometry literal, and a ```` element containing the value for the distance tolerance. +The ```` element may include an optional ``units`` attribute. + +**Bounding Box Operator** + +This operator tests whether a feature geometry attribute intersects a given bounding box: + + * ```` + +The content is an optional ```` element, and a GML envelope literal. +If the ``PropertyName`` is omitted the default geometry attribute is assumed. + +Examples +^^^^^^^^ + +* The following filter selects features with a geometry that intersects the point (1,1): + + +.. code-block:: xml + + + GEOMETRY + + + 1 1 + + + + + +* The following filter selects features with a geometry that intersects + the box [-10,0 : 10,10]: + +.. code-block:: xml + + + GEOMETRY + + + -10 0 + + + 10 10 + + + + + +Logical operators +----------------- + +Logical operators are used to create logical combinations of other filter operators. +They may be nested to any depth. +The following logical operators are available: + + * ```` + * ```` + * ```` + +The content for ```` and ```` is two filter operator elements. +The content for ```` is a single filter operator element. + +Examples +^^^^^^^^ + +* The following filter uses ```` to combine a comparison operator and a spatial operator: + +.. code-block:: xml + + + + NAME + New York + + + GEOMETRY + + + 1 1 + + + + + +.. _sld_filter_expression: + +Filter Expressions +------------------ + +Filter expressions allow performing computation on data values. +The following elements can be used to form expressions. + +**Arithmetic Operators** + +These operators perform arithmetic on numeric values. +Each contains two expressions as sub-elements. + + * ```` + * ```` + * ```` + * ``
`` + +**Functions** + +The ```` element specifies a filter function to be evaluated. +The ``name`` attribute gives the function name. +The element contains a sequence of zero or more +filter expressions providing the function arguments. +See the :ref:`filter_function_reference` for details of the functions provided by GeoServer. + +**Feature Property Values** + +The ```` element allows referring to the value of a given feature attribute. +It contains a string specifying the attribute name. + +**Literals** + +The ```` element allows specifying constant values +of numeric, boolean, string, date or geometry type. + + + + + diff --git a/doc/en/user/source/styling/sld/reference/index.rst b/doc/en/user/source/styling/sld/reference/index.rst index 528826c7b8f..7417d57b9ba 100644 --- a/doc/en/user/source/styling/sld/reference/index.rst +++ b/doc/en/user/source/styling/sld/reference/index.rst @@ -1,66 +1,66 @@ -.. _sld_reference: - -SLD Reference -============= - -The OGC **Styled Layer Descriptor (SLD)** standard defines a language for expressing -styling of geospatial data. -GeoServer uses SLD as its primary styling language. - -SLD 1.0.0 is defined in the following specification: - -* `OGC Styled Layer Descriptor Implementation Specification, Version 1.0.0 `_ - -Subsequently the functionality of SLD has been split into two specifications: - -* `OGC Symbology Encoding Implementation Specification, Version 1.1.0 `_ -* `OGC Styled Layer Descriptor profile of the Web Map Service Implementation Specification, Version 1.1.0 `_ - -GeoServer implements the SLD 1.0.0 standard, as well as some parts of the SE 1.1.0 and WMS-SLD 1.1.0 standards. - -**Elements of SLD** - -The following sections describe the SLD elements implemented in GeoServer. - -The root element for an SLD is ````. -It contains a **Layers** and **Styles** elements which -describe how a map is to be composed and styled. - -.. toctree:: - :maxdepth: 2 - - sld - layers - styles - -Styles contain **Rules** and **Filters** to determine sets of features to be styled with specific symbology. -Rules may also specify the scale range in which the feature styling is visible. - -.. toctree:: - :maxdepth: 2 - - rules - filters - -Rules contain **Symbolizers** to specify how features are styled. -There are 5 types of symbolizers: - -* ``PointSymbolizer``, which styles features as **points** -* ``LineSymbolizer``, which styles features as **lines** -* ``PolygonSymbolizer``, which styles features as **polygons** -* ``TextSymbolizer``, which styles **text labels** for features -* ``RasterSymbolizer``, which styles **raster coverages** - -Each symbolizer type has its own parameters to control styling. - - -.. toctree:: - :maxdepth: 2 - - - pointsymbolizer - linesymbolizer - polygonsymbolizer - textsymbolizer - labeling - rastersymbolizer +.. _sld_reference: + +SLD Reference +============= + +The OGC **Styled Layer Descriptor (SLD)** standard defines a language for expressing +styling of geospatial data. +GeoServer uses SLD as its primary styling language. + +SLD 1.0.0 is defined in the following specification: + +* `OGC Styled Layer Descriptor Implementation Specification, Version 1.0.0 `_ + +Subsequently the functionality of SLD has been split into two specifications: + +* `OGC Symbology Encoding Implementation Specification, Version 1.1.0 `_ +* `OGC Styled Layer Descriptor profile of the Web Map Service Implementation Specification, Version 1.1.0 `_ + +GeoServer implements the SLD 1.0.0 standard, as well as some parts of the SE 1.1.0 and WMS-SLD 1.1.0 standards. + +**Elements of SLD** + +The following sections describe the SLD elements implemented in GeoServer. + +The root element for an SLD is ````. +It contains a **Layers** and **Styles** elements which +describe how a map is to be composed and styled. + +.. toctree:: + :maxdepth: 2 + + sld + layers + styles + +Styles contain **Rules** and **Filters** to determine sets of features to be styled with specific symbology. +Rules may also specify the scale range in which the feature styling is visible. + +.. toctree:: + :maxdepth: 2 + + rules + filters + +Rules contain **Symbolizers** to specify how features are styled. +There are 5 types of symbolizers: + +* ``PointSymbolizer``, which styles features as **points** +* ``LineSymbolizer``, which styles features as **lines** +* ``PolygonSymbolizer``, which styles features as **polygons** +* ``TextSymbolizer``, which styles **text labels** for features +* ``RasterSymbolizer``, which styles **raster coverages** + +Each symbolizer type has its own parameters to control styling. + + +.. toctree:: + :maxdepth: 2 + + + pointsymbolizer + linesymbolizer + polygonsymbolizer + textsymbolizer + labeling + rastersymbolizer diff --git a/doc/en/user/source/styling/sld/reference/labeling.rst b/doc/en/user/source/styling/sld/reference/labeling.rst index 91e1ff9cf9f..3e793aa0763 100644 --- a/doc/en/user/source/styling/sld/reference/labeling.rst +++ b/doc/en/user/source/styling/sld/reference/labeling.rst @@ -1,706 +1,706 @@ -.. _sld_reference_labeling: - -Labeling -======== - -This section discusses the details of controlling label placement -via the standard SLD options. -It also describes a number of GeoServer enhanced options for label placement -that provide better cartographic output. - -LabelPlacement --------------- - -The SLD specification defines two alternative -label placement strategies which can be used in the ```` element: - -* ```` places labels at a single point -* ```` places labels along a line - -PointPlacement --------------- - -When ```` is used the geometry is labelled at a single **label point**. -For lines, this point lies at the middle of the visible portion of the line. -For polygons, the point is the centroid of the visible portion of the polygon. -The position of the label relative to the label point can be controlled by the following -sub-elements: - -.. list-table:: - :widths: 30 70 - - * - **Element** - - **Description** - * - ```` - - Determines the placement of the label relative to the label point. Values given as decimals between 0-1. - * - ```` - - Offsets the label from the anchor point. Values given in pixels. - * - ```` - - Rotates the label clockwise by a given number of degrees. - -The best way to explain these options is with examples. - - -AnchorPoint -^^^^^^^^^^^ - -The anchor point determines where the label is placed relative to the label point. - -.. code-block:: xml - - - - 0.5 - - - 0.5 - - - -The anchor point values—listed here as (X, Y) ordered pairs—are specified relative to the bounding box of the label, with values from 0 to 1 inclusive. For example: - -* *(Default)* Bottom left of the box is (0, 0) -* Top right is (1, 1) -* Center is (0.5, 0.5) - -So to have the anchor location centered just below the label (label top-centered), use (0.5, 0): - -.. code-block:: xml - - - - 0.5 - - - 0 - - - -.. figure:: img/label_bbox.png - -The following examples show how changing the anchor point affects the position of labels: - -.. figure:: img/point_x0y0_5.png - - (0, 0.5) places the label to the right of the label point - -.. figure:: img/point_x0_5y0_5.png - - (0.5, 0.5) places the center of the label at the label point - -.. figure:: img/point_x15y0_5.png - - (1, 0.5) places the label to the left of the label point - -.. figure:: img/point_x0_5y0.png - - (0.5, 0) places the label horizontally centered above the label point - - -Displacement -^^^^^^^^^^^^ - -Displacement allows fine control of the placement of the label. -The displacement values offset the location of the label -from the anchor point -by a specified number of pixels. -The element syntax is: - -.. code-block:: xml - - - - 10 - - - 0 - - - -Examples: - -.. figure:: img/point_x0y0_5_displacex10.png - :align: center - -*Displacement of X=10 pixels (compare with default anchor point of (X=0, Y=0.5) shown above)* - -.. figure:: img/point_x0y1_displacey10.png - :align: center - -*Displacement of Y=-10 pixels (compare with anchor point (X= 0.5, Y=1.0) - not shown)* - - -Rotation -^^^^^^^^ - -The optional ```` element specifies that labels should be rotated clockwise by a given number of degrees - -.. code-block:: xml - - - 45 - - -The examples below show how the rotation interacts with anchor points and displacements. - -.. figure:: img/rot1.png - -*45 degree rotation* - -.. figure:: img/rot2.png - -*45 degree rotation with anchor point (X=0.5, Y=0.5)* - -.. figure:: img/rot3.png - -*45 degree rotation with 40-pixel X displacement* - -.. figure:: img/rot4.png - -*45 degree rotation with 40-pixel Y displacement with anchor point (X=0.5, Y=0.5)* - - -LinePlacement -------------- - -To label linear features (such as a road or river), the ```` element can be specified. -This indicates that the styler should determine the best placement and rotation for the labels -along the lines. - -The standard SLD LinePlacement element provides one optional sub-element, ````. -GeoServer provides much more control over line label placement via vendor-specific options; -see below for details. - -PerpendicularOffset -^^^^^^^^^^^^^^^^^^^ - -The optional ```` element allows you to position a label above or below a line. -(This is similiar to the ```` for label points described above.) -The displacement value is specified in pixels. -A positive value displaces upwards, a negative value downwards. - -.. code-block:: xml - - - - - 10 - - - - -Examples: - -.. figure:: img/lp_1.png - -*PerpendicularOffset = 0 (default)* - -.. figure:: img/lp_2.png - -*PerpendicularOffset = 10* - - -Composing labels from multiple attributes ------------------------------------------ - -The ``