vaporwaver

Python version of existing vaporwaver PHP version

---

Python usage

A Python3 script to create vaporwave image based on PNG files. An improved version of the PHP one I did 2 years ago. However, this time I used multiple third-party libraries, which are:

• PIL (Pillow)
• glitch-this (https://github.com/TotallyNotChase/glitch-this)
• opencv-python

You can install them with pip install -r requirements.txt.

---

This program uses tkinter for the GUI tool (very pretty)

How does it works

The program takes an image, with or without transparency (though, please use an image with transparency for a better result!), we will call this image the "character" You can move the character in the X and Y axis, and scale it. You can apply a glitch amount and seed on it and also a predefined gradient map filter. The gradients are the built in opencv colormap

You can add a predefined misc item behind the character, which you can :

• Move
• Rotate
• Scale

And you can select one of the predefined background image. The output image will have a size of 460 x 595 px

Image ressources

⚠️ WARNING ⚠️

For launching, this program needs three files in specific paths. They are already in the repository, but please do not rename nor delete them. You can replace their content tho.

• picts/backgrounds/default.png
• picts/crt/crt.png
• picts/miscs/none.png

Do not remove thoses files, at any cost !

Backgrounds

The backgrounds size, in order to be selectable in the GUI list, must have the size of the output image, which means 460 x 595 px. You can name them as you want, they must be PNG files located at the picts/backgrounds folder.

Miscs

The miscs items are just decorations to put behind the character. There is no specific restriction on it. You can take any size, but they still musts be PNG files.

What does the program looks like ?

CLI mode

You can also use this program with the CLI. Fill the correct arguments to create your vaporwavec image. You can have more informations with py vaporwaver.py -h Here is the correct usage:

usage: vaporwaver.py [-h] [-b background] [-m misc] [-mx miscPosX] [-my miscPosY] [-ms miscScale] [-mr miscRotate] [-c characterPath] [-cx characterXpos] [-cy characterYpos]
                     [-cs characterScale] [-cr characterRotation] [-cg characterGlitch] [-cgs characterGlitchSeed] [-cgd characterGradient] [-cgl characterGlow] [-crt crt] [-o output]

Vaporwave image editor

optional arguments:
  -h, --help            show this help message and exit
  -b                    Background image name for the vaporwaver render (without extension) in picts/backgrounds/ folder (default: default)
  -m                    Misc image name for the vaporwaver render (without extension) in picts/miscs/ folder (default: none)
  -mx                   Misc X position (default: 0) [-100, 100]
  -my                   Misc Y position (default: 0) [-100, 100]
  -ms                   Misc scale (default: 100) [1, 200]
  -mr                   Misc rotation (default: 0) [-360, 360]
  -c                    Character image path for the vaporwaver render (default: none) [REQUIRED]
  -cx                   Character X position (default: 0) [-100, 100]
  -cy                   Character Y position (default: 0) [-100, 100]
  -cs                   Character scale (default: 100) [1, 200]
  -cr                   Character rotation (default: 0) [-360, 360]
  -cg                   Character glitch (default: 0.1) [0.1, 1]
  -cgs                  Character glitch seed (default: 1) [0, 100]
  -cgd                  Character gradient to apply, cvt colormap name (default: none) [none, autumn, bone, jet, winter, rainbow, ocean, summer, spring, cool, hsv, pink, hot, parula, magma, inferno, plasma, viridis, cividis, deepgreen]
  -cgl                  Character glow to apply (default: none) [none, red, green, blue, yellow]
  -crt                  CRT effect (default: False)
  -o                    Output file name with path (default: output.png) PNG format only

TypeScript usage

Install the package using either npm or pnpm:

npm install vaporwaver-ts
# or
pnpm install vaporwaver-ts

The package will automatically attempt to install the required Python dependencies during installation. You can manually check the dependencies by running:

npx check-vaporwaver

Import and use the package:

import { vaporwaver } from "vaporwaver-ts";

// Example usage
await vaporwaver({
    background: "neon",          // One of the predefined backgrounds in picts/backgrounds/
    misc: "diamonds",           // One of the predefined misc items in picts/miscs/
    characterPath: "./my-character.png",  // Path to your character PNG file
    characterGradient: "plasma", // Optional: apply a gradient effect
    outputPath: "./output.png"  // Where to save the result
});

// Export only the character with effects (no background or misc items)
await vaporwaver({
    characterPath: "./my-character.png",
    characterGradient: "plasma",
    characterGlitch: 2.5,
    characterOnly: true,         // Export only the character with applied effects
    outputPath: "./character-only.png"
});

Configuration (IFlag interface)

interface IFlag {
    background?: string;        // Name of background file (without .png) from picts/backgrounds/
    misc?: string;             // Name of misc file (without .png) from picts/miscs/
    miscPosX?: number;         // [-100, 100] X position of misc
    miscPosY?: number;         // [-100, 100] Y position of misc
    miscScale?: number;        // [1, 200] Scale of misc
    miscRotate?: number;       // [-360, 360] Rotation of misc
    characterPath: string;     // Path to character PNG file (required)
    characterXPos?: number;    // [-100, 100] X position of character
    characterYPos?: number;    // [-100, 100] Y position of character
    characterScale?: number;   // [1, 200] Scale of character
    characterRotate?: number;  // [-360, 360] Rotation of character
    characterGlitch?: number;  // [0.1, 10] Glitch effect intensity
    characterGlitchSeed?: number; // [0, 100] Seed for glitch effect
    characterGradient?: GradientType; // Predefined gradient type
    crt?: boolean;            // Apply CRT effect
    outputPath?: string;      // Output file path (PNG)
    characterOnly?: boolean;  // Export only the character with effects (no background/misc)
}

Available gradients

The following gradient types are available for characterGradient:

• none, autumn, bone, jet, winter, rainbow, ocean
• summer, spring, cool, hsv, pink, hot, parula
• magma, inferno, plasma, viridis, cividis, deepgreen

Requirements

• Node.js ≥ 14.0.0
• Python ≥ 3.7.0

Debug Mode

Set VAPORWAVER_DEBUG=true environment variable to enable debug logging.

Error Handling

The library now includes comprehensive error handling:

• VaporwaverError: Custom error class with detailed error information
• Validation errors for all input parameters
• PNG file validation
• Path security checks

Logging

Logs are stored in the logs directory by default:

• INFO: General operation information
• WARN: Non-critical warnings
• ERROR: Critical errors
• DEBUG: Detailed debug information (when debug mode is enabled)

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm run test

# Check Python dependencies
npm run check-deps

# Format code
npm run format

# Lint code
npm run lint

Troubleshooting

Common issues and solutions:

1. Python dependency installation fails

   • Try running pip install --user -r requirements.txt
   • Check Python version (>= 3.7.0 required)

2. File not found errors

   • Ensure all required files exist in the correct directories
   • Check file permissions

3. PNG validation fails

   • Ensure input files are valid PNG format
   • Check file permissions