********
Showcase 
********

This page shows some uses of Pymunk. If you also have done something using 
Pymunk please let me know and I can add it here!

Games
=====

.. list-table:: 
    :widths: 40 60

    * - .. image:: _static/guide-the-ball.png
      - `Guide The Ball <https://github.com/francisA88/Guide-The-Ball-1>`_

        :subscript:`made by Francis Ali. Retrieved 2020-03-30`

        A game combining Pymunk with Kivy that runs on Android mobiles!

        In Guide The Ball the task is to guide a ball through 19 
        exciting and challenging levels!

    * - .. image:: _static/My_Sincerest_Apologies.png
      - `My Sincerest Apologies <https://pyweek.org/e/wasabi24/>`_
      
        :subscript:`made by The Larry and Dan show (mauve, larry). Retrieved 
        2018-10-25`

        **Winner of PyWeek 24** (Overall Team Entry)
        
        A game of fun, shooting, and "I'm sorry to put you through this".

        A fabricator robot on Mars was supposed to make a bunch of robots! 
        But it got lazy and made robots that could make other robots. And 
        it made them smarter than they should have been. Now they've all 
        gone off and hidden away behind various tanks and computers. 
        
        Happily, he knew how to construct *you*, a simple fighting robot. 
        It's your job to clean out each area!
        
        See Daniel Popes teardown `here <http://mauveweb.co.uk/posts/2018/03/my-sincerest-apologies-teardown.html>`_
        for additional details

    * - .. image:: _static/beneath-the-ice.png
      - `Beneath the Ice <https://pyweek.org/e/chimera22/>`_

        :subscript:`made by Team Chimera (mit-mit, Lucid Design Ar). Retrieved 
        2016-09-25`

        **Winner of PyWeek 22** (Overall Team Entry)

        Beneath the Ice is a submarine exploration game and puzzle solving 
        adventure! Uncover a mysterious pariah who can't let you discover his 
        secrets, who can't let you in! Team Chimera take 3!  

    * - .. image:: _static/invisipin.png
      - `Invisipin <https://pyweek.org/e/Tee-py20/>`_  
        
        :subscript:`made by Tee. Retrieved 2016-01-25`

        **Winner of PyWeek 20** (Overall Individual Entry)
        
        A pachinko-like puzzle game. Play some balls and watch their movement 
        carefully (i.e. collect data) to reconstruct the board!

    * - .. image:: _static/angry-birds-python.png
      - `Angry Birds in Python <https://github.com/estevaofon/angry-birds-python>`_

        :subscript:`made by Estevao Fonseca. Retrieved 2016-10-30`

        Angry Birds game written in python using pygame and pymunk 

    * - .. image:: _static/SubTerrex.png
      - `SubTerrex <http://www.pygame.org/project-SubTerrex-2389-.html>`_  
        
        :subscript:`made by Paul Paterson. Retrieved 2016-01-25`

        A cave exploration game where you explore caves by descending into them 
        on ropes.

Non-Games
=========

