2.1 시작하기

노트

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

1. 패키지 배치

배포 패키지의 내용을 웹 루트에 그대로 올립니다. index.html 옆에 VIZCore3D/ 가 놓이고, 뷰어 모듈·설정 파일·엔진·CSS·샘플 모델이 모두 그 안에 있습니다.

(웹 루트)/
├── index.html                      ← 샘플 페이지 (아래 코드)
└── VIZCore3D/
    ├── VIZCore.js                  ← 뷰어 모듈 (import 대상)
    ├── Configuration.js            ← 라이선스 서버 주소 등 설정 파일
    ├── lib/shdcore/shdcore.wasm    ← 엔진 (onConfiguration 에서 경로 지정)
    ├── Resource/css/VIZCore.css    ← 페이지에서 link 필수
    └── Model/toycar/vizw/          ← 샘플 모델

자기 페이지를 만들 때는 index.html 자리에서 ./VIZCore3D/VIZCore.js 를 import 하고 VIZCore3D/Resource/css/VIZCore.css 를 link 합니다.
폴더 이름 VIZCore3D 를 바꾸면 onConfiguration 의 경로 설정도 같이 바꿔야 합니다.
IIS 에 올리는 방법은 How to Install IIS를 보세요.

2. 뷰어 페이지 작성

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta charset="utf-8" />
    <title>VIZWebCore :: SOFTHILLS</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0,user-scalable=no" />
    <script src="VIZCore3D/lib/jquery/jquery-3.2.1.js"></script>

    <link rel="stylesheet" href="VIZCore3D/Resource/css/VIZCore.css">

    <script type="module">
        import VIZ3DCore from "./VIZCore3D/VIZCore.js";
        import { VIZCore } from "./VIZCore3D/VIZCore.js";

        // 1. 뷰어 요소 — VIZWeb_Main(루트) 안의 div#view 에 VIZCore 클래스를 준다
        let view = document.getElementById("view");
        view.className = "VIZCore";

        // 2. 인스턴스 생성
        let vizcore = new VIZ3DCore(view);

        let onSelectEvent = function (event) {
            // 선택된 모델이 없음
            if (event.data.id == -1) {
                //console.log('선택된 모델이 없거나, 기존 선택상태가 해제됨.');
            }
            // 선택된 모델이 있음
            else {
                //console.log(event.data.id);
            }
        };

        // 파일 로딩 완료 시점 확인
        let onModelLoadingCompleted = function (e, loadType) {
            console.log("Loading Completed :: ", e);
            if(loadType === VIZCore.Enum.CONFIG_KEY.LOADER.COMPLETEDTIME.STRUCTURE){
                console.log("onLoad Structure :: ", e);
                // 구조정보 로딩 완료
            }
            if(loadType === VIZCore.Enum.CONFIG_KEY.LOADER.COMPLETEDTIME.MESH){
                console.log("onLoad Mesh :: ", e);
                // 모델정보 로딩 완료
            }
        };

        // 3. 엔진이 뜨기 전 설정 — VIZCore3D 경로와 WebAssembly 경로
        let onConfiguration =()=>{
            // 초기 환경설정 변경
            // VIZCore 경로 설정
            vizcore.Configuration.Default.Path = "./VIZCore3D/";
            // WebAssembly 경로 설정
            vizcore.Configuration.Default.WebAssembly.Path = "./VIZCore3D/lib/shdcore/shdcore.wasm";
        };

        let onBefore =()=>{
        };

        // 4. 초기화 완료 — 이 시점부터 API 사용 가능
        let onInit = ()=>{

            // ContextMenu 사용
            let context = new vizcore.ContextMenu(view, vizcore, VIZCore);

            vizcore.Model.OnStreamProgressChangedEvent(function(e){
                //console.log("Total : ",  e.data.total, "Current : ", e.data.current, "Percentage : ", e.data.percentage);
            });

            // Add Event Handler : Object Selected Event (모델 선택 이벤트)
            vizcore.Object3D.OnObject3DSelected(onSelectEvent);

            // View Info 확인
            let OnViewDrawInfo = function (event) {
                //console.log(event.data);
            }
            vizcore.View.OnViewDrawInfoEvent(OnViewDrawInfo);

            // 파일 열기
            vizcore.Model.OpenHeader("VIZCore3D/Model/toycar/vizw/toycar_wh.vizw", "Sample", onModelLoadingCompleted);
        };

        let option = {
                event : {
                    onInit : onInit,
                    onBefore : onBefore,
                    onConfiguration : onConfiguration,
                }
            }

        vizcore.Init(option);
    </script>
