# Revisiting viewport helper gizmo

**URL:** <https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979>\
**Category:** Resources\
**Tags:** helpers, view-helper, gizmo\
**Created:** [March 19, 2024, 3:17am UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979 "2024-03-19T03:17:13Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![Fennec](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/fennec/32/59265_2.png) [@Fennec](https://discourse.threejs.org/u/Fennec)\
**Post date:** [March 19, 2024, 3:17am UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/1 "2024-03-19T03:17:14Z")

</div>

A new view helper inspired from the [official one](https://github.com/mrdoob/three.js/blob/a7712cc3a0902f2c45e919a811622ed72ad5f5de/examples/jsm/helpers/ViewHelper.js),  
highly customisable and can be used as standalone or in conjuncture with [OrbitControls](https://threejs.org/docs/#examples/en/controls/OrbitControls), [TrackballControls](https://threejs.org/docs/?q=track#examples/en/controls/TrackballControls) or custom camera controllers like [@yomotsu/camera-controls](https://github.com/yomotsu/camera-controls).

 ![upload://kANqhYtnhr25XvM56qAfSv6Ssjk.jpeg](https://canada1.discourse-cdn.com/flex035/uploads/threejs/original/3X/7/4/74da1071f3319af6a7e0d9de229761daf0ae46be.png)

📚 [Documentation](https://fennec-hub.github.io/three-viewport-gizmo/) - 🚀 [Quickstart](https://fennec-hub.github.io/three-viewport-gizmo/quickstart) - 🛠️ [API](https://fennec-hub.github.io/three-viewport-gizmo/api) - ⚡️ [Examples](https://fennec-hub.github.io/three-viewport-gizmo/examples/orbit-controls)

> **[GitHub - Fennec-hub/three-viewport-gizmo: Three Viewport Gizmo is a highly customizable...](https://github.com/Fennec-hub/three-viewport-gizmo)**
>
> Three Viewport Gizmo is a highly customizable standalone interactive three.js view helper controls, allowing effortless integration with popular camera libraries.

P.S. I think I overdid this one, promise 🤞, this is the last time I bring this up.

---

<div class="post-metadata">

**Author:** ![wenrenqiang](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/wenrenqiang/32/54020_2.png) [@wenrenqiang](https://discourse.threejs.org/u/wenrenqiang)\
**Post date:** [March 19, 2024, 1:33pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/2 "2024-03-19T13:33:48Z")

</div>

It looks good

---

<div class="post-metadata">

**Author:** ![crystalfp](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/crystalfp/32/42772_2.png) [@crystalfp](https://discourse.threejs.org/u/crystalfp)\
**Post date:** [October 23, 2024, 3:33pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/3 "2024-10-23T15:33:31Z")

</div>

Using Typescript `import {ViewportGizmo, type GizmoOptions} from "three-viewport-gizmo";` complains that `Module '"three-viewport-gizmo"' has no exported member 'GizmoOptions'.`

Is there a working demo somewhere?  
Thanks!

---

<div class="post-metadata">

**Author:** ![Fennec](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/fennec/32/59265_2.png) [@Fennec](https://discourse.threejs.org/u/Fennec)\
**Post date:** [October 24, 2024, 9:23am UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/4 "2024-10-24T09:23:58Z")

</div>

@crystalfp,

Thanks for the heads up! There are a few other issues that need to be addressed as well. I’ll let you know once the next commit is ready in the next couple of days.

---

<div class="post-metadata">

**Author:** ![Fennec](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/fennec/32/59265_2.png) [@Fennec](https://discourse.threejs.org/u/Fennec)\
**Post date:** [November 2, 2024, 11:51am UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/5 "2024-11-02T11:51:29Z")

</div>

@crystalfp,

I’ve done a full review of the library, cleaned things up, and made sure all TypeScript types are exposed. Plus, added a new VitePress [documentation](https://fennec-hub.github.io/three-viewport-gizmo/) to make everything easier to follow. Take a look at the updated [API](https://fennec-hub.github.io/three-viewport-gizmo/api.html)—it should have what you need, including all the changes to the `GizmoOptions`.

 ![Screenshot from690x496](https://canada1.discourse-cdn.com/flex035/uploads/threejs/original/3X/2/8/2899884a2d524acbcb0a1544f10b3f3ec14fcd1f.png)

---

<div class="post-metadata">

**Author:** ![agargaro](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/agargaro/32/35529_2.png) [@agargaro](https://discourse.threejs.org/u/agargaro)\
**Post date:** [November 3, 2024, 10:09am UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/6 "2024-11-03T10:09:48Z")

</div>

Thanks a lot for sharing this library 🙂

---

<div class="post-metadata">

**Author:** ![crystalfp](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/crystalfp/32/42772_2.png) [@crystalfp](https://discourse.threejs.org/u/crystalfp)\
**Post date:** [November 8, 2024, 4:06am UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/7 "2024-11-08T04:06:56Z")

</div>

Thanks! The new version show correctly. Almost.  
If I put `placement: "bottom-right",` in the options, typescript complains:

```javascript
Type 'string' is not assignable to type 'GizmoDomPlacement | undefined'.ts-plugin(2345)

```

To make it work, I have to write `placement: "bottom-right" as GizmoDomPlacement,`

Also the `lineWidth` option makes no difference.

Now I have to study the documentation to see how to change colors (the green is barely visible). Setting the axis main and text colors makes the text invisible. And `circle: false` does nothing.

Also the hover color (white) is activated when the pointer is outside the circle few pixel over the circle (with bottom right placement).

Anyway, continue with this good work! Thanks

---

<div class="post-metadata">

**Author:** ![crystalfp](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/crystalfp/32/42772_2.png) [@crystalfp](https://discourse.threejs.org/u/crystalfp)\
**Post date:** [November 8, 2024, 4:47am UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/8 "2024-11-08T04:47:20Z")

</div>

Good news! With the following options I’m on the good path to make what I need.  
The only things that do not work are the `lineWidth` and `circle: false` that are ignored. Also, if you define axis colors but do not add `text`, the label disappears. Maybe it is best to mention this in the documentation.

```javascript
    const gizmoOptions: GizmoOptions = {
        size: 150,
        placement: "bottom-right",
        lineWidth: 2,
        sphere: {enabled: false},
        x: {colors: {main: "#0000FF", text: "aqua"}, circle: false, text: "X"},
        y: {colors: {main: "#00AA00", text: "#000"}, circle: false, text: "Y"},
        z: {colors: {main: "#FF0000", text: "#000"}, circle: false, text: "Z"},
    };

```

Have a nice day!

---

<div class="post-metadata">

**Author:** ![Fennec](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/fennec/32/59265_2.png) [@Fennec](https://discourse.threejs.org/u/Fennec)\
**Post date:** [November 8, 2024, 6:55am UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/9 "2024-11-08T06:55:59Z")

</div>

> [@crystalfp](#):
>
> To make it work, I have to write `placement: "bottom-right" as GizmoDomPlacement`

Not sure what’s causing this, It’s working fine for me, with the default `vite` ts config, even when compiling (`npm i build`).

> [@crystalfp](#):
>
> Also the `lineWidth` option makes no difference.

Also working, using `line2` under the hood for a larger width range.

> [@crystalfp](#):
>
> Setting the axis main and text colors makes the text invisible

Also working, try to configure your gizmo [here](https://fennec-hub.github.io/three-viewport-gizmo/custom.html). (I’ve also added support for the `circle` option)

> [@crystalfp](#):
>
> `circle: false` does nothing.

This one went completely over my head, too much options I guess 😅

> [@crystalfp](#):
>
> Also the hover color (white) is activated when the pointer is outside the circle few pixel over the circle

Yep! I made it this way so the gizmo doesn’t stick to the corners. I’m switching to a `css` gap instead.

Thanks for the valuable feedback, and please upgrade to the new `1.0.3` patch, I’ve added the circle support, and set the sphere offset to 0 with a default `css` offset of 10, fixing the hover gap, the rest should hopefully be working as expected.

---

<div class="post-metadata">

**Author:** ![crystalfp](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/crystalfp/32/42772_2.png) [@crystalfp](https://discourse.threejs.org/u/crystalfp)\
**Post date:** [November 8, 2024, 2:31pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/10 "2024-11-08T14:31:53Z")

</div>

Thanks for this patch. It solved various problems, except the line width:

 ![image](https://canada1.discourse-cdn.com/flex035/uploads/threejs/original/3X/6/c/6c720d9cd445d5b563494d7dc59bb81d5ea54fff.png)  
The options I use are:

```javascript
    const gizmoOptions: GizmoOptions = {
        size: 150,
        placement: "bottom-right",
        lineWidth: 2,
        sphere: {enabled: false},
        x: {colors: {main: "#0000FF", text: "#000"}, circle: false, text: "X"},
        y: {colors: {main: "#00AA00", text: "#000"}, circle: false, text: "Y"},
        z: {colors: {main: "#FF0000", text: "#000"}, circle: false, text: "Z"},
    };

```

Whatever value I put for `lineWidth`, the lines do not change. I even tried to put 8 at no avail. With this version also the y line is not draw (was in 1.0.1).  
Thanks for your help!

P.S.: the problems I had with `placement` disappeared when I correctly typed the `gizmoOptions` object.

---

<div class="post-metadata">

**Author:** ![Fennec](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/fennec/32/59265_2.png) [@Fennec](https://discourse.threejs.org/u/Fennec)\
**Post date:** [November 8, 2024, 2:36pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/11 "2024-11-08T14:36:23Z")

</div>

@crystalfp, `lineWidth: 2` with `Line2` is too low, try with `10`, `20` or higher.

---

<div class="post-metadata">

**Author:** ![crystalfp](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/crystalfp/32/42772_2.png) [@crystalfp](https://discourse.threejs.org/u/crystalfp)\
**Post date:** [November 8, 2024, 2:37pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/12 "2024-11-08T14:37:37Z")

</div>

Ah! That’s the problem! Now with 30 the lines are well visible.  
Thanks!

---

<div class="post-metadata">

**Author:** ![crystalfp](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/crystalfp/32/42772_2.png) [@crystalfp](https://discourse.threejs.org/u/crystalfp)\
**Post date:** [November 8, 2024, 2:53pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/13 "2024-11-08T14:53:52Z")

</div>

Another small thing. When I change the color of the axis, the color of the “free” spheres does not change.

 ![image](https://canada1.discourse-cdn.com/flex035/uploads/threejs/original/3X/2/8/28b11c15f3f0383d843a2f1dfe9d3709aca90ead.png)  
Here I switched the colors of x and z axis, but the spheres “on the other side” retain the original color. In my opinion it is a little confusing.

---

<div class="post-metadata">

**Author:** ![Fennec](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/fennec/32/59265_2.png) [@Fennec](https://discourse.threejs.org/u/Fennec)\
**Post date:** [November 8, 2024, 3:00pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/14 "2024-11-08T15:00:47Z")

</div>

The negative (`nx`, `ny`, `nz`) axis configuration is independent from their positive counterpart, you need set their configuration too.

```js
const gizmoOptions: GizmoOptions = {
        size: 150,
        placement: "bottom-right",
        lineWidth: 30,
        sphere: {enabled: false},
        x: {colors: {main: "#0000FF", text: "#000"}, circle: false, text: "X"},
        nx: {colors: {main: "#0000FF", text: "#000"}},
        y: {colors: {main: "#00AA00", text: "#000"}, circle: false, text: "Y"},
        z: {colors: {main: "#FF0000", text: "#000"}, circle: false, text: "Z"},
        nz: {colors: {main: "#FF0000", text: "#000"}},
    };

```

---

<div class="post-metadata">

**Author:** ![crystalfp](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/crystalfp/32/42772_2.png) [@crystalfp](https://discourse.threejs.org/u/crystalfp)\
**Post date:** [November 9, 2024, 6:03am UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/15 "2024-11-09T06:03:56Z")

</div>

Fantastic! Now the gizmo does what I want! Thanks!  
The only strange thing was that I have to explicitly disable line in nx, ny, nz otherwise the lines in the negative directions appear.  
Here are the options I use:

```javascript
    const gizmoOptions: GizmoOptions = {
        size: 150,
        placement: "bottom-right",
        lineWidth: 30,
        resolution: 64,
        sphere: {enabled: true, hoverOpacity: .2},
        x: {colors: {main: "#FF0000", text: "#000"}, text: "X"},
        y: {colors: {main: "#79FF00", text: "#000"}, text: "Y"},
        z: {colors: {main: "#0000FF", text: "#000"}, text: "Z"},
        nx: {colors: {main: "#FF0000"}, circle: false, line: false},
        ny: {colors: {main: "#79FF00"}, circle: false, line: false},
        nz: {colors: {main: "#0000FF"}, circle: false, line: false},
    };

```

Have a nice day!

---

<div class="post-metadata">

**Author:** ![crystalfp](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/crystalfp/32/42772_2.png) [@crystalfp](https://discourse.threejs.org/u/crystalfp)\
**Post date:** [November 9, 2024, 3:50pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/16 "2024-11-09T15:50:38Z")

</div>

Another small thing. I create ViewportGizmo in the same component that already calls THREEjs.  
On the console the following warnings appear:  
 ![image](https://canada1.discourse-cdn.com/flex035/uploads/threejs/original/3X/e/7/e75e91907df2484c56c74595987030728e7af694.png)  
Maybe the second warning is something I assumed has a default value (sphere color?). But the first one cannot be avoided.  
Thanks for looking!

---

<div class="post-metadata">

**Author:** ![crystalfp](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/crystalfp/32/42772_2.png) [@crystalfp](https://discourse.threejs.org/u/crystalfp)\
**Post date:** [November 9, 2024, 4:37pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/17 "2024-11-09T16:37:14Z")

</div>

Yes, adding color and hoverColor to the sphere definition silences the second warning.

But if I want the sphere color only on hover, make the gizmo not complains if color is missing or automatically if it is missing add it together with opacity = 0.

---

<div class="post-metadata">

**Author:** ![drcmda](https://avatars.discourse-cdn.com/v4/letter/d/91b2a8/32.png) [@drcmda](https://discourse.threejs.org/u/drcmda)\
**Post date:** [November 9, 2024, 7:43pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/18 "2024-11-09T19:43:26Z")

</div>

looks great @Fennec

is a view cube setting planned?

---

<div class="post-metadata">

**Author:** ![Fennec](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.threejs.org/fennec/32/59265_2.png) [@Fennec](https://discourse.threejs.org/u/Fennec)\
**Post date:** [November 9, 2024, 8:19pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/19 "2024-11-09T20:19:58Z")

</div>

> [@drcmda](#):
>
> is a view cube setting planned?

Do you have a particular model in mind!

@crystalfp,

I’ll see what I can do for the default options, for the moment you need to explicitly set them!

---

<div class="post-metadata">

**Author:** ![drcmda](https://avatars.discourse-cdn.com/v4/letter/d/91b2a8/32.png) [@drcmda](https://discourse.threejs.org/u/drcmda)\
**Post date:** [November 9, 2024, 8:43pm UTC](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979/20 "2024-11-09T20:43:30Z")

</div>

![Screenshot 2024-11-09 at 21.42.56](https://canada1.discourse-cdn.com/flex035/uploads/threejs/original/3X/7/8/787c6927d93bcf6f4db444a21be66ff8a8628ed8.png)

(from onshape)

[Next page](https://discourse.threejs.org/t/revisiting-viewport-helper-gizmo/62979.md?page=2)