Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use AHash to get color from entity in bevy_gizmos #8960

Merged
merged 1 commit into from
Jun 26, 2023
Merged

Use AHash to get color from entity in bevy_gizmos #8960

merged 1 commit into from
Jun 26, 2023

Conversation

nicopap
Copy link
Contributor

@nicopap nicopap commented Jun 26, 2023

Objective

color_from_entity uses the poor man's hash to get a fixed random color for an entity.

While the poor man's hash is succinct, it has a tendency to clump. As a result, bevy_gizmos has a tendency to re-use very similar colors for different entities.

This is bad, we would want non-similar colors that take the whole range of possible hues. This way, each bevy_gizmos aabb gizmo is easy to identify.

Solution

AHash is a nice and fast hash that just so happen to be available to use, so we use it.

@nicopap
Use AHash to get color from entity in bevy_gizmos
95ac969 
`color_from_entity` uses the poor man's hash to get a fixed random
color for an entity.

While the poor man's hash is succinct, it has a tendency to clump.
As a result, bevy_gizmos has a tendency to re-use very similar colors
for different entities.

This is bad, we would want non-similar colors that take the whole range
of possible hues. This way, each bevy_gizmos aabb gizmo is easy to
identify.

AHash is a nice and fast hash that just so happen to be available to
use, so we use it.
@nicopap nicopap added C-Enhancement A new feature A-Gizmos Visual editor and debug gizmos labels Jun 26, 2023
MrGVSV
MrGVSV approved these changes Jun 26, 2023
View reviewed changes
Copy link
Member

@MrGVSV MrGVSV left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you happen to have any before/after screenshots of this fix?

@nicopap
Copy link
Contributor Author

nicopap commented Jun 26, 2023

My method was to print the hue value for about 30 entities. Let me setup something more scientific in any case.

@alice-i-cecile alice-i-cecile added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Jun 26, 2023
@nicopap
Copy link
Contributor Author

nicopap commented Jun 26, 2023 •
edited

Here is the difference:

  • Top plot has "how many entities has this hue" for entities of generation 1 and index 0 to 10_000.
  • Bottom plot has hue for the first 100 entities
  • In red: using a hash
  • In blue: using the poor man's hash

The height of the bars show how many entities ended up with the specific hue.

You can see you only really get 9 different colors with the poor man's hash. While ahash's result is fairly well distributed across all hues.

entity-color-hashing-2023-06-26

@alice-i-cecile alice-i-cecile added this pull request to the merge queue Jun 26, 2023
@alice-i-cecile
Copy link
Member

I love this graph, thank you!

@nicopap
Copy link
Contributor Author

nicopap commented Jun 26, 2023

Here is for the first 7 and 25 entities. The poor man's hash is not bad at all if the goal is to have distinct colors (which is ours). But you can really only have 9 total.

_Ascreencap

@alice-i-cecile
Copy link
Member

alice-i-cecile commented Jun 26, 2023 •
edited

Eventually we may want to change this to quasi-random noise instead to optimize for "random but evenly spaced", but this is much better than the existing solution and simple.

