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
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,6 @@ tmp/
# Copyrighted sample maps used for local testing only — never commit.
TestData/
coverage/
ios/build/
ios/Local.xcconfig
ios/Version.xcconfig
18 changes: 15 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.PHONY: build test lint coverage app run install dmg appstore icon clean
.PHONY: build test lint coverage app run install dmg appstore icon ipad-install ipad-simulator ipad-uitests clean

build:
swift build
Expand Down Expand Up @@ -31,9 +31,21 @@ appstore:
swift package resolve
CHANNEL=appstore scripts/build-app.sh

# Redraws Resources/AppIcon.icns from scripts/make-icon.swift.
# Builds the iPad app and installs it on a connected iPad. IPAD names the iPad.
ipad-install:
scripts/install-ipad.sh

# Builds the iPad app and starts it in a simulator. IPAD_SIMULATOR names the simulator.
ipad-simulator:
scripts/run-ipad-simulator.sh

# Runs the iPad UI tests, which screenshot the window in both orientations.
ipad-uitests:
scripts/run-ipad-uitests.sh

# Redraws Resources/AppIcon.icns and the iPad's icon from scripts/make-icon.swift.
icon:
scripts/make-icon.sh

clean:
rm -rf .build build coverage
rm -rf .build build coverage ios/build
11 changes: 7 additions & 4 deletions Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,26 @@ import PackageDescription

