세라핀 파일

드라이버 단축 이름

Selafin

기본 내장 드라이버

이 드라이버는 기본적으로 내장되어 있습니다.

OGR는 2차원 세라핀(Selafin/Seraphin) 파일 읽기를 지원합니다. 세라핀은 오픈 소스 텔레맥 수리 모델(Telemac hydraulic model) 에서 쓰이는 지리 파일의 일반 산출 및 입력 포맷입니다. 이 파일 포맷은 서로 다른 시계열 단계에 있는 포인트 객체 집합의 숫자형 속성을 설명하는 데 적합합니다. 이 포인트 객체는 보통 유한 요소 모델(finite-element model)에 있는 노드에 대응합니다. 이 파일은 이런 노드들이 형성하는 요소들을 설명하는 연결성(connectivity) 테이블도 가지고 있는데, 세라핀 드라이버는 이 테이블도 읽을 수 있습니다.

세라핀 드라이버는 VSI 가상 파일을 세라핀 데이터소스로 사용할 수 있습니다.

이 드라이버는 세라핀 파일에 대한 완전한 읽기 및 쓰기를 지원합니다. 하지만, 요소(폴리곤) 객체와 노드(포인트) 객체가 밀접하게 관련되어 있는 세라핀 파일의 특수한 성질 때문에 세라핀 레이어 상에 작성 작업을 하는 것이 직관에 반대되는 결과로 이어질 수 있습니다. 일반적으로, 세라핀 데이터소스의 어떤 한 레이어에 작성 작업을 하면 다른 모든 레이어에도 부작용을 일으킬 것입니다. 또한, 업데이트 모드에서 동일한 레이어를 한 번 이상 열지 말아야 합니다. 단일 데이터소스에 쓰기 작업 2개를 동시에 처리하는 것이 복구 불가능한 데이터 오류로 이어질 수 있기 때문입니다. 이 드라이버는 데이터소스를 업데이트 모드로 열 때마다 경고를 발합니다.

드라이버 케이퍼빌리티

Create() 지원

이 드라이버는 GDALDriver::Create() 작업을 지원합니다.

지리참조 작업 지원

이 드라이버는 지리참조 작업을 지원합니다.

VirtualIO 지원

이 드라이버는 virtual I/O operations (/vsimem/, etc.) 를 지원합니다.

매직 넘버

세라핀 파일은 일반 확장자를 가지고 있지 않습니다. 파일 시작 부분에 있는 12개의 매직 넘버(magic byte)로 세라핀 포맷이 맞는지 테스트합니다:

• 파일의 처음 4바이트가 00 00 00 50 (16진법) 값들을 담고 있어야 합니다. 이 값들은 실제로 파일에 있는 80바이트 길이의 문자열의 시작을 의미합니다.

• 파일의 84바이트 위치부터, 00 00 00 50 00 00 00 04 (16진법) 값들이 읽혀야 합니다.

이 드라이버는 이 두 가지 조건을 만족하는 파일을 세라핀 파일로 간주하고 성공적으로 열었다고 리포트할 것입니다.

포맷

세라핀 포맷은 포터블하고 컴팩트한 방식으로 데이터 구조를 담도록, 그리고 데이터에 효율적인 임의 접근이 가능하도록 설계되었습니다. 세라핀 파일은 이런 목적을 위한 일반 구조를 가진 바이너리 파일입니다.

요소

세라핀 파일은 요소들의 병렬 배치(juxtaposition)로 이루어져 있습니다. 요소 유형은 다음 가운데 하나입니다:

• 정수형

• 문자열

• 부동소수점형

• 정수값 배열

• 부동소수점값 배열

Selafin Element Types

