Kortforsyningen Rastertjenesten

KORT & MATRIKELSTYRELSEN Kortforsyningen Rastertjenesten Version 1.3, 2002-05-13

Indledning Kortforsyningens rastertjeneste kan via Internettet levere udsnit af en række af Kort & Matrikelstyrelsens kortværk samt tekstbaserede informationer om disse kortværk. Det er dermed muligt vha. af fx en Internet-browser at få vist et udsnit af et kortværk over fx Helsingør. Man bestemmer selv hvilket geografisk område, man er interesseret i at se, ligesom valget af kortværk og størrelsen på kortet også er valgfrit. Kortforsyningens Rastertjeneste gør det derfor nemt at inkludere kort i applikationer, uden at man har kortværket på fx en CD-ROM, bare applikationen har adgang til Internettet. Sådanne applikationer kan være alt fra en statisk hjemmeside til mere komplekse applikationer, der kombinerer kort og andre geografiske informationer i fx offentlig forvaltning. Hvordan fungerer Rastertjenesten? Kortforsyningens Rastertjeneste er i stand til, via Internettet, at kunne returnere kortudsnit i formatet JPEG eller PNG. Disse to formater er nogle af de mest benyttede og understøttes af langt de fleste softwares inklusiv Internet-browsere. Det er derfor muligt for de fleste softwares at kunne vise kortværk fra Kortforsyningens Rastertjeneste. Man benytter Kortforsyningens Rastertjeneste ved at lave en forespørgsel (efterfølgende kaldet et http request) vha. en URL. En URL er groft sagt adressen på en web-side fx http://kortforsyning.kms.dk/default.htm. Et http request finder sted hver gang man fx indtaster en URL i en Internet-browser eller klikker på et hyperlink på en web-side. Efter man har lavet et http request sendes et svar (efterfølgende kaldet et respons) retur til den applikation, der lavede requestet (fx en Internet-browser). For Rastertjenesten afhænger responset af requestet. Det svarer blot til at man får forskellige resultater, hvis man på en søgemaskine som www.jubii.dk søger på Kort & Matrikelstyrelsen og fodbold. Rastertjenestens respons vil i langt de fleste tilfælde være et kortværk i formatet JPEG eller PNG, men kan også være i XML, hvis en fejl opstår. Man skal selv opbygge URL en da den indeholder informationer om fx det geografiske område, der ønskes returneret. Med HTML, ASP, PHP og/eller JavaScript er det nemt at gøre dette. Ønsker man at få vist et kortudsnit over Brønshøj i JPEG format må man altså opbygge en URL, der afspejler disse ønsker. En sådan URL kunne se således ud: URL en består indtil spørgsmålstegnet (?) blot af URL præfixet til den web-side, der returnerer positionen på stednavnet. Uanset hvilken af Kortforsyningens tjenester, der benyttes, er dette den samme. Efter spørgsmålstegnet er der en række parametre og deres tilhørende værdier. Alle parametrene/værdier er adskilt med et &. Hver parameters værdi findes efter parameteren adskilt med et =. Disse parametre og især værdierne kan ændres alt afhængig af en applikations behov. I dette tilfælde vil URL en forespørge et kortudsnit af kortværket D_50 (svarende til 1:50.000) med højden 370 pixels, bredden 462 pixels og i formatet JPEG. Desuden er det bedt om at kortudsnittet (der ALTID er rektangulært) skal være afgrænset af de geografiske hjørnekoordinater 718090,6177375.5 og 720400,6179225.5. Koordinaterne afhænger af projektionen, som i dette tilfælde er EPSG:32632, hvilket svarer til UTM Zone 32 WGS84. Det returnerede kort vil se således ud: Side 2 af 12

