From 291f42e56eaaf418b67d1ebe3cb40b32780d4325 Mon Sep 17 00:00:00 2001
From: WovenCoast <wovencoast14782@techie.com>
Date: Mon, 8 Dec 2025 23:28:48 +0500
Subject: [PATCH] add readme file

---
 README.md | 207 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 207 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..69c9750
--- /dev/null
+++ b/README.md
@@ -0,0 +1,207 @@
+# Scale Map Maker
+
+A web-based interactive mapping tool for creating and managing network diagrams with lines, nodes, and switches on a real map.
+
+## Getting Started
+
+Simply open `index.html` in your web browser. The application runs entirely in the browser and saves your work to localStorage automatically.
+
+## Map Navigation
+
+### Basic Movement
+- **Left Click + Drag**: Pan the map (default)
+- **Middle Mouse Button + Drag**: Pan the map
+- **Right Click + Drag** (in Select mode): Pan the map
+- **Mouse Wheel**: Zoom in/out
+- **Escape Key**: Refresh the page
+
+### Map View
+- Toggle between **Street View** and **Satellite View** using the "Satellite View" button in the toolbar
+- Your current map position and zoom level are automatically saved
+
+## Tools
+
+### Select Tool
+**Default tool** - Use this to view and interact with objects.
+
+- **Left Click on Node/Switch**: Opens a popup showing information
+- **Right Click**: Pan the map
+- Objects can be selected to view their properties
+
+### Move Tool
+Move objects around the map.
+
+- **Left Click on Node/Switch**: Start dragging to move it
+- **Right Click on Node/Switch**: Alternative way to move it
+- All connected lines update automatically when you move nodes or switches
+- Release mouse to finish moving
+
+### Delete Tool
+Remove objects from the map.
+
+- **Left Click on Node**: Delete the node (and all connected lines)
+- **Left Click on Switch**: Delete the switch (and all connected lines)
+- **Left Click on Line Endpoint**: Delete that point (or entire line if only 2 points)
+- All deletions require confirmation
+
+### Draw Line Tool
+Create lines between points on the map.
+
+- **Left Click**: Add a point to the current line
+- **Right Click**: Finish drawing the line
+- **Click on Node/Switch**: Line snaps to and connects with that object
+- **Click on Line Endpoint**: Continue drawing from that line
+- Lines automatically finish when clicking on nodes/switches
+- Lines that end near nodes/switches (within 20 pixels) automatically snap to them
+
+**Line Features:**
+- Distance is calculated and displayed for each segment
+- Total line distance shown at the midpoint
+- Lines can have multiple points/segments
+- Line endpoints can be moved in Move mode
+- Right-click on endpoint to delete that point or the entire line
+
+### Add Node Tool
+Add colored nodes to the map.
+
+- **Left Click**: Place a node at that location
+- Nodes are connection points for lines
+- Select node color from the color palette before placing
+- Node count is tracked by color in the sidebar
+
+**Node Colors Available:**
+- Red, Green, Blue, Yellow, Magenta, Cyan, Orange, Purple
+
+### Add Switch Tool
+Add network switches to the map.
+
+- **Left Click**: Place a switch at that location
+- Default: 8 ports per switch
+- Switches can connect to lines (limited by port count)
+- Port count can be edited after creation
+
+**Switch Features:**
+- Click on switch to view popup with port information
+- Edit port count using the input field (cannot reduce below used ports)
+- Switches show used/total ports (e.g., "2/8")
+- Lines automatically attach to available ports
+
+### Ruler Tool
+Measure distances on the map.
+
+- **Left Click**: Add measurement points
+- **Right Click**: Finish and reset measurement
+- Distance shown in meters and kilometers in the top-right corner
+- Useful for planning line routes
+
+### Sum Tool
+Calculate total distance of selected line segments.
+
+- Click on individual line segments to select/deselect them
+- Selected segments are highlighted
+- Total distance shown in top-right corner
+- Shows segment count and total distance in meters and kilometers
+- Switching to another tool clears the selection
+
+## Map Statistics
+
+The **Total Stats** display (top-right corner) always shows:
+- Number of lines
+- Number of switches
+- Total length of all lines (meters and kilometers)
+
+Updates automatically as you add/remove objects.
+
+## Node Count
+
+The **Node Count** section in the sidebar shows:
+- Count of nodes by color
+- Color indicator for each type
+- Updates automatically
+
+## Data Management
+
+### Auto-Save
+- All changes are automatically saved to browser localStorage
+- Data persists between sessions
+- Saves on: object creation/deletion, movement, map pan/zoom
+
+### Export
+1. Click the **Export** button
+2. Your data is encoded to a base64 string
+3. String is copied to clipboard automatically
+4. A prompt also shows the string for manual copying
+5. Save this string to transfer your map to another browser/computer
+
+### Import
+1. Click the **Import** button
+2. Paste the export code when prompted
+3. Page reloads with the imported data
+4. All existing data is replaced
+
+### Clear All
+- Click **Clear All** to delete everything
+- Requires confirmation
+- Cannot be undone (unless you have an export)
+
+## Tips and Tricks
+
+1. **Quick Refresh**: Press Escape to quickly reload the page
+2. **Precise Connections**: Lines automatically snap to nearby nodes/switches when finishing
+3. **Line Continuation**: Click on line endpoints to extend existing lines
+4. **Port Management**: Switches prevent connections beyond port capacity
+5. **Multi-Point Lines**: Create complex routes by clicking multiple points before finishing
+6. **Batch Selection**: Use Sum tool to analyze multiple line segments at once
+7. **Color Coding**: Use different node colors to categorize different types of connections
+8. **Map Views**: Switch to satellite view for better geographic context
+
+## Keyboard Shortcuts
+
+- **Escape**: Refresh the page
+
+## Popup Interactions
+
+When a popup is open (node/switch info):
+- Click inside popup to interact without triggering map actions
+- Close popup by clicking the X or clicking elsewhere on the map
+- Popups prevent accidental map clicks
+
+## Technical Details
+
+- Built with Leaflet.js for mapping
+- Uses OpenStreetMap for street view
+- Uses Google Maps for satellite view
+- Max zoom level: 25
+- Data stored in browser localStorage
+- No server required - runs entirely client-side
+
+## Browser Compatibility
+
+Works best in modern browsers:
+- Chrome/Edge (recommended)
+- Firefox
+- Safari
+
+Requires:
+- JavaScript enabled
+- localStorage support
+- Modern CSS support
+
+## Troubleshooting
+
+**Map not loading?**
+- Check internet connection (map tiles load from remote servers)
+- Try refreshing the page
+
+**Data not saving?**
+- Ensure localStorage is enabled in browser settings
+- Check if browser is in private/incognito mode (localStorage may not persist)
+
+**Import not working?**
+- Ensure you copied the complete export string
+- Check for extra spaces or characters
+- Export string should be a long base64 encoded string
+
+**Objects disappearing?**
+- Press Escape to refresh and reload from localStorage
+- Try exporting data before making changes as a backup