요소	내부 표현	비고
Integer	a b c d	정수형은 빅 엔디언 (최상위 바이트 우선) 서식의 4바이트로 저장됩니다. 정수값은 ‘224.a+216.b+28.c+d’입니다.
Floating point	a b c d	부동소수점형은 빅 엔디언 규범(최상위 바이트 우선) 아래 IEEE 754 서식의 4바이트로 저장됩니다. 런타임에서 첫 번째 부동소수점형 값을 읽을 때 엔디언 여부를 탐지합니다.
String	Length 1 2 … Length	문자열은 세 부분으로 저장됩니다: 문자열의 (문자 단위) 길이를 담고 있는 정수, 4바이트 문자열에 있는 문자들의 순열, 문자 당 1바이트 문자열의 길이를 담고 있는 정수의 반복
Array of integers	Length 1 2 … Length	정수값 배열은 세 부분으로 저장됩니다: 배열의 (바이트 단위, 즉 요소 개수의 4배) 길이를 담고 있는 정수, 4바이트 배열에 있는 정수들의 순열, 앞에서 설명한 대로 정수 당 4바이트 배열의 길이를 담고 있는 정수의 반복
Array of floating point values	Length 1 2 … Length	부동소수점값 배열은 세 부분으로 저장됩니다: 배열의 (바이트 단위, 즉 요소 개수의 4배) 길이를 담고 있는 정수, 4바이트 배열에 있는 부동소수점형 숫자들의 순열, 앞에서 설명한 대로 부동소수점형 숫자 당 4바이트 배열의 길이를 담고 있는 정수의 반복

전체 구조

세라핀 파일의 헤더는 다음 요소들을 정확히 다음 순서대로 담고 있습니다:

• 연구 제목을 담은 문자 80개 길이의 문자열: 마지막 문자 8개는 “SERAPHIN” 또는 “SERAFIN” 또는 “SERAFIND” 가운데 하나여야 합니다.

• 요소를 딱 2개 가진 정수값 배열: 첫 번째 요소는 변수(속성) nVar 의 개수이고, 두 번째 요소는 무시합니다.

• 변수의 이름을 담은 nVar 문자열: 각 문자열의 길이는 문자 32개입니다.

• 요소를 딱 10개 가진 정수값 배열:

  • 세 번째 요소가 모델 원점(origin)의 X 좌표입니다.

  • 네 번째 요소가 모델 원점의 Y 좌표입니다.

  • 열 번째 요소가 모델의 날짜를 읽어와야 하는지를 나타내는 isDate 입니다. (다음 항목 참조)

  • 덧붙여, 현재 수리 소프트웨어는 두 번째 요소를 사용하지 않지만, 이 드라이버가 데이터소스의 공간 좌표계를 투영법의 EPSG 번호를 의미하는 단일 정수 형식으로 저장하기 위해 사용합니다.

• isDate=1인 경우, 요소를 딱 6개 가진 정수값 배열: 모델의 시작일(연, 월, 일, 시, 분, 초)을 담고 있습니다.

• 요소를 딱 4개 가진 정수값 배열.:

  • 첫 번째 요소가 nElements 요소의 개수입니다.

  • 두 번째 요소가 nPoints 포인트의 개수입니다.

  • 세 번째 요소가 nPointsPerElement 요소 당 포인트의 개수입니다.

  • 네 번째 요소는 반드시 1이어야만 합니다.

• 요소를 딱 nElements*nPointsPerElement 개 가진 정수값 배열: 연속하는 nPointsPerElement 집합은 각각 요소를 구성하는 포인트의 (1에서 시작하는) 개수 목록입니다.

• 요소를 딱 nPoints 개 가진 정수값 배열: 드라이버가 무시합니다. (요소는 내부 포인트에 대해 0이어야 하고 제한 조건이 적용되는 경계 포인트에 대해서는 또다른 값이어야 합니다.)

• 요소를 딱 nPoints 개 가진 부동소수점값 배열: 포인트의 X 좌표를 담고 있습니다.

• 요소를 딱 nPoints 개 가진 부동소수점값 배열: 포인트의 Y 좌표를 담고 있습니다.

파일의 나머지 부분은 이어지는 각 시계열 단계의 실제 데이터를 담고 있습니다. 시계열 단계는 다음과 같은 요소들을 담고 있습니다:

• 요소를 딱 1개 가진 부동소수점값 배열: 시뮬레이션의 시작일에 상대적인 시계열 단계의 날짜입니다. (보통 초 단위입니다.)

• 배열의 각 항목이 딱 nPoints 개의 요소를 가진 부동소수점값 nVar 배열: 현재 시계열 단계에 있는 각 포인트의 각 속성값을 담고 있습니다.

파일과 레이어 사이의 매핑

세라핀 데이터소스의 레이어

