Kurogo Tutorial 09 - MAP Module -

Kurogo Documentation 을 순서대로 진행을 했는데요. 오늘은 좀 건너 뛰어서 해야겠습니다.

회사에서 갑자기 MAP 과 관련되서 일이 주어져서요.

아직 제대로 파악도 못했는데... 빨리 공부해서 빨리 해결해야 겠습니다.

맵 말고도 한두가지 더 일을 맡았는데 그 중 하나는 Drupal 로 하는 일이예요.

Drupal 도 배워야겠네요...

Map Module Tutorial 은 Included Modules 안의 Map Module 부분에 있습니다.

===============================

Map Module

이 맵 모듈은 맵에서 여러분들이 찾고 싶은 곳을 찾고 볼 수 있도록 해 줍니다. 장소들은 feed groups, category, subcategory 등에 의해 group 화 될 수 있습니다.

Basic Configuration

Feed Groups

각 feed group 은 center location과 appearance에 의해 base map, characterized 와 연관 돼 있습니다. 여러개의 캠버스들과 feed group들로 구성된 조직을 캠퍼스가 맵을 지역적으로 분리합니다.

Group은 SITE_DIR/config/map/feedgroups.ini file 안에서 configured 돼 있습니다. 거기에는 아래와 같이 적어도 한개의 entry 가 있어야 합니다.

[groupID]
title                = "Title of my map"
subtitle             = "Subtitle of my map"
center               = "42.3584308,-71.0597732"
DEFAULT_ZOOM_LEVEL   = 10

[groupID] 는 짧게 알파벳으로 그룹의 이름을 지어주면 됩니다. 예) “boston”, “newyork”, “daytime”, etc.
title (required) - 이 그룹에 대한 짧은 설명 e.g. “Boston Campus”
subtitle (optional) - title로 부족할 경우 좀 더 길게 설명을 추가할 수 있음
center (required) - latitude, longitude point (위도, 경도). 이 그룹의 center를 나타냄. 쉼표 전 후로 빈공간이 들어가면 안 됨.
DEFAULT_ZOOM_LEVEL (recommended) - 맵을 표시할 초기 zoom 레벨. 대개 0~21 사이의 값을 넣으면 됨. 각 숫자는 아래의 크기를 보여 줍니다.

0: earth
1: hemisphere (반구)
2: multiple continents
3: one continent
4: large country
5: medium-sized country
6: small country or large state
7: small state
8: tiny state
9: metropolitan area + vicinity
10: metropolitan area
11: large city
12: small city
13: town
14: several neighborhoods
15: a few neighborhood
16: neighborhood
17: several blocks
18: a few blocks
19: several buildings
20: a few buildings
21: a building

compliant/tablet 디바이스에서는 디폴트로 구글 맵을 사용합니다. 그리고 basic/touch 디바이스에서는 Google Static Map을 사용합니다. 쿠로고는 또한 compliant/tablet 디바이스에서 ArcGIS JavaScript를 지원합니다. 그리고 basic 디바이스에서 ArcGIS static map 을 지원합니다. 좀 더 자세한 사항은 Advanced Configuration section을 참조하세요.

Data Feeds

각 data feed는 홈스크린이나 캠퍼스에서 유저가 browse 하는 category로서 표현됩니다.

현재 아무 mapping infrastructure를 가지고 있지 않은 사람들을 위해 우리는 Google Earth를 사용해서 feeds를 생성하라고 권장합니다. Google Earth는 맵에 pin을 사용할 수 있도록 하고 결과값을 KML 파일로 export 할 수 있도록 합니다.

feed group에 feed를 add 하기 위해 SITE_DIR/config/map/feeds-GROUP.ini 파일 안에 entry를 생성합니다. (Group은 feedgroups.ini로부터 가져온 그 그룹의 id 입니다.). 각각의 entry들은 다음과 같이 만들어 집니다.

[index]
TITLE            = "Fun Places in Washington"
SUBTITLE         = "These are places I like to check out on vacation"
BASE_URL         = DATA_DIR"/washington.kml"
SEARCHABLE       = 1

