Skip to content

schdoc.md

Latest commit

 

History

History
132 lines (97 loc) · 5.07 KB

schdoc.md

File metadata and controls

132 lines (97 loc) · 5.07 KB
Raw

SchDoc

AltiumSchDoc is the public container for schematic documents. It is the most complete document object model in the current release.

Use it when you need to:

  1. create or modify .SchDoc files
  2. add schematic primitives, ports, notes, templates, and images
  3. insert components from .SchLib
  4. iterate and normalize existing schematic objects
  5. render schematic pages to SVG

Object Model

AltiumSchDoc owns a single ObjectCollection. Typed properties such as schdoc.notes, schdoc.ports, schdoc.net_labels, schdoc.components, schdoc.sheet_symbols, and schdoc.harness_connectors are live filtered views over that collection.

Use filtered views for query and traversal. Do not append to filtered views. Change membership through the document:

note = make_sch_note(...)
schdoc.add_object(note)

for note in schdoc.notes:
    note.font = SchFontSpec(name="Courier New", size=10)

schdoc.remove_object(note)
schdoc.save("updated.SchDoc")

The document resolves IndexInSheet, owner indexes, font indexes, and related serialization details when objects are added, removed, and saved.

Units

Public SchDoc authoring APIs use mils. Prefer SchPointMils, SchRectMils, SchFontSpec, ColorValue, and public enums instead of raw integer fields.

Low-level record fields may expose native Altium storage units. Use those fields only when preserving parsed data or when no high-level property exists yet.

Ownership

Some schematic records are invalid as top-level objects. Add them through their owner object so ownership and indexes stay valid.

Harness entries and harness type labels belong to harness connectors.

Sheet entries, sheet-name labels, and file-name labels belong to sheet symbols.

Component pins, designators, parameters, and implementation records belong to components.

Use schdoc.add_component_from_library(...) for normal component insertion from SchLib.

Templates

Use clear_template(), apply_template(...), and extract_template(...) for schematic title blocks and border graphics stored as Altium .SchDot templates.

By default, apply_template(...) applies template-owned drawing objects, embedded images, fonts, missing template parameters, and template metadata. It does not change the target sheet size or page setup unless requested.

If the .SchDot should also control the target page setup, pass apply_visual_sheet_settings=True:

schdoc.apply_template(
    "title_block.SchDot",
    template_filename="title_block.SchDot",
    apply_visual_sheet_settings=True,
)

That option copies visual sheet context such as sheet style, custom sheet dimensions, border and reference-zone settings, display unit, grid settings, sheet colors, sheet-number spacing, and the sheet system font. It does not copy template identity, vault/release GUIDs, sheet number, or project/page parameters.

Embedded Images

AltiumSchDoc preserves embedded IMAGE payloads in the schematic Storage stream. When Altium stores an image as a BMP preview plus a native payload such as TdxPNGImage, SVG rendering and extract_embedded_images(...) prefer the native payload so PNG alpha is preserved. Plain 32-bit BMP alpha is preserved when present; plain 24-bit BMP remains opaque.

Use schdoc.extract_embedded_images(output_dir) when writing embedded images as standalone files. Direct image.image_data access is a preservation API: it returns the raw Storage payload and may include Altium wrapper bytes before the native image. Code that needs image files should not hash or write image.image_data directly unless it intentionally wants the exact stored payload.

SVG Rendering

AltiumSchDoc.to_svg(...) accepts SchSvgRenderOptions. Normal review output includes a root viewBox in schematic pixel-canvas coordinates. Strict native/oracle output from SchSvgRenderOptions.native_altium() omits the root viewBox by default so comparison lanes can preserve the native export shape.

Set SchSvgRenderOptions(include_view_box=False) when a caller needs the normal renderer profile without a root viewBox.

Examples

Start with:

  1. hello_schdoc
  2. schdoc_vertical_pin_svg
  3. schdoc_add_note
  4. schdoc_note_command
  5. schdoc_move_note
  6. schdoc_add_harness_connector
  7. schdoc_mutate_harness_connector
  8. schdoc_add_sheet_symbol
  9. schdoc_mutate_sheet_symbol
  10. schdoc_insert_dblib_style
  11. schdoc_clean
  12. schdoc_svg
  13. schdoc_apply_dynamic_template

See API patterns for cross-cutting mutation and ownership guidance.