Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,27 @@ All notable changes to Pasteup are recorded here. The format follows

## [Unreleased]

### Added
- **Browse…** beside the folder field opens a folder browser, so a folder can be
picked instead of typed. It opens at the folder in the field, or at your home
folder, says how many images the folder you're in holds, and scans the one
you choose. Typing or pasting a path still works.
(`POST /api/jobs/browse-folder`)
- Upscaled images, from a tile of their own in step 3: every image of a bundle,
or of each picked bundle, made 2x, 3x or 4x bigger and saved in an
`Upscaled` folder as a PNG, which keeps any transparency, and a JPG on
white. (`POST /api/jobs/upscale-images`, `POST /api/jobs/upscale-images-batch`)

### Fixed
- Hidden files are no longer counted as images. A Mac writes a hidden `._`
file beside the files it copies to an exFAT or FAT32 drive or to some network
shares, so such a bundle could scan as twice its size, and making sheets then
reported the extra files as unreadable.
- Hidden folders, such as the `.Spotlight-V100` and `.Trashes` a Mac keeps on
those drives, and the `__MACOSX` folder left by unpacking a zip made on a
Mac, are no longer offered as bundles. Covers no longer take images from
them, nor from a `---Created---` folder inside the bundle.

## [0.1.0] - 2026-10-16

