Skip to content

README.md

Latest commit

 

History

History
399 lines (300 loc) · 22.4 KB

README.md

File metadata and controls

399 lines (300 loc) · 22.4 KB

angular-three-soba/abstractions

This module provides abstract components and patterns for building reusable and composable 3D elements in Angular Three. It requires the following peer dependencies:

Package Description
troika-three-text Required for using the NgtsText component.
three-mesh-bvh Required for angular-three-soba/shaders

To install these dependencies, use one of the following commands:

npm install troika-three-text three-mesh-bvh
# yarn add troika-three-text three-mesh-bvh
# pnpm add troika-three-text three-mesh-bvh

TOC

NgtsBillboard

A component that rotates its contents to always face the camera (billboarding effect). Useful for sprites, labels, or any content that should always face the viewer.

Object Inputs (NgtsBillboardOptions)

Property Description Default Value
follow Whether the billboard should follow (face) the camera. true
lockX Lock rotation on the X axis, preventing the billboard from rotating around X. false
lockY Lock rotation on the Y axis, preventing the billboard from rotating around Y. false
lockZ Lock rotation on the Z axis, preventing the billboard from rotating around Z. false 
<ngts-billboard [options]="{ follow: true, lockY: true }">
	<ngt-mesh>
		<ngt-plane-geometry />
		<ngt-mesh-basic-material />
	</ngt-mesh>
</ngts-billboard>

NgtsRoundedBox

A component that renders a box with rounded edges. Creates smooth, beveled corners on all edges of the box.

Object Inputs (NgtsRoundedBoxOptions)

Property Description Default Value
width Width of the box (X-axis). 1
height Height of the box (Y-axis). 1
depth Depth of the box (Z-axis). 1
radius Radius of the rounded corners. 0.05
smoothness Number of curve segments for corner smoothness. 4
bevelSegments Number of bevel segments. 4
steps Number of extrusion steps. 1
creaseAngle Angle threshold for creased normals calculation (radians). 0.4 
<ngts-rounded-box [options]="{ width: 2, height: 1, depth: 1, radius: 0.1 }">
	<ngt-mesh-standard-material color="orange" />
</ngts-rounded-box>

NgtsGrid

A y-up oriented, shader-based grid implementation.

This component renders a grid using a shader material, allowing for efficient rendering of large grids. It provides options to customize the appearance of the grid, such as cell size, cell thickness, cell color, section size, section thickness, section color, and more.

Object Inputs (NgtsGridOptions)

Property Description Default Value
planeArgs Default plane-geometry arguments. []
cellSize Cell size. 0.5
cellThickness Cell thickness. 0.5
cellColor Cell color. 'black'
sectionSize Section size. 1
sectionThickness Section thickness. 1
sectionColor Section color. '#2080ff'
infiniteGrid Display the grid infinitely. false
followCamera Follow camera. false
fadeDistance Fade distance. 100
fadeStrength Fade strength. 1
fadeFrom Fade from camera (1) or origin (0), or somewhere in between. 1
side Which side of the faces will be rendered. Can be THREE.FrontSide, THREE.BackSide, or THREE.DoubleSide. THREE.BackSide 
<ngts-grid />

NgtsText

High-quality text rendering with signed distance fields (SDF) and antialiasing, using troika-three-text.

This component renders high-quality text using SDF and antialiasing techniques. It supports various options for customizing the appearance of the text, such as font, font size, color, alignment, and more.

Inputs

Input Description Required
text Text content to render. Yes

Object Inputs (NgtsTextOptions)