.. list-table::
    :widths: 40 60 

    * - .. image:: _static/manim-physics.png
      - `manim-physics <https://github.com/Matheart/manim-physics>`_

        :subscript:`made by pdcxs, Matheart & Iced-Tea3. Retrieved 2021-07-05`

        This is a 2D physics simulation plugin that allows you to generate 
        complicated scenes in various branches of Physics such as rigid 
        mechanics, electromagnetism, wave etc.

    * - .. image:: _static/ar-physics.jpg
      - `Computer Vision and Phyiscs <https://amirabbasasadi.github.io/vision/python/2021/06/03/having-fun-with-computer-vision-and-physics.html>`_

        :subscript:`made by Amirabbas Asadi. Retrieved 2021-06-25`

        Just playing with OpenCV + a hand tracking model + a physics engine :)

        A very cool blog post (and video) explaining how to combine computer 
        vision and a little physics to create a simple environment for 
        Augmented Reality. In the blog Amirabbas Asadi shows how OpenCV, 
        Mediapipe and Pymunk can be combined to make a app where simulated 
        balls bounce on the hand of the user.

    * - .. image:: _static/galtonBoard.png
      - `Galton Board <https://github.com/nav9/GaltonBoard>`_

        :subscript:`made by Nav. Retrieved 2021-05-17`

        The quincunx (also known as a Galton board) created in Pymunk.
        
        This is a Galton Board simulation programmed to run in three modes, 
        with medium sized balls, small balls and large balls. A bit of 
        randomness had to be added to the ball elasticity and initialization 
        positions, to aid with proper interaction with objects.
        
    * - .. image:: _static/PySimpleGUI.png
      - `PySimpleGUI Desktop Demo <https://github.com/PySimpleGUI/PySimpleGUI>`_

        :subscript:`made by PySimpleGUI/Mike. Retrieved 2020-10-13`

        Demo of using PySimpleGUI together with Pymunk to create bouncing
        balls directly on the desktop, thanks to a transparent container 
        window.

    * - .. image:: _static/legged_robot.png
      - `Legged robot using differential evolution and perception <https://www.youtube.com/watch?v=n-OCy6ToLsU&feature=youtu.be>`_

        :subscript:`made by Nav. Retrieved 2020-08-20`

        Legged robot first using Differential Evolution to navigate terrain 
        and then learning to recognise the world via perception from its 
        senses.

    * - .. image:: _static/ambient-chimes.png
      - `Simulation of ambient chimes | Circle in a hexagon <https://youtu.be/7MRJS8ZV9VA>`_

        :subscript:`made by Jan Abraham.Retrieved 2019-11-17`

        An ambient piano chord produced by the simulation of a bouncing ball. 
        The calculations were carried out using pymunk library.
        Tuning: Kirnberger III

    * - .. image:: _static/aimoveneat.png
      - `I teach AI to move with using NEAT <https://youtu.be/ipWIH1g9DSw>`_

        :subscript:`made by Cheesy AI. Retrieved 2019-11-17`

        Recently I learned Pymunk 2d physics library.
        It is very cool so with that I made 2d Humanoid for my AI.
        Today I'm going to teach AI to move forward with NEAT.
        NEAT is a genetic algorithm for the generation of evolving artificial 
        neural networks.
        Results are quite weird but it will be fun.
        Have fun!

    * - .. image:: _static/carconf.png
      - `Car Configuration with Differential Evolotion <https://youtu.be/7ok4ESgrKg0>`_

        :subscript:`made by Nav. Retrieved 2019-05-05`

        Among the simplest AI algorithms: Differential Evolution. Brought to 
        life with Pymunk and Pygame. Each car has an objective of reaching the 
        end of the track, but has only 15 seconds to do so. They explore the 
        multidimensional search space of vehicle speed, chassis width, chassis 
        height and wheel radius, to find a variety of configurations among 
        which few are successful in helping the car cross the track. 

        Source code available at github at https://github.com/nav9/evolutionaryCarRace

    * - .. image:: _static/virtuaplant.png
      - `VirtuaPlant <https://wroot.org/projects/virtuaplant/>`_

        :subscript:`made by Jan Seidl. Retrieved 2018-06-13`

        VirtuaPlant is a Industrial Control Systems simulator which adds a 
        "similar to real-world control logic" to the basic "read/write tags" 
        feature of most PLC simulators. Paired with a game library and 2d 
        physics engine, VirtuaPlant is able to present a GUI simulating the 
        "world view" behind the control system allowing the user to have a 
        vision of the would-be actions behind the control systems.

    * - .. image:: _static/arcade-library.png
      - `The Python Arcade Library <http://arcade.academy/examples/index.html>`_

        :subscript:`made by Paul. Retrieved 2018-03-05`

        Arcade is an easy-to-learn Python library for creating 2D video games. 
        It is not directly tied to Pymunk, but includes a number of examples 
        and helper classes to use Pymunk physics from a Arcade application.
        
    * - .. image:: _static/billiARds.png
      - `billiARds  A Game of Augmented Reality Pool 
        <https://youtu.be/5ft3SDvuhgw>`_

        :subscript:`made by Alex Baikovitz. Retrieved 2017-05-21`

        Alex built billiARds for his 15-112 (Fundamentals of Programming and 
        Computer Science) term project at Carnegie Mellon University.
        Made in Python3 using OpenCV, Pygame, and Pymunk. Users can simply use 
        a pool cue stick and run the program on any ordinary surface.

    * - .. image:: _static/pyphysicssandbox.png
      - `pyPhysicsSandbox <https://github.com/jshaffstall/PyPhysicsSandbox>`_

        :subscript:`made by Jay Shaffstall. Retrieved 2017-01-01`

        pyPhysicsSandbox is a simple wrapper around Pymunk that makes it easy 
        to write code to explore 2D physics simulations. It's intended for use 
        in introductory programming classrooms. 

    * - .. image:: _static/carrom-rl.png
      - `Carrom Simulation <https://github.com/samiranrl/Carrom_rl>`_ 
    
        :subscript:`made by Samiran Roy. Retrieved 2016-10-27`

        An open source Carrom Simulator interface for testing 
        intelligent/learning agents. It provides an interface that allows 
        you to design agents that that play carrom. It is built in python, 
        using pygame + pymunk. This is the course project for 
        CS 747 - Foundations of Intelligent and Learning Agents, taught by 
        Prof. Shivaram Kalyanakrishnan at IIT Bombay.

    * - .. image:: _static/reinforcement-learning-car.png
      - `Self Driving Car <https://github.com/harvitronix/reinforcement-learning-car>`_
        
        :subscript:`made by Matt Harvey. Retrieved 2016-08-07`
        
        A project that trains a virtual car to how to move an object around a 
        screen (drive itself) without running into obstacles using a type of 
        reinforcement learning called Q-Learning.         
    