URL en kan måske se lidt kompliceret ud, men alle parametrene og deres tilhørende værdier vil blive udførligt beskrevet senere i dokumentet. URL ens syntaks er baseret på OpenGIS Web Map Server Interface Implementation Specification 1.0.0 (Open GIS WMS), hvilket betyder en ensartethed med Kortforsyningens Vektortjeneste. Da Open GIS WMS oprindelig er designet til forespørgsler af vektorkort, vil URL er til forespørgsel af Rastertjenesten afvige fra Open GIS WMS på visse punkter. Rastertjenesten er derfor ikke en sand Open GIS WMS. Jf. OpenGIS WMS er det med Rastertjenesten også muligt at forespørge på informationer om de enkelte kortværk. Disse informationer er fx den maksimale geografiske udstrækning af et kortværk eller dets pixelstørrelse (hvor mange meter svarer en pixels størrelse til). Et sådan request vil naturligvis ikke returnere et kort i PNG eller JPEG format, men et XML-formatteret dokument indeholdende informationer om kortværket. Ønsker man at lave en sådan forespørgsel er URL en ikke så kompliceret som ovenfor og kan se sådan ud: http://kortforsyning.kms.dk/service?servicename=d_50&wmtver=1.0.0&request=capabili ties Den returnerede XML tekst vil se således ud: <?xml version="1.0" encoding="iso8859-1"?> <!DOCTYPE WMT_MS_Capabilities (View Source for full doctype...)> - <WMT_MS_Capabilities version="1.0.0" updatesequence="0"> - <Service> <Name>D_50</Name> <Title>Danmark 1:50.000</Title> <Abstract>Ingen værdi</abstract> <OnlineResource>http://kortforsyning.kms.dk/service?</OnlineResource> <Fees>none</Fees> <AccessConstraints>none</AccessConstraints> </Service> - <Capability> - <Request> - <Map> Side 3 af 12

- <Format> <PNG /> <JPEG /> </Format> - <DCPType> - <HTTP> <Get onlineresource="http://kortforsyning.kms.dk/servic e?" /> </HTTP> </DCPType> </Map> - <Capability> - <Format> <WMS_XML /> </Format> - <DCPType> - <HTTP> <Get onlineresource="http://kortforsyning.kms.dk/servic e?" /> </HTTP> </DCPType> </Capability> </Request> - <Exceptions> - <Format> <BLANK /> <INIMAGE /> <WMS_XML /> </Format> </Exceptions> - <Layer queryable="0"> <Title>Danmark 1:50.000</Title> <SRS>EPSG:32632</SRS> - <Layer queryable="0"> <Name>D_50</Name> <Title>Danmark 1:50.000</Title> <Abstract>Ingen værdi</abstract> <SRS>EPSG:32632</SRS> <PixelSize unit="meter">5</pixelsize> <LatLongBoundingBox minx="441419" miny="6048538" maxx="895333" maxy="6412440" /> </Layer> </Layer> - <Layer queryable="0"> <Title>Danmark 1:50.000</Title> <SRS>EPSG:32633</SRS> - <Layer queryable="0"> <Name>D_50</Name> <Title>Danmark 1:50.000</Title> <Abstract>Ingen værdi</abstract> <SRS>EPSG:32633</SRS> <PixelSize unit="meter">5</pixelsize> <LatLongBoundingBox minx="53900" miny="6070000" maxx="537900" maxy="6393200" /> </Layer> </Layer> </Capability> </WMT_MS_Capabilities> Side 4 af 12

