3.0 시작하기

노트

이 페이지는 VIZWide3D 3.0 기준입니다. 2.1 은 2.1 시작하기, 버전과 관계없는 절차와 버전별 차이는 Getting Started를 보세요. 코드는 배포 패키지의 index.html 을 기준으로 합니다.

1. 패키지 배치

배포 패키지의 내용을 웹 루트에 그대로 올립니다. index.html 옆에 VIZCore3D/ 와 model/ 이 놓입니다.

(웹 루트)/
├── index.html            ← 샘플 페이지 (아래 코드)
├── favicon.ico
├── web.config            ← IIS 용 MIME 설정 (.vizw, .wasm 등)
├── VIZCore3D/
│   ├── VIZCore3D.js      ← 뷰어 모듈 (단일 번들, import 대상)
│   └── resource/         ← wasm, 폰트, 아바타, 텍스처 — 이름을 바꾸지 마세요
└── model/
    └── toycar/vizw/      ← 샘플 모델

자기 페이지를 만들 때는 index.html 자리에서 ./VIZCore3D/VIZCore3D.js 를 import 합니다. CSS 는 번들에 포함되어 있어 따로 link 하지 않습니다.
폴더 이름 VIZCore3D 는 바꾸지 않는 것을 권장합니다. resource/ 안의 파일 이름은 바꾸면 안 됩니다.
IIS 에 올리는 방법은 How to Install IIS를 보세요.

2. 뷰어 페이지 작성

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>VIZWide3D :: SOFTHILLS</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no" />
    <style>
        html, body { height: 100%; margin: 0; overflow: hidden; user-select: none; }
        .VIZWeb_Main { position: relative; width: 100%; height: 100%; }
    </style>
    <script type="module">
        import VIZCore3DModule from "./VIZCore3D/VIZCore3D.js";

        // 1. 뷰어 컨테이너 — VIZWeb_Main(루트) 안에 VIZCore3D(뷰) 를 둔다
        const main = document.createElement('div');
        main.className = "VIZWeb_Main";
        const view = document.createElement('div');
        view.id = "view";
        view.className = "VIZCore3D";
        main.appendChild(view);
        document.body.appendChild(main);

        // 2. 인스턴스 생성 (VIZCore3D = VIZWide3D 의 뷰어 모듈)
        const vizcore = new VIZCore3DModule(view);

        // 3. 엔진이 뜨기 전 설정 — 라이선스 서버 주소(기본 포트 8901)
        const onConfiguration = () => {
            const license = vizcore.Config.GetLicenseInfo();
            license.url = "http://127.0.0.1:8901";
            vizcore.Config.SetLicenseInfo(license);
        };

        // 4. 초기화 완료 — 이 시점부터 API 사용 가능
        const onInitialize = () => {
            // e.kind 가 Structure 면 구조(트리) 준비, Meshblock 이면 형상 준비 (vizcore.Enum.ImportFiledataKind)
            const onload = (e) => console.log("onload::", e);
            // e.reason: header-download | child-download | memory | import, e.status: HTTP 상태(네트워크 오류는 0)
            const onerror = (e) => console.log("onerror::", e);

            vizcore.Model.OpenFile("example", "./model/toycar/vizw/toycar_wh.vizw", onload, onerror);
        };

        // 5. 초기화 실패 — e.phase: "webgl" | "wasm-fetch" | "wasm-instantiate" | "subsystem-init"
        const onInitFailed = (e) => console.error("init failed::", e);

        vizcore.Init({
            event: {
                onConfiguration: onConfiguration,
                onInit: onInitialize,
                onInitFailed: onInitFailed,
            }
        });
    </script>
</head>
<body></body>
</html>

3. 초기화

vizcore.Init(option) 은 엔진(WebGL/wasm)을 띄우고 UI 를 만듭니다. 초기화를 위해서는 아래 콜백 함수들이 필요합니다. onConfiguration 은 엔진이 뜨기 전에, onInit 은 초기화가 끝난 뒤에 불립니다.

콜백	시점	하는 일
`event.onConfiguration`	엔진이 뜨기 전	라이선스 서버 주소, 모듈 경로, 다운로드 옵션 변경 (`vizcore.Config.*`)
`event.onInit`	초기화 완료 후	모델 열기, 이벤트 등록 등 API 호출 시작점
`event.onInitFailed`	초기화 실패 시	실패 단계와 원인을 받음. 이때 `onInit` 은 불리지 않음

let option = {
    event: {
        // 초기 환경 설정 콜백 (엔진이 뜨기 전)
        onConfiguration: onConfiguration,

        // 초기화 완료 후 호출
        onInit: onInitialize,

        // 초기화 실패 시 호출
        onInitFailed: onInitFailed,
    }
};

vizcore.Init(option);