Papers / Science
================

Pymunk has been used or referenced in a number of scientific papers.

List of papers which has used or mentioned Pymunk:

#. Enander, Jonas MD, Gerald E. Loeb, Henrik Jorntell, Adam M. Jones, Matthieu Kirkland, and Jordan Hurless. 
   "A Model for Self-Organization of Sensorimotor Function: The Spinal Monosynaptic Loop." 
   bioRxiv (2021).

#. Skalnik, Christopher J., Eran Agmon, Ryan K. Spangler, Lee Talman, Jerry H. Morrison, Shayn M. Peirce, and Markus W. Covert. 
   "Whole-colony modeling of Escherichia coli." 
   bioRxiv (2021).

#. Zakka, Kevin, Andy Zeng, Pete Florence, Jonathan Tompson, Jeannette Bohg, and Debidatta Dwibedi. 
   "XIRL: Cross-embodiment Inverse Reinforcement Learning." 
   arXiv preprint arXiv:2106.03911 (2021).

#. Gerstenberg, Tobias, Max Siegel, and Joshua Tenenbaum. 
   "What happened? Reconstructing the past through vision and sound." 
   (2021).

#. Liu, Lucy, Gary Choi, and L. Mahadevan. 
   "Quasicrystal kirigami." 
   arXiv preprint arXiv:2104.13399 (2021).
 
#. Delucia, Marco, Anita Catapano, Marco Montemurro, and Jérôme Pailhès. 
   "Pre-stress state in cork agglomerates: simulation of the compression moulding process." 
   International Journal of Material Forming (2021): 1-14.
 
#. Semage, Buddhika Laknath, Thommen George Karimpanal, Santu Rana, and Svetha 
   Venkatesh. 
   "Intuitive Physics Guided Exploration for Sample Efficient Sim2real Transfer." 
   arXiv preprint arXiv:2104.08795 (2021).
 
#. Dhruv, Akshit J., Reema Patel, and Nishant Doshi. 
   "Python: The Most Advanced Programming Language for Computer Science Applications." 
   (2021).
 
#. Welle, Michael C., Anastasiia Varava, Jeffrey Mahler, Ken Goldberg, Danica Kragic, and Florian T. Pokorny. 
   "Partial caging: a clearance-based definition, datasets, and deep learning." 
   Autonomous Robots (2021): 1-18.
 
#. Ji, Hao, and Yan Jin. 
   "Designing Self-Assembly Systems with Deep Multiagent Reinforcement Learning."
 
#. Mori, Hiroki, Masayuki Masuda, and Tetsuya Ogata. 
   "Tactile-based curiosity maximizes tactile-rich object-oriented actions even without any extrinsic rewards." 
   In 2020 Joint IEEE 10th International Conference on Development and 
   Learning and Epigenetic Robotics (ICDL-EpiRob), pp. 1-7. IEEE, 2020.
 
#. Jiang, Lincheng. 
   "A Computational Method to Generate One-story Floor Plans for Nursing Homes Based on Daylight Hour Potential and Shortest Path of Circulations." 
   (2020).
 
#. Chen, Ricky TQ, Brandon Amos, and Maximilian Nickel. 
   "Learning Neural Event Functions for Ordinary Differential Equations." 
   arXiv preprint arXiv:2011.03902 (2020).
 
