I think it's ready :)

.gitignore

@@ -0,0 +1,132 @@
+.idea
+.idea/*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Dalya Gartzman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,201 @@
+# PyGraphicsGui
+
+A "[CookieCutter](https://github.com/cookiecutter/cookiecutter)" for a Pythonic GUI with custom graphics - 
+clone this to jump-start your project and learn how to integrate between [ModernGL](https://github.com/ModernGL/ModernGL) 
+and [Tkinter](https://docs.python.org/3/library/Tkinter.html) on Python3.6.
+
+![Wondering what happens when tou find Waldo? You will have to find Waldo yourself!](../master/data/WhereIsWaldoDemo.gif)
+
+Wondering what happens when you find Waldo? You will have to find Waldo yourself!
+
+*This project has been tested on Windows10, Ubuntu18.04 and macOS Mojave.*
+
+
+## Table of Contents
+
+
+* [Starting Your Own Project](#starting-your-own-project)
+
+* [PyGraphicsGui Capabilities](#pygraphicsgui-capabilities)
+
+* [About This Project - The Technical Side](#about-this-project---the-technical-side)
+
+    + [The Main Folder](#the-main-folder)
+
+    + [The Source Folder](#the-source-folder)
+
+    + [The Graphic Engine Folder](#the-graphic-engine-folder)
+
+* [About This Project - My Personal Story](#about-this-project---my-personal-story)
+
+
+
+## Starting Your Own Project
+
+1. If you are on Ubuntu, [install Tkinter](https://stackoverflow.com/a/45442774/2934048) 
+(on [Windows10](https://stackoverflow.com/a/53912930/2934048) and 
+[macOS](https://www.python.org/download/mac/tcltk/) Tkinter is bundled with Python):
+
+        sudo apt-get install python3.6-tk
+
+1. Fork / Clone this repository
+
+        git clone https://github.com/DalyaG/PyGraphicsGui.git
+
+1. Install requirements:
+
+        cd PyGraphicsGui
+        
+        pip3 install -r requirements.txt
+        
+1. Test your PyGraphicsGui app!
+
+        python3 run_where_is_waldo.py
+
+## PyGraphicsGui Capabilities
+
+1. Click on the image with the left mouse button - if you didn't click on Waldo, 
+you will see a red target and will be able to continue trying.
+
+1. If you did click on Waldo - you will see a glorious exit message.
+
+1. You can also press `esc` or the `x` on the top-right corner of the window (top-left on mac),
+If you wish to close the app.
+
+1. At any point, you can resize the window and the targets of the failed detections will stay where they should.
+
+
+## About This Project - The Technical Side
+
+This project was designed to be an as-lean-as-possible skeleton for a Pythonic desktop app with graphic capabilities.
+At the same time, it is meant to be easily expanded upon, without thinking to much on technicalities such as 
+"where should I put this?" or "How do I write tests?" etc.
+
+My goal going forward is for this project to include an introduction to ModernGL, computer graphics in general, 
+Tkinter, and the Python behind-the-scenes that allow for this integration to work.
+
+In the meanwhile, I hope the many links below will help you develop your new skills :)
+
+The structure of this project is as follows:
+
+### The Main Folder
+
+* This README
+
+* Requirements file for easy install (on Ubuntu you also need to install Tkinter)
+
+* `run_where_is_waldo` - a lean runner file to run this app from terminal.
+
+* License - My goal in this project is to make this knowledge accessible, so you can do pretty much what you like
+with the knowledge I gathered here. 
+
+    If you publish something that is based on my work, be kind and link back to this project.
+
+* `data` folder - contains the image to load and the location of Waldo (don't look!).
+
+* `tests` folder - contains a base class that mocks the graphic engine, so that you could easily add tests to your app, 
+and also an example tests file that validates some mathematical calculations.
+
+### The Source Folder
+
+As can be expected, the `src` folder is where the code is...
+
+* `logging utils` holds a lean logger that helps with debugging, you can read more about it 
+[here](https://codeburst.io/copy-pastable-logging-scheme-for-python-c17efcf9e6dc).
+
+* `bounding box` is a lean dataclass that handles the location of Waldo
+
+* `window_manager.py` is the main entry point - the class `WindowManager` creates and destroys the app,
+handles user events, draws elements on screen, and communicates with the graphic engine. 
+
+    To learn more about Tkinter you can browse [this](http://effbot.org/zone/tkinter-index.htm) website, 
+    and I highly recommend the [sentdex Youtube channel](https://www.youtube.com/user/sentdex) - 
+    most of what I know about Tkinter is from 
+    [this](https://www.youtube.com/watch?v=HjNHATw6XgY&list=PLQVvvaa0QuDclKx-QpC9wntnURXVJqLyk) tutorial.
+
+### The Graphic Engine Folder 
+
+I chose to put this in a separate folder (called `graphic_engine`, inside `src`) since once you start expanding on 
+this project, and adding capabilities to your graphic engine, it helps to keep all the relevant logic in one place. 
+
+For now this folder contains:
+
+* `graphic_engine` holds the main entry point to all the graphic capabilities, which is now pretty lean.
+The API is made up of mathematical conversion methods between the different coordinate systems. I included a 
+glossary at the docstring of this class which I hope will take you the first steps in understanding this.
+
+    I somehow managed to avoid the term "viewport" in my graphic engine implementation, but it's a useful one
+    to know, as it appears *everywhere* in computer graphics. Learn more about viewport 
+    [here](https://www.youtube.com/watch?v=DnEIdu8MpjY&list=PLE67F-VQUgLgws92d9gmP-AhBN_KQRGDW&index=18).
+
+* `graphic_engine_initializer` is a helper that loads all the major graphics components, to avoid clutter in the
+main graphic engine class. I plan to expand on this topic in the future, as this initializer holds the key to
+understanding the basics of computer graphics, but for now we will settle for some external recommendations:
+
+    * The first 3 minutes of 
+    [this](https://www.youtube.com/watch?v=WMiggUPst-Q&list=PLRIWtICgwaX0u7Rf9zkZhLoLuZVfUksDP&index=2)
+    video about vertex arrays (VAOs) and vertex buffers (VBOs) sorted out so many things in my head. 
+
+    * The first half of [this](https://www.youtube.com/watch?v=21UsMuFTN0k) video helped me understand a bit 
+    about framebuffers.
+
+    * I learned a lot about graphics from 
+    [this tutorial series](https://www.youtube.com/watch?v=dwt2NAd1ZYY&list=PL4neAtv21WOlqpDzGqbGM_WN2hc5ZaVv7)
+    about [OpenFrameworks](https://openframeworks.cc/). 
+    If you have some basic C++ knowledge I recommend you check it out.
+
+    * [This](https://www.youtube.com/watch?v=-tonZsbHty8)
+    is an excellent visual explanation about the model-view-projection matrix.
+     
+        And if you want to catch up on some linear algebra, it's always good (and fun!!) to watch some 
+        3Blue1Brown videos, such as [this](https://www.youtube.com/watch?v=kYB8IZa5AuE).
+
+    * [This](https://www.youtube.com/watch?v=vQ60rFwh2ig) is an excellent explanation about 
+    [homogeneous coordinates](https://en.wikipedia.org/wiki/Homogeneous_coordinates).
+
+* `tkinter_framebuffer` is the "mediator" between the graphic engine and what is eventually presented on screen.
+This implementation takes the rendered graphics and "projects" it onto an "image" that Tkinter recognizes. 
+Tkinter "thinks" it's presenting an image when in fact it is presenting a projection of the graphics rendered
+behind the scenes. 
+
+    To understand how this object is initialized, you can read about Python's `with` statement
+    [here](https://effbot.org/zone/python-with-statement.htm).
+
+    Notice that this "image" has a constant size, and so this "mediator" needs to be re-initialized every time 
+    the window size changes.  
+
+    *A Thank You Note*: This object is almost a copy-paste of 
+    [this framebuffer](https://github.com/moderngl/moderngl/blob/master/examples/tkinter_framebuffer.py) 
+    from the moderngl repository. Understanding 
+    [this](https://github.com/moderngl/moderngl/blob/master/examples/window_tkinter.py)
+    example was a huge step for me. 
+
+* `shaders` folder - a shader is a program that sends commands to the graphics card. It's basically a set of 
+rules to apply to each pixel or object. 
+
+    Although I am using the simplest shaders in this implementation, the first half of 
+    [this](https://www.youtube.com/watch?v=C8FK9Xn1gUM&list=PLRIWtICgwaX0u7Rf9zkZhLoLuZVfUksDP&index=49)
+    video really ties the room together.
+
+    If you want to go a bit deeper - I learned a lot about shaders from 
+    [this](https://www.udemy.com/share/102cOcAEEbeFZbRHsB/) course on Udemy. You can also find some free videos
+    on [Youtube](https://www.youtube.com/watch?v=uwzEqeMd7uQ&list=PLFky-gauhF452rW98W4cyZ8_2fXBjfGOT).
+
+## About This Project - My Personal Story
+
+The first steps in computer graphics were the hardest I had to take. Not only is the math non-trivial, 
+but also the available information online is not suitable for beginners - full of jargon and assumes advanced knowledge.
+
+Add to that my vision to develop an interactive desktop app in Python, 
+and you get a month full of blood, sweat, tears, and self doubt.
+
+Once I was able to make my vision come to life, I knew I had to share my knowledge and make it accessible.
+
+Since I made the first prototype, I am easily developing tools that help me in my job as a 
+computer vision algorithms engineer. These tools assist me in making it as easy as possible for the human-in-the-loop
+to participate in the AI flow.
+
+My goal in this project is to make the onboarding stage of computer graphics as easy as possible, 
+so that anyone could develop cool apps for fun and for work.
+
+Hope you find this useful!

data/waldo_bounding_box.json

@@ -0,0 +1,6 @@
+{
+    "left": 735,
+    "top": 50,
+    "right": 770,
+    "bottom": 80
+}

requirements.txt

@@ -0,0 +1,5 @@
+mock~=4.0.2
+moderngl==5.6.1
+numpy~=1.19.0
+Pillow~=7.1.2
+PyGLM==1.0.0