Tilgængelige kort i Rastertjenesten De kortværk, som Rastertjenesten giver adgang til, er som udgangspunkt Danmarks Topografiske Kortværk (DTK) i seneste udgivelse. Som et yderlige supplement har vi medtaget et historisk kortværk - Danmark 1:20.000 udgivet i perioden ca. 1860 1920. For detaljeret information om tilgængelige kortværk henvises til appendiks 1 samt Kort & Matrikelstyrelsens kundekontor. Opbygning af URL Præfixet af URL en (frem til og med?) vil være ens uanset om hvad der forespørges på. URL en fra tidligere står nedenfor med præfixet markeret med gult: Efter spørgsmålstegnet? kommer parametrene, der består af et parameternavn og dens tilhørende værdi. Parameternavnet og værdien er adskilt med et =. Parametrene er altid adskilt med et &. I URL en nedenfor er parametrene SERVICENAME og WMTVER markeret med gult. Den første af de to parametre har altså navnet SERVICENAME og værdien D_50. Ved at ændre en eller flere af parameterværdierne, og dermed ændre requestet, vil responset tilsvarende ændres. Ændres værdien af parameteren SERVICENAME til M_20 vil der i stedet forespørges på kortværket M_20, hvilket svarer til historiske kortværk. På samme måde kan værdien af parameteren WIDTH ændres til 500, hvis der ønskes returneret et billede med bredden 500 pixels. Rækkefølgen af parametrene er vilkårlig. Der vil derfor ikke være forskel på de to nedenstående eksempler http://kortforsyning.kms.dk/service?servicename=d_50&wmtver=1.0.0&request=capabili ties http://kortforsyning.kms.dk/service?wmtver=1.0.0&servicename=d_50&request=capabili ties Parameterværdierne er case-sensitive, mens parameternavnene ikke er. Der vil derfor være forskel på SERVICENAME=D_50 og SERVICENAME=d_50. Omvendt er der ingen forskel på SERVICENAME=D_50 og ServiceName=D_50. Parametrene SERVICENAME, WMTVER og REQUEST er altid nødvendige, mens de andre er valgfrie og benyttes afhængig af forespørgslen. Flere af parametrene har desuden en standardværdi, hvilket betyder, at angives parameteren ikke i URL en, så vil Rastertjenesten benytte standardværdien for den pågældende parameter. Et eksempel er parameteren FORMAT, der har standardværdien JPEG. I de efterfølgende afsnit beskrives alle parametrene, der kan benyttes i URL en. Præfix Præfixet er starten af en URL, og ikke en parameter. Uanset hvilken service, der anvendes fra Kortforsyningen, er denne altid den samme. Præfixet er nedenfor markeret med gult: Side 5 af 12

SERVICENAME (nødvendig) Parameteren SERVICENAME angiver, hvilken tjeneste der ønskes anvendt. For Rastertjenesten er et ServiceName ensbetydende med et kortværk. Således har hvert af de tilgængelige kortværk et unikt ServiceName. Parameteren er nedenfor markeret med gult. http://kortforsyning.kms.dk/service?servicename=d_50&wmtver=1.0.0&request=capabili ties SERVICENAME er altid nødvendig uanset hvad der forespørges på i Rastertjenesten. I tabel 1 findes en oversigt over gyldige værdier. I appendiks 1 findes eksempler på de tilgængelige kortværk. WMTVER (nødvendig) Parameteren WMTVER angiver hvilken version af Open GIS WMS, der anvendes. Rastermotoren understøtter WMS version 1.0.0. Parameteren er nedenfor markeret med gult. http://kortforsyning.kms.dk/service?servicename=d_50&wmtver=1.0.0&request=capabili ties WMTVER er altid nødvendig uanset hvad der forespørges på i Rastertjenesten. Værdien kan være 1, 1.0 eller 1.0.0. De tre værdier har dog samme betydning og vil derfor ikke påvirke responset. Se i øvrigt tabel 1. REQUEST (nødvendig) Parameteren angiver hvorvidt der forespørges på et kort (JPEG eller PNG billede) eller informationer om kortværket (XML formateret tekst). Hvis der forespørges på et kort vil værdien være map (REQUEST=map), mens værdien er capabilities, hvis der ønskes informationer om kortværket. Parameteren er nedenfor markeret med gult. http://kortforsyning.kms.dk/service?servicename=d_50&wmtver=1.0.0&request=capabili ties REQUEST er altid nødvendig uanset hvad der forespørges på i Rastertjenesten. I den sidste af de ovenstående URL er vil der forespørges på informationer om kortværket D_50, fordi SERVICENAME=D_50. Se tabel 1 for gyldige værdier. Side 6 af 12

