CadacThreeViewer - A Three.js viewer for CADAC models

This package provides a 3D viewer and some functionalities for creating CADAC 3D models. It is based on the Three.js library. The CadacThreeViewer is a convenient and user-friendly JavaScript library that simplifies the usage and integration of the popular Three.js framework.

In general, it provides a set of additional functionalities, utilities, and abstractions to enhance the development experience and streamline the creation of 3D graphics and interactive web applications.

Demo

🌏 Cadac 3D Viewer example page

🧑‍💻 Cadac 3D Viewer example code

Features

The CadacThreeViewer provides the following features:

• Simplified API: The wrapper library abstracts away much of the complexity of the Three.js API, making it easier for developers to create and manipulate 3D scenes, objects, and animations.

• Higher-level Abstractions: It offers higher-level abstractions and components, such as pre-built 3D objects, cameras, lights, materials, and controls, allowing developers to quickly prototype and build 3D scenes.

• Scene management: It includes a scene manager that simplifies the management of multiple scenes, making it easier to switch between different 3D environments or levels within an application.

Getting Started

1. Include the Library in your project.

The CadacThreeViewer is available as a npm package.

npm i ngx-cadac-viewer

Include the lib dependencies in your project.

npm i --save three troika-three-text three-csg-ts

Include the Three.js library types in your project.

npm i --save-dev @types/three

2. Import the CadacThreeViewer module.

Import the CadacThreeViewer module in your Angular application.

import { NgxCadacViewerModule } from 'ngx-cadac-viewer';

@NgModule({
imports: [NgxCadacViewerModule]
})
export class AppModule {
}

3. Add the CadacThreeViewer component to your application.

• Initialize a new instance of the CadacThree class, which will handle the setup and rendering of your 3D scene.

import { CadacThree, CadacUnits } from "ngx-cadac-viewer";

export class AppComponent implements AfterViewInit, OnDestroy {
  public cadacThreeHandler: CadacThree = new CadacThree({
    sceneOptions: {
      sceneBackground: '#232323',
      // You can set the default units for the scene. 
      // The supported units are: mm, cm, m, in, km
      // The default value is mm.
      defaultUnits: CadacUnits.mm,
    }
  });

  ngAfterViewInit(): void {
    // Renders the scene and starts the animation loop.
    this.cadacThreeHandler.initScene();
  }

  ngOnDestroy(): void {
    // Disposes the scene and free up memory.
    this.cadacThreeHandler.dispose();
  }
}

• Add the CadacThreeViewer component to your Angular application.

<ngx-cadac-viewer
  (objectChangedEmitter)="objectChangedHandler($event)"
  (selectedObjectEmitter)="selectedObjectHandler($event)"
  [cadacThreeHandler]="cadacThreeHandler"
  [id]="'poc'" />

4. Add 3D objects to the scene.

• Create a new 3D object and include it to the scene

const cube = this.cadacThreeHandler.createCube(15, 2, 15, '#f8f8f8', true);
const sphere = this.cadacThreeHandler.createSphere(8, '#eec63e', true);
const cone = this.cadacThreeHandler.createCone(5, 20, 32, '#7a7979', true);

5. Add lights and some Helpers to the scene.

• Add a light to the scene

const light = this.cadacThreeHandler.setMainDirectionalLight();
light.position.set(0, 50, 55);

• Add Helpers to the scene

this.cadacThreeHandler.setGridHelper(30, 30);
this.cadacThreeHandler.toggleOrbitControls(true);
this.cadacThreeHandler.setAmbientLight();
this.cadacThreeHandler.setAxisHelper(30);

• Animate shape rotation

this.cadacThreeHandler.animateShapeRotation(cube, 0, 0.01, 0);

• Constructive Solid Geometry Operations (CSG)

  To create new shapes by merging two existing shapes, you have the option to employ CSG (Constructive Solid Geometry) operations. These operations, namely Subtract, Union, and Intersect, allow you to manipulate shapes in various ways.

  By experimenting with different combinations of these operations and altering the order of input models, you can generate a wide range of composite shapes.

  The three-csg-ts library is used to perform these operations. For more detailed information regarding CSG operations, please refer to the three-csg-ts GitHub repository.

/** Using the previous cube and sphere */