세라핀 드라이버는 데이터소스로 세라핀 파일만 입력받습니다.

각 세라핀 파일은 하나 이상의 시계열 단계를 담을 수 있습니다. 드라이버가 모든 시계열 단계를 읽어와서 각 시계열별로 레이어 2개를 생성합니다:

• 노드(포인트) 및 그 속성을 가진 레이어: 이 레이어의 이름은 데이터소스의 기본명 뒤에 (포인트라는 의미의) “_p”를 붙인 것입니다.

• 요소(폴리곤) 및 해당 요소의 꼭짓점들의 속성값들을 평균 낸 속성을 가진 레이어: 이 레이어의 이름은 데이터소스의 기본명 뒤에 (요소(element)라는 의미의) “_e”를 붙인 것입니다.

마지막으로, 시계열 단계의 개수 또는 (시작일과 경과된 초 단위 시간을 기반으로) 계산된 날짜를 레이어 이름에 추가합니다. 따라서 Results라는 파일에 있는 데이터소스를 레이어 여러 개로 읽어올 수도 있습니다:

• Results_p2014_05_01_20_00_00: 이 레이어가 노드 및 노드 속성을 담고 있으며 Results 파일이 2014년 5월 1일 오후 8시 시계열 단위에 대한 결과물을 담고 있다는 의미입니다.

• Results_e2014_05_01_20_00_00: 이 레이어가 요소 및 요소 속성을 담고 있으며 Results 파일이 2014년 5월 1일 오후 8시 시계열 단위에 대한 결과물을 담고 있다는 의미입니다.

• Results_p2014_05_01_20_15_00: 이 레이어가 노드 및 노드 속성을 담고 있으며 Results 파일이 2014년 5월 1일 오후 8시 15분 시계열 단위에 대한 결과물을 담고 있다는 의미입니다.

• …

레이어에 대한 제약 사항

세라핀 파일의 포맷 때문에, 단일 세라핀 데이터소스에 있는 레이어들은 상호 간에 독립적일 수 없습니다. 레이어 하나를 변경하면 거의 확실하게 다른 모든 레이어에도 부작용이 일어날 것입니다. 이 드라이버가 다음과 같은 제약 사항을 만족시키기 위해 모든 레이어를 업데이트하기 때문입니다:

• 모든 노드 레이어가 동일한 개수의 객체를 가집니다. 레이어 하나에 객체를 추가하거나 제거하면, 다른 모든 레이어에도 추가하거나 제거합니다.

• 서로 다른 노드 레이어에 있는 객체가 동일한 도형을 공유합니다. 포인트 하나의 위치를 변경하면, 다른 모든 레이어에서도 변경됩니다.

• 모든 요소 레이어가 동일한 개수의 객체를 가집니다. 레이어 하나에 객체를 추가하거나 제거하면, 다른 모든 레이어에도 추가하거나 제거합니다.

• 요소 레이어에 있는 모든 폴리곤이 동일한 개수의 꼭짓점을 가집니다. 요소 레이어에 첫 번째 객체를 추가할 때 꼭짓점 개수가 고정되며, 처음부터 데이터소스를 재생성하지 않는 이상 이후에 변경할 수 없습니다.

• 서로 다른 요소 레이어에 있는 객체가 동일한 도형을 공유합니다. 레이어 하나에 요소를 추가하거나 제거하면, 다른 모든 레이어에도 추가하거나 제거합니다.

• 요소 레이어에 있는 모든 객체의 모든 꼭짓점이 대응하는 노드 레이어의 포인트 객체를 가집니다. 요소 객체를 추가할 때 그 꼭짓점이 아직 존재하지 않는 경우, 노드 레이어에 대응하는 포인트를 생성합니다.

• 노드 및 요소 레이어는 “REAL” 유형 속성만 지원합니다. 실수형 숫자의 (길이 및 정밀도) 서식을 변경할 수 없습니다.

레이어 필터링 사양

세라핀 파일 하나가 레이어 수백만 개를 담고 있을 수도 있는데 사용자는 일반적으로 그 중 몇 개에만 관심이 있기 때문에, 이 드라이버는 레이어를 읽어오기 전에 레이어를 필터링할 수 있는 당의 구문(syntactic sugar)을 지원합니다. 당의 구문이란 문법적으로는 동일하면서도 사람이 읽고 쓰기 쉽게 해주는 구문을 말합니다.

