Main Content

이 페이지의 최신 내용은 아직 번역되지 않았습니다. 최신 내용은 영문으로 볼 수 있습니다.

HDF5 파일로 내보내기

개요

NCSA(National Center for Supercomputing Application)에서 개발한 HDF5(Hierarchical Data Format Version 5)는 과학 데이터를 파일에 저장하기 위한 범용 표준으로 시스템에 상관없이 사용할 수 있습니다. HDF5는 용이한 데이터의 공유를 위해 표준화된 데이터 저장 방식을 요하는 여러 공학 및 과학 분야에서 사용됩니다. HDF5 파일 형식에 대한 자세한 내용은 HDF 웹 사이트(https://www.hdfgroup.org)에서 HDF5 문서를 참조하십시오.

MATLAB®은 데이터를 HDF5 파일로 내보낼 수 있는 두 가지 방법을 제공합니다.

  • 하이 레벨 함수는 숫자형 데이터셋을 사용할 때 데이터를 내보내는 과정을 간소화합니다.

  • 로우 레벨 함수는 HDF5 C 라이브러리의 루틴에 대한 MATLAB 인터페이스를 제공합니다.

참고

별도의 호환되지 않는 형식을 가지고 있는 HDF4 파일로 내보내기에 대한 자세한 내용은 Export to HDF4 Files 항목을 참조하십시오.

MATLAB 하이 레벨 HDF5 함수를 사용하여 데이터 내보내기

MATLAB 작업 공간의 데이터나 메타데이터를 HDF5 파일에 쓸 수 있는 가장 쉬운 방법은 다음과 같은 MATLAB 하이 레벨 함수를 사용하는 것입니다.

참고

하이 레벨 함수는 숫자형 데이터와만 사용할 수 있습니다. 숫자형이 아닌 데이터를 쓰려면 로우 레벨 인터페이스를 사용해야 합니다.

  • h5create — HDF5 데이터셋 생성

  • h5write — HDF5 데이터셋에 데이터 쓰기

  • h5writeatt — HDF5 특성에 데이터 쓰기

위 함수를 사용하는 방법에 대한 자세한 내용은 예제가 포함되어 있는 해당 함수 도움말 페이지를 참조하십시오. 다음 섹션에서는 몇 가지 일반적인 사용 시나리오를 보여줍니다.

HDF5 데이터셋에 숫자형 배열 쓰기

이 예제에서는 배열을 만든 다음 이 배열을 HDF5 파일에 씁니다.

  1. 작업 공간에 MATLAB 변수를 생성합니다. 이 예제에서는 uint8형 값으로 구성된 5x5 배열을 만듭니다.

    testdata = uint8(magic(5))
  2. h5create를 사용하여 HDF5 파일과 데이터셋을 생성합니다.

    h5create('my_example_file.h5', '/dataset1', size(testdata))
  3. 데이터를 HDF5 파일에 씁니다.

    h5write('my_example_file.h5', '/dataset1', testdata)

MATLAB 로우 레벨 HDF5 함수를 사용하여 데이터 내보내기

MATLAB은 HDF5 라이브러리의 함수에 대응하는 로우 레벨 함수를 사용하여 HDF5 라이브러리의 수십 가지 함수에 직접 액세스할 수 있도록 합니다. 이 방법을 통해 사용자는 MATLAB에서 복소수 데이터형 읽기와 쓰기, HDF5 서브셋 설정 기능 사용 같은 HDF5 라이브러리의 기능에 액세스할 수 있습니다.

HDF5 라이브러리에서는 라이브러리 함수를 인터페이스라고 하는 모음으로 구성합니다. 예를 들어, 열기 및 닫기 같은 파일 작업과 관련된 모든 루틴은 H5F 인터페이스에 있습니다. 여기서 F는 파일을 나타냅니다. MATLAB은 로우 레벨 HDF5 함수를 각 HDF5 인터페이스에 대응하는 클래스로 구성합니다. 예를 들어, HDF5 파일 인터페이스(H5F)에 해당하는 MATLAB 함수는 @H5F 클래스 폴더에 있습니다.

다음 섹션에서는 MATLAB HDF5 로우 레벨 함수를 사용하는 방법을 자세히 설명합니다.

참고

이 섹션에서는 HDF5 라이브러리의 모든 기능을 기술하거나 기본적인 HDF5 프로그래밍 개념을 설명하지 않습니다. MATLAB HDF5 로우 레벨 함수를 효과적으로 사용하려면 https://www.hdfgroup.org의 공식적인 HDF5 문서를 참조하십시오.

HDF5 함수 구문과 MATLAB 함수 구문 간 매핑

대부분의 경우, MATLAB 로우 레벨 HDF5 함수의 구문은 대응하는 HDF5 라이브러리 함수의 구문과 일치합니다. 예를 들어, 다음은 HDF5 라이브러리에 있는 H5Fopen 함수의 함수 시그니처입니다. HDF5 함수 시그니처에서 hid_therr_t는 객체 식별자나 오류 상태 값을 나타내는 숫자형 값을 반환하는 HDF5 유형입니다.

hid_t H5Fopen(const char *name, unsigned flags, hid_t access_id) /* C syntax */

MATLAB에서, HDF5 인터페이스의 각 함수는 MATLAB 클래스의 메서드입니다. 아래에는 대응하는 MATLAB 함수의 시그니처가 나와 있습니다. 먼저, 이 함수는 클래스의 메서드이므로 H5F.open과 같이 점 표기법을 사용하여 MATLAB 함수를 호출해야 한다는 점에 유의하십시오. 이 MATLAB 함수는 HDF5 함수처럼 3개의 인수, 즉 이름을 포함하는 문자형 벡터, flags 인수에 대해 HDF5에서 정의한 상수, 그리고 HDF5 속성 목록 ID를 받습니다. 속성 목록을 사용하여 여러 다양한 HDF5 객체의 특성을 지정합니다. 여기에서 이 속성 목록은 파일 액세스 속성 목록입니다. 특정 함수에 사용할 수 있는 상수를 보려면 HDF5 문서를 참조하십시오. MATLAB에서 상수는 문자형 벡터로 전달됩니다.

file_id = H5F.open(name, flags, plist_id)

반면에, MATLAB 함수 시그니처가 대응하는 HDF5 라이브러리 함수와 다른 함수들도 있습니다. 다음은 MATLAB 로우 레벨 HDF5 함수를 사용할 때 유의해야 할 몇 가지 일반적인 차이점입니다.

  • HDF5 출력 파라미터가 MATLAB 반환 값이 됨 — 일부 HDF5 라이브러리 함수는 함수 파라미터를 사용하여 데이터를 반환합니다. MATLAB 함수는 여러 개의 값을 반환할 수 있으므로, 이러한 출력 파라미터는 반환 값이 됩니다. 이에 대한 예로, HDF5의 H5Dread 함수는 데이터를 buf 파라미터에 반환합니다.

    herr_t H5Dread(hid_t dataset_id,
    					  hid_t mem_type_id,
    					  hid_t mem_space_id, 
    					  hid_t file_space_id, 
    					  hid_t xfer_plist_id, 
    					  void * buf )   /* C syntax */

    대응하는 MATLAB 함수는 출력 파라미터 buf를 반환 값으로 변경합니다. 또한 MATLAB 함수에서, 0이 아니거나 음수 값인 herr_t 반환 값은 MATLAB 오류가 됩니다. 오류를 처리하려면 MATLAB try-catch 문을 사용하십시오.

    buf = H5D.read(dataset_id,
    					   mem_type_id,
     						mem_space_id,
     					   file_space_id,
     						plist_id)

  • 문자열 길이 파라미터가 필요하지 않음 — 일부 HDF5 라이브러리 함수에서 문자열 파라미터의 길이를 지정하기 위해 사용하는 길이 파라미터는 대응하는 MATLAB 함수에서 필요하지 않습니다. 예를 들어, HDF5 라이브러리의 H5Aget_name 함수는 버퍼를 출력 파라미터로 포함하고, 버퍼 크기를 입력 파라미터로 포함합니다.

    ssize_t H5Aget_name(hid_t attr_id,
                        size_t buf_size,
                        char *buf ) /* C syntax */

    대응하는 MATLAB 함수는 출력 파라미터 buf를 반환 값으로 변경하고 buf_size 파라미터는 생략합니다.

    buf = H5A.get_name(attr_id)

  • 빈 배열을 사용하여 NULL 지정 — HDF5 라이브러리 함수가 값 NULL을 허용할 경우 대응하는 MATLAB 함수는 빈 배열([])을 사용합니다. 예를 들어, HDF5 라이브러리의 H5Dfill 함수는 지정된 채우기 값 대신 값 NULL을 허용합니다.

    herr_t H5Dfill(const void *fill,
                   hid_t fill_type_id, void *buf, 
                   hid_t buf_type_id, 
                   hid_t space_id ) /* C syntax */

    대응하는 MATLAB 함수를 사용할 때 NULL 대신 빈 배열([])을 지정할 수 있습니다.

  • 셀형 배열을 사용하여 여러 개의 상수 지정 — HDF5 라이브러리의 일부 함수에서는 상수로 구성된 배열을 지정해야 합니다. 예를 들어, H5Screate_simple 함수에서 데이터스페이스의 차원이 무제한일 수 있음을 지정하려면 maxdims의 차원에 상수 H5S_UNLIMITED를 사용합니다. MATLAB에서는 상수를 문자형 벡터로 전달하기 때문에, 같은 결과를 얻으려면 문자형 벡터로 구성된 셀형 배열을 사용해야 합니다. 다음 코드 조각은 이 데이터스페이스의 각 차원에 이 상수를 지정하기 위해 문자형 벡터로 구성된 셀형 배열을 사용한 예를 보여줍니다.

    ds_id = H5S.create_simple(2,[3 4],{'H5S_UNLIMITED' 'H5S_UNLIMITED'}); 
    

HDF5 데이터형과 MATLAB 데이터형 간 매핑

HDF5 로우 레벨 함수는 HDF5 파일에서 데이터를 읽어오거나 HDF5 파일에 데이터를 쓸 때, 자동으로 HDF5 데이터형을 MATLAB 데이터형에 매핑합니다.

숫자(정수와 부동소수점)와 문자(ASCII)에 주로 사용되는 이진 형식 같은 원자형 데이터형의 경우, MATLAB이 유사한 데이터형을 지원하기 때문에 일반적으로 매핑이 간단합니다. 이러한 매핑 목록은 HDF5 원자형 데이터형과 MATLAB 데이터형 간 매핑 표를 참조하십시오.

HDF5 원자형 데이터형과 MATLAB 데이터형 간 매핑

HDF5 원자형 데이터형MATLAB 데이터형
비트 필드압축 8비트 정수로 구성된 배열
부동소수점MATLAB single형과 double형(64비트 이하를 차지하는 경우)
정수형(부호 있는 정수와 부호 없는 정수)상응하는 MATLAB 정수형(부호 있는 정수와 부호 없는 정수)
불투명uint8 값으로 구성된 배열
참조uint8 값으로 구성된 배열
문자열MATLAB 문자형 배열

하나 이상의 원자형 데이터형이 모여 이루어진 구조체, 다차원 배열 및 가변 길이 데이터형(1차원 배열) 같은 복합 데이터형의 경우, HDF5 데이터형에 대한 매핑이 때때로 모호할 수 있습니다. HDF5에서, 각 요소에 단일 uint8형 값이 포함된 5x5 데이터 세트는 uint8형 값의 5x5 배열이 포함된 1x1 데이터 세트와 완전히 다릅니다. 첫 번째 경우의 데이터 세트는 단일 값의 25개 관측값을 포함합니다. 두 번째 경우의 데이터 세트는 25개 값으로 구성된 단일 관측값을 포함합니다. MATLAB에서 이러한 데이터 세트는 모두 5x5 행렬로 표현됩니다.

데이터가 복합 데이터 세트인 경우, 의도한 매핑 결과를 얻기 위해 HDF5 데이터형을 직접 생성해야 할 수 있습니다. 디폴트 매핑 목록은 HDF5 복합 데이터형과 MATLAB 데이터형 간 매핑 표를 참조하십시오. H5Dwrite 함수를 사용하여 파일에 데이터를 쓸 때 데이터형을 지정할 수 있습니다. 자세한 내용은 HDF5 데이터형 인터페이스 문서를 참조하십시오.

HDF5 복합 데이터형과 MATLAB 데이터형 간 매핑

HDF5 복합 데이터형MATLAB 데이터형
배열배열에 포함된 데이터형의 차원을 확장합니다. 예를 들어, HDF5에서 정수로 구성된 배열은 MATLAB에서 정수로 구성된 2차원 배열로 매핑됩니다.
복합형MATLAB 구조체. 참고: MATLAB에서 HDF5 데이터를 나타내는 모든 구조체는 스칼라입니다.
열거형각각 연관된 이름을 갖는 정수로 구성된 배열
가변 길이MATLAB 1차원 셀형 배열

데이터 세트 차원 보고

MATLAB 로우 레벨 HDF5 함수는 MATLAB 하이 레벨 함수와 다른 방식으로 데이터 세트 차원과 데이터 세트의 형태를 보고합니다. MATLAB 하이 레벨 함수는 사용 편의성을 위해 MATLAB의 열 우선(Column-major) 인덱싱과 일관되게 데이터 세트 차원을 보고합니다. MATLAB 로우 레벨 함수는 HDF5 라이브러리와의 일관성을 유지하면서 중첩 데이터 세트 및 복잡한 데이터형도 지원할 수 있도록 C의 행 우선(Row-major) 방향을 사용하여 배열 차원을 보고합니다.

MATLAB 로우 레벨 함수를 사용하여 HDF5 데이터 세트에 데이터 쓰기

이 예제에서는 MATLAB® HDF5 로우 레벨 함수를 사용하여 데이터 세트를 HDF5 파일에 쓴 다음 이 파일에서 데이터 세트를 읽어오는 방법을 보여줍니다.

HDF5 파일에 쓸 2x3 배열 데이터를 생성합니다.

testdata = [1 3 5; 2 4 6];

시스템 임시 폴더에 새 HDF5 파일 my_file.h5를 생성합니다. MATLAB H5F.create 함수를 사용하여 파일을 생성하십시오. 이 MATLAB 함수는 HDF5 함수 H5Fcreate에 대응합니다. 인수로는 파일에 할당할 이름, 파일에 대한 액세스 유형(여기서는 'H5F_ACC_TRUNC'), 그리고 파일 생성 속성 목록과 파일 액세스 속성 목록으로 지정된 추가적인 특성을 선택적으로 지정합니다. 여기서는 이러한 속성 목록에 디폴트 값('H5P_DEFAULT')을 사용합니다. C 상수는 MATLAB 함수에 문자형 벡터로 전달하십시오.

filename = fullfile(tempdir,'my_file.h5');
fileID = H5F.create(filename,'H5F_ACC_TRUNC','H5P_DEFAULT','H5P_DEFAULT');

H5F.create는 HDF5 파일에 해당하는 파일 ID를 반환합니다.

MATLAB 변수를 포함할 데이터 세트를 파일에 생성합니다. HDF5 프로그래밍 모델에서는 데이터 세트의 데이터형과 차원(데이터스페이스)을 별개의 엔터티로 정의해야 합니다. 먼저, H5T.copy 함수를 사용하여 데이터 세트에 사용되는 데이터형을 지정하십시오(여기서는 double). 이 MATLAB 함수는 HDF5 함수 H5Tcopy에 대응합니다.

datatypeID = H5T.copy('H5T_NATIVE_DOUBLE');

H5T.copy는 데이터형 식별자를 반환합니다.

HDF5 함수 H5Screate_simple에 대응하는 H5S.create_simple을 사용하여 데이터스페이스를 생성합니다. 첫 번째 입력값 2는 데이터스페이스의 랭크입니다. 두 번째 입력값은 데이터셋의 각 차원 크기를 지정하는 배열입니다. HDF5는 데이터를 행 우선 순서로 저장하고 MATLAB 배열은 열 우선 순서로 구성되기 때문에, 데이터의 레이아웃을 유지하려면 H5Screate_simple을 사용하기 전에 차원 범위의 순서를 반대로 바꿔야 합니다. 이를 위해 fliplr을 사용할 수 있습니다.

dims = size(testdata);
dataspaceID = H5S.create_simple(2,fliplr(dims),[]);

H5S.create_simple은 데이터스페이스 식별자 dataspaceID를 반환합니다. 행 우선 순서를 사용하는 다른 소프트웨어 프로그램(예: The HDF Group의 H5DUMP)은 데이터셋의 크기를 2x3 대신 3x2로 보고할 수 있습니다.

HDF5 함수 H5Dcreate에 대응하는 H5D.create를 사용하여 데이터 세트를 생성합니다. 파일 ID, 데이터 세트에 할당할 이름, 데이터형 식별자, 데이터스페이스 식별자 및 데이터 세트 생성 속성 목록 삭별자를 인수로 지정하십시오. 'H5P_DEFAULT'는 디폴트 속성 목록 설정을 지정합니다.

dsetname = 'my_dataset';  
datasetID = H5D.create(fileID,dsetname,datatypeID,dataspaceID,'H5P_DEFAULT');

H5D.create는 데이터 세트 식별자 datasetID를 반환합니다.

HDF5 함수 H5Dwrite에 대응하는 H5D.write를 사용하여 데이터 세트에 데이터를 씁니다. 입력 인수는 데이터 세트 식별자, 메모리 데이터형 식별자, 메모리 공간 식별자, 데이터스페이스 식별자, 전송 속성 목록 식별자 및 데이터 세트에 쓰려는 MATLAB 변수의 이름입니다. 상수 'H5ML_DEFAULT'는 HDF5 데이터형에 자동 매핑되도록 지정합니다. 상수 'H5S_ALL'H5D.write가 모든 데이터를 파일에 쓰도록 지시합니다.

H5D.write(datasetID,'H5ML_DEFAULT','H5S_ALL','H5S_ALL',...
    'H5P_DEFAULT',testdata);

데이터 세트, 데이터스페이스, 데이터형 및 파일 객체를 닫습니다. MATLAB 함수 내에 사용된 경우, 이러한 식별자는 범위를 벗어나면 자동으로 닫힙니다.

H5D.close(datasetID);
H5S.close(dataspaceID);
H5T.close(datatypeID);
H5F.close(fileID);

방금 쓴 데이터 세트를 읽어오기 위해 HDF5 파일을 엽니다. H5F.open을 사용하여 파일을 읽기 전용 액세스로 여십시오. 이 MATLAB 함수는 HDF5 함수 H5Fopen에 대응합니다.

fileID = H5F.open(filename,'H5F_ACC_RDONLY','H5P_DEFAULT');

HDF5 함수 H5Dopen에 대응하는 H5D.open을 사용하여, 읽어올 데이터 세트를 엽니다. 이 예제의 앞부분에서 정의한 파일 ID와 데이터 세트의 이름을 인수로 지정하십시오.

datasetID = H5D.open(fileID,dsetname);

HDF5 함수 H5Dread에 대응하는 H5D.read를 사용하여 데이터를 MATLAB 작업 공간으로 읽어옵니다. 입력 인수는 데이터 세트 식별자, 메모리 데이터형 식별자, 메모리 공간 식별자, 데이터스페이스 식별자 및 전송 속성 목록 식별자입니다.

returned_data = H5D.read(datasetID,'H5ML_DEFAULT',...
    'H5S_ALL','H5S_ALL','H5P_DEFAULT');

원래 MATLAB 변수 testdata를 방금 생성한 변수 returned_data와 비교해 보겠습니다.

isequal(testdata,returned_data)
ans = logical
   1

두 변수가 동일합니다.

대규모 데이터 세트 쓰기

대규모 데이터 세트를 쓰려면 HDF5 라이브러리의 청크 설정 기능을 사용해야 합니다. 이를 위해, 속성 목록을 생성하고 H5P.set_chunk 함수를 사용하여 청크 크기를 속성 목록에 설정합니다. 데이터 세트의 차원이 [2^16 2^16]이고 청크 크기가 1024x1024라고 가정하겠습니다. 그런 다음, H5P_DEFAULT 값을 사용하는 대신 속성 목록을 데이터 세트 생성 함수 H5D.create에 마지막 인수로 전달합니다.

dims = [2^16 2^16];
plistID = H5P.create('H5P_DATASET_CREATE'); % create property list

chunk_size = min([1024 1024], dims); % define chunk size 
H5P.set_chunk(plistID, fliplr(chunk_size)); % set chunk size in property list

datasetID = H5D.create(fileID, dsetname, datatypeID, dataspaceID, plistID); 

데이터의 올바른 레이아웃 유지하기

데이터스페이스를 처리하는 다음과 같은 함수를 사용할 경우, 데이터의 올바른 레이아웃을 유지하기 위해 차원 범위를 뒤집어야 합니다.

  • H5D.set_extent

  • H5P.get_chunk

  • H5P.set_chunk

  • H5S.create_simple

  • H5S.get_simple_extent_dims

  • H5S.select_hyperslab

  • H5T.array_create

  • H5T.get_array_dims