# MaPiCo — Map Placement & Coordinates Export

MaPiCo is a web application for placing objects on a map and exporting coordinates or tables.

---

## Features

- Interactive SVG canvas: pan, zoom, fit-to-view
- Precise placement on background images (click-to-place)
- Line placement with adjustable count and Shift-snapping (horizontal/vertical)
- Rectangular/grid placement via click+drag or A→B clicks; orientation toggle (x/y), rows/columns inputs
- Marquee selection, multi-select (Ctrl/Cmd), range-select (Shift) and batch edit
- Copy/paste selected elements with Ctrl+C / Ctrl+V or the selection panel buttons
- Keyboard arrow movement for selected elements (Shift = 10px steps)
- Auto Placement with multiple reference samples, optional auto-cropped bounds and Scan-Area limiting
- Persistent storage in IndexedDB (Dexie)
- Configurable addressing builder (literal/alpha/numeric) with auto-increment; apply to selection
- Per-type ObjectProps addressing templates for device IDs/addresses
- CSV import/export with per-type mappings (driven by `/elements.json`)
- Project save/load (JSON)
- Auto-Save with interval, optional File System Access handle, and download fallback
- Customizable element types via runtime `elements.json`


Quick Start
-----------

### Windows

1. Start `MaPiCo-win.exe`.
2. Load a background image (map, layout, plan)
3. Select or configure an element type
4. Choose placement mode (Place, Line, Rect, or Auto)
5. Place elements or run scan
6. Apply addressing and export if needed

### macOS

1. ## REMOVE QUARANTINE `xattr -dr com.apple.quarantine MaPiCo-macos`
2. Start app: `./MaPiCo-linux`

### Linux

1. Make executable: `chmod +x MaPiCo-linux`
2. Start app: `./MaPiCo-linux`

---

### App Config
- Edit `MaPiCo_data/app.config` to set `HOST`, `PORT` (0=random port), `BROWSER`, and `OPEN_BROWSER`.

Default `app.config`:

```ini
HOST=127.0.0.1
PORT=0
BROWSER=default
OPEN_BROWSER=true
```

### Storage & Persistence

- All app data (elements, background image metadata, settings) is persisted client-side in IndexedDB using Dexie.
- Data is stored only in IndexedDB (Dexie).
- Storage works offline and survives reloads and browser restarts.

### Auto-Save

- Enable via Tools → Auto-Save and choose an interval (minutes). While enabled, the app periodically saves your current project (elements and background image).
- Save strategy: In production the app first attempts a network save to `./autosave-project.json` (PUT, falling back to POST). If the endpoint is unavailable or you run locally, it uses the File System Access API when you selected a target file via “Choose file...”. If no persistent handle is available, a rate-limited download named `autosave-project.json` is triggered as a fallback.
- Note: Selecting a file handle requires a user gesture; the autosave timer never opens a file picker by itself.

---

### Export & Import

- **CSV Export**: Use the file menu to download CSVs of elements (name, x, y) or type-specific exports.
- **Project Backup**: Save the project as JSON via the file menu and reload it later if needed.

---

### Auto Placement

- Switch to Auto mode and draw one or more reference boxes around complete target shapes.
- Press `A` to switch directly to Auto Placement.
- Use **Scan-Area** to limit detection to a selected part of the drawing for faster and more accurate scans. Scan-Area is only a search boundary; it does not create or modify reference templates.
- **Auto-crop templates** tightens approximate user drawings to detected borders before scanning.
- **Threshold** controls match strictness, and **Max hits** caps results only; the app should append detected matches and not invent fallback placements.
- Appended detections use the same global addressing counters as manual placement.
- Copy/paste also advances the same global addressing counters for newly pasted elements.

---

### Runtime elements.json

- The app reads `/elements.json` at runtime.
- In the packaged build this maps to `MaPiCo_data/elements.json`.
- If `MaPiCo_data/elements.json` is missing, the MaPiCo server creates it with default element definitions.
- Users can edit the generated `MaPiCo_data/elements.json` file and reload the app to use the updated element types.

---

## This software includes open-source components:

- React (MIT License)
- Vite (MIT License)
- Font Awesome Free icons (CC BY 4.0 License, https://fontawesome.com)
- Icons by Font Awesome Free – https://fontawesome.com – License: CC BY 4.0


## Copyright
---------

Unauthorized redistribution or modification prohibited.  
Copyright © 2026 Bickert Web Design