</head>
<body>
    <div class="VIZWeb_Main">
        <div id="view"></div>
    </div>
</body>
</html>

3. 초기화

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

콜백	시점	하는 일
`event.onConfiguration`	엔진이 뜨기 전	VIZCore3D 경로, WebAssembly 경로 등 초기 환경 설정
`event.onBefore`	엔진이 뜨기 전	전 처리 작업
`event.onInit`	초기화 완료 후	ContextMenu 생성, 모델 열기, 이벤트 등록 등 API 호출 시작점

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

        // 전 처리 콜백
        onBefore: onBefore,

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

vizcore.Init(option);

3.0 에는 onBefore 가 없고, 초기화 실패 콜백 onInitFailed 가 추가되었습니다.

onConfiguration

초기 환경 설정을 변경하려면 onConfiguration 함수에서 설정할 수 있습니다.

let onConfiguration = () => {
    // VIZCore 경로 설정
    vizcore.Configuration.Default.Path = "./VIZCore3D/";

    // WebAssembly 경로 설정
    vizcore.Configuration.Default.WebAssembly.Path =
        "./VIZCore3D/lib/shdcore/shdcore.wasm";
};

경고

경로가 변경되거나 VIZCore3D 폴더 이름을 변경한 경우, onConfiguration 에서도 반드시 동일하게 수정해야 합니다.

onBefore

VIZCore3D 실행 전에 필요한 작업이 있다면 onBefore 함수에서 처리할 수 있습니다.

let onBefore = () => {
    // 전 처리 작업
};

onInit

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

let onInit = () => {
    // ContextMenu 사용
    let context = new vizcore.ContextMenu(view, vizcore, VIZCore);

    // 로딩 진행 이벤트
    vizcore.Model.OnStreamProgressChangedEvent(function (e) {
        // e.data.total
        // e.data.current
        // e.data.percentage
    });

    // 모델 선택 이벤트
    vizcore.Object3D.OnObject3DSelected(onSelectEvent);

    // View 정보 이벤트
    let OnViewDrawInfo = function (event) {
        // event.data
    };
    vizcore.View.OnViewDrawInfoEvent(OnViewDrawInfo);

    // 모델 열기 (5절)
    vizcore.Model.OpenHeader(
        "./VIZCore3D/Model/toycar/vizw/toycar_wh.vizw",
        "Sample",
        onModelLoadingCompleted
    );
};

사용된 API

4. 라이선스 서버 연결

노트

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

주소는 VIZCore3D/Configuration.js 파일의 AUTHORITY_PARAMS 에서 설정합니다. 파일을 열어 아래와 같이 수정합니다.

this.AUTHORITY_PARAMS = {
    Data: 'http://127.0.0.1:8901'
};

연결되지 않으면 화면에 License error! 창이 뜨고 모델이 보이지 않습니다.
오류 메시지별 원인은 License Error를 보세요.
상세: Connect · Disconnect

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

// 로딩 완료 시점 확인 — loadType 으로 구분
let onModelLoadingCompleted = function (e, loadType) {
    if (loadType === VIZCore.Enum.CONFIG_KEY.LOADER.COMPLETEDTIME.STRUCTURE) {
        // 구조정보 로딩 완료 — 노드·속성 API 는 이때부터
    }
    if (loadType === VIZCore.Enum.CONFIG_KEY.LOADER.COMPLETEDTIME.MESH) {
        // 형상 로딩 완료 — 형상이 필요한 API 는 이때부터
    }
};

// 분할 VIZW 모델 (VIZWide3D 용) 열기 — 헤더를 열고 구조·형상을 단계적으로 내려받는다
vizcore.Model.OpenHeader("./VIZCore3D/Model/toycar/vizw/toycar_wh.vizw", "Sample", onModelLoadingCompleted);

