Metadata-Version: 2.4
Name: bishopviz
Version: 1.0.1
Summary: Generate random ASCII art from plain text and media using the drunken bishop algorithm
Author-email: nautrw <nautrw@proton.me>
License-Expression: MIT
Project-URL: Homepage, https://github.com/nautrw/bishopviz
Project-URL: Repository, https://github.com/nautrw/bishopviz.git
Project-URL: Issues, https://github.com/nautrw/bishopviz/issues
Project-URL: CI, https://github.com/nautrw/bishopviz/actions
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click==8.5.0
Requires-Dist: streamlit[charts]==1.62.0
Requires-Dist: pandas==3.0.5
Requires-Dist: plotly==7.0.0
Dynamic: license-file

# bishopviz
Drunken Bishop algorithm implementation for random ASCII art generation from
md5 hashes, and for data visualization from generated art.

<img width="370" height="314" alt="demo" src="https://github.com/user-attachments/assets/a80dfa58-feb5-4721-8c28-cc0dbc5114b8" />

# Installation
(Recommended) If you have [pipx](https://pipx.pypa.io/stable/) installed:
```sh
pipx install bishopviz
```
Otherwise:
```sh
pip install bishopviz
```
Or, to use the web version, go to https://bishopviz.streamlit.app
# Try it
## Web App
The web app is the same algorithm, but shows some data visualizations about it.
Go to [the website](https://bishopviz.streamlit.app), type anything into the text area, and then do `ctrl+Enter`.
## CLI
A quick demo of the colors and animation:
```sh
bishopviz -a 0.1 -C
```
To specify a file to generate randomart for, add the `-f` flag and then specify a file path.

To see all of the options of the CLI, run:
```sh
bishopviz --help
```
# Features
- **md5** hash from a random string or a file
- Implementation of the drunken bishop algorithm to generate randomart
- Various character sets (like texture packs!) for the final graph
- Visualize the algorithm over time via animations and generation count
- (CLI) Graph with colors representing the visit frequency
- (Webapp) Web App with data visualizations from the algorithm
## CLI Help Menu
```txt
Usage: bishopviz [OPTIONS]

  Drunken Bishop algorithm implementation for random ASCII art generation from
  md5 hashes.

Options:
  -f, --file-feed TEXT  Use the contents of any file as the input.
  -a, --animate FLOAT   Display the algorithm's progress as an animation, with
                        the specified number of seconds as the interval
                        between frames.
  -c, --charset TEXT    Use a different character set for the graph. Options:
                        ascii, ascii_alt, emoji, emoji2, emoji3, emoji4,
                        greek, cyrillic, katakana, math, blocks, faces, cars,
                        plants  [default: ascii]
  -C, --colors          Whether to colorize the output.
  -d, --data            Open a Streamlit app to run the algorithm and
                        visualize data.
  --no-start-end        Don't show the start and end positions on the graph.
  -h, --help            Show this message and exit.
  ```
# How It Works
For a better explanation, check out [this awesome paper](https://www.dirk-loss.de/sshvis/drunken_bishop.pdf) on the topic.

First, an md5 hash is generated from the input (this can be text, an image, video, etc.). This hash is then encoded into 128 bits, and then split into 64 pairs of 2 bits each.

The algorithm generates a 2-dimensional 17x9 matrix and then tracks the position of a "bishop", which starts off in the middle of the matrix.

It will iterate over the byte pairs and move in a certain direction depending on the pair:

|Bit|Direction|
|---|---|
|00|Up, Left|
|01|Up, Right|
|10|Down, Left|
|11|Down, Right|

My program, while iterating over the pairs, will track certain variables to then create data visualizations using Streamlit and Plotly. 
# Technologies/Libraries Used
- [Streamlit](https://pypi.org/project/streamlit/), to create the web app
- [Plotly](https://pypi.org/project/plotly/), to create the graphs
- [Pandas](https://pypi.org/project/pandas/), to manipulate the data generated by the algorithm
- [Click](https://pypi.org/project/click/), for the CLI
- [*The drunken bishop: An analysis of the OpenSSH
fingerprint visualization algorithm* by Loss et al.](https://www.dirk-loss.de/sshvis/drunken_bishop.pdf) for insights on how the algorithm worked
