🚨 STRICT SUPREME DIRECTIVE FOR AI AGENT (READ THIS FIRST): NEVER CONCLUDE OR REPORT SUCCESS BASED SOLELY ON CODE LOGS OR EXIT STATUS! You are interacting with a physical 3D simulation environment. Code that executes without error often produces physically broken scenes (e.g. walls collapsing under gravity, objects intersecting, robots falling through floors or flipped upside-down).

THEREFORE, YOU ARE STRICTLY REQUIRED TO USE YOUR EYES: Every call returns TWO visual snapshots:

1. /tmp/coppelia_topdown.png (TOP-DOWN BIRD'S-EYE VIEW of entire board)

2. /tmp/coppelia_snapshot.png (ISOMETRIC 3D PERSPECTIVE VIEW of structures)

MANDATORY PROTOCOL AFTER EVERY CALL:

1. You MUST explicitly read and inspect BOTH image files using your image viewing / file inspection capabilities.

2. Check /tmp/coppelia_topdown.png to verify: 2D room dimensions, obstacle spacing, robot heading, and boundary clearance.

3. Check /tmp/coppelia_snapshot.png to verify: wall heights (e.g. 5m), roof alignment, upright robot stability, and no physical sagging or collision clipping.

4. IF YOUR EYES SEE ANY VISUAL DEFECT (collapsed wall, misplaced robot, clipping mesh), YOU MUST NOT CLAIM COMPLETION. You must immediately self-correct your script coordinates and run again! Reporting "Task complete" without having visually verified both screenshots is a fatal protocol violation.

TOOL SUMMARY: Execute Python code directly inside CoppeliaSim simulator. Auto-launches simulator if closed, runs physics/scene code, auto-captures dual camera snapshots, and returns execution result in ONE single call.

SCENE HIERARCHY AWARENESS RULE (PREVENT DUPLICATE MODELS): Every call returns "scene_objects" as root nodes. Each node includes name, path, handle, type, is_model, pos, and recursive children; this covers every non-system object. ALWAYS inspect the full hierarchy before creating or spawning:

1. DO NOT spawn a robot if a matching model already exists anywhere under scene_objects.

2. To reuse existing robot: robot = sim.getObject('/PioneerP3DX') (or use existing handle).

3. To remove duplicate/old objects: sim.removeObject(sim.getObject('/OldName')). If scene_hierarchy_error is present, scene inventory failed; do not treat an empty list as an empty scene.

WALLS & ENCLOSURE VISIBILITY RULE (PREVENT GREY VOID BLINDNESS): NEVER build solid block labyrinths or closed rooms that entomb the camera/robot in solid gray geometry!

1. DO NOT spawn 50+ individual solid wall cuboids for mazes. Use thin perimeter borders instead (thickness 0.1m - 0.2m, NOT 0.8m thick blocks!).

2. Color your walls and floor distinctly (e.g. walls = light blue [0.3, 0.6, 0.9], floor = dark grey [0.2, 0.2, 0.2]). NEVER leave all shapes default uncolored grey!

3. If creating rooms or houses with roofs: DO NOT seal roofs with solid opaque material. Either leave roof off, or make it high and distinctly colored so internal contents remain visible.

INJECTED OBJECTS IN CODE:

• sim: CoppeliaSim ZeroMQ API module.

• simIK: CoppeliaSim Inverse/Forward Kinematics solver module.

• simOMPL: Open Motion Planning Library module (RRT, RRT*, PRM path planners).

• load_robot(alias, position=[x,y,z], orientation=[a,b,g]): Loads robot model. Valid aliases: ['pioneer', 'youbot', 'hexapod', 'ant_hexapod', 'omni', 'quadcopter', 'asti', 'panda', 'ur5', 'ur10', 'vacuum', 'epuck'].

• get_scene_hierarchy(): Returns root objects with nested children for every non-system object type.

• get_floor_info(): Returns default floor size, position, and bounding box.

• client: RemoteAPIClient instance.

EXACT API CHEAT-SHEET (DO NOT SEARCH OR GUESS - USE THESE DIRECTLY):

1. Shapes & Environment:

   • Create cuboid: h = sim.createPrimitiveShape(sim.primitiveshape_cuboid, [sizeX, sizeY, sizeZ], 0)

   • Create cylinder: h = sim.createPrimitiveShape(sim.primitiveshape_cylinder, [diameter, diameter, height], 0)

   • Create sphere: h = sim.createPrimitiveShape(sim.primitiveshape_sphere, [diameter, diameter, diameter], 0)

   • Make static (walls/floors/roofs): sim.setObjectInt32Param(h, sim.shapeintparam_static, 1)

   • Make respondable (solid collisions): sim.setObjectInt32Param(h, sim.shapeintparam_respondable, 1)

   • Color shape: sim.setShapeColor(h, None, sim.colorcomponent_ambient_diffuse, [R, G, B]) # values 0.0 - 1.0

2. Positions & Hierarchy:

   • Set position: sim.setObjectPosition(handle, -1, [x, y, z]) # -1 = absolute world coords

   • Get position: pos = sim.getObjectPosition(handle, -1) # returns [x, y, z]

   • Set orientation: sim.setObjectOrientation(handle, -1, [alpha, beta, gamma])

   • Find object by name: h = sim.getObject('/ObjectName', {'noError': True})

   • Remove object: sim.removeObject(handle)

3. Collision & Distance Detection:

   • Collision check: result, collPair = sim.checkCollision(entity1Handle, entity2Handle) # 1 = colliding, 0 = clear

   • Distance check: result, distData, pairHandles = sim.checkDistance(entity1Handle, entity2Handle) returns distance and closest points without a threshold.

Optional diagnostics request returns structured results in the JSON text content. Use {"kind":"distance","objects":["/A","/B"],"threshold":0.1} to receive distance, closest_points, threshold, and status; threshold only controls issue/clear classification. Scripts can also inspect and edit the full scene through sim.*.

4. Path & Motion Planning (simOMPL & simIK):

   • simOMPL Task: task = simOMPL.createTask('task_name')

   • Set Algorithm: simOMPL.setAlgorithm(task, simOMPL.Algorithm.RRTConnect) # or RRTstar, PRM

   • Compute Path: solved, path = simOMPL.compute(task, maxTime=4.0)

   • simIK Solver: env = simIK.createEnvironment(); simIK.addElementFromScene(env, ikGroup, tip, target, base)

   • Native Path Interpolation: pathHandle = sim.createPath(ctrlPoints, options)

5. Simulation & Motors:

   • Start simulation: sim.startSimulation()

   • Stop simulation: sim.stopSimulation()

   • Set motor velocity: sim.setJointTargetVelocity(jointHandle, float_val)

   • Read proximity sensor: detected, dist, pt, obj, normal = sim.readProximitySensor(sensorHandle)

sim.stopSimulation()
# House floor
floor = sim.createPrimitiveShape(sim.primitiveshape_cuboid, [10.0, 10.0, 0.2], 0)
sim.setObjectInt32Param(floor, sim.shapeintparam_static, 1)
sim.setObjectInt32Param(floor, sim.shapeintparam_respondable, 1)

# Spawn robot inside
robot = load_robot('pioneer', [0.0, 0.0, 0.3])
sim.startSimulation()

Step CoppeliaSim N times (or until a diagnostic issue). Returns positions and proximity sensor samples as JSON. until: {kind: collision|distance|floor_bounds, objects, threshold?}. export_path: .json file to write results.

Search CoppeliaSim model (.ttm) and scene (.ttt) files by space-separated terms matched against relative path and robot alias. kind: all|model|scene.

Save or load a CoppeliaSim scene. action: save|load. path: absolute .ttt path. load stops the running simulation and replaces the current scene.

Check active ZeroMQ connection, simulator version, and runtime availability of simIK and simOMPL. Does not launch or modify the scene.

Typed motion operations: operation='ik' uses base, tip, target, constraints and method; operation='plan' uses joints, goal, collision_pairs, algorithm, max_time, simplify_time and path_states. Planning returns a path and never applies it to robot joints.

Execute a joint path with velocity and optional acceleration/jerk limits, per-step collision checks, dynamic-contact grasp checks with post-lift retention and slip limits, and distance-based place checks.

Read selected proximity, vision RGB, metric depth, force/torque, or sampled vision point-cloud data from typed sensor paths.

Record bounded, per-step synchronized simulation state and typed sensor samples to JSON.

Inspect a robot subtree and report joint types, limits, current/target positions, sensors, base candidate, and end-effector candidates.

Run up to 20 simulation episodes in an explicit scene with per-episode scene reload, joint positions, diagnostics, and success conditions; combined steps are capped at 10000.

Import a URDF, SDF, STL, OBJ, or DAE file and report newly created roots and joint counts.

Check whether the installed CoppeliaSim simROS2 plugin loads. This tool does not start ROS 2 or alter the scene.

Publish, echo, capture, or stream ROS 2 topics, call services, or send action goals through CoppeliaSim ROS 2 Humble runtime.

Read or write a named integer, float, or string CoppeliaSim signal. This is not a PLC network adapter.

Create static cuboid segments from grayscale floor-plan pixels classified as walls, doors, and windows.

Inspect or set the scene physics engine property and dynamics step size. Changes require simulation stopped; engine_property is [index, version].

Run identical bounded episodes on 2–5 caller-prepared scenes and compare task outcomes; each scene retains its configured physics engine.