// 단일 VIZW 모델 (VIZWeb3D 용) 열기
// vizcore.Model.Open("./VIZCore3D/Model/toycar.vizw");

콜백을 넘기지 않으면 OnModelOpenedEvent 가 호출됩니다.
진행률은 OnStreamProgressChangedEvent 로 받습니다.
상세: Model.OpenHeader · Model.Open

6. 프레임워크 사용 시

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

배포 패키지의 VIZCore3D/ 폴더를 둘로 나눠 넣습니다. 스크립트(VIZCore.js, Configuration.js 등)는 src/VIZCore3D 에 복사해 번들에 포함시키고, 엔진과 리소스는 public/VIZCore3D 로 옮깁니다.

(프로젝트)/
├── public/
│   └── VIZCore3D/            ← 빈 폴더를 만들고 아래 두 폴더를 옮깁니다
│       ├── lib/              ← shdcore.wasm
│       └── Resource/         ← CSS, 폰트, 텍스처
└── src/
    └── VIZCore3D/            ← VIZCore.js, Configuration.js 등 스크립트

뷰어 컨테이너(div.VIZWeb_Main > div#view)가 DOM 에 붙은 뒤(Vue mounted, React useEffect)에 인스턴스를 만들고 Init 을 호출합니다.
CSS 는 컴포넌트에서 ./VIZCore3D/Resource/css/VIZCore.css 를 import 합니다.
라이선스 서버 주소는 4. 라이선스 서버 연결과 같이 Configuration.js 에서 설정합니다.

Vue
React

Viewer.vue
<script>
import "./VIZCore3D/Resource/css/VIZCore.css";
import VIZ3DCore from "./VIZCore3D/VIZCore.js";
import { VIZCore } from "./VIZCore3D/VIZCore.js";

export default {
  mounted() {
    const modelUrl = "https://example.com/models/sample_wh.vizw";   // 서버가 내려주는 VIZW URL

    let view = document.getElementById("view");
    view.className = "VIZCore";
    let vizcore = new VIZ3DCore(view);

    vizcore.Init({
      event: {
        onConfiguration() {
          vizcore.Configuration.Default.Path = "./VIZCore3D/";
          vizcore.Configuration.Default.WebAssembly.Path =
            "./VIZCore3D/lib/shdcore/shdcore.wasm";
        },
        onInit() {
          let context = new vizcore.ContextMenu(view, vizcore, VIZCore);
          vizcore.Model.OpenHeader(modelUrl, "Sample");
        },
      },
    });
  },
};
</script>

<template>
  <div id="app">
    <div class="VIZWeb_Main">
      <div id="view"></div>
    </div>
  </div>
</template>

import { useEffect, useRef } from "react";
import "./VIZCore3D/Resource/css/VIZCore.css";
import VIZ3DCore from "./VIZCore3D/VIZCore.js";
import { VIZCore } from "./VIZCore3D/VIZCore.js";

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

  useEffect(() => {
    const modelUrl = "https://example.com/models/sample_wh.vizw";   // 서버가 내려주는 VIZW URL

    const view = viewRef.current;
    view.className = "VIZCore";
    const vizcore = new VIZ3DCore(view);

    vizcore.Init({
      event: {
        onConfiguration() {
          vizcore.Configuration.Default.Path = "./VIZCore3D/";
          vizcore.Configuration.Default.WebAssembly.Path =
            "./VIZCore3D/lib/shdcore/shdcore.wasm";
        },
        onInit() {
          const context = new vizcore.ContextMenu(view, vizcore, VIZCore);
          vizcore.Model.OpenHeader(modelUrl, "Sample");
        },
      },
    });
  }, []);

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

7. 로컬 실행

정보

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

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

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

다음 단계

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

1. 패키지 배치​

2. 뷰어 페이지 작성​

3. 초기화​

onConfiguration​

onBefore​

onInit​

사용된 API​

4. 라이선스 서버 연결​

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

6. 프레임워크 사용 시​

7. 로컬 실행​

다음 단계​