183 lines
10 KiB
HTML
183 lines
10 KiB
HTML
<!--
|
|
~ Copyright (c) 2025-2026 Taras Greben
|
|
~ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Commercial-pcb-retrace
|
|
~ See LICENSE file for details.
|
|
-->
|
|
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments)}gtag("consent","default",{ad_storage:"granted",ad_user_data:"granted",ad_personalization:"granted",analytics_storage:"granted"});gtag("consent","default",{ad_storage:"denied",ad_user_data:"denied",ad_personalization:"denied",analytics_storage:"denied",region:"AT,BE,BG,HR,CY,CZ,DK,EE,FI,FR,DE,GR,HU,IE,IT,LV,LT,LU,MT,NL,PL,PT,RO,SK,SI,ES,SE,IS,LI,NO,GB,CH,UA".split(",")});</script>
|
|
<!-- Google tag (gtag.js) -->
|
|
<script async src="https://www.googletagmanager.com/gtag/js?id=G-X1MKL6C4B0"></script>
|
|
<script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments)}gtag("js",new Date());gtag("config","G-X1MKL6C4B0");</script>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<link rel="icon" href="favicon.ico">
|
|
<title>User Guide - PCB ReTrace</title>
|
|
<link rel="stylesheet" href="common.css">
|
|
<style>
|
|
/* Override common.css app locks for document flow */
|
|
html, body {
|
|
height: auto !important;
|
|
overflow-y: auto !important;
|
|
display: block !important;
|
|
margin: 0; padding: 0;
|
|
}
|
|
|
|
body { background: #f8fafc; color: #334155; line-height: 1.6; }
|
|
|
|
.container {
|
|
max-width: 800px;
|
|
margin: 0 auto;
|
|
padding: 2rem 1rem;
|
|
background: white;
|
|
min-height: 100vh;
|
|
box-shadow: 0 0 20px rgba(0,0,0,0.05);
|
|
box-sizing: border-box;
|
|
}
|
|
|
|
h1 { color: #0f172a; margin-bottom: 0.5rem; border-bottom: 1px solid #e2e8f0; padding-bottom: 1rem; }
|
|
h2 { color: #1e293b; margin-top: 2.5rem; margin-bottom: 1rem; font-size: 1.5rem; }
|
|
h3 { color: #2563eb; margin-top: 1.5rem; font-size: 1.1rem; }
|
|
|
|
.badge { display: inline-block; padding: 0.2rem 0.6rem; border-radius: 4px; font-size: 0.75rem; font-weight: bold; background: #e2e8f0; color: #475569; }
|
|
.badge.pro { background: #dcfce7; color: #166534; }
|
|
|
|
ul, ol { padding-left: 1.5rem; margin-bottom: 1rem; }
|
|
li { margin-bottom: 0.5rem; }
|
|
|
|
.tip-box { background: #eff6ff; border-left: 4px solid #2563eb; padding: 1rem; margin: 1.5rem 0; border-radius: 0 4px 4px 0; font-size: 0.95rem; }
|
|
.warn-box { background: #fff1f2; border-left: 4px solid #f43f5e; padding: 1rem; margin: 1.5rem 0; border-radius: 0 4px 4px 0; font-size: 0.95rem; }
|
|
|
|
code { background: #f1f5f9; padding: 0.2rem 0.4rem; border-radius: 3px; font-family: monospace; font-size: 0.9em; color: #0f172a; border: 1px solid #e2e8f0; }
|
|
|
|
.nav-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 2rem; padding-bottom: 0.5rem; border-bottom: 1px solid #e2e8f0; }
|
|
.back-link { text-decoration: none; color: #64748b; font-weight: 600; display: flex; align-items: center; gap: 0.5rem; }
|
|
.back-link:hover { color: #2563eb; }
|
|
|
|
footer { margin-top: 4rem; padding-top: 2rem; border-top: 1px solid #e2e8f0; color: #94a3b8; font-size: 0.8rem; text-align: center; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<div class="container">
|
|
<nav class="nav-header">
|
|
<a href="index.html" class="back-link">← Back to Home</a>
|
|
<span style="color:#94a3b8; font-size:0.9rem;">Documentation</span>
|
|
</nav>
|
|
|
|
<h1>PCB ReTrace Guide</h1>
|
|
<p class="lead">A local-first browser tool for reverse engineering, documenting, and inspecting printed circuit boards.</p>
|
|
|
|
<div class="tip-box">
|
|
<strong>Privacy Note:</strong> This application runs 100% in your browser. All images and data are stored in your browser's local database (IndexedDB). No data is uploaded to any server.
|
|
</div>
|
|
|
|
<h2>1. Concept & Hierarchy</h2>
|
|
<p>ReTrace organizes data to match physical hardware:</p>
|
|
<ol>
|
|
<li><strong>Device:</strong> The physical unit (e.g., "Multimeter Model X").</li>
|
|
<li><strong>Board:</strong> A specific PCB inside the device (e.g., "Mainboard", "Power Supply").</li>
|
|
<li><strong>Images:</strong> Photos of the board (Top, Bottom, Angled shots).</li>
|
|
</ol>
|
|
|
|
<h2>2. The Workflow</h2>
|
|
|
|
<h3>Step 1: Setup</h3>
|
|
<p>Create a <strong>New Device</strong> and a <strong>New Board</strong> using the top menu. Then, upload your images. High-resolution, flat photos work best.</p>
|
|
|
|
<h3>Step 2: Mapping Components (BOM)</h3>
|
|
<p>Navigate to the <strong>Images</strong> tab. Click on a component in the photo to mark it.</p>
|
|
<ul>
|
|
<li>The app switches to the <strong>BOM</strong> list.</li>
|
|
<li>Enter the Reference (e.g., <code>R1</code>).</li>
|
|
<li>If identifying the value requires calculation, click the tool icon to open the built-in decoders (Resistor Bands, Inductors).</li>
|
|
</ul>
|
|
|
|
|
|
<h3>Step 3: Tracing Nets</h3>
|
|
<p>Use the <strong>Inspect</strong> and <strong>Nets</strong> tabs to document connectivity.</p>
|
|
<ul>
|
|
<li><strong>Smart Naming:</strong> Click near a component to add a node. If the component is defined in the BOM, the tool <strong>auto-suggests the label</strong> (e.g., <code>R1.1</code>) using geometry (Angle & Distance). It automatically accounts for board rotation and flips pin logic for Bottom-side images.</li>
|
|
<li><strong>Pinout Help:</strong> Click the <button style="padding:0 5px; font-size:0.75rem; border-radius:50%; line-height:1;">?</button> button in the naming dialog to view standard conventions (e.g., "Stripe = Pin 1" for Tantalum).</li>
|
|
<li><strong>New Net:</strong> If no net is currently active, entering a name for a node will <strong>automatically start a new net</strong>.</li>
|
|
<li><strong>Export:</strong> In the Nets tab, you can export a <code>.net</code> (KiCad) and <code>.cir</code> (SPICE) file to help verify your reverse engineering in a professional EDA tool.</li>
|
|
</ul>
|
|
|
|
<h3>Step 4: Schematic Generation (Schema ReTrace)</h3>
|
|
<p>Switch to the <strong>Schema</strong> tab to automatically generate a schematic diagram from your traced nets.</p>
|
|
<ul>
|
|
<li><strong>Auto Layout:</strong> ReTrace uses a built-in routing engine to organize components and draw wires intelligently.</li>
|
|
<li><strong>Interactive Editing:</strong> Drag components to rearrange them. Right-click (or long-press on mobile) to rotate or replace the symbol.</li>
|
|
<li><strong>KiCad Libraries:</strong> Click "Libraries" to import actual <code>.kicad_sym</code> libraries (or ZIP files) and assign standard symbols to your components.</li>
|
|
<li><strong>Standalone Mode:</strong> You can use this tool independently by visiting <code>schema.html</code> to visualize any standard KiCad <code>.net</code> or SPICE <code>.cir</code> netlist.</li>
|
|
</ul>
|
|
|
|
<h2>3. Computer Vision & Stitching</h2>
|
|
<p>ReTrace uses Computer Vision (CV) for <strong>Spatial Alignment</strong>. It allows you to synchronize the view across different images.</p>
|
|
|
|
<div class="warn-box">
|
|
<strong>Important:</strong> The CV engine does <em>not</em> automatically recognize components (it won't read "10k" off a resistor). Its purpose is to mathematically align coordinates between images so you can see through the board.
|
|
</div>
|
|
|
|
<h3>Auto-Stitch (Same Side)</h3>
|
|
<p>When you upload a new image, ReTrace <strong>automatically attempts to stitch</strong> it against existing images on the board in the background. If features match (e.g., a close-up vs. a wide shot), connections are created automatically.</p>
|
|
<p>You can also run this manually:</p>
|
|
<ol>
|
|
<li>Open <strong>Image Settings</strong> on your Main image.</li>
|
|
<li>Select <strong>Stitch / Connections</strong> -> <strong>Run Auto-CV</strong>.</li>
|
|
</ol>
|
|
|
|
<h3>Manual Stitch (Top vs. Bottom)</h3>
|
|
<p>To create an "X-Ray" view where clicking a pin on the Top automatically shows the corresponding pin on the Bottom:</p>
|
|
<ol>
|
|
<li>Select your <strong>Top Image</strong>.</li>
|
|
<li>Go to <strong>Image Settings</strong> -> <strong>Connections</strong>.</li>
|
|
<li>Find your <strong>Bottom Image</strong> and click <strong>"Edit Stitch"</strong>.</li>
|
|
<li><strong>Flip Target:</strong> Click the <button style="padding:0 4px; font-size:0.8em;">↔ Flip Target</button> button. This mirrors the bottom image horizontally.</li>
|
|
<li><strong>Match Points:</strong> Click 4 common features (Vias, Holes, Corners) visible on both images.</li>
|
|
<li>Click <strong>Save Match</strong>.</li>
|
|
</ol>
|
|
|
|
<h2>4. Tools</h2>
|
|
<p>ReTrace includes standalone calculators accessible from the BOM editor:</p>
|
|
<ul>
|
|
<li><strong>Resistor:</strong> 3-6 Band decoder with reverse lookup.</li>
|
|
<li><strong>Inductor:</strong> Standard and Military codes.</li>
|
|
<li><strong>Coil:</strong> Calculator for hand-wound air-core inductors.</li>
|
|
</ul>
|
|
|
|
<h2>5. Data Management</h2>
|
|
<ul>
|
|
<li><strong>Device Export (ZIP):</strong> Full backup including all boards and images.</li>
|
|
<li><strong>Board Export (ZIP):</strong> Portable backup of a single board.</li>
|
|
<li><strong>CSV Export:</strong> Standard spreadsheet export for BOM ordering.</li>
|
|
<li><strong>KiCad Export (.net):</strong> Exports identified components and traced nets for use in PCB design software.</li>
|
|
</ul>
|
|
|
|
<h2>6. Sharing & Deep Links</h2>
|
|
<p>You can share a device setup by hosting the exported ZIP file on a public server and creating a "Deep Link" to it.</p>
|
|
|
|
<h3>URL Format</h3>
|
|
<p>Append `?import={URL}` to the studio address:</p>
|
|
<code>https://pcb.etaras.com/studio.html?import=https://example.com/my-device.zip</code>
|
|
|
|
<h3>Server Requirements (CORS)</h3>
|
|
<div class="warn-box">
|
|
<strong>Crucial:</strong> The server hosting the ZIP file must allow <strong>Cross-Origin Resource Sharing (CORS)</strong>.
|
|
</div>
|
|
<p>The browser will block the download if the server does not send the header <code>Access-Control-Allow-Origin: *</code>.</p>
|
|
<ul>
|
|
<li><strong>GitHub Pages:</strong> Supports CORS by default. Recommended for public sharing.</li>
|
|
<li><strong>AWS S3 / Google Cloud:</strong> Requires bucket configuration to allow GET requests from any origin.</li>
|
|
</ul>
|
|
<h3>Live Demo</h3>
|
|
<p>See this feature in action at the official <strong><a href="https://dev-lab.github.io/pcb-retrace-examples/" target="_blank">PCB ReTrace Examples Gallery</a></strong>. All projects there are hosted on GitHub Pages and load via Deep Links.</p>
|
|
<footer>
|
|
Copyright © 2025—2026 Taras Greben.
|
|
</footer>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|