#. Jain, Ayush, Andrew Szot, and Joseph J. Lim. 
   "Generalization to New Actions in Reinforcement Learning." 
   arXiv preprint arXiv:2011.01928 (2020).
 
#. Petitgirard, Julien, Tony Piguet, Philippe Baucour, Didier Chamagne, Eric 
   Fouillien, and Jean-Christophe Delmare. 
   "Steady State and 2D Thermal Equivalence Circuit for Winding Heads—A New Modelling Approach." 
   Mathematical and Computational Applications 25, no. 4 (2020): 70.
   
#. Hook, Joosep, Seif El-Sedky, Varuna De Silva, and Ahmet Kondoz. 
   "Learning data-driven decision-making policies in multi-agent environments for autonomous systems." 
   Cognitive Systems Research 65 (2021): 40-49.
 
#. Matthews, Elizabeth A., and Juan E. Gilbert. 
   "ATLAS CHRONICLE: DEVELOPMENT AND VERIFICATION OF A SYSTEM FOR PROCEDURAL GENERATION OF STORY-DRIVEN GAMES."
 
#. Ipe, Navin. 
   "Context and event-based cognitive memory constructs for embodied intelligence machines."
    
#. Ipe, Navin. 
   "An In-Memory Physics Environment as a World Model for Robot Motion Planning." 
   (2020).
 
#. Li, Yunzhu, Antonio Torralba, Animashree Anandkumar, Dieter Fox, and 
   Animesh Garg. 
   "Causal Discovery in Physical Systems from Videos." 
   arXiv preprint arXiv:2007.00631 (2020).
 
#. Suh, H. J., and Russ Tedrake. 
   "The Surprising Effectiveness of Linear Models for Visual Foresight in 
   Object Pile Manipulation." 
   arXiv preprint arXiv:2002.09093 (2020).
 
#. Vos, Bastiaan. 
   "The Sailing Tug: A feasibility study on the application of Wind-Assisted 
   towing of the Thialf." 
   (2019).
 
#. Wong, Eric C. 
   "Example Based Hebbian Learning may be sufficient to support Human 
   Intelligence." 
   bioRxiv (2019): 758375.
 
#. Manoury, Alexandre, and Cédric Buche. 
   "Hierarchical Affordance Discovery using Intrinsic Motivation." 2019.
 
#. Mounsif, Mehdi, Sebastien Lengagne, Benoit Thuilot, and Lounis Adouane. 
   "Universal Notice Network: Transferable Knowledge Among Agents." 
   In 2019 6th International Conference on Control, Decision and Information 
   Technologies (CoDIT), pp. 563-568. IEEE, 2019.
 
#. Du, Yilun, and Karthik Narasimhan. 
   "Task-Agnostic Dynamics Priors for Deep Reinforcement Learning." 
   In International Conference on Machine Learning, pp. 1696-1705. 2019.
 
#. Siegel, Max Harmon. 
   "Compositional simulation in perception and cognition." 
   PhD diss., Massachusetts Institute of Technology, 2018.
 
#. Caselles-Dupré, Hugo, Louis Annabi, Oksana Hagen, Michael Garcia-Ortiz, and 
   David Filliat. 
   "Flatland: a Lightweight First-Person 2-D Environment for Reinforcement Learning." 
   arXiv preprint arXiv:1809.00510 (2018).
 
#. Yingzhen, Li, and Stephan Mandt. 
   "Disentangled Sequential Autoencoder." 
   In International Conference on Machine Learning, pp. 5656-5665. 2018.
 
#. Melnik, Andrew. 
   "Sensorimotor Processing in the Human Brain and in Cognitive Architectures." 
   (2018).
 
#. Li, Yingzhen, and Stephan Mandt. 
   "A Deep Generative Model for Disentangled Representations of Sequential Data." 
   arXiv preprint arXiv:1803.02991 (2018).
 
#. Hongsuk Yi, Eunsoo Park and Seungil Kim (이홍석, 박은수, and 김승일.)
   "Deep Reinforcement Learning for Autonomous Vehicle Driving" 
   ("자율주행자동차 주행을 위한 심화강화학습.")
   2017 Korea Software Engineering Conference 
   (한국정보과학회 학술발표논문집 (2017): 784-786.)
 
