1. Prerequisites
----------------


Python 3 – the script requires Python 3.8+ (the shebang #!/usr/bin/env python3
assumes a modern interpreter).  ansilove – the external program that actually
renders the ANSI art to PNG. Install it before running the script.
On Debian/Ubuntu: sudo apt-get install ansilove
On macOS with Homebrew: brew install ansilove
Or compile from source per the official repo if you need a newer version.
Permissions – the script will rename, delete, and create files in the target
directory, so the user executing it must have write permission there.


2. Make the script executable (optional)
----------------------------------------

chmod +x upconverter.py
You can now run it directly (./upconverter.py …) or invoke it with python3


3. Directory layout
-------------------

Create (or identify) a folder that contains the ANSI‑art files you want to
convert. The script will:

(a) Scan the folder, pick the newest regular file, and treat that as the
source.
(b) Delete every other file in the same folder (after the source is renamed to
a safe ASCII‑only name).
(c) Produce a PNG and a ansiupconverted.zip archive inside that folder.
Important: Because the script removes all other files, run it on a dedicated
temporary folder or a copy of your originals.


4. Running the script
---------------------

python3 upconverter.py /path/to/your/folder
or, if you made it executable:

./upconverter.py /path/to/your/folder

What happens next (interactive prompts)?

Pixel‑width reference table – the script prints a static table showing the
pixel width associated with each allowed scaling factor (2‑8).
Scale factor – you’ll be asked to enter a scaling factor. Press Enter to
accept the default (3×) or type a number between 2 and 8.
Ice‑colors palette – you’ll be prompted “Enable ice‑colors? (y/N)”. 
Type y for the special ice‑colors palette, otherwise just press Enter or
type n.

After you answer the prompts, the script:

(a) Sanitises the source filename (keeps only ASCII characters 33‑126).
(b) Deletes every other file in the directory.
(c) Calls ansilove with the chosen flags (-R <scale> and optionally -i).
(d) Writes the resulting PNG (<source‑stem>.png).
(e) Packages that PNG into ansiupconverted.zip.
(f) If everything succeeds you’ll see a “SUCCESS – all steps completed.” message and the zip file ready for use.


5. Typical workflow example
---------------------------

# (a) Prepare a clean folder
mkdir ~/tmp/ansi‑convert
cp *.ans ~/tmp/ansi‑convert/

# (b) Run the converter
python3 upconverter.py ~/tmp/ansi‑convert
# → Follow the prompts (e.g., press Enter for default scale, type “y” for
# ice‑colors)

# (c) Retrieve the result
ls ~/tmp/ansi‑convert
# You’ll see:
#   myfile.png          # the rendered image
#   ansiupconverted.zip # the archive containing the PNG


6. Optional post‑processing
---------------------------

If you only need the ZIP archive, you can let the script keep the intermediate PNG, or uncomment the two lines near the end of main() (the png_path.unlink() call) to automatically delete the PNG after zipping.


7. Troubleshooting tips
-----------------------

Symptom: ansilove: command not found
Likely Cause: ansilove isn’t installed or isn’t on $PATH.	
Fix: Install ansilove (see step 1) or add its location to your PATH.

Symptom: “No regular files found”	
Likely Cause: The target directory is empty or contains only sub‑directories.
Fix: Place at least one .ans (or any file) in the folder.

Symptom: Permission errors while deleting files	
Likely Cause: Script lacks write rights in the folder.	
Fix: Run the script as a user with appropriate permissions or adjust folder
ownership (chown/chmod).

Symptom: “Sanitised filename already exists”	
Likely Cause: Two files resolve to the same ASCII‑only name after sanitisation.
Fix: Rename one of the originals manually before running the script.


8. Quick recap (one‑liner)
--------------------------

python3 upconverter.py <folder-with-ans-files>

Answer the interactive prompts --> a PNG is rendered --> it’s zipped into
ansiupconverted.zip.


9. Mystic Menu Integration
--------------------------

Action List                       Data:
(GD)) Display a File              ansi-splash-screen
(FG) File Group Change            ex. 123 (whatever group) holds the uploaded
(FA) File Area Change             ex. 456 (whatever area) holds the uploaded
(FU) Upload Files
(DD) Execute External Programe    /path/to/upconverter-python.py /path/to/
                                  working-directory
(FD) Download Program             exact path to diectory and filename that
                                  holds upconverter.zip


prOps: This BBS Mod is made to you for free from The PHATstar Society
cOmpIlEd bY: warmfuzzy & Silent Partner
cOmplEtEd On: 2025 September 23
