Skip to content
Document Version v2026.08.31.0
Download PDF

First Launch and Import

Goal

Help you complete a full first-use loop: start in the library, import something, open it, and return to the library again.

Supported Platforms

  • iOS
  • macOS

Intended Audience

  • New users who want to complete their first import loop
  • Testers validating import behavior from the library into the workspace

Prerequisites

  • PCBAtlas can already launch into the library
  • You have either one of the built-in samples or your own design/manufacturing project files ready

Steps

  1. Start from the library and choose Import File or Import Folder for the source.
  2. If the source is IPC-2581 XML, choose the import intent when prompted.
  3. Wait for the library progress banner to complete, then open the resulting document.
  4. Confirm that standalone PCB sources open in PCB Viewer; schematic sources and KiCad projects with a schematic open in Schematic Workbench, and revisions are updated as expected.

Result

  • The source is imported into the library as a new document or revision, and the workspace opens the corresponding PCB Viewer or Schematic Workbench.

Default Content on First Cold Launch

When the library is empty, the app automatically seeds it with three sample documents that can be opened right away:

  • h730duino (ODB++ manufacturing data)
  • BluePhil (KiCad design board)
  • WooKey Mainboard (a KiCad project containing a PCB and hierarchical schematics)

If you just want to learn the interaction flow, open one of these samples first. If you want to validate your own data, continue with the import flow below.

Current Import Paths

Import File

  • a standalone DSN, KiCad .kicad_pcb, KiCad .kicad_sch, or IPC-2581 XML
  • an ordinary KiCad .zip, or an ODB++ / Gerber / Drill manufacturing archive recognized by the app
  • a compatible .epcbdoc.zip document package

Do not import .kicad_pro as an isolated file. A project needs its sibling schematics, libraries, and settings, so use Import Folder. A standalone .kicad_sch can be imported directly only when it does not reference child sheets. A multi-sheet schematic must also be imported through its project folder; the app does not present a second file picker to obtain directory permission.

Import Folder

  • a KiCad project directory with a valid .kicad_pro, including schematic-only projects

Source Selection in Folders and Archives

Import Folder accepts KiCad projects only: PCBAtlas must find a valid .kicad_pro. If there is no project file or the project cannot be reopened, import fails directly rather than falling back to a .kicad_pcb or .kicad_sch import. If multiple projects are found, it asks you to choose explicitly rather than selecting one silently. After a successful import, every regular file in the selected directory is preserved in the same revision at its original relative path, including notes or manufacturing output outside the project closure. An unreadable file, symbolic link, or another unsupported directory entry fails the whole import rather than saving only part of it.

When you choose a project directory from Files, iCloud Drive, or a third-party file provider, the app first prepares the complete directory as a local temporary snapshot and then checks the project entry. Historical directories such as .history stay in the revision at their original paths, but a PCB or schematic inside them remains historical supporting material and does not compete with the current design beside .kicad_pro for the opening entry.

For a project that still uses KiCad 5 .sch schematics, if the .kicad_pro points to a same-name .kicad_sch that no longer exists but an exactly same-name .sch is present in the directory, PCBAtlas recognizes that .sch and its child sheets as the project schematic and permits a dual PCB-and-schematic canvas. It does not select an unrelated .sch. Legacy project directories with only .pro and no .kicad_pro remain outside the Import Folder support boundary.

When a KiCad project opens, the app first opens the schematic with the same name as the project; if none has that name, it selects an available schematic by path order. A project with both PCB and schematic prepares two canvases in one progress stage and shows dual canvases by default when preparation completes. A project with only one design source shows a single canvas and has no canvas-switch button.

Special Behavior for IPC-2581

When you select an IPC-2581 XML, the app does not assume whether it should be treated as design-side or manufacturing-side data. Instead, it shows a confirmation dialog so you can choose:

  • import as design data
  • import as manufacturing data
  1. Click Import File or Import Folder on the library home page.
  2. Use Import File for standalone files and archives; use Import Folder for a complete KiCad project directory containing .kicad_pro.
  3. After selecting a file, if it is an IPC-2581 XML, choose the import intent.
  4. Wait for the import progress banner at the top of the library to advance.
  5. When import finishes, a new document card appears, or the revision count of the target document increases.
  6. Open the document. Confirm that a project with both PCB and schematic shows dual canvases by default; a document with only one design source shows a single canvas. Also confirm complete Project / Data content.