index 는 숫자입니다. (0서부터 시작) 이 인덱스는 이 feed의 sort order(정렬순서)를 나타냅니다.
TITLE 은 카테고리 리스트에 보이는 카테고리의 desctiptive name 입니다.
SUBTITLE (optional) 은 title 옆에 붙는 간략한 description 입니다.
BASE_URL (required) 은 데이터 소스의 URL이나 파일의 위치입니다.
SEARCHABLE - 그냥 1로 세팅하세요.
Note: .kml 포맷이 아니라 .kmz 을 사용한다면 엔트리 안에 다음의 것들을 지정하셔야 합니다.

RETRIEVER_CLASS       = "KMZDataRetriever"

쿠로고는 또한 ArcGIS RES API와 ESRI Shapefile 포맷으로 데이터를 지원합니다. 만약 이 포맷을 사용한다면 혹은 data feeds와 base maps를 다른 것으로 바꾸기를 원한다면 Advanced Configuration section을 참조하세요.

User Interface Options

The following options appear by default in SITE_DIR/config/map/module.ini:
아래 옵션들은 SITE_DIR/config/map/module.ini 에서 디폴트로 설정돼 있는 값들입니다.

BOOKMARKS_ENABLED          = 1
MAP_SHOWS_USER_LOCATION    = 1
SHOW_DISTANCES             = 1
DISTANCE_MEASUREMENT_UNITS = "Imperial"
SHOW_LISTVIEW_BY_DEFAULT   = 0

BOOKMARKS_ENABLED - 유저가 위치를 즐겨찾기 하게할 지 말지를 정함
MAP_SHOWS_USER_LOCATION - 유저가 지도에 location marker를 display 하게 할지 말지를 정함. This does not turn off geolocation in general.
SHOW_DISTANCES - 검색된 위치로부터의 거리를 표시할 지 여부를 정함.
DISTANCE_MEASUREMENT_UNITS - either “Metric” or “Imperial”. Metric 이나 Imperial 중에 하나를 선택하면 됨
SHOW_LISTVIEW_BY_DEFAULT - 만약에 단 하나의 캠퍼스만 있다면 map module의 index page는 compliant devices에서 지도를 full screen으로 보여 줄겁니다. 만약 이 값이 1로 세팅돼 있다면 맵 모듈의 index page 는 list view를 보여줄 겁니다. 또한 멀티 캠퍼스라면 파라미터에 상관없이 index page는 list view를 보여 줄 겁니다.   multip

Advanced Configuration

Feed Groups

title, subtitle, center 이외에 각 그룹은 다음과 같은 것들을 지정해 줍니다.

- JS_MAP_CLASS (optional) - JavaScript map을 지원하는 디바이스를 사용하기 위한 base map의 type . Base Maps를 보세요.
- DYNAMIC_MAP_BASE_URL (required if JS_MAP_CLASS is ArcGISJSMap) - base map JavaScript API 가 host 돼 있는 base URL
- STATIC_MAP_CLASS (optional) - JavaScript map을 지원하지 않는 디바이스를 사용하기 위한 base map의 type . Base Maps를 보세요.
- STATIC_MAP_BASE_URL (required if STATIC_MAP_CLASS is ArcGISStaticMap or WMSStaticMap) - static base map service가 호스트 돼 있는 base URL
- NEARBY_THRESHOLD (optional, defaults to 1000) -인근 위치를 검색할 때 사용하는 meter로 된 거리
- NEARBY_ITEMS (optional, defaults to 0) - 인근 검색할 떄 return 되는 item들의 maximum number.값이 0이면 제한이 없음.

Example configuration:

[honolulu]
title                = "Honolulu Campus"
subtitle             = "Our new satellite office that nobody knows about"
center               = "21.3069444,-157.8583333"
JS_MAP_CLASS         = "ArcGISJSMap"
DYNAMIC_MAP_BASE_URL = "http://myhost/MapServer"
STATIC_MAP_CLASS     = ArcGISStaticMap
STATIC_MAP_BASE_URL  = "http://myhost/MapServer"
NEARBY_THRESHOLD     = 1609
NEARBY_ITEMS         = 12

