Edit. Enhance. Create. Privately.
PeaBox Photo Lab is a lightweight, privacy-first photo editing and creator toolkit built with Python, Streamlit, Pillow, and NumPy.
It is designed for users who want practical photo-editing capabilities without the complexity of a professional graphics suite.
Along with everyday image adjustments, PeaBox Photo Lab includes creative effects, smart enhancements, social-media exports, colour palette extraction, style comparisons, watermarking, image inspection, and creator-focused utilities.
- 🖥️ Simple browser-based interface
- 🔒 Privacy-first local workflow
- 🎨 Non-destructive editing
- 🪄 Smart Auto Optimize
- 🌡️ Temperature and tonal adjustments
- 🎞️ Creative presets
- 🖌️ Artistic effects
- 👀 Before/after comparison
- 📐 Social-media crop formats
- 🎨 Colour palette extraction
- 🖼️ Style comparison sheet
- 🏷️ Watermark and branding tools
- 📦 Social Format Pack export
- 🔍 Image quality inspector
- 📤 JPEG, PNG and WebP export
- 🧹 Fresh exports without copying original EXIF metadata
- #what-is-peabox-photo-lab
- #who-is-it-for
- #features
- #system-requirements
- #installation
- #windows-installation
- #linux-installation
- #macos-installation
- #starting-peabox-photo-lab
- #user-guide
- #photo-editing-controls
- #creative-lab
- #creator-toolkit
- #image-inspector
- #exporting-images
- #recommended-workflows
- #privacy
- #project-structure
- #troubleshooting
- #developer-guide
- #contributing
- #security
- #roadmap
- #license
PeaBox Photo Lab aims to provide commonly needed photo-editing and creator functions without forcing users to learn a complicated professional image editor.
The basic workflow is intentionally simple:
Upload
↓
Enhance
↓
Edit
↓
Create
↓
Inspect
↓
Export
The application runs through a browser interface while Python performs the image processing.
Your original photograph is not overwritten.
PeaBox Photo Lab can be useful for:
- Casual photographers
- Bloggers
- Content creators
- Teachers
- Students
- Small businesses
- Social-media managers
- Website owners
- Presentation creators
- Developers
- Anyone needing quick image preparation
PeaBox Photo Lab is not intended to replace full professional image-editing applications.
Instead, its philosophy is simple:
Make useful image editing easy, fast, approachable and extensible.
The editor includes controls for:
- Brightness
- Contrast
- Saturation
- Sharpness
- Temperature
- Shadows
- Highlights
- Rotation
- Horizontal mirror
- Vertical flip
All adjustments are non-destructive.
Changing a control regenerates the edited image from the original uploaded photograph.
Not sure where to begin?
Enable:
Smart Auto Optimize
PeaBox automatically performs a combination of tonal correction, exposure balancing and sharpening.
It is designed to provide a useful starting point before manual editing.
A simple workflow is:
Upload Photo
↓
Smart Auto Optimize
↓
Review Result
↓
Fine-tune Manually
↓
Export
PeaBox Photo Lab provides several built-in photographic styles.
Adds a cleaner, brighter and more colourful appearance.
Useful for:
- everyday photography
- products
- travel images
- web content
- social-media posts
Produces a warmer and slightly softer photographic treatment.
Useful for:
- travel
- lifestyle images
- portraits
- landscapes
Introduces a cooler colour tone with additional contrast.
Useful for:
- architecture
- business content
- urban photography
- editorial-style images
Creates a high-contrast monochrome treatment.
Useful for:
- artistic photography
- architecture
- portraits
- dramatic compositions
Reduces contrast and colour intensity while introducing warmer tones.
Useful for:
- retro graphics
- travel photos
- lifestyle images
- creative posts
PeaBox can automatically center-crop photographs using common aspect ratios.
Available options include:
Original
1:1
4:5
3:2
16:9
9:16
Square format.
Useful for:
- profile images
- square posts
- thumbnails
- product photography
Portrait-oriented format.
Useful for:
- vertical posts
- product photographs
- people photography
Traditional photography-style ratio.
Widescreen format.
Useful for:
- website banners
- presentations
- thumbnails
- landscape visuals
Vertical format.
Useful for:
- mobile-first content
- stories
- vertical promotional graphics
Note: The current crop feature uses center cropping rather than interactive drag-to-select cropping.
Controls the overall brightness of the image.
Move right to brighten the photograph.
Move left to darken it.
Controls the difference between lighter and darker areas.
Higher contrast can make an image appear stronger and more dramatic.
Lower contrast creates a softer appearance.
Controls colour intensity.
Increase saturation for stronger colours.
Decrease saturation for more muted colours.
Adjusts perceived image sharpness.
Use this carefully.
Extremely high values can exaggerate noise and compression artefacts.
Changes the overall colour temperature.
Positive values create a warmer appearance.
Negative values create a cooler appearance.
Adjusts darker areas of the image.
Increasing shadows can help reveal details in dark areas.
Adjusts brighter areas of the photograph.
This can help balance images with bright regions.
PeaBox includes a collection of creative image effects.
Open:
Creative add-ons
Choose an effect and adjust:
Effect Strength
Selective Colour Pop keeps colours around a selected hue while shifting other areas toward grayscale.
Controls include:
Colour-pop hue
Hue range
A narrower range isolates colours more aggressively.
A wider range keeps more surrounding colours.
Useful for:
- product photography
- advertisements
- posters
- visual storytelling
- creative social posts
Duotone converts the image into a design based primarily on two colours.
Choose:
Duotone Shadows
Duotone Highlights
Example:
Shadows: #172554
Highlights: #FBBF24
This creates a navy-and-gold visual treatment.
Useful for:
- posters
- thumbnails
- presentation graphics
- brand visuals
- album-style artwork
Adds a soft glowing appearance.
Particularly useful for:
- landscapes
- portraits
- lifestyle photographs
- travel images
- atmospheric photographs
Adjust:
Effect Strength
to control the intensity.
Transforms a photograph into a sketch-like interpretation.
Reducing the effect strength can produce an interesting mixture of the original photograph and the sketch effect.
Transforms the photograph into pixel-style artwork.
Adjust:
Pixel Size
Smaller blocks preserve more detail.
Larger blocks create stronger pixelation.
Useful for:
- retro art
- gaming visuals
- avatars
- experimental graphics
- creative posts
Gradually darkens areas near the edges of the photograph.
This can help focus attention toward the centre of the image.
Increase:
Effect Strength
for a stronger vignette.
PeaBox Photo Lab includes simple tools for preparing images for publishing.
Open:
Brand kit and finishing
Enter your desired watermark.
Example:
PeaBox Labs
Available positions include:
Bottom right
Bottom left
Top right
Top left
Center
You can also change:
Watermark opacity
Add a border to the finished photograph.
Configure:
Border width
Border colour
Example:
Width: 2%
Colour: #FFFFFF
This creates a simple white frame.
Open:
Editor
Enable:
Before and after view
The application displays:
Original Edited
↓ ↓
Before After
This is particularly useful for judging whether editing has improved the photograph.
The Creator Toolkit provides additional utilities intended for bloggers, marketers, creators and small businesses.
Open:
Creator Toolkit
PeaBox examines the edited photograph and extracts prominent colours.
Example output:
#172554
#2563EB
#F59E0B
#F8FAFC
#334155
#94A3B8
Colours are displayed visually and provided in JSON.
Example:
{
"palette": [
"#172554",
"#2563EB",
"#F59E0B",
"#F8FAFC",
"#334155",
"#94A3B8"
]
}This can be useful for:
- website themes
- presentation themes
- branding
- social-media graphics
- blog design
- complementary designs
Instead of testing every preset individually, PeaBox can create a comparison sheet.
The sheet includes:
Original
Clean Pop
Warm Film
Cool Editorial
Mono Punch
Vintage Fade
Select:
Download style proof sheet
PeaBox generates an image containing the different variants.
This makes choosing a photographic style easier.
A single photograph often needs several different sizes for publishing.
PeaBox can automatically create several aspect-ratio variants.
Current formats include:
Square 1:1
Portrait 4:5
Landscape 16:9
Story 9:16
Select:
Download social format pack (ZIP)
PeaBox generates the images and packages them into a ZIP archive.
Instead of:
Crop
Export
Crop again
Export again
Crop again
Export again
you can use:
Edit once
↓
Generate Social Pack
↓
Download ZIP
Open:
Image Inspector
The inspector displays information including:
Width
Height
Megapixels
Aspect Ratio
Resolution Health
Example:
Width: 4032
Height: 3024
Megapixels: 12.2 MP
Aspect: 1.33:1
PeaBox also provides a basic warning when an image may be relatively small for larger exports.
This warning is intended as convenience guidance rather than a universal image-quality standard.
Recommended environment:
Python 3.10+
Windows / Linux / macOS
Modern web browser
Main Python dependencies:
Streamlit
Pillow
NumPy
Dependencies are listed in:
requirements.txt
You can either clone the repository using Git or download the project as a ZIP file from GitHub.
git clone YOUR_REPOSITORY_URLEnter the project directory:
cd peabox-photo-labPeaBox includes:
run_windows.bat
Double-click this file.
The launcher will:
Create virtual environment
↓
Activate environment
↓
Install dependencies
↓
Start Streamlit
↓
Launch PeaBox Photo Lab
Open Command Prompt or PowerShell inside the project directory.
First check Python:
py --versionCreate a virtual environment:
py -3 -m venv .venv.venv\Scripts\activate.\.venv\Scripts\Activate.ps1Install dependencies:
python -m pip install -r requirements.txtStart PeaBox:
python -m streamlit run app.pyDo not use:
source .venv/bin/activateinside regular PowerShell or Command Prompt.
That command is intended for Unix-style shells.
Use:
.\.venv\Scripts\Activate.ps1in PowerShell.
Or:
.venv\Scripts\activatein Command Prompt.
Open a terminal and enter the project directory:
cd peabox-photo-labMake the launcher executable:
chmod +x run_linux_mac.shRun:
./run_linux_mac.shpython3 -m venv .venvActivate:
source .venv/bin/activateInstall dependencies:
python -m pip install -r requirements.txtStart:
python -m streamlit run app.pyOpen Terminal.
Enter the project directory:
cd peabox-photo-labCreate the virtual environment:
python3 -m venv .venvActivate:
source .venv/bin/activateInstall:
python -m pip install -r requirements.txtStart:
python -m streamlit run app.pyOr use:
chmod +x run_linux_mac.sh
./run_linux_mac.shOnce everything is installed:
python -m streamlit run app.pyYour terminal will display the local Streamlit address.
Open that address in a browser.
Click:
Browse files
Choose an image.
Supported formats in the current application include:
JPG
JPEG
PNG
WebP
Choose:
None
Clean Pop
Warm Film
Cool Editorial
Mono Punch
Vintage Fade
If you want complete manual control, leave this set to:
None
Enable:
Smart Auto Optimize
Review the result.
You can then fine-tune the photograph manually.
Choose:
Original
1:1
4:5
3:2
16:9
9:16
Choose the ratio based on where you plan to use the image.
Use:
Brightness
Contrast
Shadows
Highlights
An example starting point might be:
Brightness: +5
Contrast: +10
Shadows: +10
Highlights: -5
This is only an example.
Every photograph is different.
Use:
Saturation
Temperature
For warmer photographs:
Temperature → Positive
For cooler photographs:
Temperature → Negative
Use:
Sharpness
Avoid excessive sharpening, particularly on compressed or noisy images.
Open:
Creative add-ons
Choose:
Selective Colour Pop
Duotone
Dreamy Glow
Pencil Sketch
Pixel Art
Focus Vignette
Adjust:
Effect Strength
until you are satisfied with the result.
Open:
Brand kit and finishing
Configure:
Watermark
Watermark position
Watermark opacity
Border
Border colour
Open:
Image Inspector
Review:
Dimensions
Megapixels
Aspect ratio
Resolution health
Open:
3. Export
Select your file format:
JPEG
PNG
WEBP
Set quality.
Example:
JPEG
Quality: 92
Choose a maximum long edge:
Original
4096
2560
2048
1600
1080
Enter your filename.
Example:
my-edited-photo
Finally click:
Download edited photo
Suitable for:
- photographs
- blogs
- websites
- social sharing
- general image use
JPEG allows adjustable export quality.
Useful for:
- lossless PNG output
- graphics
- screenshots
- assets where PNG is preferred
PNG files can be larger than equivalent photographic JPEG or WebP files.
Useful for:
- websites
- blogs
- modern web workflows
PeaBox provides adjustable WebP quality.
Upload
↓
Smart Auto Optimize
↓
Clean Pop
↓
Fine-tune brightness
↓
Export JPEG
Upload
↓
16:9 Crop
↓
Smart Auto
↓
Adjust Contrast
↓
Add Watermark
↓
Resize
↓
Export JPEG/WebP
Upload
↓
Edit Master Image
↓
Creator Toolkit
↓
Generate Social Format Pack
↓
Download ZIP
Upload Image
↓
Edit
↓
Creator Toolkit
↓
Colour Palette Extractor
↓
Copy HEX Values
Upload
↓
Creative Add-ons
↓
Choose Effect
↓
Adjust Strength
↓
Add Border
↓
Export
Privacy is an important design principle of PeaBox Photo Lab.
When the application is run locally, processing takes place through the locally running Python application.
The current PeaBox application:
- reads uploaded images for processing
- processes them in the application process
- creates export data in memory
- does not intentionally save uploaded photographs into a persistent application image library
- creates a freshly encoded image for export
- does not copy the original photograph's EXIF metadata into the exported image
The current export process creates a newly encoded image.
Original EXIF metadata is not intentionally copied into the exported image.
This can help avoid unintentionally preserving source metadata in the edited version.
If metadata privacy is critically important, independently inspect sensitive images before publication.
There is an important difference between running PeaBox locally and deploying it to a server.
Browser
↓
Local Streamlit
↓
Local Python
↓
Image Processing
The software and image processing run on your computer.
Browser
↓
Internet
↓
Remote Streamlit Server
↓
Image Processing
A remotely hosted version necessarily receives uploaded image data on the server.
Remote deployments should therefore consider:
- HTTPS
- authentication
- infrastructure security
- access control
- server logging
- temporary image handling
- retention policies
- backups
- privacy requirements
peabox-photo-lab/
│
├── app.py
├── requirements.txt
├── pyproject.toml
│
├── run_windows.bat
├── run_linux_mac.sh
│
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── SUPPORT.md
├── LICENSE
│
├── .gitignore
├── .editorconfig
│
└── .github/
│
├── ISSUE_TEMPLATE/
│ ├── bug_report.yml
│ ├── feature_request.yml
│ └── config.yml
│
├── workflows/
│ └── python-checks.yml
│
├── dependabot.yml
└── pull_request_template.md
Try:
py --versionor:
python --versionIf neither command works, install Python and reopen your terminal.
Do not use:
source .venv/bin/activatefrom Windows Command Prompt or normal PowerShell.
Use:
.venv\Scripts\activateUse:
.\.venv\Scripts\Activate.ps1You can run the virtual environment without activating it.
Install dependencies with:
.\.venv\Scripts\python.exe -m pip install -r requirements.txtThen start PeaBox with:
.\.venv\Scripts\python.exe -m streamlit run app.pyInstall the dependencies:
python -m pip install -r requirements.txtThen use:
python -m streamlit run app.pyinstead of:
streamlit run app.pyExample:
ModuleNotFoundError: No module named 'PIL'
Install dependencies:
python -m pip install -r requirements.txtMake sure you are using the same Python environment that PeaBox uses.
Check that the file is one of the supported types:
JPG
JPEG
PNG
WebP
Try opening the image in another image viewer to ensure the source file is not corrupt.
High-resolution photographs may require significantly more memory after they are decompressed for editing.
You can try:
- using a smaller copy
- closing unnecessary applications
- reducing output dimensions
- avoiding unnecessarily large source images for web content
Check:
Preset
Smart Auto
Brightness
Contrast
Saturation
Temperature
Effect Strength
Export Format
Export Quality
For JPEG and WebP, try increasing the quality setting if compression is visibly affecting the result.
Clone the project:
git clone YOUR_REPOSITORY_URLEnter the directory:
cd peabox-photo-labCreate a virtual environment:
python -m venv .venv.\.venv\Scripts\Activate.ps1source .venv/bin/activateInstall dependencies:
python -m pip install -r requirements.txtStart:
python -m streamlit run app.pyBefore committing:
python -m py_compile app.pyManually test:
JPG Upload
PNG Upload
WebP Upload
JPEG Export
PNG Export
WebP Export
Crop
Rotate
Mirror
Smart Auto
Presets
Creative Effects
Watermark
Borders
Palette Extraction
Proof Sheet
Social Format Pack
Image Inspector
Provides the primary application and image-processing logic.
Provides the browser-based application interface.
Provides core image manipulation including enhancement, filtering, colour operations, drawing and image transformations.
PeaBox uses functionality from modules including:
Image
ImageOps
ImageEnhance
ImageFilter
ImageDraw
ImageChops
ImageFont
Provides array and pixel-level calculations used for custom image effects.
Contributions are welcome.
Interesting contribution areas include:
Creative effects
New presets
Image processing algorithms
Performance
Accessibility
User interface improvements
Automated testing
Documentation
Export formats
Batch processing
Creator utilities
Localization
Recommended workflow:
Fork Repository
↓
Create Branch
↓
Make Changes
↓
Test
↓
Commit
↓
Submit Pull Request
Please read:
CONTRIBUTING.md
before submitting significant changes.
Use the included GitHub:
Bug Report
issue form.
Please provide:
Operating system
Python version
Browser
Image format
Approximate dimensions
Steps to reproduce
Expected result
Actual result
Error message
Do not publicly upload:
Private photographs
Passwords
API keys
Tokens
Credentials
Personal information
Use the:
Feature Request
GitHub issue form.
A useful feature request should explain:
- The user problem
- The proposed feature
- The expected user experience
- Why the feature is valuable
- Whether it requires external services
If you discover a vulnerability, do not publish sensitive vulnerability details through a regular public issue.
Read:
SECURITY.md
and use the repository's configured private security-reporting mechanism where available.
The following are possible future directions rather than commitments.
- Interactive crop selection
- Straighten tool
- Resize by exact dimensions
- Exposure
- Curves
- Levels
- HSL adjustment
- Blur controls
- Histogram view
- Custom export profiles
- Saved brand presets
- Logo watermark upload
- Batch watermarking
- More social-media presets
- Thumbnail generator
- Collage generator
- Contact-sheet customization
Potential future experimentation could include:
- Background removal
- Object segmentation
- Subject-aware adjustments
- Noise reduction
- Image upscaling
- Portrait enhancement
- Local AI-assisted editing
- Intelligent auto-crop
Potential improvements include:
- Undo / redo
- Editing history
- User-created presets
- Drag-and-drop workflow
- Keyboard shortcuts
- Dark/light themes
- Localization
- Desktop packaging
PeaBox Photo Lab follows five basic principles.
Users should not need professional photography knowledge to perform common tasks.
Features should solve practical image creation and publishing problems.
Where practical, image processing should remain on the user's machine.
One photograph should easily become multiple publishing assets.
Developers should be able to understand, modify and extend the application.
peabox-photo-lab
PeaBox Photo Lab
A privacy-first, local photo editor built with Python, Streamlit and Pillow, featuring smart enhancements, creative effects and creator tools.
python
streamlit
pillow
photo-editor
image-processing
image-editor
photo-effects
creator-tools
privacy-first
webp
photo-enhancement
open-source
peabox
PeaBox Photo Lab v2.0.0
Release title:
PeaBox Photo Lab 2.0 - Creator Toolkit
PeaBox Photo Lab is distributed under the MIT License.
See:
LICENSE
for the complete license terms.
PeaBox Photo Lab is part of the PeaBox collection of practical creator, publishing, AI and productivity tools.
The PeaBox philosophy is simple:
Build useful tools. Keep them approachable. Let people make them their own.
If you find PeaBox Photo Lab useful:
- ⭐ Star the repository
- 🐛 Report bugs
- 💡 Suggest features
- 🔧 Contribute improvements
- 🍴 Fork the project
- 📣 Share it with others