{"id":28396890,"url":"https://github.com/anker661/mcl-simulator","last_synced_at":"2026-05-02T05:04:35.400Z","repository":{"id":295585702,"uuid":"980235453","full_name":"ANKer661/MCL-Simulator","owner":"ANKer661","description":"A Monte Carlo Localization (MCL) simulator in Python. Includes clear visualization system with MP4 output and particle confidence highlighting.","archived":false,"fork":false,"pushed_at":"2025-06-04T14:15:50.000Z","size":40253,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-27T13:40:14.150Z","etag":null,"topics":["localization","monte-carlo","monte-carlo-localization","particle-filter","robotics"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ANKer661.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-08T19:45:08.000Z","updated_at":"2025-06-04T14:15:52.000Z","dependencies_parsed_at":"2025-05-26T11:10:35.407Z","dependency_job_id":null,"html_url":"https://github.com/ANKer661/MCL-Simulator","commit_stats":null,"previous_names":["anker661/mcl-simulator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ANKer661/MCL-Simulator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ANKer661%2FMCL-Simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ANKer661%2FMCL-Simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ANKer661%2FMCL-Simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ANKer661%2FMCL-Simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ANKer661","download_url":"https://codeload.github.com/ANKer661/MCL-Simulator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ANKer661%2FMCL-Simulator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263271501,"owners_count":23440396,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["localization","monte-carlo","monte-carlo-localization","particle-filter","robotics"],"created_at":"2025-05-31T23:38:38.105Z","updated_at":"2026-05-02T05:04:35.395Z","avatar_url":"https://github.com/ANKer661.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Monte Carlo Localization (MCL) Robot Simulation\n\nCourse project, USI, Robotics, 2025 Spring.\n\nA Python implementation of Monte Carlo Localization for robot navigation in 2D environments with obstacles. This project simulates a robot using particle filters to estimate its position and orientation while navigating through a known map.\n\n## Features\n\n- **Monte Carlo Localization Algorithm**: Particle filter-based localization with configurable parameters\n- **Robot Simulation**: Realistic robot movement with noise modeling\n- **Sensor Simulation**: Distance sensor with measurement noise\n- **Efficient Visualization**: High-resolution animation of robot and particle states and movement in resonable time\n- **Flexible World Maps**: JSON-based map definition with obstacles\n\n## Project Structure\n\n![Architecture](figs/architect.png)\n\n```\n├── simulator.py       # Main simulation engine, control and visualization logic\n├── robot.py           # Robot and particle group implementations\n├── mcl.py             # Monte Carlo Localization algorithm\n├── worldmap.py        # World map handling\n├── assets/            # Asset folder containing map definitions and related images\n│   ├── map1.json\n│   ├── map2.json\n│   ├── map1_preview.png\n│   └── map2_preview.png\n└── README.md          # This file\n```\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.12** (recommended)\n- Required Python packages:\n  - numpy\n  - matplotlib\n  - shapely\n  - tqdm\n  - ffmpeg\n\nMake sure these packages are installed in your environment before running the examples.\n\nTo get started:\n```bash\ngit clone https://github.com/ANKer661/MCL-Simulator.git\ncd MCL-Simulator\ncode .  # or open the project with your preferred editor\n```\n\n### Basic Usage\n\nRefer to `noise.py` or `symmetric.py` in the `usage_example` directory.\nTo generate a video of the MCL process, run the following command:\n\n```bash\npython -m usage_example.symmetric\n# or python -m usage_example.noise\n```\n\n### Map Creation\n\nSee `usage_example/map_creation.ipynb` for an example of map creation.\n\n## Configuration Parameters\n\n### Simulator Parameters\n\n| Parameter                        | Description                                  | Default         |\n|----------------------------------|----------------------------------------------|-----------------|\n| `world_map`                      | World map object                             |                 |\n| `control_node`                   | Motion control input                         |                 |\n| `num_particles`                  | Number of particles in the filter            |                 |\n| `init_x`, `init_y`, `init_theta` | Robot's initial position and orientation     |                 |\n| `robot_radius`                   | Robot's physical radius                      |                 |\n| `sample_radius`                  | Particle sampling radius                     |                 |\n| `sensor_max_distance`            | Maximum sensor range                         | 100             |\n| `likelyhood_sigma`               | Likelihood function standard deviation       | 10              |\n| `measurement_sigma`              | Sensor measurement noise                     | 1               |\n| `ema_alpha`                      | Exponential moving average smoothing factor  | 0.9             |\n| `v_sigma`, `w_sigma`             | Motion model noise parameters                | 0.1             |\n| `resample_factor`                | Resampling threshold (fraction of particles) | 0.5             |\n| `resample_random_probability`    | Random resampling probability                | 0.1             |\n| `fps`                            | Frames per second for simulation rendering   | 30              |\n| `speedup`                        | Simulation speed multiplier                  | 1               |\n| `dpi`                            | DPI for video rendering                      | 100             |\n| `save_file_name`                 | Output video file name                       | \"simulation.mp4\"|\n| `add_size_bar`                   | Whether to render a size scale bar           | False           |\n| `random_seed`                    | Random seed for reproducibility              | 0               |\n\n\n### Control Node Parameters\n\n| Parameter       | Description                           | Default |\n| --------------- | ------------------------------------- | ------- |\n| `max_linear`    | Maximum linear velocity               | 10.0    |\n| `max_angular`   | Maximum angular velocity              | 2.0     |\n| `safe_distance` | Obstacle avoidance distance           | 30      |\n| `turning_step`  | Steps to turn when avoiding obstacles | 1000    |\n\n\n## Animation Output\n\nThe simulator generates:\n- **MP4 Animation**: Real-time visualization of the MCL process\n\n### Visualization Elements\n\n![Screenshot of Produced Animation](figs/step_500.png)\n\n- **Blue Circle**: Real robot position and orientation\n- **Red/Gray Particles**: Particle filter estimates\n  - Red: High-confidence particles (survived ≥10 resampling cycles)\n  - Gray: Regular particles\n  - Transparency: Particle weight/confidence\n- **Gray Areas**: Free space.\n- **White Areas**: Obstacle.\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanker661%2Fmcl-simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanker661%2Fmcl-simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanker661%2Fmcl-simulator/lists"}