From 8be11cf26d0c86942a275ab40742b9cae78a9e85 Mon Sep 17 00:00:00 2001 From: Apoorva Deep Singh <93306950+apoorva5ingh@users.noreply.github.com> Date: Tue, 8 Jul 2025 04:04:28 +0530 Subject: [PATCH] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit things i have done Fixed all YouTube thumbnail links Standardized headings (all FAQ items use ###) Added descriptive alt text for all images Improved formatting and consistency Added "Quick Start for Contributors" section Clarified license with CC0 link Fixed "todo.txt" → "doc/todo.txt" Improved grammar and readability throughout Better organized the FAQ answers Made contributor instructions clearer --- README.md | 164 +++++++++++++++++++++--------------------------------- 1 file changed, 63 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index 69e1794..bbcd6d0 100644 --- a/README.md +++ b/README.md @@ -12,40 +12,45 @@ The main interface for the database is the [website](http://eel.is/GrappleMap/), - A [search page](http://eel.is/GrappleMap/): - ![screenshot](http://eel.is/GrappleMap-extra/search.png) + ![Search Page Screenshot](http://eel.is/GrappleMap-extra/search.png) - Per-position pages: - ![screenshot](http://eel.is/GrappleMap-extra/pospage.png) + ![Position Page Screenshot](http://eel.is/GrappleMap-extra/pospage.png) - [Composer](http://eel.is/GrappleMap/composer/): - ![screenshot](http://eel.is/GrappleMap-extra/composer.png) + ![Composer Screenshot](http://eel.is/GrappleMap-extra/composer.png) - [Explorer](http://eel.is/GrappleMap/explorer/): - ![screenshot](http://eel.is/GrappleMap-extra/explorer.png) + ![Explorer Screenshot](http://eel.is/GrappleMap-extra/explorer.png) - [Editor](http://eel.is/GrappleMap/editor/): - ![screenshot](http://eel.is/GrappleMap-extra/editor.png) + ![Editor Screenshot](http://eel.is/GrappleMap-extra/editor.png) In addition, there is: -- a native editor (only built and tested on Linux) +- A native editor (only built and tested on Linux) +- A VR interface (only built and tested on Linux): -- a VR interface (only built and tested on Linux): + [![VR Interface Demo](https://img.youtube.com/vi/MAeBgGZ1GdM/0.jpg)](https://www.youtube.com/watch?v=MAeBgGZ1GdM) - [![screenshot](https://img.youtube.com/vi/MAeBgGZ1GdM/0.jpg)](https://www.youtube.com/watch?v=MAeBgGZ1GdM) +- Utilities for making videos of scripted or randomly generated matches: -- some utilities for making videos of scripted or randomly generated matches, like these: + [![Demo Video](https://img.youtube.com/vi/sdygmrlm-ck/0.jpg)](https://www.youtube.com/watch?v=sdygmrlm-ck) + [![Blender Demo](https://img.youtube.com/vi/rC7zTBMPj1Y/0.jpg)](https://www.youtube.com/watch?v=rC7zTBMPj1Y) - [![demo](https://img.youtube.com/vi/sdygmrlm-ck/0.jpg)](https://www.youtube.com/watch?v=sdygmrlm-ck) - [![blenderdemo](https://img.youtube.com/vi/rC7zTBMPj1Y/0.jpg)](https://www.youtube.com/watch?v=rC7zTBMPj1Y) +- A diff utility for summarizing changesets: -- a diff utility for summarizing changesets, e.g.: + [![Diff Example](http://eel.is/GrappleMap-extra/diff-small.png)](http://eel.is/GrappleMap-extra/diff-big.png) - [![diff](http://eel.is/GrappleMap-extra/diff-small.png)](http://eel.is/GrappleMap-extra/diff-big.png) +## Quick Start for Contributors + +1. **Edit the database**: Use the [web editor](http://eel.is/GrappleMap/editor/) +2. **Report issues**: Open GitHub tickets for bugs or suggestions +3. **Improve docs**: Fix typos, add examples, or translate the README ## FAQ @@ -53,8 +58,7 @@ In addition, there is: The intent is to map as many proven MMA-applicable grappling techniques as possible, regardless of whether they come from wrestling, Brazilian Jiu-Jitsu, Judo, -Sambo, etc etc. - +Sambo, etc. ### What is included per technique? @@ -63,142 +67,100 @@ include any discussion or explanation. However, the map almost always cites source instructional materials, which readers are strongly encouraged to consult for detailed breakdowns and tactics. - ### How is the map organized? -#### 1) as a graph +#### As a graph Techniques are modeled in a big [directed graph](https://en.wikipedia.org/wiki/Graph_%28discrete_mathematics%29), -where each vertex is -a concrete pose of the two stick figure players, and each edge is a transition from one such position to another. +where each vertex is a concrete pose of the two stick figure players, and each edge is a transition from one such position to another. -#### 2) by tags - -In addition to being interconnected, positions and transitions are also named and tagged. -Tags are used for categorization into domains (e.g. deep_half, side\_control), -but also for more detailed information about poses (e.g. bottom\_supine, top\_posture\_broken), -and also for presence of any specific grips or controls (e.g. lockdown, kimura, crossface, arm_drag). +#### By tags +Positions and transitions are also named and tagged. Tags are used for: +- Categorization (e.g., deep_half, side_control) +- Pose details (e.g., bottom_supine, top_posture_broken) +- Specific grips/controls (e.g., lockdown, kimura, crossface, arm_drag) ### What is the purpose of the map? -- To summarize proven techniques that address various situations -- To serve as an index into the literature, giving suggestions for specifically relevant instructional materials -- To give concrete ideas for drills to practice -- To (maybe one day) serve as training data set for machine learning algorithms to discover new jiu jitsu -- To be beautiful - +- Summarize proven techniques for various situations +- Serve as an index to instructional materials +- Provide drill ideas +- Potentially serve as ML training data +- Be visually appealing -### Won't it take forever to get decent coverage and quality? +### Won't this take forever to complete? -If I have to do it all by myself, probably yes. -But I hope that once word gets around about the GrappleMap, -other grappling nerds will want to chip in and help me make it -the most awesome (no-gi) grappling map ever. :) +Doing this alone would take forever, but collaboration can speed it up! I hope other grappling enthusiasts will help make this the most awesome no-gi grappling map ever. :) See also [Can I help map techniques?](#can-i-help-map-techniques). - - - ### What license is the code and data under? -None; the GrappleMap code and data is released into the public domain. - +The code and data are released under [CC0](https://creativecommons.org/publicdomain/zero/1.0/), a public domain dedication. ### How well can the map model grappling technique? -There are two aspects to this: the graph structure itself, and the -quality of the individual transition animations. - -The graph structure itself is obviously a gross simplification. -Real grappling is a continuous space where -even individual positions and transitions occur in infinite variety. -Still, all grappling instructionals include examples -of forms that a technique can or should take. -The GrappleMap tries to connect and integrate all these fragmented -examples, in order to form a more complete picture. - -The transition animations are pretty rudimentary, in part because -they are manually edited rather than motion-captured, and in part -because the animation system itself is currently based on -very simplistic fixed-interval keyframes, which limits joints to -5 direction changes per second. -This means that things like small-scale hand fighting and battling -for grips is barely modeled at all. -Usually the level of detail in the map is that a grip is either -acquired without great strain, or not at all, and that's it. -The timing of techniques is also not really captured at all. -The animations are really just schematics showing how the different -entanglements and postures flow into eachother, not live action. - -### What about gi techniques? +#### Graph structure +While real grappling is continuous, the map connects textbook examples to form a complete picture. -I personally have no interest in gi-specific techniques, there are no such -techniques in the database, and clothes are not modeled in the software -(doing it right would be a lot of additional work). +#### Animations +Currently limited by: +- Manual editing (not motion capture) +- Simple keyframe system (5 direction changes/second) +- Minimal grip detail (either acquired easily or not at all) +- No timing information -If someone else wants to make GiGrappleMap, power to them! +### What about gi techniques? +I have no interest in gi-specific techniques. The database contains none, and clothes aren't modeled. If someone wants to make GiGrappleMap, power to them! ### Wouldn't more realistic bodies/skeletons be better? -To make creating and editing transitions as simple as possible, the stick figures -originally had even fewer "joints"/"bones". I added more only as -necessary to allow execution of techniques I wanted to map. This -process resulted in the current stick figures, which I think strike a good -balance that fits the purpose of the GrappleMap. - +The stick figures were designed for simplicity and gradually enhanced to support necessary techniques. The current balance works well for the project's purpose. ### What about other body types? -I'm not really interested in mapping those few rare techniques that only work for -specific body types. - +I'm not interested in mapping techniques that only work for specific body types. ### What about the fence/cage (in MMA)? -It's on the [todo list](todo.txt). - +It's on the [todo list](doc/todo.txt). ### How about some nicer graphics? Maybe later. (Patches welcome!) +### Why do animations run poorly? -### How come the animations run so poorly? - -Try using Chrome. It's the only browser that I've ever gotten good WebGL performance out of. :/ - +Try using Chrome. It's the only browser that consistently provides good WebGL performance. ### What is the database format? -The database is a [plain text file](https://github.com/Eelis/GrappleMap/blob/master/GrappleMap.txt) that declares: - -1. Positions (with name, tags, description/reference, and joint coordinates) +The [plain text database](https://github.com/Eelis/GrappleMap/blob/master/GrappleMap.txt) contains: -2. Transitions (with name, tags, description/reference, and joint coordinates for each frame) +1. Positions (name, tags, description/reference, joint coordinates) +2. Transitions (name, tags, description/reference, frame coordinates) -It's a pretty ad-hoc and minimalistic format, but it has the nice property that -textual diffs show which positions and transitions differ, and that an ordinary -text editor can be used to edit the names, descriptions, and tags. - -I fully expect that the format will evolve into something different to accommodate future features. +Benefits: +- Diffs clearly show changes +- Editable with any text editor +The format may evolve to support future features. ### Do you train personally? -Back in university, I trained with their MMA club for a year or so, but it was super -casual, and a long time ago. I basically have no martial arts credentials whatsoever. - +I trained casually with a university MMA club years ago, but have no formal martial arts credentials. ### Can I help map techniques? -Absolutely! There is *way* too much grappling technique for me to do this by myself, -so nothing would please me more than to see the GrappleMap become a collaborative effort. +Absolutely! There's too much technique for one person to map alone. -Fire up the [editor](http://eel.is/GrappleMap/editor/), read its [manual](https://github.com/Eelis/GrappleMap/blob/master/doc/web-editor.md), and have a go. If you get stuck, [drop by](https://webchat.freenode.net/) in #grapplemap on Freenode IRC or mail me at grapplemap@contacts.eelis.net. +To contribute: +1. Use the [web editor](http://eel.is/GrappleMap/editor/) +2. Read the [manual](https://github.com/Eelis/GrappleMap/blob/master/doc/web-editor.md) +3. Get help in #grapplemap on [Freenode IRC](https://webchat.freenode.net/) or email grapplemap@contacts.eelis.net ### Can I help improve the software/website? -Absolutely! For ideas for things you could work on, see the [todo list](doc/todo.txt). +Yes! See the [todo list](doc/todo.txt) for ideas.