데이터소스를 지정할 때, Results[0:10] 처럼 데이터소스 바로 뒤에 레이어 필터링 사양 이 올 수도 있습니다. 레이어 필터링 사양의 효과는 모든 세라핀 파일로부터 어떤 시계열 단계를 불러올 것인지를 지시하는 것입니다.

레이어 필터링 사양은 쉼표로 구분된 지정 범위의 순열(sequence)로, 지정 범위를 대괄호로 감싸고 앞에 ‘e’ 또는 ‘p’ 문자가 붙을 수도 있습니다. 이 ‘e’ 또는 ‘p’ 문자는 각각 요소만 또는 노드만 선택하도록 하는 역할입니다. 아무 문자도 붙지 않는 경우 노드와 요소 둘 다 선택합니다. 각 지정 범위는:

• 단일 시계열 단계 1개를 표현하는 (0애서 시작하는) 숫자 하나이거나,

• 또는 쌍점으로 구분된 숫자 2개 집합입니다: 이 경우, 이 두 숫자를 포함해서 그 사이에 있는 모든 시계열 단계를 선택합니다. 첫 번째 숫자가 생략되었다면 범위가 파일의 시작(첫 번째 시계열 단계)부터 시작합니다. 두 번째 숫자가 생략되었다면 범위가 파일의 마지막(마지막 시계열 단계)까지 포함합니다.

음의 숫자도 사용할 수 있습니다. 이 경우, 마지막 시계열을 -1로 보고 파일의 마지막부터 셉니다.

다음은 레이어 필터링 사양의 예시입니다:

Examples of layer filtering specifications

[0]	첫 번째 시계열 단계만, 노드 및 요소 둘 다 반환
[e:9]	처음 시계열 단계 10개만, 요소를 가진 레이어만 반환
[p-4:]	마지막 시계열 단계 4개만, 노드를 가진 레이어만 반환
[3,10,-2:-1]	4번째, 11번째, 그리고 마지막 2개의 시계열 단계, 노드 및 요소 둘 다 반환

데이터소스 생성 옵션

ogr2ogr 유틸리에 -dsco 옵션을 사용하면 데이터셋 생성 옵션을 지정할 수 있습니다:

• TITLE: 세라핀 파일에 저장되는 데이터소스의 제목입니다. 이 제목의 길이는 문자 72개를 넘어서는 안 됩니다. 72개보다 긴 경우, 파일에 맞추기 위해 절단될 것입니다.

• DATE: 시뮬레이션의 시작일입니다. 세라핀 파일에 있는 각 레이어는 기준일로부터 초 단위로 셈하는 날짜로 구별됩니다. 이 옵션으로 그 기준일을 지정할 수 있습니다. 이 옵션값의 서식은 ‘YYYY-MM-DD_hh:mm:ss’이어야만 합니다. 이 서식은 시간대를 언급하지 않습니다.

다음은 데이터소스 생성 옵션의 예시입니다:

-dsco TITLE="My simulation" -dsco DATE=2014-05-01_10:00:00

레이어 생성 옵션

ogr2ogr 유틸리에 -lco 옵션을 사용하면 레이어 생성 옵션을 지정할 수 있습니다:

• DATE: 시뮬레이션 시작일에 상대적인 시계열 단계의 날짜입니다. (데이터소스 생성 옵션을 참조하십시오.) 이 옵션의 값은 시작일로부터 지난 시간을 초 단위로 지정하는 부동소수점형 값입니다.

다음은 레이어 생성 옵션의 예시입니다:

-lco DATE=24000

세라핀 데이터소스의 생성 및 업데이트에 관한 메모

이 드라이버는 세라핀 데이터소스의 생성 및 쓰기를 지원하지만, 이 때 주의해야 할 점이 몇 가지 있습니다.

새 데이터소스를 생성하는 경우, 데이터소스가 어떤 레이어, 객체 또는 속성도 담고 있지 않습니다.

