Art

A CLI tool for generating beautiful 2D generative art in Go. This project leverages the generativeart library to create stunning algorithmic artwork with customizable parameters.

Table of Contents

• Installation
• Quick Start
• Available Art Types
• Command Reference
• Configuration
• Examples
• Development
• Troubleshooting
• Planned Features
• Contributing
• License

Installation

Requirements

• Go 1.18 or higher
• Make (optional, for using Makefile targets)

From Source

# Clone the repository
git clone https://github.com/rexposadas/art.git
cd art

# Build the application
go build -o art

# Verify installation
./art --help

Using Make

# Build with race detector
make build

# Build optimized release version
make build-release

# Run all tests
make tests

# Show all available make targets
make

Quick Start

Generate your first piece of art:

# Build and generate circles
make build
./art circles

# This creates a directory called "output" with your generated image
ls -lh output/

On macOS, you can open the generated images:

open output/*

Sample Output

Here are examples of art generated by this tool:

Default circles pattern:

High-resolution circles (300x300):

Available Art Types

The CLI supports the following art generation commands:

Art Type	Description	Canvas	Command
circles	Circular loop patterns	Default	./art circles
circles-gradient	Circles with color gradients	Default	./art circles gradient
circles-grid	Grid-based circle patterns	Default	./art circles grid
circles-loop	Looping circle sequences	Default	./art circles loop
dot	Dot line patterns	512x512+	./art dot
hole	Hole/void patterns	Default	./art hole
julia	Julia set fractals	Default	./art julia
perls	Pearl-like designs	Default	./art perls
smoke	Smoke/fire effects	Default	./art smoke
squares	Random geometric shapes	Default	./art squares
squares-spiral	Spiral square patterns	Default	./art squares spiral

Command Reference

Basic Usage

./art <command> [subcommand] [flags]

Global Flags

Flag	Short	Type	Default	Description
--file	-f	string	``	Path to configuration file
--count	-c	integer	1	Number of images to generate

Examples

# Generate a single circles image with default settings
./art circles

# Generate 5 circles images
./art circles -c 5

# Generate circles using a custom config file
./art circles -f input/config.json

# Generate 10 squares with custom config
./art squares -c 10 -f input/config.json

# Generate dot patterns (requires larger canvas)
./art dot -f input/config.json

# Generate Julia set fractals
./art julia -c 3

Subcommands

Some art types support subcommands for variations:

# Circles variations
./art circles           # Regular circles (default)
./art circles gradient  # Gradient variant
./art circles grid      # Grid-based variant
./art circles loop      # Loop variant

# Squares variations
./art squares           # Regular squares
./art squares spiral    # Spiral variant

Configuration

Configuration File

Configuration files allow you to customize canvas size, output directory, and other parameters. Configuration files use JSON format.

Default Configuration

When no config file is specified, the following defaults are used:

{
  "out": {
    "prefix": "sample",
    "dir": "output"
  },
  "canvas": {
    "width": 300,
    "height": 300
  }
}

Custom Configuration

You can create custom configuration files to adjust canvas size and output location:

{
  "out": {
    "prefix": "my-art",
    "dir": "output/generated"
  },
  "canvas": {
    "width": 1024,
    "height": 1024
  }
}

Configuration Options

Option	Type	Description	Example
out.prefix	string	Filename prefix for generated images	"my-art"
out.dir	string	Output directory path	"output/generated"
canvas.width	integer	Canvas width in pixels	1024
canvas.height	integer	Canvas height in pixels	1024

Using a Configuration File

# Use a custom config file
./art circles -f input/config.json

# Generate multiple images with custom config
./art circles -c 10 -f input/config.json

# Create output in a specific directory
./art circles -f config/high-res.json

Important Notes

• Command-specific prefixes: Each art command automatically uses its own prefix for output files (e.g., smoke-, squares-, dot-, hole-, etc.) unless overridden in the config file
• dot command: Requires minimum canvas size of 512x512
• Default size: 300x300 (fast generation, good for testing)
• High resolution: 1024x1024 or 2048x2048 (slower, higher quality)
• Output directory: Created automatically if it doesn't exist

Examples

Generate a Single Image

./art circles
# Output: output/circles-300x300_<uuid>.png

Generate Multiple Images

./art circles -c 5
# Output: 5 PNG files in output/ directory

Generate with High Resolution

Create a config file config/hires.json:

{
  "out": {
    "prefix": "hires",
    "dir": "output/hires"
  },
  "canvas": {
    "width": 2048,
    "height": 2048
  }
}

Then run:

./art circles -f config/hires.json

Use the Sample Makefile

The repo includes a sample Makefile for batch generation:

# Generate art for all types
make -f sample-Makefile all

Generate Different Art Types

# Generate various art types
./art squares -c 3
./art perls -c 2
./art julia -c 1
./art smoke -c 1
./art hole -c 1

# Check output
ls -lh output/

Development

Build

# Build with race detector
make build

# Build optimized release binary
make build-release

Testing

# Run all tests
make tests

# Run tests with coverage report
make test-coverage

# View coverage report (after running test-coverage)
open coverage.html

Code Quality

# Format code
make fmt

# Run linter (requires golangci-lint)
make lint

Maintenance

# Download/update dependencies
make deps

# Clean build artifacts and generated files
make clean

# Show Go version
make version

Troubleshooting

Canvas Size Error

Problem: Canvas width is too small. Minimum is 512. Got 300

Solution: Use a larger canvas in your config file:

{
  "canvas": {
    "width": 1024,
    "height": 1024
  }
}

Or use the provided config file:

./art dot -f input/config.json

No Output Directory

Problem: failed to create dir output - <error>

Solution: Ensure parent directory exists and you have write permissions:

# Check directory exists
ls -la ./

# Verify permissions
chmod 755 .

Invalid Config File

Problem: failed to parse config: <error>

Solution: Validate your JSON configuration file:

# Check JSON syntax
cat input/config.json | python -m json.tool

# Or use a JSON validator online

Image Generation Failed

Problem: failed to generate <type> images: <error>

Solution:

• Check canvas size is reasonable (at least 256x256)
• Ensure you have disk space
• Try with a smaller canvas size to test

File Already Exists

Each generated image gets a unique identifier in the filename, so overwrites shouldn't occur. If you're concerned about overwriting:

# Use different prefixes in config
./art circles -f config/art1.json
./art circles -f config/art2.json

Planned Features

• Configuration file support
• Generate config file for each image (for reproducibility)
• Parallel generation flag (--workers)
• Web gallery/preview interface
• TOML configuration format support
• Output directory flag (--output-dir)
• Timestamped output subdirectories

Contributing

Contributions are welcome! To contribute:

1. Report Issues: Create an issue describing the problem or feature request
2. Submit Changes: Create a pull request with your improvements
3. Testing: Ensure all tests pass before submitting:

   make tests

Please follow the existing code style and include tests for new features.

License

This project is licensed under the MIT License.

See the LICENSE file for full details.