let package = Package(
name: "Mapsmith",
platforms: [.macOS(.v15)],
platforms: [.macOS(.v15), .iOS(.v18)],
products: [
.executable(name: "Mapsmith", targets: ["Mapsmith"]),
.library(name: "MapsmithCore", targets: ["MapsmithCore"])
.library(name: "MapsmithCore", targets: ["MapsmithCore"]),
// The app shared by the Mac executable and the iPad project in ios/.
.library(name: "MapsmithUI", targets: ["MapsmithUI"])
],
dependencies: [
.package(url: "https://github.com/scooper4711/tabletop-kit.git", from: "1.0.0")
],
targets: [
.target(name: "MapsmithCore", dependencies: [.product(name: "TablesideShared", package: "tabletop-kit")]),
.executableTarget(
name: "Mapsmith",
.target(
name: "MapsmithUI",
dependencies: [
"MapsmithCore", .product(name: "AppNotices", package: "tabletop-kit"),
.product(name: "TablesideShared", package: "tabletop-kit")
]
),
.executableTarget(name: "Mapsmith", dependencies: ["MapsmithUI"]),
.testTarget(
name: "MapsmithCoreTests",
dependencies: ["MapsmithCore", .product(name: "TablesideShared", package: "tabletop-kit")]
Expand Down
32 changes: 26 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=scooper4711_mapsmith&metric=coverage)](https://sonarcloud.io/summary/new_code?id=scooper4711_mapsmith)
[![GitHub Release](https://img.shields.io/github/v/release/scooper4711/mapsmith)](https://github.com/scooper4711/mapsmith/releases)
[![GitHub Downloads](https://img.shields.io/github/downloads/scooper4711/mapsmith/total)](https://github.com/scooper4711/mapsmith/releases)
[![Platform](https://img.shields.io/badge/platform-macOS%2015%2B-informational)](#requirements)
[![Platform](https://img.shields.io/badge/platform-macOS%2015%2B%20%7C%20iPadOS%2018%2B-informational)](#requirements)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

Have you tried printing a Flip-Mat PDF or an adventure's map at home? The map is far bigger than a sheet of
paper, and printing it "to fit" shrinks the squares until your miniatures no longer fit them.

Mapsmith is a Mac app that prints battle maps at true scale, one grid square per inch, on ordinary printer
Mapsmith is a Mac and iPad app that prints battle maps at true scale, one grid square per inch, on ordinary printer
paper. It finds the map's grid, splits the map into pages that fit your printer's printable area at exactly
one inch per square, and prints them, ready to trim and tape together.

Expand Down Expand Up @@ -59,9 +59,21 @@ Grid detection sums edge strength along every row and column of the map and find
autocorrelation. If no grid is found, the app falls back to the PDF's own page scale or the image's DPI
metadata, and you can always type the pixels per grid square yourself in the inspector.

### On the iPad

The iPad app (it runs on the iPhone too) prints the same true-scale pages. The differences:

- **Open** a PDF or image from the file browser, from Files or another app's share sheet (*Open in Mapsmith*), or
by dropping it on the window. One map is shown at a time.
- **Open from Scrollkeeper** lists the maps in the library Scrollkeeper on the iPad shares, and opens those it has
downloaded. Scrollkeeper on the iPad takes no requests, so download a map there first.
- The iPad has no Page Setup: choose the **paper** and the printer's **margin** (¼ in suits most printers) in the
inspector. Every page prints at 100%, whatever the printer's printable area.
- **Ink Prices** (the drop in the toolbar) holds the cartridge prices for the printer chosen in the inspector.

## Requirements

macOS 15 or later.
macOS 15 or later, or iPadOS (or iOS) 18 or later.

## Installing a release

Expand Down Expand Up @@ -109,9 +121,15 @@ make test # runs the unit tests
make lint # runs SwiftLint
make coverage # runs the tests and enforces the coverage threshold
make dmg # packages the app into a disk image
make icon # redraws Resources/AppIcon.icns
make icon # redraws Resources/AppIcon.icns and the iPad's icon
make ipad-simulator # builds the iPad app and starts it in a simulator
make ipad-install # builds the iPad app and installs it on a connected iPad
make ipad-uitests # runs the iPad UI tests, which screenshot both orientations
```

The iPad app is `ios/Mapsmith.xcodeproj` (scheme `Mapsmith-iPad`). To build it with your own Apple developer team,
put `DEVELOPMENT_TEAM = <team>` in `ios/Local.xcconfig` (see `ios/Signing.xcconfig`).

Building needs Xcode 16 or later (Swift 6 toolchain). `scripts/sign-app.sh` signs the app with the Developer ID when
the keychain holds a Developer ID Application certificate, and ad hoc otherwise. Open `Package.swift` in Xcode to
run and debug it.
Expand All @@ -120,13 +138,15 @@ Tests that read real maps use PDFs in `TestData/`, which is not committed becaus
Copy or link your own Flip-Mat PDFs there to run them; they are skipped when the folder is empty.

The code is in two parts: `Sources/MapsmithCore` holds all the logic and is unit tested (grid detection,
finding maps in PDFs, planning and exporting pages), and `Sources/Mapsmith` is the SwiftUI app.
finding maps in PDFs, planning and exporting pages), and `Sources/MapsmithUI` is the SwiftUI app, shared by the Mac
(`Sources/Mapsmith`) and the iPad (`ios/`).

## Where things are stored

| What | Where |
|---|---|
| Images dropped from other apps | `~/Library/Caches/io.github.scooper4711.Mapsmith/Dropped Maps/` |
| Images dropped from other apps | `~/Library/Caches/io.github.scooper4711.Mapsmith/Dropped Maps/`; on the iPad, the app's caches |
| Ink prices; on the iPad also the paper, margin and printer | the app's preferences |
| Exported pages | wherever you save them, as PDF files |
| Maps opened from Scrollkeeper | Scrollkeeper's downloads folder; Mapsmith only reads Scrollkeeper's map list |

Expand Down
17 changes: 0 additions & 17 deletions Resources/PrivacyInfo.xcprivacy

This file was deleted.

4 changes: 4 additions & 0 deletions Sources/Mapsmith/main.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
import MapsmithUI

// The Mac entry point. The app itself lives in the MapsmithUI target, shared with the iPad.
MapsmithApp.main()
10 changes: 10 additions & 0 deletions Sources/MapsmithCore/DroppedImageStore.swift
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,16 @@ public struct DroppedImageStore: Sendable {
return url
}

/// Copies a dropped file (on the iPad a PDF arrives as a file only readable during the drop) under a name not
/// already in use and returns where it went.
public func saveCopy(of file: URL, suggestedName: String?, type: UTType) throws -> URL {
try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
let url = unusedURL(baseName: Self.baseName(from: suggestedName ?? file.lastPathComponent),
fileExtension: type.preferredFilenameExtension ?? file.pathExtension)
try FileManager.default.copyItem(at: file, to: url)
return url
}

private static func baseName(from suggestedName: String?) -> String {
let stem = suggestedName.map { ($0 as NSString).deletingPathExtension } ?? ""
let safe = stem.replacingOccurrences(of: "/", with: "-").replacingOccurrences(of: ":", with: "-")
Expand Down
50 changes: 50 additions & 0 deletions Sources/MapsmithCore/PaperChoice.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
import CoreGraphics

/// A paper size the user picks where there is no Page Setup (the iPad), with the printer's unprintable border.
public enum PaperChoice: String, CaseIterable, Identifiable, Sendable {
case letter, legal, a4, a3, tabloid

/// What fits most AirPrint printers: their unprintable border is 1/4 in or less.
public static let defaultMarginInches: CGFloat = 0.25
/// The margin is kept between nothing and a quarter of the narrowest paper's width.
public static let marginRange: ClosedRange<CGFloat> = 0...2

public var id: String { rawValue }

public var title: String {
switch self {
case .letter: "US Letter"
case .legal: "US Legal"
case .a4: "A4"
case .a3: "A3"
case .tabloid: "Tabloid"
}
}

/// The paper's size in points, portrait.
public var size: CGSize {
switch self {
case .letter: CGSize(width: 612, height: 792)
case .legal: CGSize(width: 612, height: 1008)
case .a4: CGSize(width: 595.28, height: 841.89)
case .a3: CGSize(width: 841.89, height: 1190.55)
case .tabloid: CGSize(width: 792, height: 1224)
}
}

/// The printable page: the paper with `marginInches` left blank on every side, the margin clamped to
/// `marginRange`.
public func geometry(marginInches: CGFloat) -> PageGeometry {
let clamped = min(max(marginInches, Self.marginRange.lowerBound), Self.marginRange.upperBound)
let margin = clamped * pointsPerInch
let paper = CGRect(origin: .zero, size: size)
return PageGeometry(paperSize: size, imageableRect: paper.insetBy(dx: margin, dy: margin))
}

/// The paper the user's region most likely uses: US Letter in the US and Canada and the other Letter
/// countries, A4 elsewhere.
public static func regionalDefault(regionCode: String?) -> PaperChoice {
let letterRegions: Set = ["US", "CA", "MX", "PH", "CL", "CO", "VE", "GT", "CR", "PA", "DO", "SV", "NI", "PR"]
return regionCode.map(letterRegions.contains) == true ? .letter : .a4
}
}
30 changes: 24 additions & 6 deletions Sources/MapsmithCore/Scrollkeeper/ScrollkeeperBridge.swift
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,13 @@ import Foundation
import Observation
import TablesideShared

/// What Mapsmith needs from the system to work with another app. The app uses `NSWorkspace`;
/// tests use a fake.
/// What Mapsmith needs from the system to work with another app. The Mac app uses `NSWorkspace`, the iPad app
/// `UIApplication`; tests use a fake.
@MainActor
public protocol ApplicationLauncher {
/// Whether Scrollkeeper here answers requests from other apps. Only the Mac's does; on the iPad Mapsmith reads
/// the shared library and nothing else.
var takesRequests: Bool { get }
func isInstalled(_ bundleIdentifier: String) -> Bool
/// Opens the URL without bringing its app to the front.
func openInBackground(_ url: URL)
Expand Down Expand Up @@ -38,6 +41,8 @@ public final class ScrollkeeperBridge {
public enum State: Equatable, Sendable {
case idle
case notInstalled
/// Scrollkeeper takes no requests and hasn't shared its library (yet).
case noSharedLibrary
/// Asked for the list; Scrollkeeper may still be starting or loading its library.
case waiting
case unsupportedVersion
Expand Down Expand Up @@ -75,16 +80,24 @@ public final class ScrollkeeperBridge {
return
}
if readLibrary() { return }
guard launcher.takesRequests else {
state = .noSharedLibrary
return
}
state = .waiting
launcher.openInBackground(Self.requestURL(host: "index", sku: nil))
}

/// Reads the library list again after Scrollkeeper says it changed, while the list shown came from it.
/// Reads the library list again after Scrollkeeper says it changed, or Mapsmith comes back to the
/// foreground, while the list shown came from it or there was none to show.
public func refreshLibrary() {
guard isShowingLibrary else { return }
guard isShowingLibrary || state == .noSharedLibrary else { return }
_ = readLibrary()
}

/// Whether Scrollkeeper can be asked to download a title; when not, the user downloads it in Scrollkeeper.
public var takesRequests: Bool { launcher.takesRequests }

/// Reads the list Scrollkeeper handed over.
public func receive(_ file: URL) {
isShowingLibrary = false
Expand All @@ -105,7 +118,7 @@ public final class ScrollkeeperBridge {
}

/// Opens the title's files when they are in the shared folder; otherwise asks Scrollkeeper to download the
/// title when needed and open it in Mapsmith.
/// title when needed and open it in Mapsmith, or where Scrollkeeper takes no requests, brings it forward.
public func open(_ entry: ScrollkeeperIndex.Entry) {
guard entry.localFiles.isEmpty else {
openDocuments(entry.localFiles)
Expand All @@ -114,7 +127,8 @@ public final class ScrollkeeperBridge {
send(entry, opens: true)
}

/// Asks Scrollkeeper to download the title without opening it.
/// Asks Scrollkeeper to download the title without opening it, or where it takes no requests, brings it
/// forward to download it there.
public func download(_ entry: ScrollkeeperIndex.Entry) {
send(entry, opens: false)
}
Expand Down Expand Up @@ -158,6 +172,10 @@ public final class ScrollkeeperBridge {
}

private func send(_ entry: ScrollkeeperIndex.Entry, opens: Bool) {
guard launcher.takesRequests else {
launchScrollkeeper()
return
}
requests[entry.sku] = ScrollkeeperRequest(sku: entry.sku, opens: opens, phase: .requested)
launcher.openInBackground(Self.requestURL(host: opens ? "open" : "download", sku: entry.sku))
}
Expand Down
7 changes: 7 additions & 0 deletions Sources/MapsmithUI/AppLinks.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
import Foundation

enum AppLinks {
// A literal URL that is known to parse.
// swiftlint:disable:next force_unwrapping
static let privacyPolicy = URL(string: "https://github.com/scooper4711/mapsmith/blob/main/PRIVACY.md")!
}
Loading
Loading