새 레이어를 생성하는 경우, 데이터소스에 있는 기존 (노드 또는 요소) 동일 유형의 다른 레이어와 동일한 객체 및 속성 개수를 자동적으로 상속받습니다. 객체는 다른 레이어의 대응하는 객체와 동일한 도형을 상속받습니다. 속성은 0으로 설정됩니다. 아직 데이터소스에 아무 레이어도 없다면 객체와 속성이 없는 새 레이어를 생성합니다. 어떤 경우에도 새 레이어를 생성할 때 실제로는 노드 및 요소 레이어 2개를 추가합니다.

레이어에 새 객체 및 속성을 추가하거나 제거할 수 있습니다. 그 습성은 레이어 유형에 따라 (노드인지 요소인지에 따라) 달라집니다. 다음 표는 서로 다른 사용례에서의 드라이버 습성을 설명합니다:

The behavior of the Selafin driver

작업	노드 레이어	요소 레이어
객체의 도형 변경	현재 레이어와 데이터소스에 있는 다른 모든 레이어에서 노드의 좌표를 변경합니다.	현재 레이어와 데이터소스에 있는 다른 모든 레이어에서 요소의 모든 꼭짓점의 좌표를 변경합니다. 꼭짓점 개수를 변경할 수는 없습니다. 꼭짓점 순서가 중요합니다.
객체의 속성 변경	현재 레이어에 있는 노드의 속성만 변경합니다.	영향을 미치지 않습니다.
새 객체 추가	현재 레이어와 다른 모든 레이어에서 객체 목록의 마지막에 새 노드를 추가합니다. 새 노드의 속성을 새 객체의 값으로 설정합니다.	새 객체의 꼭짓점 개수가 현재 레이어에 있는 다른 객체들과 동일한 경우에만 이 작업을 할 수 있습니다. 꼭짓점이 현재 노드 집합에 존재하는지 확인합니다. 꼭짓점과 노드 사이의 거리가 노드 레이어에 있는 두 노드 사이의 평균 거리의 약 1/1,000인 최대 오차 허용 거리 미만인 경우 해당 꼭짓점과 노드가 동등하다고 간주합니다. 대응하는 노드를 찾았다면, 그 노드를 요소의 꼭짓점으로 사용합니다. 대응하는 노드를 찾지 못 한 경우, 모든 관련 레이어에 새 노드를 생성합니다.
객체 삭제	현재 레이어와 데이터소스에 있는 다른 모든 레이어에서 노드를 제거합니다. 데이터소스에 있는 모든 요소 레이어로부터 이 노드를 꼭짓점으로 사용하는 모든 요소도 제거합니다.	현재 레이어와 데이터소스에 있는 다른 모든 레이어에서 요소를 제거합니다.

일반적으로, 이런 구현된 작업 습성이 딱 사용자가 예상할 습성입니다. 예를 들어 ogr2ogr 유틸리티를 사용해서 노드와 요소 사이의 내부 링크를 변경하지 않고 파일을 재투영할 수 있습니다.

세라핀 데이터소스를 업데이트하는 작업은 아주 느리다는 사실을 기억해야 할 것입니다. 이 포맷에서 객체의 빠른 삽입 또는 삭제를 할 수 없고 각 작업마다 반드시 파일을 재생성해야만 하기 때문입니다.

VSI 가상 파일 시스템 API 지원

이 드라이버는 VSI 가상 파일 시스템 API가 관리하는 파일의 읽기 및 쓰기를 지원합니다. VSI 가상 파일 시스템 API가 관리하는 파일에는 “정규” 파일은 물론 /vsizip/ (읽기-쓰기) , /vsigzip/ (읽기 전용) , /vsicurl/ (읽기 전용) 도메인에 있는 파일도 포함됩니다.

기타 메모

세라핀 표준에는 공간 좌표계 사양이 없습니다. 공간 좌표계 구현은 드라이버에 추가된 사양으로 파일에서 사용되지 않는 데이터 필드에 공간 좌표계를 저장합니다. 향후 세라핀 표준을 이용하는 소프트웨어가 이 필드를 이용하게 되어 공간 좌표계 사양을 망가트릴 수도 있습니다. 이 경우, 드라이버가 그래도 세라핀 파일을 읽어올 수는 있지만 세라핀 파일을 작성하는 경우 다른 목적을 가지고 있을 수도 있는 값을 덮어쓰게 될 것입니다.