Init 은 브라우저가 WebAssembly 를 지원하면 true, 지원하지 않으면 false 를 돌려주고 초기화하지 않습니다.
2.1 에 있던 onBefore 콜백은 3.0 에 없습니다.

onConfiguration

초기 환경 설정을 변경하려면 onConfiguration 함수에서 설정할 수 있습니다. 설정 파일을 편집하지 않고 vizcore.Config.* API 로 바꿉니다.

let onConfiguration = () => {
    // 라이선스 서버 주소 설정 (4절)
    const license = vizcore.Config.GetLicenseInfo();
    license.url = "http://127.0.0.1:8901";
    vizcore.Config.SetLicenseInfo(license);
};

onInit

VIZCore3D 실행 시점에 필요한 작업은 onInit 함수에서 처리할 수 있습니다.

let onInitialize = () => {
    // 로딩 진행 이벤트
    vizcore.Model.OnLoadingProgress(function (e) {
        // 다운로드 진행 상태
    });

    // 모델 선택 이벤트
    vizcore.Object3D.OnObject3DSelected((e) => console.log("selected::", e));

    // 모델 열기 (5절)
    vizcore.Model.OpenFile("example", "./model/toycar/vizw/toycar_wh.vizw", onload, onerror);
};

onInitFailed

초기화가 실패하면 onInitFailed 가 불리고 onInit 은 불리지 않습니다. 인자는 { phase, error, message } 입니다.

let onInitFailed = (e) => {
    // e.phase: "webgl" | "wasm-fetch" | "wasm-instantiate" | "subsystem-init"
    console.error("init failed", e.phase, e.message);
};

사용된 API

4. 라이선스 서버 연결

노트

라이선스 서버 기본 포트는 8901 입니다.

주소는 설정 파일을 편집하지 않고 onConfiguration 에서 API 로 설정합니다.

let onConfiguration = () => {
    const license = vizcore.Config.GetLicenseInfo();   // { url, routingFilters }
    license.url = "http://127.0.0.1:8901";
    vizcore.Config.SetLicenseInfo(license);
};

라이선스 검사는 onInit 뒤에 실행됩니다. 연결되지 않으면 뷰 화면에 License error! 메시지가 표시되고 모델이 보이지 않습니다. onInitFailed 는 호출되지 않습니다(이 콜백은 WebGL·wasm 초기화 실패 전용입니다).
오류 메시지별 원인은 License Error를 보세요.
상세: Config.SetLicenseInfo

5. 모델 열기와 로딩 완료 판단

// 로딩 완료 시점 확인 — e.kind 로 구분
let onload = (e) => {
    if (e.kind === vizcore.Enum.ImportFiledataKind.Structure) {
        // 구조정보 로딩 완료 — 노드·속성 API 는 이때부터
    }
    if (e.kind === vizcore.Enum.ImportFiledataKind.Meshblock) {
        // 형상 로딩 완료 — 형상이 필요한 API 는 이때부터
    }
};

// 로딩 실패
let onerror = (e) => {
    // e.reason: "header-download" | "child-download" | "memory" | "import", e.status: HTTP 상태(네트워크 오류는 0)
    console.log("onerror::", e);
};

// 모델 열기 — 열려 있던 파일은 모두 닫고 새로 연다
vizcore.Model.OpenFile("example", "./model/toycar/vizw/toycar_wh.vizw", onload, onerror);

여러 파일을 함께 열려면 Model.AddFile 을 씁니다. onload · onerror 는 OpenFile 과 같습니다.
진행률은 OnLoadingProgress 로 받습니다.
상세: Model.OpenFile · Model.AddFile

6. 프레임워크 사용 시

프로젝트 자체는 프레임워크 프로젝트 준비를 보고 만듭니다. 여기서는 배포 패키지를 넣는 위치와 초기화 코드만 다룹니다.

배포 패키지의 VIZCore3D/ 폴더를 프로젝트의 정적 폴더(public/) 에 그대로 복사합니다. 빌드 도구(Vite, webpack)가 번들을 다시 묶지 않도록 src/ 가 아니라 public/ 에 두고, 실행 시점에 URL 로 불러옵니다.

(프로젝트)/
├── public/
│   └── VIZCore3D/
│       ├── VIZCore3D.js      ← 배포 패키지 그대로
│       └── resource/         ← 이름을 바꾸지 마세요 (VIZCore3D.js 가 자기 위치 기준으로 찾습니다)
└── src/
    └── (아래 코드)

컴포넌트가 화면에 붙은 뒤(Vue onMounted, React useEffect) 뷰어를 만들고, 빠질 때(Vue onBeforeUnmount, React cleanup) vizcore.Release() 로 정리합니다.
모듈은 public/VIZCore3D/ 에 두고 절대 URL 로 import() 합니다. 예제의 @vite-ignore · webpackIgnore 주석은 지우지 마세요.
뷰어를 넣을 영역에 높이만 주면 됩니다. .VIZWeb_Main 에 position: absolute 를 주지 마세요. (임베딩 가이드)
라이선스 서버 주소는 onConfiguration 에서 설정합니다. (4. 라이선스 서버 연결)