The first release on PyPI.
Expand Down
129 changes: 123 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ publishing: cut out by hand and pasted onto a layout board.
main image.
- **Preview video:** an MP4 slideshow of the sheets, exactly as long as you ask
(Etsy's listing videos run 5 to 15 s).
- **Upscaled images:** every image made 2x, 3x or 4x bigger, saved in an
`Upscaled` folder as a PNG, which keeps any transparency, and a JPG on white.
- **Clean-up:** transparent PNGs land on white instead of black, phone photos
are turned upright, and near-white backgrounds can be removed.
- **Batch mode:** process every bundle folder under a parent folder in one go.
Expand Down Expand Up @@ -114,7 +116,8 @@ PyPI trusts `release.yml` running in this repository's `pypi` environment.
Project layout:
- `src/pasteup/main.py`: the FastAPI app
- `src/pasteup/routes/`: the page and the `/api/jobs` endpoints
- `src/pasteup/services/`: scanning, page composition, collages, export, video
- `src/pasteup/services/`: scanning and browsing folders, page composition,
collages, export, video
- `src/pasteup/models/`: request and response schemas
- `src/pasteup/templates/` and `src/pasteup/static/`: the UI
- `src/pasteup/cli.py`: the `pasteup` command; `shortcut.py` makes its launchers
Expand All @@ -131,6 +134,12 @@ Input scan supports the following image extensions (case-insensitive):

Notes:
- Folder scan is **non-recursive** (only files directly inside the selected folder).
- Hidden files, whose names start with a dot, are skipped. Most are the `._`
files a Mac writes beside the files it copies to an exFAT or FAT32 drive or
to some network shares: they carry the image's extension but hold no image.
- Hidden folders, `__MACOSX` (left by unpacking a zip made on a Mac) and
`---Created---` are never offered as bundles, and covers don't look inside
them.
- Export output format supports `PNG` and `JPG`.

---
Expand All @@ -149,6 +158,7 @@ Default UI values:
- `background_tolerance`: `240`
- `background_feather`: `1`
- `include_partial_page`: `false`
- upscaling `scale`: `2` (also `3` or `4`)

Behavior defaults:
- Scan sample size: first `5` files (`sample_files`) in sorted order.
Expand Down Expand Up @@ -186,6 +196,34 @@ Validates a folder and scans for supported image files.
- `estimated_pages` (int): `image_count // 12` (whole pages only).
- `message` (str): summary or error detail.

### `POST /api/jobs/browse-folder`
Lists the folders inside a folder, for the folder browser behind **Browse…**. A
page can't read the path of a folder picked with the browser's own file
chooser, so the UI browses through this instead.

**Request body**
```json
{
"folder_path": "~/Pictures"
}
```
A blank `folder_path` lists the home folder.

**Response fields**
- `path` (str): the folder listed. One that does not exist or cannot be opened
gives way to the nearest folder above it that can, and `message` says why.
- `parent_path` (str | null): the folder above it; `null` at the top of a drive.
- `breadcrumbs` (list): `name` and `path` of each folder from the top of the
drive down to this one.
- `folders` (list): `name` and `path` of each folder inside, sorted, leaving
out hidden folders, `__MACOSX` and `---Created---`.
- `image_count` (int): supported images directly inside, counted as
`scan-folder` counts them.
- `places` (list): shortcuts: the home folder, its Desktop, Documents,
Downloads and Pictures folders when it has them, and each drive on Windows.
- `message` (str): empty unless a different folder was listed than the one
asked for.

### `POST /api/jobs/scan-selected-batch-folders`
Validates selected batch subfolders under a scanned parent folder and reports which selected folders are ready for generation.

Expand Down Expand Up @@ -364,22 +402,88 @@ Makes one cover per bundle folder, as `/generate-all-folders` does for sheets.
`pages_generated`, `total_images`, `output_path`, `output_files` and `message`
- `message` (str)

### `POST /api/jobs/upscale-images`
Makes every image of a folder bigger, saving each as a PNG and as a JPG in an
`Upscaled` folder inside `output_path`: `Upscaled/PNG/<name>.png` and
`Upscaled/JPG/<name>.jpg`. The PNG keeps any transparency; the JPG is
flattened onto white. Images are resampled with Lanczos, which keeps edges
smooth but adds no detail.

**Request body**
```json
{
"folder_path": "/path/to/images",
"output_path": "/path/to/output",
"scale": 2,
"dpi": 300
}
```
- `scale` (`2` | `3` | `4`, default `2`): how many times bigger each side becomes.
- `dpi` (int, 1-1200, default `300`): stamped into every file.
- Each file keeps its image's name, so upscaling again replaces what the last
run made.
- Files sharing a name in different formats, such as `art.png` and `art.jpg`,
would be saved over each other, so one gives both formats: PNG first, then
WebP, then JPG.
- Upscaled images are capped at 100 megapixels; an image that would pass that
is left out and named in the response.

**Response fields**
- `success` (bool): whether any image was upscaled
- `scale` (int)
- `total_images` (int): images upscaled
- `output_path` (str): the `Upscaled` folder
- `png_folder`, `jpg_folder` (str): the two folders inside it
- `output_files` (list[str]): every file written
- `images_skipped` (int): files that could not be read as images
- `too_large_files` (list[str]): images left out for passing the cap
- `same_name_files` (list[str]): files left out for sharing a name with the
image that was used
- `message` (str)

### `POST /api/jobs/upscale-images-batch`
Upscales each selected bundle into `<created_output_root_path>/<bundle>/Upscaled`.

**Request body**
```json
{
"parent_folder_path": "/path/to/parent-folder",
"created_output_root_path": "/path/to/created-output-root",
"selected_subfolders": ["/path/to/parent-folder/bundle-a", "/path/to/parent-folder/bundle-b"],
"scale": 4,
"dpi": 300
}
```

**Response fields**
- `success` (bool)
- `created_output_root_path` (str)
- `processed_folders`, `selected_folders`, `total_detected_folders`,
`generated_folders` (int): as for `/generate-all-folders`
- `scale` (int)
- `bundle_results` (list): per bundle, `folder_name`, `success`,
`total_images`, `output_path`, `images_skipped`, `too_large_files`,
`same_name_files` and `message`
- `message` (str)

---

## Using the app
1. Run `pasteup`; it opens in your browser.
2. **Pick your clip art.** Choose **One bundle** (a folder of images) or **Many
bundles** (a folder with one folder inside per bundle), enter the folder and
click **Scan folder**. Results go in a `---Created---` folder next to it.
bundles** (a folder with one folder inside per bundle), then click
**Browse…**: open folders until you're in the right one, and **Use this
folder** scans it. Or type or paste its path and click **Scan folder**.
Results go in a `---Created---` folder next to it.
- One bundle: **Folder check** says how many images it found and how many
full sheets of 12 they make. If the folder holds only other folders, pick
one under **Choose folders**.
- Many bundles: every bundle inside is listed, picked and checked in one go.
Untick any you want to skip. A bundle that fails its check can be unticked,
or fixed and checked again with **Check selected bundles**.
3. **Set up the page.** Size, units, DPI and format apply to sheets and covers
alike. **Clean up white backgrounds** can make near-white backgrounds pure
white or transparent.
alike, and DPI to upscaled images too. **Clean up white backgrounds** can
make near-white backgrounds pure white or transparent.
4. **Make your images.**
- **Preview sheets:** every image, 12 to a page (`POST /api/jobs/generate`,
or `POST /api/jobs/generate-all-folders` for many bundles), optionally with a
Expand All @@ -388,6 +492,10 @@ Makes one cover per bundle folder, as `/generate-all-folders` does for sheets.
(`POST /api/jobs/generate-cover-collage`, or
`POST /api/jobs/generate-cover-collage-batch`). **Only use certain images**
limits it to the files you name.
- **Upscaled images:** every image 2x, 3x or 4x bigger, as a PNG and a JPG
in an `Upscaled` folder (`POST /api/jobs/upscale-images`, or
`POST /api/jobs/upscale-images-batch`). It runs on its own, with no
sheets or cover needed.
5. **Your files** lists what was made and where it was saved; **Copy** puts a
path on the clipboard.

Expand All @@ -400,6 +508,9 @@ Makes one cover per bundle folder, as `/generate-all-folders` does for sheets.
- Trailing images that do not fill a complete page are left out by default; the
response reports how many. Set `include_partial_page: true` to render that final
page with its unused cells left white.
- Upscaling resamples each image: edges stay smooth, but no detail is added,
so at 4x clip art looks soft. AI upscalers can invent detail; Pasteup has
none built in.

---

Expand Down Expand Up @@ -470,7 +581,7 @@ Symptoms:
Fixes:
- Confirm files are directly in the selected folder (non-recursive scan).
- Confirm extensions are supported.
- Check that files are not hidden/system placeholders.
- Check the files aren't hidden: names starting with a dot are skipped.

### Permission errors
Symptoms:
Expand All @@ -482,6 +593,12 @@ Fixes:
- Verify write permission on output folder.
- Try a user-owned directory (for example inside your home directory).

### "Pasteup isn't allowed to open" Desktop, Documents or Downloads on a Mac
macOS asks before a program reads these folders, and Pasteup reads them as the
terminal app it runs in (Terminal, for the `pasteup --shortcut` launcher). If
that was refused, turn the folder on for your terminal app under **System
Settings › Privacy & Security › Files and Folders**, then restart Pasteup.

---

## How images are loaded
Expand Down
96 changes: 96 additions & 0 deletions src/pasteup/models/schemas.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@

from mullion import DEFAULT_TOLERANCE, BackgroundCleanMode
from pasteup.services.cover_collage import CoverCollageFittingMode, CoverCollageTemplate
from pasteup.services.upscaler import UPSCALE_FACTORS
from mullion import DEFAULT_DPI

from pydantic import AliasChoices, BaseModel, Field, field_validator
Expand Down Expand Up @@ -117,6 +118,25 @@ class ScanResponse(BaseModel):
message: str


class BrowseFolderRequest(BaseModel):
folder_path: str = Field(default="", description="The folder to list. Blank lists the home folder.")


class FolderLink(BaseModel):
name: str
path: str


class BrowseFolderResponse(BaseModel):
path: str = Field(description="The folder listed: the one asked for, or the nearest that could be listed.")
parent_path: str | None = Field(description="The folder above it; null at the top of a drive.")
breadcrumbs: list[FolderLink] = Field(description="Each folder from the top of the drive down to this one.")
folders: list[FolderLink] = Field(description="The folders inside, without hidden ones, __MACOSX or ---Created---.")
image_count: int = Field(description="Supported images directly inside, as the scan counts them.")
places: list[FolderLink] = Field(description="Shortcuts: home, its standard folders, and drives on Windows.")
message: str = Field(description="Why another folder was listed than the one asked for; empty otherwise.")


class SelectedBatchFolderValidationRequest(BaseModel):
parent_folder_path: str
selected_subfolders: list[str] = Field(
Expand Down Expand Up @@ -318,6 +338,82 @@ class BatchCoverCollageGenerationResponse(BaseModel):
message: str


class UpscaleOptions(BaseModel):
"""How much bigger, and the resolution to stamp; shared by both upscale requests."""

scale: int = Field(default=2, description="How many times bigger each side becomes: 2, 3 or 4.")
dpi: int = Field(default=DEFAULT_DPI, gt=0, le=1200, description="Resolution stamped into the files.")

@field_validator("scale")
@classmethod
def validate_scale(cls, value: int) -> int:
if value not in UPSCALE_FACTORS:
raise ValueError(f"scale must be one of {', '.join(map(str, UPSCALE_FACTORS))}.")
return value


class UpscaleRequest(UpscaleOptions):
folder_path: str
output_path: str = Field(description="The bundle's output folder; an Upscaled folder is made inside it.")


class UpscaleResponse(BaseModel):
success: bool
scale: int
total_images: int = Field(description="Images upscaled, each saved as PNG and as JPG.")
output_path: str = Field(description="The Upscaled folder, with a PNG and a JPG folder inside.")
png_folder: str
jpg_folder: str
output_files: list[str]
images_skipped: int = Field(default=0, description="Files that could not be read as images.")
too_large_files: list[str] = Field(
default_factory=list, description="Images left out because upscaled they would pass 100 megapixels."
)
same_name_files: list[str] = Field(
default_factory=list,
description="Files left out because an image of the same name in another format gave both formats.",
)
message: str


class BatchUpscaleRequest(UpscaleOptions):
parent_folder_path: str
created_output_root_path: str = Field(
validation_alias=AliasChoices("created_output_root_path", "output_root_path"),
)
selected_subfolders: list[str] = Field(
validation_alias=AliasChoices("selected_subfolders", "selected_subfolder_paths"),
)

@field_validator("selected_subfolders", mode="before")
@classmethod
def normalize_selected_subfolders(cls, value: object) -> list[str] | None:
return _normalize_optional_string_list(value, field_name="selected_subfolders")


class BatchUpscaleResult(BaseModel):
folder_name: str
success: bool
total_images: int
output_path: str
images_skipped: int = 0
too_large_files: list[str] = Field(default_factory=list)
same_name_files: list[str] = Field(default_factory=list)
message: str


class BatchUpscaleResponse(BaseModel):
success: bool
scale: int
processed_folders: int
generated_folders: int
total_detected_folders: int
selected_folders: int
bundle_results: list[BatchUpscaleResult]
created_output_root_path: str
message: str


class BatchGenerationRequest(OutputQualityOptions):
parent_folder_path: str
created_output_root_path: str
Expand Down
Loading
Loading