Data Feeds

TITLE, SUBTITLE, BASE_URL 이외에 각 feed 는 아래와 같은 값들을 정해 줍니다.

- MODEL_CLASS - 데이터 소스 타입과 관련된 데이타 모델 클래스. 디폴트는 MapDataModel 임.
- RETRIEVER_CLASS - feed를 위해 사용되는 data retriever class (디폴트가 아니라면). 디폴트는 MODEL_CLASS에 따라 다름. 만약 custom model class를 사용하지 않는다면 이것은 KMZ 파일에만 필요할 것임 (which need KMZDataRetriever).
- SEARCHABLE - 이 데이타 소스가 internal search result에 포함되어야 하는지의 여부를 나타내는 boolean 값. 이 값은 external search engine을 사용한다면 관계가 없음. 디폴트는 false임.
- HIDDEN (optional) - true이면 이 feed는 browsable category의 리스트에 나타나지 않음. 이 기능은 site가 user가 browse 할 수 있는 search results에 표시될 서로 다른 placemarks의 세트를 갖기를 원할 경우 사용될 수 있을 겁니다. 그 placemark의 set는 user가 browse 할 수 있는 search results에 표시될 겁니다.

개별적인 feed 들에 대한 어떤 config 값들의 세트는 서로 연관된 feed group 에서 그 값을 override 할 수 있습니다. 예를 들어 'honlulu' feed group은 검색할 때 인근 1000미터 반경을 찾아 볼 겁니다. 하지만 밀집한 feed 가 있어서 반경 200미터에서만 검색하기를 원합니다. 이럴 경우 NEARBY_THRESHOLD 를 개별적인 feed로 세팅할 수 있습니다. override 할 수 있는 config 파라미터들은 DEFAULT_ZOOM_LEVEL, JS_MAP_CLASS, DYNAMIC_MAP_BASE_URL, STATIC_MAP_CLASS, STATIC_MAP_BASE_URL, NEARBY_THRESHOLD, NEARBY_ITEMS 가 있습니다.


KML/KMZ

KML은 맵 모듈의 디폴트 feed type 입니다. 다른말로 feed config 가 MODEL_CLASS 나 RETRIEVER_CLASS 로 정해주지 않았다면 코로고는 이 feed를 KML 포맷으로 처리할 겁니다.

쿠로고는 KML tags의 subset 만 지원합니다. 쿠로고는 <MultiGeometry>, <Model>, <gx:Track>, <gx:Multitrack>를 제외한 모든 지원하지 않는 tags를 무시할 겁니다. 이럴 경우 Kurogo는 exception을 throw 합니다. 또한 몇개의 태그들은 parse 되지만 UI에서는 보이지 않습니다.

아래 tags 들은 parse 되고 UI에도 나타납니다.

<Folder>
    <name>
    <description>
<StyleMap>
    <Pair>
        <key>
        <styleURL>
<Style>
    <iconStyle>
        <href>
        <w>
        <h>
    <balloonStyle>
        <bgColor>
        <textColor>
    <lineStyle>
        <color>
        <weight>
    <polyStyle>
        <fill>
        <color>
<Placemark>
    <address>
    <name>
    <description>
    <Snippet>
    <Point>
        <coordinates>
    <Polygon>
        <outerBoundaryIs>
        <innerBoundaryIs>
    <LineString>
        <coordinates>
    <LinearRing>

   
아래 tags 들은 parse 되지만 UI에 영향을 주지는 않습니다.   

<Document>
    <name>
    <description>

    <scale> (under iconStyle)

   
좀 더 자세한 사항은 구글의 KML documentation을 참조하세요.

ArcGIS Server

ArcGIS 서버를 사용하려면 feeds-<group>.ini 안의 아래 사항들을 설정하셔야 합니다.