Import file and import folder entry points

Import progress banner with stage and percentage

What Feedback You Will See

  • The top of the library shows an in-progress banner with a title, stage detail, and percentage.
  • When opening a project, portrait or compact layouts stay on the Viewer progress page. Interactive content is shown directly only after canvas preparation completes; the UI does not switch early to Project.
  • If you manually open another document during import, the task still completes, but it does not forcibly switch focus back to the newly imported document.
  • If you drop a new board file into the workspace while another document is open, the app first asks whether to replace the current content.

After Importing a KiCad Project or Schematic

After importing .kicad_pro through Import Folder or an ordinary KiCad .zip, PCBAtlas stores the related KiCad project files inside the library revision and exposes a Project page in the workspace. Import Folder also retains other regular files from the selected directory. It groups content under Source Documents / Libraries / Settings so you can confirm which board files, schematics, library files, and settings were captured. A standalone .kicad_sch enters the schematic workspace directly through Import File without requesting its parent directory.

When you open a schematic, the workspace still uses the 2D canvas, but the right Workbench switches to the schematic-specific structure:

  • Sheets: inspect hierarchy, breadcrumb, and openable child sheets.
  • Search: search Symbols / Nets / Labels / Text / Markers in Current Sheet or Whole Project.
  • Selection / Details: show the object selected from search results or canvas pick.
  • Problems: show import issue details, unsupported content, and clear issue messages when the schematic workbench is unavailable.

The schematic canvas supports picking for symbol / pin / wire / bus / label / text / junction / marker. Selection, details, and highlight stay synchronized, overlapping hits can be cycled, and a selected non-net object is framed by an orange locator. When a PCB route is available, single-canvas mode offers View on PCB; it switches to the PCB, selects the matching placement or pad when possible, otherwise highlights the connected net, and fits the view to the target. Split view keeps cross-probe linked across both canvases. Layout edits stay in dedicated EDA tools.

From the action menu on a document card, you can:

  • append a design revision
  • append a manufacturing revision

That means import is not only for creating new documents. It is also how ongoing revision history is maintained for the same project.

Current Rule for Re-importing the Same Name and Format

When a source comes back with the same document name and the same format, the current version treats it as another input round for the same document rather than automatically creating a new top-level card:

  • if the newly imported original source is byte-identical to the current revision, the app reports that nothing changed and ignores the import
  • if the original source is different, the app stores it as a new revision under that document and switches to the latest revision
  • revision labels are displayed dynamically as A1 / A2 / ... based on the document name

Recommendations

  • For a first validation pass, start with a single DSN or KiCad file.
  • For manufacturing data, confirm the archive or directory is complete before importing.
  • For iterative updates to the same project, prefer appending revisions instead of creating multiple nearly identical documents.

Common Questions

Why does the app ask again after I pick IPC-2581?

Because the same IPC-2581 XML may be treated as design-side or manufacturing-side data, and the current version asks you to choose explicitly.

Why do the design and manufacturing intents for the same IPC-2581 sometimes look almost identical after import?

That is normal in the current version. For IPC-2581, the main difference today is the library-side import intent and document classification, not an immediately obvious visual difference in the workspace.

  • If you choose the design intent, the document is managed as design-side material.
  • If you choose the manufacturing intent, the document is managed as manufacturing-side material.
  • That classification affects later management behavior, such as the default append-revision type.
  • Importing the same IPC-2581 with both intents usually creates two separate documents instead of auto-merging them.

At the same time, the current display behavior does not yet express the design-vs-manufacturing distinction very strongly once the file is open, so the visible result can still look quite similar.

Why doesn’t the import picker list every manufacturing-package suffix?

Manufacturing import accepts common archives, directories, and general data inputs. The final result depends on what the app can actually recognize from the selected source.