Transform flat maps into printable globe segments!
Orbsmith is a Python application that converts spherical map images (like world maps, moon maps, or planetary surfaces) into printable "gore" segments that can be cut out and assembled into beautiful 3D globes.
- 🎯 User-Friendly: Interactive setup wizard for beginners
- ⚡ Flexible: Command-line options for power users
- 🖨️ Print-Ready: High-quality 600 DPI PDF output
- 📏 Customizable: Support for any ball size (5-100cm circumference)
- 🌙 Versatile: Works with Earth, Moon, Mars, or any spherical map
- 🔧 Smart: Automatic print optimization for dark images
- 📱 Cross-Platform: Works on Windows, macOS, and Linux
One-Line Installation:
git clone https://github.com/yourusername/orbsmith.git && cd orbsmith && ./setup.shChoose your platform and run the appropriate setup script:
# Double-click setup.bat or run in Command Prompt:
setup.bat# Recommended: Universal setup
./setup.sh
# Advanced: macOS-specific (with Homebrew support)
./scripts/setup-mac.sh# Recommended: Universal setup
./setup.sh
# Advanced: Distribution-specific setup
./scripts/setup-linux.sh# Works on Windows, macOS, and Linux with PowerShell
./scripts/setup.ps1💡 Advanced Setup Options: Check the
scripts/folder for specialized setup scripts with additional features like Homebrew integration, distribution detection, and interactive Python setup.
The setup script will:
- ✅ Check Python 3.7+ installation
- ✅ Install all dependencies (Pillow, numpy, reportlab)
- ✅ Create virtual environment (recommended, falls back to system if needed)
- ✅ Activate virtual environment automatically
- ✅ Create input/ and output/ folders
- ✅ Test the installation with --help command
- ✅ Provide clear next steps and usage examples
Both setup.sh (Linux/macOS) and setup.bat (Windows) perform identical operations:
- 🔍 System Check: Verify Python 3.7+ and pip are installed
- 🏗️ Environment Setup: Create virtual environment (
venv/) to isolate dependencies - 📦 Dependencies: Install required packages from
requirements.txt - 📁 Folders: Create
input/andoutput/directories - 🧪 Validation: Test installation by running
python main.py --help - 📋 Guidance: Display usage examples and next steps
Virtual Environment Benefits:
- 🛡️ Isolation - Prevents conflicts with other Python projects
- 🔄 Clean - Easy to remove by deleting
venv/folder - ✅ Automatic - Scripts handle activation/deactivation
- 🔄 Fallback - Uses system Python if virtual environment fails
If you prefer manual setup:
git clone https://github.com/yourusername/orbsmith.git
cd orbsmith
pip install -r requirements.txt
python main.pyAlternative Python-based setup:
python scripts/setup.py # Interactive Python setuppython main.pyFollow the guided prompts to:
- 📁 Choose your map image
- 📏 Select ball size (with handy presets)
- 🖨️ Configure print optimization
- ✨ Generate your globe gores!
# Try the moon map sample
python main.py samples/moon_map.jpg
# Try the earth map sample
python main.py samples/earth_map.jpg --size 25# Basic usage with sample
python main.py samples/moon_map.jpg
# Custom ball size with sample
python main.py samples/earth_map.jpg --size 25
# Disable print optimization
python main.py your_image.jpg --no-optimization
# Custom output filename
python main.py your_image.jpg --output my_custom_globe.pdf
# See available images
python main.py --listpython main.py [IMAGE] [OPTIONS]
Arguments:
IMAGE Input image filename (if not specified, interactive mode)
Options:
-s, --size SIZE Ball circumference in cm (default: 22)
-o, --output FILE Output PDF filename
--no-optimization Disable print brightness/contrast optimization
--interactive Force interactive mode even with arguments
--list List available input images
-h, --help Show help message| Size | Circumference | Use Case | Gore Count |
|---|---|---|---|
| Small | 16cm (π×5cm radius) | Desktop display, teaching aid | 13 gores |
| Medium | 22cm (π×7cm radius) | Recommended - Tennis/baseball size | 13 gores |
| Large | 31cm (π×10cm radius) | Impressive display piece | 13 gores |
| Jumbo | 47cm (π×15cm radius) | Educational institution | 13 gores |
💡 Tip: Medium (22cm) works great with tennis balls, baseballs, or similar sized spheres!
Orbsmith includes smart print optimization for better physical results:
- ✅ Dark space images (moon maps, deep space)
- ✅ Low contrast maps (need brightness boost)
- ✅ Satellite imagery (often needs enhancement)
- ❌ Already bright maps (artistic world maps)
- ❌ High contrast images (black & white maps)
- ❌ Pre-optimized images (professionally prepared)
Settings:
- 🔆 Brightness boost: +40%
- 🎨 Contrast boost: +10%
orbsmith/
├── main.py # Main application entry point
├── requirements.txt # Python dependencies
├── README.md # Project documentation
├── LICENSE # Public domain license
├── setup.sh # Setup script (Linux/macOS)
├── setup.bat # Setup script (Windows)
├── samples/ # Sample images to try
│ ├── moon_map.jpg # Lunar surface map (175KB, 1024x512)
│ └── earth_map.jpg # Earth topographic map (93KB, 1024x512)
├── input/ # Place your own map images here
├── output/ # Generated PDFs appear here
│ └── 2024-08-05_14-30-15/ # Timestamped folders
├── scripts/ # Advanced setup scripts & utilities
│ ├── README.md # Documentation for advanced scripts
│ ├── setup.ps1 # PowerShell setup (cross-platform)
│ ├── setup-mac.sh # macOS-specific with Homebrew
│ ├── setup-linux.sh # Linux distribution-specific
│ ├── setup.py # Python interactive setup
│ └── test-setup.sh # Setup validation script
└── src/ # Source code modules
├── config.py # Configuration settings
├── cli.py # Command-line interface
├── image_processing.py # Image manipulation
├── gore_generator.py # Core gore generation
├── layout_manager.py # Page layout logic
├── pdf_generator.py # PDF creation
├── progress.py # Progress tracking
├── validation.py # Input validation
├── presets.py # Ball size presets
├── file_manager.py # File operations
└── reporter.py # Output summaries
- PNG - Recommended for best quality
- JPEG/JPG - Good for photographs
- TIFF - High-quality scientific images
- Recommended resolution: 5187×2598 pixels (2:1 aspect ratio)
- Minimum resolution: 2000×1000 pixels
- 📥 Input: Spherical map image (rectangular projection)
- 🔄 Processing: Converts to 13 gore segments using spherical geometry
- 📐 Layout: Arranges gores optimally on A4 pages
- 🖨️ Output: High-quality 600 DPI PDF ready for printing
Globe gores are curved segments that, when assembled, form a sphere. Orbsmith:
- Divides the sphere into 13 segments (optimal for assembly)
- Uses bilinear interpolation for smooth curves
- Applies spherical mapping mathematics
- Optimizes for minimal distortion
python main.py lunar_surface.jpg --size 22Create a detailed moon globe perfect for astronomy education.
python main.py world_map.png --size 31 --output earth_globe.pdfGenerate a large Earth globe for geography lessons.
python main.py mars_surface.jpg --size 16 --no-optimizationBuild a Mars globe with accurate surface features.
- 📄 Printed gores (on cardstock recommended)
- ✂️ Sharp scissors or craft knife
- 🎈 Spherical base (ball, balloon, styrofoam sphere)
- 📏 Ruler for precise cutting
- 🔗 Glue (spray adhesive or glue stick)
- Print the PDF on cardstock (heavier paper works better)
- Cut out each gore carefully along the edges
- Test fit gores around your sphere before gluing
- Apply one gore at a time, starting from the top
- Smooth out air bubbles as you go
- Overlap edges slightly for seamless appearance
- 💡 Score fold lines lightly before assembly
- 🎯 Start with opposite gores for better alignment
- 🔍 Work in good lighting for precision
- ⏱️ Take your time - rushing leads to wrinkles
- Python: 3.7 or higher
- Dependencies: Only 3 packages (Pillow, numpy, reportlab)
- Memory: ~500MB for large images
- Disk Space: ~100MB for typical projects
- Processing Time: 1-5 minutes for typical images
- Output Size: 1-10MB PDFs
- Resolution: 600 DPI for crisp printing
- Color Space: RGB with print optimization
python main.py --list # Check available imagesMake sure your image is in the input folder.
- ✅ Use images with 2:1 aspect ratio (width:height)
- ✅ Minimum 2000×1000 pixels recommended
- ✅ Higher resolution = better print quality
python main.py your_image.jpg --size 25 # Try larger ball- ✅ Enable print optimization for dark images
- ✅ Use cardstock paper (heavier than regular paper)
- ✅ Print at highest quality setting
"Command not found" or "Permission denied"
# Make setup script executable (Linux/macOS)
chmod +x setup.sh
./setup.sh
# Windows: Right-click setup.bat → "Run as administrator""Virtual environment creation failed"
- ✅ Scripts automatically fall back to system Python
- ✅ This warning is usually safe to ignore
- ✅ All features work with system Python installation
"Dependencies failed to install"
# Try manual installation
pip install Pillow numpy reportlab
# Or use advanced scripts with system package managers
./scripts/setup-mac.sh # macOS with Homebrew
./scripts/setup-linux.sh # Linux with apt/yum/etc- 📖 Check this README thoroughly
- 🐛 Run with
--helpfor command options - 🔍 Validate your input image format and size
- 💡 Try the interactive mode for guided setup
- 🛠️ Check
scripts/README.mdfor advanced setup options
Orbsmith is open source and welcomes contributions!
- 🎨 Additional map projections (Mercator, Robinson, etc.)
- 🔧 Batch processing for multiple images
- 📱 Mobile-friendly web interface
- 🎯 Custom gore counts (beyond 13)
- 🖼️ Image preprocessing tools
git clone https://github.com/yourusername/orbsmith.git
cd orbsmith
pip install -r requirements.txt
python main.py --helpThis project is released into the Public Domain under the Unlicense.
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or distribute
this software for any purpose, commercial or non-commercial.
- Spherical geometry algorithms inspired by cartographic research
- Gore generation techniques from traditional globe-making
- Community feedback from educators and makers
- Open source Python ecosystem (PIL, numpy, reportlab)
🌍 Made with ❤️ for educators, makers, and space enthusiasts!
Transform any world into a globe you can hold in your hands.