Parameterisable Full Field Dimensions

[energy-in-joles]

Key Changes:

1. removed the class properties for Field, since Field can now come in variable sizes. These call should be made on the dataclass FieldDimensions instead, if you don't want to initialise a Field object.
2. Ensure that starting formation is well formed within the expected FieldBounds box in sim. This way, the first frame is valid immediately. This was done by normalizing formation positions anisotropically so that the exact formation positions are adjusted to the bound size.
3. Removed the use of assertions everywhere and replace with proper error handling.
4. Added pink overlay to indicate field bounds on rsim render.
5. Added resizing of field render for rsim based on the FieldDimensions provided.
   .
6. Relaxed position refiner to look at full field instead of just field bounds. This is not a major issue, as proper masking is expected from real vision. Strict vision bounding causes unintuitive and difficult to debug issues.

Render of GREAT_EXHIBITION_FIELD_DIMS with pink overlay to show FieldBounds.

Issues:

1. rsim field change is currently cosmetic only. Major reworking needs to be done to ensure the walls are moved correctly (see Entities leaving boundaries in rSim #113).
2. defense_utils.py and defense_strategy.py currently use hardcoded field coords, preventing the full customisation of FieldDimensions (see Hardcoded field coords in defense_utils.py and defense_strategy.py #114).

---

This pull request introduces a significant refactor and generalization of field geometry and formation logic across the codebase, making the system more flexible for different field sizes and configurations. The most important changes are the introduction of the new FieldBounds and FieldDimensions classes, the refactoring of the Field class to use these new abstractions, and the overhaul of the formation system to support scalable and mirrored formations. Additionally, some code cleanup and formatting improvements were made.

Field Geometry Generalization and Refactor:

• Introduced FieldBounds and FieldDimensions in utama_core/config/field_params.py. These classes encapsulate all field geometry, bounds, and derived properties, supporting both standard and custom field sizes. This replaces hardcoded field constants and provides validation and convenience methods for geometric calculations.
• Refactored the Field class in utama_core/entities/game/field.py to use FieldBounds and FieldDimensions for all geometry and property calculations, removing old class constants and related methods. All geometric queries (goal lines, defense areas, field bounds, etc.) now delegate to the new configuration classes, making the codebase more modular and adaptable. [1] [2] [3] [4]

Formations System Overhaul:

• Rewrote the formation logic in utama_core/config/formations.py to support scalable, normalized formations and mirroring for left/right teams. Added validation to ensure robots fit within bounds and do not overlap, and introduced the FormationType enum and FormationEntry type for clarity.

Code Cleanup and Formatting:

• Removed redundant is_ball_in_goal methods from Ball and GameFrame classes, as these are now superseded by the more general field abstractions. [1] [2]
• Improved formatting and clarity in utama_core/data_processing/refiners/position.py, including better multi-line argument formatting and docstring updates for filtering logic. [1] [2] [3] [4]

Configuration and Usage Updates:

• Updated the main entry point (main.py) to use the new FieldBounds initialization and to pass the correct field bounds to the StrategyRunner. Also changed the simulation mode to grsim for consistency with the new configuration.

These changes collectively make the codebase more maintainable, extensible, and robust to different field configurations, while also improving code clarity and safety.

[Copilot]

Pull request overview

This PR refactors field geometry handling to be configurable (rather than hardcoded to standard SSL dimensions), updates field/bounds validation accordingly, and wires the new abstractions through strategy runtime + vision refinement (including an option to keep out-of-bounds vision during sim/test setup).

Changes:

• Introduces FieldDimensions / FieldBounds in config.field_params (with standard + exhibition presets) and updates Field/StrategyRunner to consume them.
• Reworks bounding-box validation utilities to raise ValueError, accept full-field dimensions as parameters, and adds assert_contains.
• Adds incl_out_of_bounds_vision plumbing to the position refiner/camera combiner and defers StrategyRunner game setup into a pre-run step.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
utama_core/config/field_params.py	New canonical source for field geometry/dimensions and derived shapes.
utama_core/entities/game/field.py	Delegates all geometry (goal lines/defense areas/bounds) to FieldDimensions.
utama_core/global_utils/math_utils.py	Updates bounding-box validation + adds bounding-box containment helper.
utama_core/run/strategy_runner.py	Accepts full_field_dims, validates bounds against it, and defers game setup to pre-run.
utama_core/run/game_gater.py	Passes through out-of-bounds vision option to the position refiner during gating.
utama_core/data_processing/refiners/position.py	Adds incl_out_of_bounds_vision to refine/combine pipeline.
utama_core/strategy/common/abstract_strategy.py	Renames min-bounds hook to get_min_bounding_req and adds SpaceRequirements.
utama_core/strategy/common/init.py	Re-exports SpaceRequirements.
utama_core/strategy/examples/utils.py	CalculateFieldCenter now reads bounds from blackboard game field at setup.
utama_core/strategy/examples/one_robot_placement_strategy.py	Updates strategy requirements API usage and center calculation.
utama_core/strategy/examples/two_robot_placement.py	Updates strategy requirements API usage and center calculation.
utama_core/strategy/examples/startup_strategy.py	Renames min-bounds hook to get_min_bounding_req.
utama_core/strategy/examples/go_to_ball_ex.py	Renames min-bounds hook to get_min_bounding_req.
utama_core/strategy/examples/defense_strategy.py	Renames min-bounds hook to get_min_bounding_req.
utama_core/strategy/examples/motion_planning/simple_navigation_strategy.py	Renames min-bounds hook to get_min_bounding_req.
utama_core/strategy/examples/motion_planning/random_movement_strategy.py	Renames min-bounds hook to get_min_bounding_req.
utama_core/strategy/examples/motion_planning/oscillating_obstacle_strategy.py	Renames min-bounds hook to get_min_bounding_req.
utama_core/strategy/examples/motion_planning/multi_robot_navigation_strategy.py	Renames min-bounds hook to get_min_bounding_req.
utama_core/entities/game/game_frame.py	Removes is_ball_in_goal (expected to be handled via new field abstractions).
utama_core/entities/game/ball.py	Removes is_ball_in_goal (expected to be handled via new field abstractions).
utama_core/motion_planning/src/planning/controller.py	Removes obsolete controller implementation tied to legacy field constants.
utama_core/tests/config/test_field_dimensions.py	New tests validating geometry derivation + validation rules for FieldDimensions.
utama_core/tests/global_utils/test_math_utils.py	Updates tests for new assert_valid_bounding_box signature/exception type.
utama_core/tests/abstract_strategy/test_assertions.py	Updates field requirement assertions to new API + ValueError semantics.
utama_core/tests/strategy_runner/test_runner_misconfig.py	Updates misconfig tests for new errors + custom full-field dimensions case.
utama_core/tests/strategy_runner/test_exp_ball.py	Updates dummy strategies for new get_min_bounding_req hook name.
utama_core/tests/strategy_runner/test_error_handling.py	Adapts to StrategyRunner pre-run setup and renamed stop-repeat parameters.
utama_core/tests/strategy_runner/teleport_position_accuracy_test.py	Updates dummy strategy hook name.
utama_core/tests/strategy_runner/strat_runner_test_utils.py	Updates dummy strategy API to match new runner/strategy init flow.
utama_core/tests/strategy_runner/integration_test.py	Removes outdated integration test tied to legacy field constants.
utama_core/tests/refiners/position_unit_test.py	Switches tests to STANDARD_FIELD_DIMS.full_field_bounds.
utama_core/tests/refiners/position_refiner_integration_test.py	Switches integration test to STANDARD_FIELD_DIMS.full_field_bounds.
utama_core/tests/motion_planning/random_movement_test.py	Updates to use STANDARD_FIELD_DIMS half-length/width.
utama_core/tests/controller/test_sim_controller.py	Updates full-field bounds constant to use STANDARD_FIELD_DIMS.
utama_core/tests/strategy_examples/test_placement_coords.py	Adjusts sim teleport positions to use field bounds center.
utama_core/tests/strategy_examples/test_two_robot_placement_coords.py	Adjusts sim teleport positions and runner init ordering for bounds.

[Copilot]

Pull request overview

Copilot reviewed 37 out of 37 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 39 out of 39 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 45 out of 45 changed files in this pull request and generated 2 comments.

[fred-huang122]

questions

[fred-huang122]

get_min_bounding_req() now advertises that this strategy works on any field size, but the helpers it delegates to still hardcode standard SSL geometry (goalkeep.py, defense_utils.py, and defend_parameter.py all use fixed ±4.5, ±3.0, and ±0.5 values). On non-standard fields that will defend the wrong x-line and clamp to the wrong goal mouth. Either keep this strategy restricted to standard dimensions or thread game.field geometry through those helpers first.

[fred-huang122]

I will fix this and do a commit in another branch, as i have some other fixes as well

[energy-in-joles]

#114

[fred-huang122]

another one

[fred-huang122]

full_field_dims is only being translated into render_field_overrides here. SSLBaseEnv still instantiates RSimSSL from field_type and then reads the physical field params back from the simulator, so the underlying RSIM boundaries/physics stay on the default pitch. That makes the RSIM side of this refactor render-only for custom dimensions unless the simulator field itself is also reconfigured.

[energy-in-joles]

#112

[Copilot]

Pull request overview

Copilot reviewed 45 out of 45 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 47 out of 47 changed files in this pull request and generated no new comments.