Vue
React

Viewer.vue
<script setup>
import { onMounted, onBeforeUnmount, ref } from 'vue';

const view = ref(null);
let vizcore = null;
let cancelled = false;   // 언마운트 뒤 늦게 끝난 import 가 인스턴스를 만들지 않게

onMounted(async () => {
  const moduleUrl = new URL('/VIZCore3D/VIZCore3D.js', location.origin).href;   // public 폴더 기준, 절대 URL
  const modelUrl = 'https://example.com/models/sample_wh.vizw';   // 서버가 내려주는 VIZW URL
  const { default: VIZCore3DModule } =
    await import(/* @vite-ignore */ /* webpackIgnore: true */ moduleUrl);
  if (cancelled) return;

  vizcore = new VIZCore3DModule(view.value);

  vizcore.Init({
    event: {
      onConfiguration: () => {
        const license = vizcore.Config.GetLicenseInfo();
        license.url = 'http://127.0.0.1:8901';
        vizcore.Config.SetLicenseInfo(license);
      },
      onInit: () => {
        vizcore.Model.OpenFile('example', modelUrl,
          (e) => console.log('onload::', e),
          (e) => console.log('onerror::', e));
      },
      onInitFailed: (e) => console.error('init failed', e),
    },
  });
});

// 언마운트 — 엔진·UI·리스너를 걷어낸다 (DOM 이 아직 있는 onBeforeUnmount 에서)
onBeforeUnmount(() => {
  cancelled = true;
  if (vizcore) vizcore.Release();
});
</script>

<template>
  <div class="VIZWeb_Main">
    <div id="view" class="VIZCore3D" ref="view"></div>
  </div>
</template>

<style>
html, body, #app { height: 100%; margin: 0; }
.VIZWeb_Main { position: relative; width: 100%; height: 100%; }
</style>

import { useEffect, useRef } from 'react';
import './viewer.css';

export default function Viewer() {
  const viewRef = useRef(null);

  useEffect(() => {
    let vizcore = null;
    let cancelled = false;   // 언마운트 뒤 늦게 끝난 import 가 인스턴스를 만들지 않게

    (async () => {
      const moduleUrl = new URL('/VIZCore3D/VIZCore3D.js', location.origin).href;   // public 폴더 기준, 절대 URL
      const modelUrl = 'https://example.com/models/sample_wh.vizw';   // 서버가 내려주는 VIZW URL
      const { default: VIZCore3DModule } =
        await import(/* @vite-ignore */ /* webpackIgnore: true */ moduleUrl);
      if (cancelled) return;

      vizcore = new VIZCore3DModule(viewRef.current);

      vizcore.Init({
        event: {
          onConfiguration: () => {
            const license = vizcore.Config.GetLicenseInfo();
            license.url = 'http://127.0.0.1:8901';
            vizcore.Config.SetLicenseInfo(license);
          },
          onInit: () => {
            vizcore.Model.OpenFile('example', modelUrl,
              (e) => console.log('onload::', e),
              (e) => console.log('onerror::', e));
          },
          onInitFailed: (e) => console.error('init failed', e),
        },
      });
    })();

    // 언마운트 — 엔진·UI·리스너를 걷어낸다. StrictMode 가 개발 모드에서 넣는 mount→unmount→mount 의 중간 정리도 여기로 온다.
    return () => {
      cancelled = true;
      if (vizcore) vizcore.Release();
    };
  }, []);

  return (
    <div className="VIZWeb_Main">
      <div id="view" className="VIZCore3D" ref={viewRef}></div>
    </div>
  );
}

src/viewer.css
html, body, #root { height: 100%; margin: 0; }
.VIZWeb_Main { position: relative; width: 100%; height: 100%; }

7. 로컬 실행

정보

VSCode 기준으로 설명하며 VSCode 사용을 권장합니다.

VSCode Extensions 에서 Live Server 설치
index.html 우클릭 → Open with Live Server

Vue·React 프로젝트는 프레임워크 프로젝트 준비의 실행 명령(npm run dev)을 씁니다.
라이선스 서버가 떠 있지 않으면 화면에 License error! 창이 뜨고 모델이 보이지 않습니다. FAQ를 보세요.

다음 단계

API 3.0 — 모델, 뷰, 리뷰(노트·측정·마크업), 단면, 비교 등 API 레퍼런스

1. 패키지 배치​

2. 뷰어 페이지 작성​

3. 초기화​

onConfiguration​

onInit​

onInitFailed​

사용된 API​

4. 라이선스 서버 연결​

5. 모델 열기와 로딩 완료 판단​

6. 프레임워크 사용 시​

7. 로컬 실행​

다음 단계​