Bemærk at der ved en forespørgsel om informationer (REQUEST=capabilities) kun benyttes parametrene SERVICENAME, WMTVER og REQUEST. De efterfølgende parametre benyttes derfor kun, hvis der forespørges på et kort (REQUEST=map). WIDTH (valgfri) Værdien angiver bredden i pixels af billedet. Værdien skal være et heltal mellem 1 og 1200. Se i øvrigt tabel 1. Parameteren er nedenfor markeret med gult. HEIGHT (valgfri) Værdien angiver højden i pixels af billedet. Værdien skal være et heltal mellem 1 og 1200. Se i øvrigt tabel 1. Parameteren er nedenfor markeret med gult. FORMAT (valgfri) Formatet på det returnerede kortudsnit. Rastermotoren understøtter både JPEG og PNG. Parameteren er nedenfor markeret med gult. JPEG-formatet har den fordel, at billedet kan komprimeres så dets størrelse (målt i kb) kan reduceres relativt meget set i forhold til reduktionen af billedets visuelle kvalitet. Det er med JPEG derfor muligt at reducere datatransferen via Internettet til fordel for brugere med langsomme forbindelser (modem). Med PNG sker der ingen kompression. SRS (valgfri) Kortprojektionen for det returnerede kort. Defineres i SRS Spatial Reference System. Gyldige værdier er EPSG:32632 og EPGS:32633 svarende til henholdsvis UTM Zone 32 EUREF89 og UTM Zone 33 EUREF89. Parameteren er nedenfor markeret med gult. Parameterens standardværdi er EPSG:32632. Se i øvrigt tabel 1. BBOX (nødvendig) Bounding Box (BBOX) parameteren definerer billedets nederste venstre og øverste højre hjørnekoordinat (xmin, ymin, xmax, ymax) i den valgte projektion, defineret i SRS. Parameteren er nedenfor markeret med gult. Side 7 af 12

Bemærk at der benyttes amerikansk notation, det vil sige, at punktum benyttes som decimalseparator mens komma bruges til at adskille de enkelte koordinater. Det er ikke tilladt at benytte tusindtal separator. Se i øvrigt tabel 1. Det er vigtigt at huske på, at uanset værdien af BBOX og dermed hjørnekoordinaterne vil billedet altid returneres i dimensionen defineret af parametrene WIDTH og HEIGHT! Det betyder, at selvom BBOX angiver et kvadratisk geografisk område samtidig med at WIDTH er dobbelt så stor som HEIGHT, så returneres billedet med en dobbelt så stor bredde som højde Koordinaterne vil dog altid være repræsenteret i det returnerede billede uanset dimensionerne. Dvs. centreret omkring koordinaten angivet i BBOX. Et eksempel på dette ses nedenfor. Eksempel Et geografisk område defineres med BBOX=518000,6250000,528000,6260000. Dette område er beliggende omkring Viborg. Området er kvadratisk idet bredde/højdeforholdet er (528000-518000)/( 6260000-6250000) = 1. Samtidig forespørges om et billede, hvor bredden er dobbelt så stor som højden ved fx WIDTH=400 og HEIGHT=200. Resultatet vil være, at billedet returneres med en bredde og højde på henholdsvis 400 og 200, altså et billede med dobbelt så stor bredde som højde. Dette billede er vist til venstre nedenfor. I billedet er med rød stiplet streg angivet området defineret i BBOX. Billedet til højre viser området defineret af BBOX. I eksemplet ovenover betyder det, at hjørnekoordinaterne defineret i BBOX og som står i URL en ikke længere er lig hjørnekoordinaterne i det returnerede billede, idet et billede altid returneres i dimensionen defineret i WIDTH og HEIGHT. De nye/aktuelle hjørnekoordinater bliver af Rastertjenesten udregnet på basis af centerkoordinaten, der findes fra BBOX. Centerkoordinaten vil i ovenstående tilfælde være (528000-518000),(6260000-6250000) = 523000,6255000. De nye hjørnekoordinater udregnes herefter på basis af centerkoordinaten, pixelstørrelsen i billedet og billedets dimensioner: Xmin = CenterX - (beregnet_pixelstørrelse * (WIDTH/2)) Ymin = CenterY - (beregnet_pixelstørrelse * (HEIGHT/2)) Xmax = CenterX + (beregnet_pixelstørrelse * (WIDTH/2)) Ymax = CenterY + (beregnet_pixelstørrelse * (HEIGHT/2)) Den beregnede pixelstørrelse beregnes på baggrund af billedets dimensioner i pixels og det geografiske område defineret i BBOX. Fx udregnes den horisontale pixelstørrelse således: Beregnet pixelstørrelse = (Xmax Xmin) / WIDTH Der skelnes ikke mellem horisontal og vertikal pixelsstørelse. I tilfælde, hvor de ikke er ens benyttes den største af de to. På den måde sikres BBOX hjørnekoordinaterne altid at være tilstede i det returnerede billede, som vist på billederne ovenover. Side 8 af 12