// Subtract the sphere from the cube
const sub = handler.csgSubtract(
    { mesh: cube, position: new Vector3(10, 0, 0) },
    { mesh: sphere, position: new Vector3(10, 0, 0) },
    CadacCSGOperation.SUBTRACT,
    '#09ff00'
  );

// Union the sphere and the cube
const int = handler.csgIntersect(
  { mesh: cube, position: new Vector3(0, 10, 0) },
  { mesh: sphere, position: new Vector3(0, 10, 0) },
  CadacCSGOperation.INTERSECT,
  '#ff0000'
);

// Union the sphere and the cube
const union = handler.csgUnion(
  { mesh: box, position: new Vector3(0, 0, 10) },
  { mesh: sphere, position: new Vector3(0, 0, 10) },
  CadacCSGOperation.UNION,
  '#e3b107'
);

• Add texts to the scene
  • The texts are created using the troika-three-text library.

  For more detailed information, please refer to the troika-three-text GitHub repository.

const text = this.cadacThreeHandler.createText('Hello Cadac', 1, new Vector3(0, 10, 0), '#ff0000');

API Reference

CadacThree

The CadacThree class is the main class of the CadacThreeViewer library. It is responsible for the setup and rendering of the 3D scene.

Methods Description

| Method | Description | |-----------------------------|--------------------------------------------| | initScene | Creates a new Three.js scene. | | createCube | Creates a new cube. | | createSphere | Creates a new sphere. | | createCylinder | Creates a new cylinder. | | createCone | Creates a new cone. | | createCylinder | Creates a new cylinder. | | createCapsule | Creates a new capsule. | | createCircle | Creates a new circle. | | createPlane | Creates a new plane. | | updateObjectOpacity | Updates the opacity of an object. | | updateObjectColor | Updates the color of an object. | | updateObjectGeometry | Updates the geometry of an object. | | mergeMeshes | Merges multiple meshes into a single mesh. | | csgSubtract | CSG subtract operation. | | csgUnion | CSG union operation. | | csgIntersect | CSG intersect operation. | | SceneShapes | Gets all cadac shapes in the scene. | | toggleOrbitControls | Enables or disables the OrbitControls. | | setMainDirectionalLight | Creates a new main directional light. | | setAmbientLight | Creates a new ambient light. | | setGridHelper | Creates a new grid helper. | | setAxisHelper | Creates a new axis helper. | | animateShapeRotation | Animates the rotation of a shape. | | dispose | Disposes the scene. |

Types & Methods

export type CadacThreeShapeRotation = {
  shape: CadacThreeShape,
  xSpeed: number,
  ySpeed: number,
  zSpeed: number
}

export enum CadacUnits {
  mm = 'mm', // default
  cm = 'cm',
  m = 'm',
  inch = 'inch',
  km = 'km',
}

export enum CadacCSGOperation {
  SUBTRACT = "SUBTRACT",
  INTERSECT = "INTERSECT",
  UNION = "UNION"
}

export const DEFAULTS_CADAC = {
  UNIT: CadacUnits.mm,
  COLOR: '#f4f4f4',
  CAMERA_NEAR: 0.1,
  CAMERA_FAR: 1000,
  CAMERA_FOV: 50,
  CAMERA_POSITION: new THREE.Vector3(0, 10, 20),
  CAMERA_LOOK_AT: new THREE.Vector3(0, 0, 0)
}

export declare enum CadacPlanes {
  XY = "XY",
  YZ = "YZ",
  XZ = "XZ"
}

export type CadacThreeOptions = {
  defaultUnits?: CadacUnits;
  elRef?: ElementRef;
  sceneOptions?: CadacThreeSceneOptions;
};

export type CadacThreeSceneOptions = {
  elRef?: ElementRef,
  scene?: THREE.Scene,
  camera?: THREE.PerspectiveCamera,
  renderer?: THREE.WebGLRenderer,
  sceneBackground: string
  defaultUnits?: CadacUnits
};

export type CadacMergeMesh = {
  mesh: THREE.Mesh,
  position: THREE.Vector3,
}

export type CadacObjectData = {
  object: CadacThreeShape;
  position?: THREE.Vector3;
  rotation?: THREE.Euler;
  scale?: THREE.Vector3;
  geometry?: BoxGeometry | SphereGeometry | CylinderGeometry | Geometry;
};