MODEL_CLASS = "ArcGISDataModel"

만약에 service 가 여러 layer를 가지고 있다면 Kurogo는 한번에 한 layer 만 사용합니다. 여러분은 feed 별로 다른 layer 를 할당하셔야 됩니다.

ARCGIS_LAYER_ID = <number>

<number> 는 layer를 나타내는 숫자로 된 ID 입니다. 이 ID를 할당함으로서 feed 별 layer를 지정합니다. sublayer는 현재 지원되지 않습니다.

좀 더 자세한 사항을 보시려면 Esri의 ArcGIS server documentation을 보세요.

Shapefile

To use shapefiles, specify the following in feeds-<group>.ini:
shapefile을 이용하려면 feeds-<group>.ini 안에 있는 아래 내용을 사용하세요.

MODEL_CLASS = "ShapefileDataModel"

network 상에 위치한 Shapefile들은 directory들을 포함하고 있지 않은 sip 폴더에 있어야 합니다. (예: contents 들은 모두 .shp, .dbf, .shx, and .prj 파일들입니다). zipped 된 shapefile들을 사용하려면 ZipArchive 확장자가 PHP에서 사용 가능해야 합니다.

큰 shapefile들은 unzip 되 있고 DATA_DIR의 subdirectory에 locally 저장돼 있을 겁니다. 이런 경우에 BASE_URL은 반드시 확장자 없이 지정되어야 합니다. 예) DATA_DIR”/myshapefile.shp” 와 DATA_DIR”/myshapefile.dbf” 로 구성된 shapefile은 반드시 다음과 같이 지정돼야 합니다.

BASE_URL = DATA_DIR"/myshapefile"

좀 더 자세한 사항을 아시려면 Wikipedia의 Shapefile specification 부분을 보세요.

Configuring Display Options

SHOW_DISTANCES - (optional, defaults to true) item 까지의 거리를 보여줄지 여부
DISTANCE_MEASUREMENT_UNITS - (optional, defaults to ‘Metric’) Imperial (인치, 야드, 마일 등) 이나 Metric (미터 단위) 로 거리를 보여줄 지 여부.
MAP_SHOWS_USER_LOCATION - (optional, defaults to false) 지도에 user의 위치를 보여줄 지 여부.
BOOKMARKS_ENABLED - (optional, defaults to true) true로 세팅돼 있으면, bookmarked 된 entry로의 link 가 나타남. 만약 아무 entry 도 bookmark 돼 있지 않다면 entry 가 bookmark 될 때까지 이 링크는 나타나지 않을 겁니다.

Base Maps

Kurogo의 base 맵은 아래의 configuration과 default rules 를 따릅니다. :

JS_MAP_CLASS 와 STATIC_MAP_CLASS 가 따로 명시돼 있지 않다면 Kurogo는 디폴트로 basic/touch device에 대해서는 Goggle Static Maps를 그리고 compliant/tablet device에 대해서는 Google Maps를 사용할 겁니다.

만약 TATIC_MAP_CLASS 만이 명시돼 있다면 compliant/tablet 와 basic/touch devices 모두 STATIC_MAP_CLASS 가 명시되서 base map 을 사용할 겁니다. JS_MAP_CLASS 만 명시됐다면 basic/touch devices 에도 Google Static Maps 가 적용될 겁니다.

JavaScript base maps (compliant and tablet only)

JS_MAP_CLASS 에 적용 가능한 옵션은 아래와 같습니다. .

Google Maps

Google Map을 (디폴트를 그냥 사용하지 않고) 명시적으로 사용하려면 아래 configuration을 참조하세요.

JS_MAP_CLASS = "GoogleJSMap"

좀 더 자세한 사항은 Google’s Maps documentation을 참조하세요.

ArcGIS Tiled Service Maps

ArcGIS tile server 로부터 tiles 를 얻어서 사용하려면 아래 configuration을 참조하세요.

JS_MAP_CLASS = "ArcGISJSMap"
DYNAMIC_MAP_BASE_URL = "http://..."