Til hvert kortværk (SERVICENAME) er der tilknyttet en original pixelstørrelse. Den beregnede pixelstørrelse må ikke afvige mere end en faktor 2 fra den originale. Det betyder at forholdet mellem den originale pixelstørrelse og den beregnede ikke må være mindre end 0,5 eller større end 2. Se eksemplet nedenfor Eksempel I en URL er der bl.a. defineret følgende: SERVICENAME=D_300 BBOX=518000,6250000,528000,6260000 WIDTH=400 HEIGHT=200 Beregnet horisontal pixelstørrelse = (528000-518000)/400 = 25 meter/pixel Beregnet vertikal pixelstørrelse = (6260000-6250000)/200 = 50 meter/pixel Da 50 > 25 er den beregnede pixelstørrelse = 50 meter/pixel Den originale pixelstørrelse for D_300 er 37,5 meter/pixel. Det betyder at den mindste og største tilladte beregnede pixelstørrelse er henholdsvis 0,5 * 37,5 og 2 * 37,5. Den beregnede pixelstørrelse skal dermed være mellem 18,75 og 75 meter/pixel. Da den er 50 meter/pixel returneres billedet med det pågældende kortudsnit. Samme URL benyttes, dog med SERVICENAME =D_200, der har en original pixelstørrelse på 20 meter/pixel. Den beregnede pixelstørrelse er den samme som ovenfor, men nu er den tilladte beregnede pixelstørrelse fra 0,5 * 20 til 2 * 20, altså fra 10 til 40 meter/pixel. Da den beregende pixelstørrelse er 50 meter/pixel vil forespørgslen i dette tilfælde resultere i en såkaldt exception. For information om exceptions henvises til afsnittet Exceptions. Ovenstående kan helt undgås, vha. parameteren ORIGINALRES, som er beskrevet nedenfor. Se i øvrigt tabel 1 for yderligere information. ORIGINALRES (valgfri) Parameteren angiver hvorvidt billedet skal benytte den originale pixelstørrelse eller ej. Hvis ORIGINALRES=true bevarer billedet altid sin originale pixelstørrelse. I så tilfælde vil kortudsnittets geografiske udbredelsesområde defineres udfra nederste venstre hjørne (xmin og ymin), billedets bredde og højde (WIDTH og HEIGHT) samt den originale pixelstørrelse. Den sidste halvdel af BBOX (som er xmax og ymax) bliver derfor ignoreret. Parameteren er nedenfor markeret med gult. RS=EPSG:32632&BBOX=718090,6177375.5,720400,6179225.5&ORIGINALRES=true&WIDTH= 462&HEIGHT=370&F Parameterens standardværdi er false. Se i øvrigt tabel 1. EXCEPTIONS (valgfri) En exception opstår i Rastertjenesten, når man har lavet et ugyldigt request, ved fx at undlade at angive en eller flere nødvendige parameterværdier, eller hvis BBOX resulterer i en pixelsstørrelse, der afviger mere eller mindre end en faktor 2 fra den originale pixelstørrelse. Når en exception opstår returnerer Rastertjenesten ikke et kort. I stedet returneres et tomt billede, et billede indeholdende fejlmeddelelsen (forklaring på hvorfor der opstod en exception) eller en XML-formateret fejlmeddelelse. Hvilken af de tre typer, der ønskes, defineres i parameteren EXCEPTION. Mulige parameterværdier er INIMAGE (fejlmeddelelse i billede), BLANK (tomt billede) og WMS_XML (XML-formateret fejlmeddelelse), med sidstnævnte som standardværdi. Benyttes INIMAGE eller BLANK vil det returnerede billede have den forespurgte dimension defineret i WIDTH og HEIGHT og med formatet defineret i FORMAT. Med WMS_XML returneres fejlmeddelelsen i XML som nedenfor: Side 9 af 12