Property Description Default Value
font URL to the font file (supports .ttf, .otf, .woff). undefined
fontSize Font size in world units. 1
color Text color. undefined
fontWeight Font weight (numeric or string like 'bold'). undefined
fontStyle Font style. Can be 'italic' or 'normal'. undefined
maxWidth Maximum width for text wrapping in world units. undefined
lineHeight Line height multiplier. undefined
letterSpacing Letter spacing in world units. undefined
textAlign Text alignment. Can be 'left', 'right', 'center', or 'justify'. undefined
anchorX Horizontal anchor point. Can be 'left', 'center', 'right', or a number. 'center'
anchorY Vertical anchor point. Can be 'top', 'top-baseline', 'middle', 'bottom-baseline', 'bottom', or a number. 'middle'
clipRect Clipping rectangle [minX, minY, maxX, maxY]. undefined
depthOffset Depth offset for z-fighting prevention. undefined
direction Text direction for bidirectional text. Can be 'auto', 'ltr', or 'rtl'. undefined
overflowWrap How to handle text overflow and wrapping. Can be 'normal' or 'break-word'. undefined
whiteSpace Whitespace handling mode. Can be 'normal', 'overflowWrap', or 'nowrap'. undefined
outlineWidth Width of the text outline. undefined
outlineOffsetX Horizontal offset for the outline. undefined
outlineOffsetY Vertical offset for the outline. undefined
outlineBlur Blur radius for the outline. undefined
outlineColor Color of the text outline. undefined
outlineOpacity Opacity of the text outline (0-1). undefined
strokeWidth Width of the text stroke. undefined
strokeColor Color of the text stroke. undefined
strokeOpacity Opacity of the text stroke (0-1). undefined
fillOpacity Opacity of the text fill (0-1). undefined
sdfGlyphSize Size of the SDF glyph texture. Higher values improve quality but use more memory. 64
debugSDF Enable debug visualization of the SDF texture. undefined
characters Characters to pre-render for the font. Improves performance for known character sets. undefined
glyphGeometryDetail Detail level for glyph geometry. undefined

Outputs

Output Description
synced Emitted when the text has been synced and is ready for rendering. Returns the Troika Text mesh instance. 
<ngts-text text="Hello, World!" />

NgtsText3D

Renders 3D text using Three.js TextGeometry.

This component renders 3D text using TextGeometry. It requires fonts in JSON format generated through typeface.json.

Inputs

Input Description Required
font Font source. Can be a URL to a typeface.json file or a preloaded font object. Yes
text Text content to render as 3D geometry. Yes

Object Inputs (NgtsText3DOptions)

Property Description Default Value
size Font size. 1
height Text extrusion height. 0.2
curveSegments Number of curve segments. 8
bevelEnabled Enable bevel. false
bevelThickness Bevel thickness. 0.1
bevelSize Bevel size. 0.01
bevelOffset Bevel offset. 0
bevelSegments Number of bevel segments for smoother beveled edges. 4
letterSpacing Letter spacing. 0
lineHeight Line height multiplier. 1
smooth Threshold for merging vertices to create smooth normals. undefined 
<ngts-text-3d font="path/to/font.json" text="Hello, World!">
	<ngt-mesh-standard-material color="gold" />
</ngts-text-3d>

NgtsLine

Renders a THREE.Line2 or THREE.LineSegments2 (depending on the value of segments).

Inputs

Input Description Required
points Array of points. Accepts Vector3, Vector2, coordinate tuples, or flat numbers. Yes

Object Inputs (NgtsLineOptions)

Property Description Default Value
color Line color. 0xffffff
lineWidth Line width in pixels. 1
segments Whether to render as THREE.LineSegments2 instead of THREE.Line2. false
dashed Whether the line is dashed. undefined
vertexColors Array of colors for vertex coloring. Supports RGB or RGBA tuples. undefined 
<ngts-line [points]="[[0, 0, 0], [1, 1, 1]]" />

NgtsQuadraticBezierLine

Renders a THREE.Line2 using THREE.QuadraticBezierCurve3 for interpolation.

Inputs

Input Description Default Value
start Starting point of the bezier curve. [0, 0, 0]
end Ending point of the bezier curve. [0, 0, 0]
mid Control point. If not provided, automatically calculated. undefined

Object Inputs (NgtsQuadraticBezierLineOptions)

Property Description Default Value
segments Number of segments to approximate the bezier curve. 20
lineWidth Line width. 1

Also accepts all NgtsLineOptions except segments (boolean).

<ngts-quadratic-bezier-line [start]="[0, 0, 0]" [end]="[1, 1, 1]" />

NgtsCubicBezierLine

Renders a THREE.Line2 using THREE.CubicBezierCurve3 for interpolation.

Inputs

Input Description Required
start Start point. Yes
end End point. Yes
midA First control point. Yes
midB Second control point. Yes

