Financial Assets 3D Hero — Documentation

🚀 Quick Start (5 Minutes Setup)

Get the 3D Hero running in minutes:

Run the project using Live Server (required for GLB models)
Add the #hero-container HTML markup to your page
Set your .glb model path using data-model-path
Call init3DHero(container)

🎉 Done! Your interactive 3D hero is ready.

1. Overview

This template provides a complete interactive 3D Hero Section designed specifically for:

Financial & Fintech websites
Investment platforms
Asset management & corporate landing pages

Key Features

Full 360° rotation with mouse / touch interaction
Optional auto-rotation with adjustable speed
Zoom in & out camera controls
Lightweight Three.js implementation
No JavaScript editing required for customization
All core settings are controlled directly from HTML using data-* attributes.

2. Technical Requirements

Because this template loads external GLB 3D models, it must be run in a web server environment.

Requirements

Basic HTML knowledge (JavaScript knowledge not required)
Modern browsers: Chrome, Edge, Firefox, Safari
Live Server or any local / hosted web server
GSAP animation library (included in package)

⚠️ GLB models will NOT load via file:// protocol.

VS Code Recommendation: Install Live Server extension → Right‑click index.html → Open with Live Server.

3. File Structure

Ensure the following structure is preserved:

/assets
├─ css
├─ fonts
├─ js
├─ static/models
└─ three
    /index.html
    /01-bank-corporate-blue.html
    /02-bank-corporate-blue-dark.html
    /03-bank-premium-gold.html
    /04-bank-premium-gold-dark.html
    /05-crypto-trading-blue.html
    /06-crypto-trading-blue-dark.html
    /07-crypto-asset-gold.html
    /08-crypto-asset-gold-dark.html
    /documentation.html

4. Installation & Initialization

Step 1 — Load Required Scripts

Add the scripts before the closing </body> tag.

⚠️ GSAP must be loaded before main.js.

Step 2 — Add the Hero Container

Place this HTML where the 3D hero should appear:

⚠️ Do not remove the <canvas id="webgl"> element.

Step 3 — Initialize the 3D Scene

This final step initializes the 3D hero using the settings defined in the HTML container (#hero-container). This script must be placed before the closing </body> tag to ensure all elements are fully loaded.

5. Theme Class Requirement

🔵 Blue Theme Models

If you are using a blue-themed model such as:

model-coin-blue.glb
model-bank-blue.glb

You must add the following class to your <body> tag for correct lighting and color harmony:

🚨 If using a Default Theme model (e.g., model-gold.glb), no additional class is required. (No class added = Default Theme)

6. Data Attributes Reference

All customization is handled directly in HTML.

Attribute	Type	Description	Recommended Values
`data-model-path`	String	Path to `.glb` model (Required).	`./assets/static/models/...`
`data-scale`	Number	Adjusts the model's visual size. • `1.0` is the original export size. • Values below `1.0` shrink the model.	0.5 to 1.5 (Varies by model)
`data-position-x`	Number	Horizontal model offset	0 (Recommended: -0.8 ~ 0.2)
`data-position-Y`	Number	Vertical model offset	0 (Recommended: -0.2 ~ 0.5)
`data-camera-init-z`	Number	Initial camera distance	3 – 6
`data-auto-rotate`	Boolean	Enable auto rotation	`true` / `false`
`data-rotation-speed`	Number	Controls speed and direction. • Positive (+): Default rotation direction • Negative (-): Reverse rotation direction • Higher value: Faster rotation speed	-2.0 to 2.0
`data-directional-color`	Hex	Main directional light color	`0xbcd6c5`

7. Common Customization Examples

Disable Auto Rotation

data-auto-rotate="false"

The model will remain static until the user interacts with it.

Adjust Rotation Speed & Direction

data-auto-rotate="true"
data-rotation-speed="-3"

Set data-auto-rotate="true" to enable this. Use a negative value (e.g., -3) to reverse the rotation direction.

Move Camera Closer

data-camera-init-z="3.2"

8. Model-Specific Setup Examples

Instead of manually configuring every attribute, the fastest way to build your hero section is to use our pre-configured HTML files.

Open with Live Server

To ensure 3D models load correctly, open any file from 01-bank-corporate-blue.html to 08-crypto-asset-gold-dark.html using a Live Server (e.g., VS Code Live Server extension).
Choose Your Style

Browse through the different themes such as Bank, Crypto, Blue, or Gold to find the design that perfectly matches your project.
Copy & Paste

Once you find a style you like, simply copy the <div id="hero-container" ...> block and paste it into your project.

💡 Pro Tips for Customization:

Update Text: You can easily change the titles and descriptions by editing the text inside the <div class="textGroup">.
Optimal Settings: Each preset already includes the best values for scale, lighting, and camera position, so you don't have to worry about the details.

9. Replacing the 3D Model

When replacing the default 3D model, minor adjustments are usually required to ensure the model appears correctly within the canvas.

Upload Your Model
Place your finalized .glb file into the following directory:
```
/assets/static/models/
```
Update the Model Path
Update the data-model-path attribute in your HTML to reference the new file.
Adjust Model Scale

Since every 3D model is exported with different dimensions, you may need to scale it to fit the hero area.
- data-scale — Controls the physical size of the model. (e.g., Use 0.6 if the model is too large, or 1.2 if it is too small.)

⚠️ Optional Fine-Tuning:
After loading a new model, you may also want to adjust the lighting and camera distance for optimal visual results:

data-camera-init-z — Adjusts how close or far the camera is from the model
data-directional-color — Changes the primary light color

10. Mobile & Responsive Support

Fully responsive on mobile & tablet
Touch drag rotation supported
Mobile-friendly performance optimizations

11. Performance Tips

For best results:

Use optimized GLB files (under 5MB recommended)
Avoid extremely high-poly models
Use only one hero instance per page

12. Troubleshooting (FAQ)

Blank Screen / Model Not Visible

Run via Live Server (not file://)
Check data-model-path
Keep data-camera-init-z between 3–6
Ensure WebGL is enabled in your browser

Auto Rotation Not Working

Confirm GSAP is loaded before main.js
Verify init3DHero(container) is executed

Model Size or Framing Issues

If the model appears too small, too large, or poorly framed within the canvas:

Adjust data-camera-init-z (Recommended): This is the most common way to fix framing. Increase the value to move the camera back (model looks smaller), or decrease it to move closer (model looks larger). (Typical range: 3.0 to 6.0)
Adjust data-scale: If the model itself is fundamentally too tiny or massive regardless of camera distance, use this to change the physical size of the object.

13. Support Policy

✔ Included (6 Months)

Bug fixes related to provided files
Basic integration guidance
GLB model loading issues

✘ Not Included

Custom feature development
Framework conversions (React, Vue, etc.)
Hosting or server setup

14. License

Personal & Commercial Use Allowed
Redistribution or resale is strictly prohibited