사용자 심볼·이미지 표시

해도 위에 응용 데이터(선박 위치·항적·랑데부 지점·이벤트 마커 등)를 표시하는 두 가지 방식.

방식 비교

API 그룹	용도	회전	스케일
UserImage	단순 PNG 마커 표시	×	×
Usersymbol	심볼 라이브러리 등록 후 재사용	○	○
Userobj	심볼 인스턴스를 맵에 레이어로 영속화	○	○

1. UserImage: 빠른 PNG 마커

가장 간단한 경우. 한 장의 PNG 를 화면의 특정 위경도에 그린다.

// 초기화 시 한 번 - 이미지 핸들 생성
int markerHandle = hencUserImageNew("assets/ship-marker.png");
if (markerHandle < 0) {
    fprintf(stderr, "marker image load failed\n");
}

// 매 프레임 - 선박 위치 변경 시
void onTick(int view, double shipLon, double shipLat) {
    hencRender(view);                                       // 해도 먼저
    hencUserImageDrawAtMapPos(view, markerHandle, shipLon, shipLat);
    hencSwapBuffer(view);
}

// 응용 종료 시
hencUserImageDelete(markerHandle);

2. Usersymbol: 회전 가능한 선박 아이콘

여러 선박을 표시하고 각각 다른 진행 방향(heading)으로 회전시키고 싶을 때.

// 1. 심볼 저장소 초기화 (응용 시작 시 한 번)
hencUsersymbolInit();

// 2. 이미지를 심볼 라이브러리에 등록 - symbolName 으로 나중에 참조
int shipSymbolId = hencUsersymbolAddNewImage(
    "SHIP_ICON",            // 이름 (응용에서 임의 지정)
    "assets/ship-icon.png", // 이미지 파일
    32, 32                  // 기준 크기 (px)
);

// 3. 맵에 심볼 인스턴스 추가 - 위경도, 회전각(degree), 스케일
hencUsersymbolAddToMap(
    view,
    shipSymbolId,
    129.42,    // longitude
    35.10,     // latitude
    45.0,      // heading (degree clockwise from north)
    1.0        // scale
);

// 4. 매 프레임 렌더링 시 자동으로 심볼이 그려진다
hencRender(view);
hencSwapBuffer(view);

// 5. 응용 종료 시 일괄 해제
hencUsersymbolClear();

3. Userobj: 항적 레이어처럼 영속화

심볼들을 “사용자 객체 레이어” 로 묶어 일괄 표시·숨김·삭제하기.

// 항적 추적 - 매 N초마다 현재 위치를 항적 객체에 추가
int trackObjId = -1;

void onPositionUpdate(int view, double lon, double lat) {
    if (trackObjId < 0) {
        // 항적 객체 신규 생성
        trackObjId = hencUserobjAdd(view, "TRACK_VESSEL_001");
    }

    // 위치 누적 (실제 함수 사양은 API 레퍼런스 참고 - 객체에 점 추가 로직)
    // hencUserobjGet 으로 현재 객체 핸들을 가져와 점·심볼 추가
}

// 응용 종료 또는 사용자가 "항적 지우기" 클릭 시
hencUserobjDel(view, trackObjId);

자주 마주치는 문제

• 이미지가 안 보임: PNG 파일이 32비트 RGBA 가 아니거나, 경로가 작업 디렉토리 기준이 아님. 절대경로로 시도.
• 회전 방향이 반대: heading 은 시계 방향(북→동→남→서) degree 이다. 항해 conventions 와 일치.
• 줌 변경 시 심볼이 너무 작아짐/커짐: hencSetSymbolScale 또는 hencSetAutoScaleToZoom 으로 자동 스케일 동작 조정.

관련 API

• 이미지: hencUserImageNew / hencUserImageDrawAtMapPos / hencUserImageDelete
• 심볼: hencUsersymbolInit / hencUsersymbolAddNewImage / hencUsersymbolAddToMap
• 객체 레이어: hencUserobjAdd / hencUserobjDel / hencUserobjGet
• 스케일 옵션: hencSetSymbolScale / hencSetAutoScaleToZoom