Parse category bitmask SDF element in Surface DOM (backport #1630)

[mergify]

🎉 New feature

Summary

Parses the category_bitmask SDF element:
https://sdformat.org/spec/1.12/collision/#contact_category_bitmask

In short, collision occurs if (category_bitmask1 & collide_bitmask2) | (category_bitmask2 & collide_bitmask1)
evaluates to non-zero.

Currently in gazebo, collision occurs if (collide_bitmask1 & collide_bitmask2) evaluates to non-zero. To preserve backward compatibility, here's a proposed implementation (to be implemented in gz-physics):

• if collide_bitmask is set and category_bitmask is not set, then category_bitmask is set to the same value as collide_bitmask

Example 1: collide_bitmask is set but category_bitmask is not for both collision entities (existing behavior in gz-physics):

• entity1:
  • collide_bitmask1: 0x1
  • category_bitmask1: (not set, so defaults to 0x1 )
• entity2:
  • collide_bitmask2: 0x2
  • category_bitmask2: (not set, so defaults to 0x2 )
    Result of (category_bitmask1 & collide_bitmask2) | (category_bitmask2 & collide_bitmask1): No collision. Preserves existing behavior.

Example 2: collide_bitmask and category_bitmask are set for both collision entities

• entity1:
  • collide_bitmask1: 0x1
  • category_bitmask1:0x2
• entity2:
  • collide_bitmask2: 0x2
  • category_bitmask2: 0x1
    Result of (category_bitmask1 & collide_bitmask2) | (category_bitmask2 & collide_bitmask1): Collision occurs!

Example 3: collide_bitmask and category_bitmask are set for one collision entity while only collide_bitmask is set for the other collision entity

• entity1:
  • collide_bitmask1: 0x1
  • category_bitmask1: (not set, so defaults to 0x1)
• entity2:
  • collide_bitmask2: 0x2
  • category_bitmask2: 0x1
    Result of (category_bitmask1 & collide_bitmask2) | (category_bitmask2 & collide_bitmask1): Collision occurs!

The category bitmask field in Surface DOM uses std::optional type so we are able to know if the value is set or not.

Checklist

• Signed all commits for DCO
• Added a screen capture or video to the PR description that demonstrates the feature
• Added tests
• Added example and/or tutorial
• Updated documentation (as needed)
• Updated migration guide (as needed)
• Consider updating Python bindings (if the library has them)
• codecheck passed (See contributing)
• All tests passed (See test coverage)
• Updated Bazel files (if adding new files). Created an issue otherwise.
• While waiting for a review on your PR, please help review another open pull request to support the maintainers
• Was GenAI used to generate this PR? If so, make sure to add "Generated-by" to your commits. (See this policy for more info.)

Generated-by: Remove this if GenAI was not used.

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by and Generated-by messages.

Backports: If this is a backport, please use Rebase and Merge instead.

---

This is an automatic backport of pull request #1630 done by [Mergify](https://mergify.com).