Object Inputs (NgtsCubicBezierLineOptions)

Property Description Default Value
segments Number of segments to divide the Bezier curve into. 20
lineWidth Line width. 1

Also accepts all NgtsLineOptions except segments (boolean).

<ngts-cubic-bezier-line [start]="[0, 0, 0]" [end]="[1, 1, 1]" [midA]="[0.5, 0.5, 0.5]" [midB]="[0.5, 0.5, 0.5]" />

NgtsCatmullRomLine

Renders a THREE.Line2 using THREE.CatmullRomCurve3 for interpolation.

Inputs

Input Description Required
points Array of points. Yes

Object Inputs (NgtsCatmullRomLineOptions)

Property Description Default Value
closed Whether the curve should be closed (connect end to start). false
curveType Type of curve. Can be 'centripetal', 'chordal', or 'catmullrom'. 'centripetal'
tension Tension parameter for the curve (0 to 1). 0.5
segments Number of segments to divide the curve into for rendering. 20
lineWidth Line width. 1

Also accepts all NgtsLineOptions except segments (boolean).

<ngts-catmull-rom-line [points]="[[0, 0, 0], [1, 1, 1]]" />

NgtsEdges

Abstracts THREE.EdgesGeometry. It pulls the geometry automatically from its parent, optionally you can ungroup it and give it a geometry prop. You can give it children, for instance a custom material. NgtsEdges is based on NgtsLine and supports all of its options.

Object Inputs (NgtsEdgesOptions)

Property Description Default Value
geometry Geometry to use for the edges. If not provided, uses parent geometry. undefined
threshold Angle threshold in degrees for edge detection. 15
lineWidth Width of the edge lines. 1

Also accepts all NgtsLineOptions.

<ngt-mesh>
	<ngt-box-geometry />
	<ngt-mesh-basic-material />
	<ngts-edges [options]="{ threshold: 15, scale: 1.1, color: 'white', lineWidth: 4 }" />
</ngt-mesh>

NgtsPrismGeometry

Abstracts THREE.ExtrudeGeometry to create a prism geometry.

Inputs

Input Description Required
vertices Array of 2D vertices defining the base shape. Yes
attach Defines how the geometry attaches to its parent. No

Object Inputs (NgtsPrismGeometryOptions)

Property Description Default Value
height Height of the prism extrusion. 1
bevelEnabled Enable bevel. false

Also accepts all THREE.ExtrudeGeometryOptions except depth.

<ngt-mesh>
	<ngts-prism-geometry [vertices]="[[0, 0], [1, 0], [1, 1], [0, 1]]" />
	<ngt-mesh-basic-material />
</ngt-mesh>

NgtsGradientTexture

A declarative THREE.Texture which attaches to "map" by default. You can use this to create gradient backgrounds.

Inputs

Input Description Required
stops Gradient stops array. Yes
colors Gradient colors array. Must be the same size as stops Yes
attach Defines how the texture attaches to its parent. No

Object Inputs (NgtsGradientTextureOptions)

Property Description Default Value
type Gradient type. Can be 'linear' or 'radial'. 'linear'
size Height of the gradient texture canvas in pixels. 1024
width Width of the gradient texture canvas in pixels. 16
innerCircleRadius Inner circle radius for radial gradients. 0
outerCircleRadius Outer circle radius for radial gradients. 'auto' 
<ngt-mesh-basic-material>
	<ngts-gradient-texture [stops]="[0, 0.5, 1]" [colors]="['red', 'green', 'blue']" />
</ngt-mesh-basic-material>

helper

A function to add helpers to existing nodes in the scene. It handles removal of the helper on destroy and auto-updates it by default.

class MyCmp {
	mesh = viewChild.required<ElementRef<Mesh>>('mesh');
	boxHelper = helper(this.mesh, () => BoxHelper, { args: () => ['cyan'] });
}

Note: injectHelper is deprecated. Use helper instead.

NgtsHelper

A declarative way to add helpers to existing nodes in the scene. It handles removal of the helper on destroy and auto-updates it by default.

<ngt-mesh>
	<ngts-helper [type]="BoxHelper" [options]="['cyan']" />
</ngt-mesh>