ArcGIS Dynamic Service Map으로부터 얻어 사용할 수 있는 추가적인 dynamic layer는 DYNAMIC_MAP_BASE_URL에 배열로 명시해서 base map 의 윗부분에 추가할 수 있습니다.

DYNAMIC_MAP_BASE_URL[] = "http://my.tiled.service/MapServer" DYNAMIC_MAP_BASE_URL[] = "http://my.dynamic.service/MapServer"

DYNAMIC_MAP_BASE_URL의 첫번째 element 는 반드시 tiled service 라야 합니다. 1개만 지정되고 단 1개만 tiled service 라야 합니다.

좀 더 자세한 사항은 Esri’s ArcGIS JavaScript documentation 을 참조하세요.

Static image base maps

STATIC_MAP_CLASS에 사용될 수 있는 옵션은 아래와 같습니다.

Google Static Maps

디폴트를 그냥 사용하지 않고 Google Static Maps를 명시적으로 사용하려면 아래 configuration을 사용하세요.

STATIC_MAP_CLASS = "GoogleStaticMap"

Google Static Maps는 현재 polygon overlay를 지원하지 않습니다.

좀 더 자세한 사항은 Google’s Static Maps documentation을 보세요.

Web Map Service (WMS)

WMS service 에서 images를 사용하시려면 아래 configuration을 이용하세요.

STATIC_MAP_CLASS = "WMSStaticMap"
STATIC_MAP_BASE_URL = "http://..."

overlays를 WMS map에 추가하는 것은 가능하지 않습니다.

좀 더 자세한 사항은 Open Geospatial Consortium’s WMS documentation 을 참조하세요.

ArcGIS exported images

ArcGIS로부터 export된 이미지를 사용하려면 아래 configuration을 이용하시면 됩니다.

STATIC_MAP_CLASS = "ArcGISStaticMap"
STATIC_MAP_BASE_URL = "http://..."

export된 image에 overlay를 추가하는 것은 가능하지 않습니다.

좀 더 자세한 사항은 Esri’s export API documentation 을 참조 하세요.

Map Search

Map search 는 module.ini에서 설정합니다. 만약 이게 설정돼 있지 않으면 Kurogo는 디폴트로 MapSearch 클래스를 사용합니다. 이 클래스는 선택된 feed group 전체를 보게 될 겁니다.

옵션으로 아래 파라미터들이 설정될 수 있습니다.

MAP_SEARCH_CLASS          = "MyMapSearchSubclass"
MAP_EXTERNAL_SEARCH_CLASS = "GoogleMapSearch"

MAP_SEARCH_CLASS 를 사용해서 map module 안에 Searches 를 initiate 할 수 있습니다. MAP_SEARCH_CLASS의 디폴트는 MapSearch 입니다. Search는 modules에 의해 initiate 됩니다. 만약 optional config parameter MAP_EXTERNAL_SEARCH_CLASS 가 다른 클래스로 configure 됐다면 map module은 다른 search class를 사용할 겁니다.

기본적으로 제공되는 GoogleMapSearch 클래스는 Google Places 나 the Google Geocoding service를 사용합니다. Geocoding가 디폴트 입니다. Places를 사용하려면 (구글로부터 API key 를 받았다는 것을 가정하고..) SITE_DIR/config/maps.ini 파일에 아래 configuration을 하세요.

[maps]
USE_GOOGLE_PLACES     = 1
GOOGLE_PLACES_API_KEY = AbCDeFGH123789zzzzzzzzzzzzzzzzzzzxwycbA

Terms of Use for External Providers

Google Maps 유저나 그과 관계된 제품(Kurogo installation에 주요하게 포함돼 있는 제품)을 사용하는 유저들은 이 모든 제품들에 대한 usage 제한에 대해 염두에 두셔야 합니다.

Google Maps/Earth API terms 는 여기에 있습니다.

사용량이 많은 site의 경우 embedded Google Maps 의 최근 변경된 usage limit에 대해 주의하실 필요가 있습니다.