-
Notifications
You must be signed in to change notification settings - Fork 3
docs: improve README with modern structure and navigation #35
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| --- | ||
| mode: agent | ||
| description: Create a meaningful branch and commit all pending changes, then advise on pushing. | ||
| --- | ||
|
|
||
| Review the current state of the repository and commit all pending changes with a well-crafted message. | ||
|
|
||
| ## Steps | ||
|
|
||
| 1. **Inspect changes** — run `git status` and `git diff` (or `git diff --cached`) to understand exactly what has changed and why. | ||
|
|
||
| 2. **Derive a branch name** — based on the nature of the changes, choose a concise, kebab-case branch name following the pattern `<type>/<short-description>`, e.g. `docs/modernize-readme` or `feat/add-3d-visualizations`. Use a standard type prefix: `feat`, `fix`, `docs`, `refactor`, `chore`, `test`, or `style`. | ||
|
|
||
| 3. **Create and switch to the branch** — run: | ||
| ```sh | ||
| git checkout -b <branch-name> | ||
| ``` | ||
|
|
||
| 4. **Stage all changes** — run: | ||
| ```sh | ||
| git add -A | ||
| ``` | ||
|
|
||
| 5. **Write a commit message** — follow the Conventional Commits format: | ||
| ``` | ||
| <type>(<optional scope>): <short imperative summary> | ||
|
|
||
| <optional body — explain what changed and why, not how> | ||
| ``` | ||
| Keep the subject line under 72 characters. Include a body only if the change needs context beyond what the subject conveys. | ||
|
|
||
| 6. **Commit** — run: | ||
| ```sh | ||
| git commit -m "<message>" | ||
| ``` | ||
|
|
||
| 7. **Advise on pushing** — do NOT push. Instead, tell the user the exact command to push and open a PR when they are ready: | ||
| ```sh | ||
| git push -u origin <branch-name> | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,174 +1,160 @@ | ||
| [](https://github.com/66-m/sorting-visualizer/actions/workflows/maven.yml) | ||
| [](https://opensource.org/licenses/MIT) | ||
| <div align="center"> | ||
|
|
||
| <img src="images/logo.png" alt="Logo" width="160" height="160"> | ||
|
|
||
| <h1>Sorting Algorithm Visualizer</h1> | ||
|
|
||
| <br /> | ||
| <div align="center"> | ||
| <img src="images/logo.png" alt="Logo" width="200" height="200"> | ||
|
|
||
| <h1 align="center">Sorting Algorithm Visualizer</h1> | ||
|
|
||
| <p align="center"> | ||
| Visualizes and Audiolizes Sorting Algorithms!<br/> | ||
| <br /> | ||
| <br /> | ||
| <a href="https://github.com/66-m/sorting-visualizer/releases/latest"><strong>Try it »</strong></a> | ||
| <br /> | ||
| <br /> | ||
| · | ||
| <a href="https://github.com/66-m/sorting-visualizer/issues">Report Bug / Request Feature</a> | ||
| </p> | ||
| </div> | ||
| <br /> | ||
| This sorting visualizer offers both visual and auditory demonstrations of sorting algorithms. It features 22 different sorting methods represented through a collection of 30 visuals, including a selection of 3D models. A settings menu is included to enable users to adjust the appearance and functionality of the visualizer. | ||
| <p>Visualize and audiolize sorting algorithms in real time — with 22 algorithms, 30 visualizations, and full 3D support.</p> | ||
|
|
||
| [](https://github.com/66-m/sorting-visualizer/actions/workflows/maven.yml) | ||
| [](https://opensource.org/licenses/MIT) | ||
| [](https://github.com/66-m/sorting-visualizer/releases/latest) | ||
|
|
||
| <br/> | ||
|
|
||
| [**Download latest release »**](https://github.com/66-m/sorting-visualizer/releases/latest) | ||
| · | ||
| [Report a bug or request a feature](https://github.com/66-m/sorting-visualizer/issues) | ||
|
|
||
| <br/> | ||
|
|
||
| <img src="images/demo.png" alt="Program demo" width="80%"> | ||
|
|
||
| <div align="center"> | ||
| <img src="images/demo.png" alt="Program demo"> | ||
| <p align="center"> | ||
| </div> | ||
|
|
||
| ## Downloading and running the visualizer | ||
| You can download the latest version of this visualizer [here](https://github.com/66-m/sorting-visualizer/releases/latest) | ||
| --- | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| Download the [prebuilt JAR file](https://github.com/66-m/sorting-visualizer/releases/latest/download/sorting-visualizer.jar) and run it with | ||
| - [Getting Started](#getting-started) | ||
| - [Building from Source](#building-from-source) | ||
| - [Features](#features) | ||
| - [Sorting Algorithms](#sorting-algorithms) | ||
| - [Visualizations](#visualizations) | ||
| - [Controls & Settings](#controls--settings) | ||
| - [Acknowledgements](#acknowledgements) | ||
|
|
||
| java -jar sorting-visualizer.jar | ||
| --- | ||
|
|
||
| ## Getting Started | ||
|
|
||
| ## Building the project yourself | ||
| ### Requirements: | ||
| Download the [prebuilt JAR](https://github.com/66-m/sorting-visualizer/releases/latest/download/sorting-visualizer.jar) and run it with: | ||
|
|
||
| * An installed JDK (Java 25 or later). Download [here](https://jdk.java.net/25/) | ||
| * Make sure your [environment variables](https://www.baeldung.com/java-home-on-windows-7-8-10-mac-os-x-linux) are set. | ||
| ```sh | ||
| java -jar sorting-visualizer.jar | ||
| ``` | ||
|
|
||
| ### Clone this repository: | ||
| > **Requires Java 25 or later.** Download from [jdk.java.net/25](https://jdk.java.net/25/). | ||
|
|
||
| git clone https://github.com/66-m/sorting-visualizer.git | ||
| cd sorting-visualizer | ||
| --- | ||
|
|
||
| ## Building from Source | ||
|
|
||
| ### Building the Code: | ||
| **Requirements:** | ||
| - JDK 25 or later — [download here](https://jdk.java.net/25/) | ||
| - Ensure your [JAVA_HOME environment variable](https://www.baeldung.com/java-home-on-windows-7-8-10-mac-os-x-linux) is set | ||
|
|
||
| 1. Open a terminal in the project folder and execute one of the following: | ||
| **Clone and build:** | ||
|
|
||
| ```sh | ||
| # using the bundled Maven wrapper (recommended on Linux/Mac) | ||
| git clone https://github.com/66-m/sorting-visualizer.git | ||
| cd sorting-visualizer | ||
|
|
||
| # Build (using bundled Maven wrapper — recommended) | ||
| ./mvnw clean package | ||
| # or, if you prefer convenience scripts provided in this repo: | ||
| # or use the convenience script: | ||
| ./build | ||
| ``` | ||
|
|
||
| 2. Run the compiled jar with either: | ||
| **Run:** | ||
|
|
||
| ```sh | ||
| java -jar target/sorting-visualizer.jar | ||
| # or using the helper script: | ||
| # or: | ||
| ./run | ||
| ``` | ||
|
|
||
| (The helper scripts `build` and `run` are provided for Unix-like systems; they simply wrap the above commands.) | ||
|
|
||
| > The `build` and `run` helper scripts are provided for Unix-like systems. | ||
|
|
||
| ## Features | ||
| --- | ||
|
|
||
| * Selecting algorithms: | ||
| - Quick Sort (Middle Pivot) | ||
| - Quick Sort (Dual Pivot) | ||
| - Merge Sort | ||
| - Shell Sort | ||
| - Selection Sort | ||
| - Double Selection Sort | ||
| - Insertion Sort | ||
| - Heap Sort | ||
| - Gravity Sort | ||
| - Radix Sort (LSD, Base 10) | ||
| - Gnome Sort | ||
| - Comb Sort | ||
| - Odd Even Sort | ||
| - Bubble Sort | ||
| - Cocktail Shaker Sort (Shaker Sort) | ||
| - Cycle Sort | ||
| - Counting Sort | ||
| - American Flag Sort | ||
| - Bucket Sort | ||
| - Pigeonhole Sort | ||
| - Tim Sort | ||
| - Bogo Sort | ||
|
|
||
|
|
||
| * Running all algorithms | ||
| - Changing the execution order | ||
| - Selecting which algorithms to run | ||
|
|
||
|
|
||
| * Changing the array size | ||
|
|
||
|
|
||
| * Changing the shuffle type | ||
| - Random | ||
| - Reverse | ||
| - Almost Sorted | ||
| - Sorted | ||
|
|
||
|
|
||
| * Selecting Visualizations: | ||
| - Bars | ||
| - Scatter Plot | ||
| - Scatter Plot Linked | ||
| - Number Plot | ||
| - Disparity Graph | ||
| - Disparity Graph Mirrored | ||
| - Horizontal Pyramid | ||
| - Color Gradient Graph | ||
| - Circle | ||
| - Disparity Circle | ||
| - Disparity Circle Scatter | ||
| - Disparity Circle Scatter Linked | ||
| - Disparity Chords | ||
| - Disparity Square Scatter | ||
| - Swirl Dots | ||
| - Phyllotaxis | ||
| - Image Vertical | ||
| - Image Horizontal | ||
| - Hoops | ||
| - Morphing Shell | ||
| - Sphere (3D) | ||
| - Sphere Hoops (3D) | ||
| - Spheric Disparity Lines (3D) | ||
| - Disparity Sphere Hoops (3D) | ||
| - Cube (3D) | ||
| - Cubic Lines (3D) | ||
| - Pyramid (3D) | ||
| - Plane (3D) | ||
| - Disparity Plane (3D) | ||
| - Mosaic Squares | ||
|
|
||
|
|
||
| * Selecting different color gradients and creating your own | ||
|
|
||
| * Showing Measurements during the execution | ||
| - Sorted percentage | ||
| - Counting comparisons | ||
| - Measuring the estimated real time | ||
| - Counting swaps | ||
| - Counting writes to the main array | ||
| - Counting writes to possible auxiliary arrays | ||
|
|
||
|
|
||
| * Option to display a comparison table at the end of the execution | ||
|
|
||
|
|
||
| * Controlling animation speed | ||
|
|
||
|
|
||
| * Muting Sound | ||
|
|
||
|
|
||
| * Canceling execution | ||
| ## Features | ||
|
|
||
| ### Sorting Algorithms | ||
|
|
||
| 22 algorithms available: | ||
|
|
||
| | | | | | ||
| |---|---|---| | ||
| | Quick Sort (Middle Pivot) | Quick Sort (Dual Pivot) | Merge Sort | | ||
| | Shell Sort | Selection Sort | Double Selection Sort | | ||
| | Insertion Sort | Heap Sort | Gravity Sort | | ||
| | Radix Sort (LSD, Base 10) | Gnome Sort | Comb Sort | | ||
| | Odd Even Sort | Bubble Sort | Cocktail Shaker Sort | | ||
| | Cycle Sort | Counting Sort | American Flag Sort | | ||
| | Bucket Sort | Pigeonhole Sort | Tim Sort | | ||
| | Bogo Sort | | | | ||
|
|
||
| **Algorithm run options:** | ||
| - Run all algorithms in sequence | ||
| - Change the execution order | ||
| - Select which algorithms to include | ||
|
|
||
| ### Visualizations | ||
|
|
||
| 30 visualizations including 3D models: | ||
|
|
||
| <details> | ||
| <summary>2D Visualizations (20)</summary> | ||
|
|
||
| - Bars | ||
| - Scatter Plot / Scatter Plot Linked | ||
| - Number Plot | ||
| - Disparity Graph / Disparity Graph Mirrored | ||
| - Horizontal Pyramid | ||
| - Color Gradient Graph | ||
| - Circle | ||
| - Disparity Circle / Disparity Circle Scatter / Disparity Circle Scatter Linked | ||
| - Disparity Chords | ||
| - Disparity Square Scatter | ||
| - Swirl Dots | ||
| - Phyllotaxis | ||
| - Image Vertical / Image Horizontal | ||
| - Hoops | ||
| - Morphing Shell | ||
| - Mosaic Squares | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>3D Visualizations (10)</summary> | ||
|
|
||
|
Comment on lines
+123
to
+131
|
||
| - Sphere | ||
| - Sphere Hoops | ||
| - Spheric Disparity Lines | ||
| - Disparity Sphere Hoops | ||
| - Cube | ||
| - Cubic Lines | ||
| - Pyramid | ||
| - Plane | ||
| - Disparity Plane | ||
|
|
||
| </details> | ||
|
|
||
| ### Controls & Settings | ||
|
|
||
| - **Array:** Configurable size and shuffle type (Random, Reverse, Almost Sorted, Sorted) | ||
| - **Color gradients:** Choose from presets or create your own | ||
| - **Speed:** Adjustable animation speed | ||
| - **Sound:** Toggle mute at any time | ||
| - **Live measurements:** sorted %, comparisons, swaps, array writes, auxiliary writes, estimated real time | ||
| - **Comparison table:** Optionally display a summary after all algorithms have run | ||
| - **Cancel:** Stop execution at any time | ||
|
|
||
| --- | ||
|
|
||
| ## Acknowledgements | ||
| Thanks to [w0rthy](https://www.youtube.com/c/w0rthyA) and [Musicombo](https://www.youtube.com/c/Musicombo) for their amazing videos and inspiring me to start this project. | ||
|
|
||
| Also thanks to [@micycle1](https://github.com/micycle1) for his mirror of the processing4 core library, making it available for maven. | ||
| Thanks to [w0rthy](https://www.youtube.com/c/w0rthyA) and [Musicombo](https://www.youtube.com/c/Musicombo) for their amazing videos and for inspiring this project. | ||
|
|
||
| Thanks to [@micycle1](https://github.com/micycle1) for his mirror of the processing4 core library, making it available for Maven. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
“audiolize” is not standard spelling in English and reads like a typo in the project tagline. Consider replacing it with a more common verb (e.g., “sonify” / “add audio to”) to improve readability/searchability.