DOCSEARCHbyAlgolia
Submit Docs

python-altium

repository·master·Indexed 41 days ago

https://github.com/vadmium/python-altium

A Python command-line tool for parsing Altium schematic (*.SchDoc) files. It allows users to convert schematics to SVG format or view them in a graphical window using the --renderer tk flag. The tool handles OLE compound documents, parsing object records, property lists, and coordinate data from the FileHeader and Storage streams.

Tokens
2.1K
Snippets
2
Records
12
Agent score
2%

What's inside python-altium

  1. Understand the Altium Schematic File Format Structure

    master

    Altium schematic files are structured as OLE compound documents containing a FileHeader stream. The stream consists of an initial Header object followed by indexed objects starting from zero.

    Object Hierarchy and Ordering

    • Header: The first object (equivalent to |RECORD=0).
    • Sheet: The first indexed object (index 0) immediately following the header.
    • Indexed Objects: All subsequent objects are indexed starting from 0. Their type is determined by the |RECORD property.
    • Ownership: Objects have a hierarchical ownership relationship and are stored in depth-first order. For example, a Component object typically appears before its child objects (like pins or lines).

    To correctly parse the file, follow the depth-first traversal to maintain the parent-child relationships between components and their constituent parts.

  2. Understand the Altium .SchDoc file structure

    master

    Altium .SchDoc files are structured as OLE compound documents. The schematic data is not stored in a single flat file but is distributed across different streams within the OLE container:

    • FileHeader stream: This is the primary stream containing the main sequence of schematic object records.
    • Storage stream: Contains embedded files for Image objects. It uses a header with |HEADER=Icon storage.
    • Additional stream: An optional stream that may contain extra records following the sequence in the FileHeader stream.

    Each stream consists of a sequence of object records (also referred to as primitives or parts).

  3. Parse Altium object records and property lists

    master

    An object record in an Altium stream follows a specific binary format:

    1. Payload Length: 2 bytes (little-endian encoding).
    2. Type Flag: 1 byte (set to 0 for property lists).
    3. Record Type: 1 byte.

    Property Lists

    If the record type is 0, the payload is a property list. Properties are separated by the pipe character (|).

    Key characteristics of properties:

    • Naming: Most names are uppercase and run together (e.g., |LOCATIONX=200). Exceptions include |DISPLAY_UNIT and coordinate properties.
    • Case Sensitivity: Property names are likely case-insensitive.
    • Repetition: Some properties can repeat (e.g., |HOTSPOTGRIDON=T).
    • Termination: Property lists are followed by a null terminator byte.

    Storage Stream Records

    Records in the Storage stream (after the initial header) use type 1 and follow this format:

    • 0xD0 (1 byte)
    • Filename length (1 byte)
    • Filename
    • Compressed size (4 bytes, little-endian)
    • zlib-compressed data (including zlib header)

  4. Install dependencies for python-altium

    master

    To use the Altium schematic reader, ensure you have the following dependencies installed:

    • Python 3
    • olefile: Required for parsing the Altium schematic files.
    • TK: Required only if you want to display schematics in a window using the --renderer tk flag.
    • Pillow: Required only if the schematics you are processing contain bitmap images.

  5. Parse Sheet Objects (|RECORD=31)

    master

    The Sheet object (index 0) defines the global properties of the schematic.

    Key Properties:

    • |SHEETSTYLE: Predefined paper size (e.g., 0: A4, 10: Letter, 17: OrCAD E).
    • |WORKSPACEORIENTATION: 0 for Landscape, 1 for Portrait.
    • |DISPLAY_UNIT: 1 for Millimetres, 4 for Mils/Inches.
    • |AREACOLOR: Background color of the drawing area.
    • |SNAPGRIDON|VISIBLEGRIDON: Grid configuration.
    • |FONTIDCOUNT: Defines the fonts available in the sheet.
    • |TITLEBLOCKON: Boolean to enable/disable the title block.

  6. Parse Component Objects (|RECORD=1)

    master

    A Component object defines a schematic part and acts as a parent to child objects like pins and labels.

    Key Properties:

    • |LIBREFERENCE: Library reference.
    • |PARTCOUNT: Number of separated parts (e.g., a quad op-amp has 4 parts, but this value is often one higher than expected, so 5 implies 4 parts).
    • |CURRENTPARTID: The ID of the specific part instance. When iterating through child objects, ignore those where |OWNERPARTID is set to a different number (other than -1) to avoid duplicating parts of multi-part components.
    • |DISPLAYMODE: Used to determine if objects belonging to this part should be rendered.
    • |COMPONENTDESCRIPTION, |COMPONENTKIND: Optional metadata.
    • |LIBRARYPATH, |SOURCELIBRARYNAME: Library information.
    • |PINSMOVEABLE: Boolean indicating if pins can be moved.

  7. Parse Parameter Objects (|RECORD=41)

    master

    Parameters are labels used for component values or sheet-level metadata.

    Key Properties:

    • |NAME: The name of the parameter.
    • |TEXT: The value. If it starts with =, it is a reference to another parameter with a matching |NAME under the same |OWNERINDEX.
    • |OWNERINDEX: If 0 (or omitted), it is a sheet parameter. Otherwise, it refers to a component.
    • |LOCATION.X|LOCATION.X_FRAC|LOCATION.Y|LOCATION.Y_FRAC: Coordinate data.
    • |ORIENTATION: Text alignment/rotation.
    • |%UTF8%TEXT|%UTF8%NAME: Optional UTF-8 encoded versions of the text/name.

  8. Parse Pin Objects (|RECORD=2)

    master

    Pins are child objects of a Component.

    Key Properties:

    • |OWNERINDEX: The index of the parent component part.
    • |OWNERPARTID: Matches the component's |CURRENTPARTID.
    • |ELECTRICAL: Signal type:
      • 0: Input
      • 1: Bidirectional
      • 2: Output
      • 3: Open collector
      • 4: Passive
      • 5: Hi-Z
      • 6: Open emitter
      • 7: Power
    • |PINCONGLOMERATE: Bitmask for pin properties:
      • Bits 0–1 (mask 0x03): Orientation (0: Right, 1: Up, 2: Left, 3: Down).
      • Bit 3 (mask 0x08): Whether the pin name is shown.
      • Bit 4 (mask 0x10): Whether the designator is shown.
    • |DESIGNATOR: The pin number/letter.
    • |NAME: The pin function name.
    • |LOCATION.X|LOCATION.Y: The connection point on the component.

  9. Reference Altium Object Record Types

    master

    The following table maps |RECORD values to their corresponding object types in an Altium schematic file:

    RECORDObject Type
    0Header
    1Component
    2Pin
    3IEEE Symbol
    4Label
    5Bezier
    6Polyline
    7Polygon
    8Ellipse
    9Piechart
    10Round rect
    11Elliptical arc
    12Arc
    13Line
    14Rectangle
    15Sheet symbol
    16Sheet entry
    17Power port
    18Port
    22No ERC
    25Net label
    26Bus
    27Wire
    28Text frame
    29Junction
    30Image
    31Sheet
    32Sheet name
    33File name
    34Designator
    37Bus entry
    39Template
    41Parameter
    43Warning sign
    44Implementation list
    45Implementation

  11. Reference Altium property data types

    master

    When parsing properties, expect the following data formats:

    • Strings: Usually ASCII. Non-ASCII strings often use Windows CP-1252, frequently accompanied by a UTF-8 encoded version in a separate property.
    • Coordinates (Points): Represented as |LOCATION.X=200|LOCATION.Y=100. The origin (0,0) is at the bottom-left; Y values increase upwards.
    • Coordinate Lists: Formatted as |LOCATIONCOUNT=2|X1=100|Y1=100|X2=200|Y2=100.
    • Integers: Decimal integers (e.g., |RECORD=31). Used for enumerations, bitfields, and dimensions. Dimensions are typically in units of 1/100" (10 mils / 0.254 mm).
    • Real Numbers: Decimal numbers with fractional parts (e.g., |ENDANGLE=360.000). Usually three decimal places. Omitted if the value is zero.
    • Boolean: Represented by T (True) or F (False) (e.g., |ISHIDDEN=T). If a property is False, it is often omitted entirely.
    • Colours: RGB values inherited from Delphi TColor. A single integer contains Red, Green, and Blue bits:
      • Red: Bits 0–7 (mask 0x0000FF)
      • Green: Bits 8–15 (mask 0x00FF00)
      • Blue: Bits 16–23 (mask 0xFF0000)
    • Line Width: Encoded as an integer:
      • Omitted: 4 mil
      • 1: 10 mil
      • 2: 20 mil
      • 3: 40 mil