{"id":29470064,"url":"https://github.com/talinthedev/zig-mcl","last_synced_at":"2025-07-14T12:02:34.336Z","repository":{"id":301641381,"uuid":"1009893095","full_name":"TalinTheDev/zig-mcl","owner":"TalinTheDev","description":"A MCL simulation implementation in Zig using Raylib","archived":false,"fork":false,"pushed_at":"2025-07-05T01:40:27.000Z","size":15574,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-05T02:50:42.648Z","etag":null,"topics":["localization","mcl","monte-carlo","monte-carlo-localization","monte-carlo-simulation","raylib","robotics","robotics-competition","robotics-programming","robotics-simulation","simulation","vex-robotics","vex-v5","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TalinTheDev.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-06-27T22:53:37.000Z","updated_at":"2025-07-05T01:40:31.000Z","dependencies_parsed_at":"2025-06-28T00:27:57.572Z","dependency_job_id":null,"html_url":"https://github.com/TalinTheDev/zig-mcl","commit_stats":null,"previous_names":["talinthedev/zig-mcl"],"tags_count":0,"template":false,"template_full_name":"TalinTheDev/zig-raylib-template","purl":"pkg:github/TalinTheDev/zig-mcl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TalinTheDev%2Fzig-mcl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TalinTheDev%2Fzig-mcl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TalinTheDev%2Fzig-mcl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TalinTheDev%2Fzig-mcl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TalinTheDev","download_url":"https://codeload.github.com/TalinTheDev/zig-mcl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TalinTheDev%2Fzig-mcl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265288501,"owners_count":23741195,"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","mcl","monte-carlo","monte-carlo-localization","monte-carlo-simulation","raylib","robotics","robotics-competition","robotics-programming","robotics-simulation","simulation","vex-robotics","vex-v5","zig"],"created_at":"2025-07-14T12:01:19.603Z","updated_at":"2025-07-14T12:02:34.328Z","avatar_url":"https://github.com/TalinTheDev.png","language":"Zig","readme":"# zig-mcl\n\nA MCL simulation implementation in Zig using Raylib.\n\n## What is it?\nMonte Carlo localization is a type of particle filter used in robotics to allow\nrobots to locate their position in their environment using simulated particles.\nTo read more about MCL, start off with this amazing video [Particle Filters |\nRobot Localization](https://www.youtube.com/watch?v=ydC0mE0ZYSA) (also linked in\nCredits below). Then you can read the [Wikipedia page on\nMCL](https://en.wikipedia.org/wiki/Monte_Carlo_localization) for more\ninformation.\n\nAfter that, good luck!\n\nThis is a simulation of MCL written in Zig and rendered using Raylib. The orange\ncircle (hidden at first), represents the robot's position based directly off of\nthe user's inputs. The blue circle represents this position but with an error on\nall axes, to simulate a real life robot. All the green dots represent the\nsimulated particles that the robot would be creating to run MCL and based on\nthose, the pink dot represents the position of the robot as estimated by MCL. \n\nTo move the robots around, use W/S for forward/backwards movement and A/D or\narrow keys for rotation (the small black dots on the circle represent the\nfront).\n\nA good run will eventually look like this: ![A screenshot of the simulation\nrunning](/latestRun-v2.png)\n\n### Talin's v1.0.0 Notes\nMy simulation/implementation is far from perfect and there are many, many, many\nbetter alternatives to look at if you want to just blindly copy the code. But\nthis was a fun challenge for me and I learned a lot while making it. Considering\nhow much I knew about MCL when I started 3 days ago (none), I'm pretty happy\nwith how decently okay this has turned out. But again, don't expect anything\ncrazy when you run the simulation. It runs decently well until it breaks.\nSometimes it doesn't start off great and doesn't fix itself for a long time.\nThat's okay, trust. It'll eventually find its way over to the correct position.\nMight not hold it for long but unless something comes in the way, once its on\nthe right position, it doesn't usually leave it.\n\nOh also, don't try kidnapping (teleporting it to a random position) the robot.\nYou will be disappointed.\n\nI started this with the goal to eventually use MCL in my VEXv5 team (765A)'s\nbot. Don't know if we will be doing that but the field is setup to somewhat\nresemble the field for the 2025-2026 game, Push Back (no parking spots though).\nI did add some other random obstacles around the field however to help with MCL\nworking because (and I realize this is an issue I will face with the VEX\nimplementation), the Push Back field is very symmetrical and MCL often gets\nlost.\n\nMy code, by the way, is very much not optimized because I was focusing more on\nthe MCL implementation and getting this working ASAP so some parts of this are\nquite ugly and very expensive. But, 2000 particles at 10 FPS (which I think is\nreasonable for a VEX v5 brain = ~100ms between frames) is still good enough for\nme for now.\n\n### Alex's v2.0.0 Notes\nI'm from @TalinTheDev's VEX team (765A), and I've expanded upon his\nimplementation of MCL. After way too much research on particle filters, I think\nI finally understand how it works. There are still a lot of ways to improve\nthis, but I think I've brought it up to the point where we could conceivably use\nthis for an actual VEX robot. A big thing I've changed is asteroids-style\nmovement instead of eight-way movement so that it feels more like how an actual\nrobot would move. I also think that the biggest improvement comes from the\nresampling algorithm that I used, called low-variance resampling, which you can\nsearch up. Finally, in order to handle particle degeneracy, I used the effective\nsample size (N eff) to slow down resampling. There are a couple of tuning\nconstants that will need to be adjusted in order to give the optimal\nperformance.\n\nStill don't try kidnapping (teleporting it to a random position) the robot,\nbecause you will still be disappointed. And also because I haven't implemented\nhandling the case where the particles go too far away from the robot.\n\nSome factors could affect MCL that I'm not sure how we would be able to fix if\nwe use it for VEX, like other robots on the field, irregular obstacles, and\nsymmetry, but those are problems for another time.\n\n### Alex's v2.1.0 Notes\nI've now implemented rescattering of the particles if they stray too far away\nfrom the robot (such as after kidnapping, which you can now try). I also improved\nthe raycasting math, which for some reason made the particle filter 10x faster, so\nthat's great. I've also increased the speed of the robot and framerate so the\nsimulation feels a lot smoother. Finally, I removed the extra obstacles, so now\nthere's just the VEX Push Back field. Despite the symmetry, the particle filter\nworks surprisingly well.\n\n## Running Simulation\nTo run, install Zig v0.14.0 and then run: `zig build run`.\n\nI will, at some point, upload pre-built releases executables to Github but too\nlazy at the moment.\n\n## Credits\n### Contributors\n- @TalinTheDev\n- @alex-oh205\n\n### Quick links\n  - [Particle Filters | Robot\n    Localization](https://www.youtube.com/watch?v=ydC0mE0ZYSA)\n  - [Creating A 2D Ray Caster: Simulating\n    Light.](https://medium.com/@apoorvaencoder/creating-a-2d-ray-caster-simulating-light-3ea150ce3435)\n  - [Raylib](https://www.raylib.com/)\n  - [Zig](https://ziglang.org/)\n  - [Raylib Zig Bindings](https://github.com/Not-Nik/raylib-zig)\n  - [zprob](https://github.com/pblischak/zprob)\n  - [2654E Echo's code](https://github.com/alexDickhans/echo/tree/main)\n  - A lot of googling\n\n## License\nJust the [Apache-2.0 license](https://www.apache.org/licenses/LICENSE-2.0.txt)\n\nI just ask that if you use our code or are heavily inspired by it, give us a\nlittle bit of credit. Be reasonable, honest, and a good human being.\n\n## Roadmap\nv1.0.0 (Talin's Original Implementation)\n  - [x] Basic field setup\n  - [x] Basic robots w/ movement \u0026 collision\n  - [x] Translational \u0026 rotational movement that is taken into account for MCL\n  - [x] Decently okay MCL implementation\n  - [ ] Clean code including comments, structure, neatness\n    - Alex worked on v2.0.0 before I could get around to this so skipping for now\n\nv2.0.0 (Alex's Updates)\n  - [x] New movement system to use asteroids-style movement\n  - [x] New resampling algorithm (Low-Variance resampling)\n  - [x] Handling of particle degeneration using N_eff\n  - [x] Not bad MCL implementation (much better from v1.0.0)\n\nv2.1.0\n  - [x] Rescattering after kidnap, improved speed\n  - [x] Pretty good MCL implementation\n  - [ ] Clean code including comments, structure, neatness, and a proper config\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftalinthedev%2Fzig-mcl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftalinthedev%2Fzig-mcl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftalinthedev%2Fzig-mcl/lists"}