<?xml version= 1.0 encoding= ISO8859-1?> <WMTException version= 1.0.0 >Fejlmeddelelse</WMTException> Parameteren er nedenfor markeret med gult. JPEGQUALITY (valgfri) Parameter hvor det er muligt at angive en kvalitetsværdi for output-billede. Gyldige værdier er heltal fra og med 1 til og med 100, hvor 100 er bedste kvalitet. Jo lavere kvalitet jo mindre fylder billedet og dermed færre data at overføre via Internettet. Parameterens standardværdi er 50. Parameteren er nedenfor markeret med gult. ORMAT=JPEG&JPEGQUALITY=80&EXCEPTION=WMS_XML Nedenfor ses et eksempel med forskellige JPEGQUALITY. JPEGQUALITY=10 Filstørrelse = 10 kb JPEGQUALITY=100 Filstørrelse = 109 kb Side 10 af 12

Tabel 1: Oversigt over parametrene I Rastertjenesten Parameter Datatype Standardværdi Gyldig værdi Benyttes Præfix Tekst - http://kortforsyning.kms.dk/service? Altid SERVICENAME Tekst - D_OVERSIGT, D_3200, D_850, D_500, D_300, D_200, D_100, Altid D_50, D_25, M_20 WMTVER Tekst - 1 Altid 1.0 1.0.0 REQUEST Tekst - map Altid capabilties BBOX Liste - Kommasepareret liste med mindst to og maksimalt fire Ved REQUEST=map kommatal. Tallenes rækkefølge er xmin, ymin, xmax, ymax. To tal er kun tilladt, hvis ORIGINALRES=true SRS Tekst EPSG:32632 EPSG:32632 Ved REQUEST=map EPSG:32633 WIDTH Heltal 100 >= 1 og <= 1200 Ved REQUEST=map HEIGHT Heltal 100 >= 1 og <= 1200 Ved REQUEST=map FORMAT Tekst JPEG JPEG Ved REQUEST=map PNG EXCEPTION Tekst WMS_XML WMS_XML Ved REQUEST=map INIMAGE BLANK JPEGQUALITY Heltal 50 >= 1 og <= 100 Ved REQUEST=map og FORMAT=JPEG ORIGINALRES Boolean false true false Ved REQUEST=map

Overbelastning Ekstrem overbelastning af Kortforsyningen kan medføre en Exception i form af et billede med en oprindelig størrelse på 100x100 pixels. Billedet vil dog skaleres og returneres i den forespurgte størrelse defineret i WIDTH og HEIGHT. Fejlhåndtering Parametrene i URL en valideres når requestet modtages af Rastertjenesten. Valideringen tjekker om de nødvendige parametre er inkluderet i URL en, om parameterværdierne er gyldige jf. ovenstående og tabel 1. Er resultatet af valideringen positivt returneres det forespurgte kort eller information. Er der derimod en fejl vil en exception opstå. Hvordan Rastertjenesten skal reagere på exceptions, defineres i parameteren EXCEPTION se afsnittet EXCEPTION. Bemærk at parameterværdierne er case sensitive! Der er altså forskel SERVICENAME=D_50 og SERVICENAME=d_50. Der kan opstå tilfælde, hvor man får et kortudsnit, der ikke er som forventet. Dette skyldes oftest, at et eller flere parameternavne er stavet/tastet forkert. Rastertjenesten vil derfor ikke kunne registrere parameteren og dens tilhørende værdi. I stedet benyttes standardværdien, hvis en sådan findes. Et eksempel er nedenstående URL, hvor der ønskes et billede med formatet PNG. OMAT=PNG&TRANSPARENT=false&EXCEPTION=WMS_XML Rastertjenesten vil mod forventning returnere et billede i formatet JPEG, fordi parameteren FORMAT er stavet/tastet forkert (FOMAT). Det tolkes af Rastertjenesten som at parameteren ikke findes. Standardværdien, som er JPEG, anvendes i stedet.