#. Fraccaro, Marco, Simon Kamronn, Ulrich Paquet, and Ole Winther. 
   "A Disentangled Recognition and Nonlinear Dynamics Model for Unsupervised 
   Learning." 
   arXiv preprint arXiv:1710.05741 (2017).
 
#. Kister, Ulrike, Konstantin Klamka, Christian Tominski, and Raimund Dachselt. 
   "GraSp: Combining Spatially‐aware Mobile Devices and a Display Wall for Graph 
   Visualization and Interaction." 
   In Computer Graphics Forum, vol. 36, no. 3, pp. 503-514. 2017.
 
#. Kim, Neil H., Gloria Lee, Nicholas A. Sherer, K. Michael Martini, Nigel 
   Goldenfeld, and Thomas E. Kuhlman. 
   "Real-time transposable element activity in individual live cells." 
   Proceedings of the National Academy of Sciences 113, no. 26 (2016): 7278-7283.
 
#. Baheti, Ashutosh, and Arobinda Gupta. 
   "Non-linear barrier coverage using mobile wireless sensors." 
   In Computers and Communications (ISCC), 2017 IEEE Symposium on, pp. 804-809. 
   IEEE, 2017.
 
#. Espeso, David R., Esteban Martínez-García, Victor De Lorenzo, and Ángel 
   Goñi-Moreno. 
   "Physical forces shape group identity of swimming Pseudomonas putida cells." 
   Frontiers in Microbiology 7 (2016).
 
#. Goni-Moreno, Angel, and Martyn Amos. 
   "DiSCUS: A Simulation Platform for Conjugation Computing." 
   In International Conference on Unconventional Computation and Natural 
   Computation, pp. 181-191. Springer International Publishing, 2015.
 
#. Amos, Martyn, et al. 
   "Bacterial computing with engineered populations." 
   Phil. Trans. R. Soc. A 373.2046 (2015): 20140218.
 
#. Crane, Beth, and Stephen Sherratt. 
   "rUNSWift 2D Simulator; Behavioural Simulation Integrated with the rUNSWift 
   Architecture." 
   UNSW School of Computer Science and Engineering (2013).
 
#. Miller, Chreston Allen. 
   "Structural model discovery in temporal event data streams."
   Diss. Virginia Polytechnic Institute and State University, 2013.
 
#. Pumar García, César. 
   "Simulación de evolución dirigida de bacteriófagos en poblaciones de bacterias 
   en 2D." 
   (2013).
 
#. Simoes, Manuel, and Caroline GL Cao. 
   "Leonardo: a first step towards an interactive decision aid for port-placement 
   in robotic surgery." 
   Systems, Man, and Cybernetics (SMC), 2013 IEEE International Conference on. 
   IEEE, 2013.
 
#. Goni-Moreno, Angel, and Martyn Amos. 
   "Discrete modelling of bacterial conjugation dynamics." 
   arXiv preprint arXiv:1211.1146 (2012).
 
#. Matthews, Elizabeth A. 
   "ATLAS CHRONICLE: A STORY-DRIVEN SYSTEM TO CREATE STORY-DRIVEN MAPS."
   Diss. Clemson University, 2012.
 
#. Matthews, Elizabeth, and Brian Malloy. 
   "Procedural generation of story-driven maps." 
   Computer Games (CGAMES), 2011 16th International Conference on. IEEE, 2011.
 
#. Miller, Chreston, and Francis Quek. 
   "Toward multimodal situated analysis." 
   Proceedings of the 13th international conference on multimodal interfaces. 
   ACM, 2011.
 
#. Verdie, Yannick. 
   "Surface gesture & object tracking on tabletop devices."
   Diss. Virginia Polytechnic Institute and State University, 2010.
 
#. Agrawal, Vivek, and Ryan Kerwin. 
   "Dynamic Robot Path Planning Among Crowds in Emergency Situations."

  
List last updated 2021-06-22. If something is missing or wrong, please contact 
me!

.. (list made using "Chicago" style citation)

Cite Pymunk
-----------

If you use Pymunk in a published work and want to cite it, below is a bibtex
example. Feel free to modify to fit your style. (Make sure to modify the 
version number if included.):

.. code-block:: bibtex

  @misc{pymunk,
    author = {Victor Blomqvist},
    title = {Pymunk: A easy-to-use pythonic rigid body 2d physics library (version 6.0.0)},
    year = {2007},
    url = {https://www.pymunk.org},
  }