Merged via the queue into bevyengine:main with commit 1e73312 Jun 26, 2023
24 checks passed
@nicopap nicopap mentioned this pull request Jul 16, 2023
Merged
github-merge-queue bot pushed a commit that referenced this pull request Jul 21, 2023
@nicopap
Replace AHash with a good sequence for entity AABB colors (#9175)
cd92405 
# Objective

- #8960 isn't optimal for very distinct AABB colors, it can be improved

## Solution

We want a function that maps sequential values (entities concurrently
living in a scene _usually_ have ids that are sequential) into very
different colors (the hue component of the color, to be specific)

What we are looking for is a [so-called "low discrepancy"
sequence](https://en.wikipedia.org/wiki/Low-discrepancy_sequence). ie: a
function `f` such as for integers in a given range (eg: 101, 102, 103…),
`f(i)` returns a rational number in the [0..1] range, such as `|f(i) -
f(i±1)| ≈ 0.5` (maximum difference of images for neighboring preimages)

AHash is a good random hasher, but it has relatively high discrepancy,
so we need something else.
Known good low discrepancy sequences are:

#### The [Van Der Corput
sequence](https://en.wikipedia.org/wiki/Van_der_Corput_sequence)

<details><summary>Rust implementation</summary>

```rust
fn van_der_corput(bits: u64) -> f32 {
    let leading_zeros = if bits == 0 { 0 } else { bits.leading_zeros() };
    let nominator = bits.reverse_bits() >> leading_zeros;
    let denominator = bits.next_power_of_two();

    nominator as f32 / denominator as f32
}
```

</details>

#### The [Gold Kronecker
sequence](https://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/)

<details><summary>Rust implementation</summary>

Note that the implementation suggested in the linked post assumes
floats, we have integers

```rust
fn gold_kronecker(bits: u64) -> f32 {
    const U64_MAX_F: f32 = u64::MAX as f32;
    // (u64::MAX / Φ) rounded down
    const FRAC_U64MAX_GOLDEN_RATIO: u64 = 11400714819323198485;
    bits.wrapping_mul(FRAC_U64MAX_GOLDEN_RATIO) as f32 / U64_MAX_F
}
```

</details>

### Comparison of the sequences

So they are both pretty good. Both only have a single (!) division and
two `u32 as f32` conversions.

- Kronecker is resilient to regular sequence (eg: 100, 102, 104, 106)
while this kills Van Der Corput (consider that potentially one entity
out of two spawned might be a mesh)

I made a small app to compare the two sequences, available at:
https://gist.github.com/nicopap/5dd9bd6700c6a9a9cf90c9199941883e

At the top, we have Van Der Corput, at the bottom we have the Gold
Kronecker. In the video, we spawn a vertical line at the position on
screen where the x coordinate is the image of the sequence. The
preimages are 1,2,3,4,… The ideal algorithm would always have the
largest possible gap between each line (imagine the screen x coordinate
as the color hue):


https://github.com/bevyengine/bevy/assets/26321040/349aa8f8-f669-43ba-9842-f9a46945e25c

Here, we repeat the experiment, but with with `entity.to_bits()` instead
of a sequence:


https://github.com/bevyengine/bevy/assets/26321040/516cea27-7135-4daa-a4e7-edfd1781d119

Notice how Van Der Corput tend to bunch the lines on a single side of
the screen. This is because we always skip odd-numbered entities.

Gold Kronecker seems always worse than Van Der Corput, but it is
resilient to finicky stuff like entity indices being multiples of a
number rather than purely sequential, so I prefer it over Van Der
Corput, since we can't really predict how distributed the entity indices
will be.

### Chosen implementation

You'll notice this PR's implementation is not the Golden ratio-based
Kronecker sequence as described in
[tueoqs](https://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/).
Why?

tueoqs R function multiplies a rational/float and takes the fractional
part of the result `(x/Φ) % 1`. We start with an integer `u32`. So
instead of converting into float and dividing by Φ (mod 1) we directly
divide by Φ as integer (mod 2³²) both operations are equivalent, the
integer division (which is actually a multiplication by `u32::MAX / Φ`)
is probably faster.

## Acknowledgements

- `inspi` on discord linked me to
https://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/
and the wikipedia article.
- [this blog
post](https://probablydance.com/2018/06/16/fibonacci-hashing-the-optimization-that-the-world-forgot-or-a-better-alternative-to-integer-modulo/)
for the idea of multiplying the `u32` rather than the `f32`.
- `nakedible` for suggesting the `index()` over `to_bits()` which
considerably reduces generated code (goes from 50 to 11 instructions)
cart pushed a commit that referenced this pull request Aug 10, 2023
@nicopap @cart
Replace AHash with a good sequence for entity AABB colors (#9175)
5d8351d 
# Objective

- #8960 isn't optimal for very distinct AABB colors, it can be improved

## Solution

We want a function that maps sequential values (entities concurrently
living in a scene _usually_ have ids that are sequential) into very
different colors (the hue component of the color, to be specific)

What we are looking for is a [so-called "low discrepancy"
sequence](https://en.wikipedia.org/wiki/Low-discrepancy_sequence). ie: a
function `f` such as for integers in a given range (eg: 101, 102, 103…),
`f(i)` returns a rational number in the [0..1] range, such as `|f(i) -
f(i±1)| ≈ 0.5` (maximum difference of images for neighboring preimages)

AHash is a good random hasher, but it has relatively high discrepancy,
so we need something else.
Known good low discrepancy sequences are:

#### The [Van Der Corput
sequence](https://en.wikipedia.org/wiki/Van_der_Corput_sequence)

<details><summary>Rust implementation</summary>

```rust
fn van_der_corput(bits: u64) -> f32 {
    let leading_zeros = if bits == 0 { 0 } else { bits.leading_zeros() };
    let nominator = bits.reverse_bits() >> leading_zeros;
    let denominator = bits.next_power_of_two();

    nominator as f32 / denominator as f32
}
```

</details>

#### The [Gold Kronecker
sequence](https://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/)

<details><summary>Rust implementation</summary>

Note that the implementation suggested in the linked post assumes
floats, we have integers

```rust
fn gold_kronecker(bits: u64) -> f32 {
    const U64_MAX_F: f32 = u64::MAX as f32;
    // (u64::MAX / Φ) rounded down
    const FRAC_U64MAX_GOLDEN_RATIO: u64 = 11400714819323198485;
    bits.wrapping_mul(FRAC_U64MAX_GOLDEN_RATIO) as f32 / U64_MAX_F
}
```

</details>

### Comparison of the sequences

So they are both pretty good. Both only have a single (!) division and
two `u32 as f32` conversions.

- Kronecker is resilient to regular sequence (eg: 100, 102, 104, 106)
while this kills Van Der Corput (consider that potentially one entity
out of two spawned might be a mesh)

I made a small app to compare the two sequences, available at:
https://gist.github.com/nicopap/5dd9bd6700c6a9a9cf90c9199941883e

At the top, we have Van Der Corput, at the bottom we have the Gold
Kronecker. In the video, we spawn a vertical line at the position on
screen where the x coordinate is the image of the sequence. The
preimages are 1,2,3,4,… The ideal algorithm would always have the
largest possible gap between each line (imagine the screen x coordinate
as the color hue):


https://github.com/bevyengine/bevy/assets/26321040/349aa8f8-f669-43ba-9842-f9a46945e25c

Here, we repeat the experiment, but with with `entity.to_bits()` instead
of a sequence:


https://github.com/bevyengine/bevy/assets/26321040/516cea27-7135-4daa-a4e7-edfd1781d119

Notice how Van Der Corput tend to bunch the lines on a single side of
the screen. This is because we always skip odd-numbered entities.

Gold Kronecker seems always worse than Van Der Corput, but it is
resilient to finicky stuff like entity indices being multiples of a
number rather than purely sequential, so I prefer it over Van Der
Corput, since we can't really predict how distributed the entity indices
will be.

### Chosen implementation

You'll notice this PR's implementation is not the Golden ratio-based
Kronecker sequence as described in
[tueoqs](https://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/).
Why?

tueoqs R function multiplies a rational/float and takes the fractional
part of the result `(x/Φ) % 1`. We start with an integer `u32`. So
instead of converting into float and dividing by Φ (mod 1) we directly
divide by Φ as integer (mod 2³²) both operations are equivalent, the
integer division (which is actually a multiplication by `u32::MAX / Φ`)
is probably faster.

## Acknowledgements

- `inspi` on discord linked me to
https://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/
and the wikipedia article.
- [this blog
post](https://probablydance.com/2018/06/16/fibonacci-hashing-the-optimization-that-the-world-forgot-or-a-better-alternative-to-integer-modulo/)
for the idea of multiplying the `u32` rather than the `f32`.
- `nakedible` for suggesting the `index()` over `to_bits()` which
considerably reduces generated code (goes from 50 to 11 instructions)
@nicopap nicopap deleted the entity-hash-color branch August 30, 2023 13:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@alice-i-cecile alice-i-cecile alice-i-cecile approved these changes

@MrGVSV MrGVSV MrGVSV approved these changes

Assignees
No one assigned
Labels
A-Gizmos Visual editor and debug gizmos C-Enhancement A new feature S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
3 participants
@nicopap @alice-i-cecile @MrGVSV