ft-ps-visu 1.0.6

A terminal visualizer for the 42 push_swap project with real-time TUI, controlled disorder generation, and interactive playback.

ft_ps_visu

A terminal visualizer for the 42 push_swap project. It generates controlled random sequences with specific disorder levels, runs your push_swap executable, and renders a real-time TUI (Terminal User Interface) with interactive playback controls.

---

---

Features

• Real-time TUI visualization — watch your push_swap algorithm sort stacks live in the terminal.
• Controlled disorder generation — creates sequences with precise inversion percentages.
• Four test modes — adaptive, simple, medium, and complex.
• Selectable number ranges — generate values across the full INT_MIN–INT_MAX span, -1M–1M, or 0–1M.
• Interactive controls — play/pause, forward/reverse, step-by-step, speed adjustment, and more.
• stderr logs viewer — inspect anything your push_swap prints to stderr in a scrollable screen.
• File replay — load numbers and/or operations from files (--nums / --ops) to debug specific cases.
• True-color bars — gradient-colored bars representing values for easy visual tracking.
• Responsive layout — adapts to terminal resize events.

---

Requirements

• Python 3.7+
• A compiled push_swap executable that accepts a --<mode> flag and the numbers to sort
• A terminal that supports:
  • ANSI escape codes
  • True-color (24-bit RGB) for the best experience
  • Alternate screen buffer (\033[?1049h / \033[?1049l)

Note: On Windows, use Windows Terminal, WSL, or any modern terminal emulator. The classic cmd.exe console may not render Unicode block characters or true-color correctly.

---

Installation

Tip: If you run into installation errors, try updating pip first:

pip install --upgrade pip
# or
pip3 install --upgrade pip

Option 1: Install from PyPI (recommended)

Using pip:

pip install ft_ps_visu

Using pip3:

pip3 install ft_ps_visu

User-local install (no sudo required — pip):

pip install --user ft_ps_visu

Using python3 -m pip:

python3 -m pip install ft_ps_visu

Note: When using --user, the ft_ps_visu binary is installed to a user-local bin/ directory. Make sure this directory is on your PATH, or use the python3 -m execution methods shown below.

---

Option 2: Install from source

Clone this repository:

git clone https://github.com/italoalmeida0/ft_ps_visu.git
cd ft_ps_visu

Editable / development mode (pip):

pip install -e .

Normal install (pip):

pip install .

---

Option 3: Run with pipx (isolated, no install required)

If you have pipx installed, you can run the visualizer directly without permanently installing it:

pipx run ft_ps_visu ./push_swap

Or install it into an isolated environment:

pipx install ft_ps_visu

Then run normally:

ft_ps_visu ./push_swap

---

Make sure your push_swap binary is compiled and executable:

make
chmod +x push_swap

---

Usage

Basic usage

ft_ps_visu ./push_swap

With custom number of elements:

ft_ps_visu ./push_swap 100

With custom disorder percentage (0–55):

ft_ps_visu ./push_swap 500 30

If ft_ps_visu is not found on your PATH, run via the module:

python3 -m ft_ps_visu ./push_swap

Or using the .cli submodule directly:

python3 -m ft_ps_visu.cli ./push_swap

From the cloned source directory (no install required):

python3 ft_ps_visu/cli.py ./push_swap

---

Replay from files (--ops / --nums)

Instead of generating random numbers and running push_swap, you can load operations and/or numbers directly from files. This is useful for replaying and debugging specific test cases (for example, reports generated by ft_ps_tester).

Flag	Description
--ops <file>	Load operations from a file instead of running push_swap
--nums <file>	Load input numbers from a file instead of generating them

Both flags are optional and can be used independently or together.

Replay only the operations (numbers are still generated randomly):

ft_ps_visu --ops report_100_simple_ops_1.txt ./push_swap

Replay with both numbers and operations from files (push_swap is not executed):

ft_ps_visu --ops report_100_simple_ops_1.txt --nums report_100_simple_nums_1.txt ./push_swap

When --ops is passed, --nums is required. The push_swap path becomes optional but can still be provided (for example, to enable the make feature).

Note: When --ops is provided, the visualizer does not run push_swap. Controls that would regenerate data or change generation parameters are hidden from the UI.

---

Controls

Key	Action
P	Play / Pause
O	Toggle Forward / Reverse direction
N	Next step (forward one operation)
B	Back step (reverse one operation)
X	Increase speed
Z	Decrease speed
G	Re-generate data with current settings
M	Cycle through modes (adaptive → simple → medium → complex)
A	Decrease number of elements
S	Increase number of elements
D	Decrease disorder percentage
F	Increase disorder percentage
R	Cycle number range (MIN_MAX → -1M→1M → 0→1M)
E	Check if Stack A is sorted (shows OK/KO)
I	Open the push_swap stderr logs viewer
C	Run make in the push_swap directory
Q	Quit

Note: Controls G, M, A, S, D, F, R, I, C are hidden when --ops is used. Controls G, A, S, D, F, R are hidden when --nums is used without --ops (M, I, C remain available). I and C require a push_swap path to be provided.

Make screen (C)

Pressing C opens a make screen that runs make in the directory of the provided push_swap executable.

Key	Action
W	Return to the visualizer (only if the binary exists)
C	Run make again
R	Run make re
Q	Quit

Logs screen (I)

Pressing I opens a scrollable viewer showing everything your push_swap wrote to stderr during the last run (for example, Error messages). Use ↑/↓ (or k/j) to scroll and W to return. This control is only available when a push_swap path is provided and --ops is not used.

---

Number ranges

Press R to cycle the interval used to generate random values. The default is MIN_MAX.

Mode	Generated values	Description
MIN_MAX	-2147483648 … 2147483647	Full 32-bit signed integer range (default)
-1M -> 1M	-1000000 … 999999	Mixed positive and negative values
0 -> 1M	0 … 999999	Non-negative values only

The current range is shown in the top info bar as Range: <mode>. This control is only available when numbers are generated randomly (hidden when --nums or --ops is used).

---

Modes / Flags

Your push_swap must support the following flags (passed as --<mode> before the numbers):

Mode	Disorder range	Description
simple	15.0% – 19.9%	Nearly sorted sequences
medium	20.0% – 49.9%	Moderately shuffled sequences
complex	50.0% – 55.0%	Heavily shuffled sequences
adaptive	15.0% – 55.0%	Random disorder across the full spectrum

Note: If your push_swap does not implement these flags, the visualizer will still work if your program ignores unknown flags and simply sorts the provided numbers.

---

How it works

1. Generate a random sequence with the desired size and disorder level.
2. Run your push_swap executable with the sequence.
3. Capture the operations printed to stdout.
4. Render a TUI showing both stacks as colored bars.
5. Animate the operations at the chosen speed, allowing forward and reverse playback.

---

License

This project is licensed under the MIT License.