export declare enum CadacEventDataTypes {
  OBJECT_SELECTED = "OBJECT_SELECTED",
  OBJECT_CHANGED = "OBJECT_CHANGED",
  TOGGLE_RESTRICTED_PLANE = "TOGGLE_RESTRICTED_PLANE"
}

export type CadacEventData = {
  type: CadacEventDataTypes;
  payload?: any;
};

export type CadacThreeShape = THREE.Mesh | THREE.Line | THREE.Points

updateObjectOpacity(opacity: number, object?: CadacThreeShape): void;
updateObjectColor(color: string, object?: CadacThreeShape): void;
updateObjectGeometry(geometry: BufferGeometry, object?: CadacThreeShape): void;
initScene(): void;
dispose(): void;
createCube(width?: number, height?: number, depth?: number, color?: string, addToScene?: boolean, unit?: CadacUnits): Mesh<import("three").BoxGeometry, import("three").MeshBasicMaterial>;
createSphere(radius?: number, color?: string, addToScene?: boolean, unit?: CadacUnits): Mesh<import("three").SphereGeometry, import("three").MeshBasicMaterial>;
createCone(radius?: number, height?: number, radialSegments?: number, color?: string, addToScene?: boolean, unit?: CadacUnits): Mesh<import("three").ConeGeometry, import("three").MeshBasicMaterial>;
createCylinder(radiusTop?: number, radiusBottom?: number, height?: number, radialSegments?: number, color?: string, addToScene?: boolean, unit?: CadacUnits): Mesh<import("three").CylinderGeometry, import("three").MeshBasicMaterial>;
createCapsule(radius?: number, height?: number, capSegments?: number, radialSegments?: number, color?: string, addToScene?: boolean, unit?: CadacUnits): Mesh<import("three").CapsuleGeometry, import("three").MeshBasicMaterial>;
createCircle(radius?: number, segments?: number, color?: string, addToScene?: boolean, unit?: CadacUnits): Mesh<import("three").CircleGeometry, import("three").MeshBasicMaterial>;
createPlane(width?: number, height?: number, color?: string, addToScene?: boolean, unit?: CadacUnits): Mesh<import("three").PlaneGeometry, import("three").MeshBasicMaterial>;
mergeMeshes(meshes: CadacMergeMesh[], color?: string, addToScene?: boolean): Mesh<BufferGeometry<import("three").NormalBufferAttributes>, import("three").MeshPhongMaterial>;
csgSubtract(meshes1: CadacMergeMesh, meshes2: CadacMergeMesh, operation?: CadacCSGOperation, color?: string, addToScene?: boolean): Mesh<BufferGeometry<import("three").NormalBufferAttributes>, Material | Material[]>;
csgIntersect(meshes1: CadacMergeMesh, meshes2: CadacMergeMesh, operation?: CadacCSGOperation, color?: string, addToScene?: boolean): Mesh<BufferGeometry<import("three").NormalBufferAttributes>, Material | Material[]>;
csgUnion(meshes1: CadacMergeMesh, meshes2: CadacMergeMesh, operation?: CadacCSGOperation, color?: string, addToScene?: boolean): Mesh<BufferGeometry<import("three").NormalBufferAttributes>, Material | Material[]>;
createText(text: string, fontSize?: number, position?: Vector3, color?: string, addToScene?: boolean): any;
toggleOrbitControls(active: boolean): void;
toggleTransformControls(mesh: Object3D | undefined, active: boolean): void;

setAmbientLight(color?: string, intensity?: number): void;
setAxisHelper(size?: number): void;
setMainDirectionalLight(color?: string, intensity?: number): THREE.DirectionalLight;
animateShapeRotation(shape: THREE.Mesh<THREE.BoxGeometry, THREE.MeshPhongMaterial>, xSpeed?: number, ySpeed?: number, zSpeed?: number): void;
setGridHelper(size?: number, divisions?: number): void;
setLineSegments(sphere: CadacThreeShape, color?: string): void;
setEventClickListener({ object, callback }: CadacClickObjectListenerData): void;

Documentation

For detailed documentation and examples, refer to the official Three.js documentation.

Compatibility

This library is compatible with the latest version of Three.js (at the time of writing "three": "^0.152.2"). Ensure that you are using a compatible version of Three.js to avoid any compatibility issues.