Skip to content

ip_image_polarity

ip_image_polarity

Wrapper for image polarity token.

ImagePolarityEnum

Bases: GerberCodeEnum

Image polarity.

Image Polarity (IP)

Note: The IP command is deprecated.

The IP command is responsible for setting the polarity for the entire image. It is designed to be used only once, preferably at the very beginning of the file.

7.1.3.1 Positive Image Polarity

Under the positive image polarity: - The image is generated in accordance with the specifications provided elsewhere in this document. - It's worth noting that, by default, image generation has always assumed a positive image polarity.

7.1.3.2 Negative Image Polarity

When the negative image polarity is in use: - The intent is to produce an image that portrays clear areas against a dark backdrop. - The initial state of the entire image plane is dark, as opposed to being clear. - The polarity effects between dark and clear regions are interchanged. Essentially, what was dark becomes white and vice-versa. - For negative image polarity, the very first graphics object that gets produced must possess a dark polarity. As a result, it takes on the role of clearing the dark backdrop.

Source code in src/pygerber/gerberx3/state_enums.py 
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
class ImagePolarityEnum(GerberCodeEnum):
    """Image polarity.

    ### Image Polarity (IP)

    Note: The IP command is deprecated.

    The `IP` command is responsible for setting the polarity for the entire image. It is
    designed to be used only once, preferably at the very beginning of the file.

    #### 7.1.3.1 Positive Image Polarity
    Under the positive image polarity:
    - The image is generated in accordance with the specifications provided elsewhere in
        this document.
    - It's worth noting that, by default, image generation has always assumed a positive
        image polarity.

    #### 7.1.3.2 Negative Image Polarity
    When the negative image polarity is in use:
    - The intent is to produce an image that portrays clear areas against a dark
        backdrop.
    - The initial state of the entire image plane is dark, as opposed to being clear.
    - The polarity effects between dark and clear regions are interchanged. Essentially,
        what was dark becomes white and vice-versa.
    - For negative image polarity, the very first graphics object that gets produced
        must possess a dark polarity. As a result, it takes on the role of clearing the
        dark backdrop.
    """

    POSITIVE = "POS"
    NEGATIVE = "NEG"

ExtendedCommandToken

Bases: Token

3.3 Commands.

Commands are the core syntactic element of the Gerber format. A Gerber file is a stream of commands. Commands define the graphics state, create graphical objects, defines apertures, manage attributes and so on.

Commands are built with words, the basic syntactic building block of a Gerber file. A word is a non-empty character string, excluding the reserved characters '' and '%', terminated with an ''

free_character = /[^%*]/; # All characters but * and %
word = {free_character}+ '*';

For historic reasons, there are two command syntax styles: word commands and extended commands.

command =
| extended_command
| word_command
;
word_command = word;
extended_command = '%' {word}+ '%';

Word commands are identified by a command code, the letter G, D or M followed by a positive integer, e.g. G02. Most word commands only consist of the command code, some also contain coordinates.

Extended commands are identified by a two-character command code that is followed by parameters specific to the code. An extended command is enclosed by a pair of "%" delimiters

An overview of all commands is in section 2.8, a full description in chapters 3.5 and 5.

Example 1

The example below shows a stream of Gerber commands.

G04 Different command styles*
G75*
G02*
D10*
X0Y0D02*
X2000000Y0I1000000J0D01*
D11*
X0Y2000000D03*
M02*
Example 2

The example below shows a stream of Gerber extended commands.

%FSLAX26Y26*%
%MOMM*%
%AMDonut*
1,1,$1,$2,$3*
$4=$1x0.75*
1,0,$4,$2,$3*
%
%ADD11Donut,0.30X0X0*%
%ADD10C,0.1*%

See section 3.3 of The Gerber Layer Format Specification

Source code in src/pygerber/gerberx3/tokenizer/tokens/bases/extended_command.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
class ExtendedCommandToken(Token):
    """## 3.3 Commands.

    Commands are the core syntactic element of the Gerber format. A Gerber file is a stream of
    commands. Commands define the graphics state, create graphical objects, defines apertures,
    manage attributes and so on.

    Commands are built with words, the basic syntactic building block of a Gerber file. A word is a
    non-empty character string, excluding the reserved characters '*' and '%', terminated with an '*'

    ```ebnf
    free_character = /[^%*]/; # All characters but * and %
    word = {free_character}+ '*';
    ```

    For historic reasons, there are two command syntax styles: word commands and extended
    commands.

    ```ebnf
    command =
    | extended_command
    | word_command
    ;
    word_command = word;
    extended_command = '%' {word}+ '%';
    ```


    Word commands are identified by a command code, the letter G, D or M followed by a positive
    integer, e.g. `G02`. Most word commands only consist of the command code, some also contain
    coordinates.

    Extended commands are identified by a two-character command code that is followed by
    parameters specific to the code. An extended command is enclosed by a pair of "%" delimiters

    An overview of all commands is in section 2.8, a full description in chapters 3.5 and 5.


    ---

    ## Example 1

    The example below shows a stream of Gerber commands.

    ```gerber
    G04 Different command styles*
    G75*
    G02*
    D10*
    X0Y0D02*
    X2000000Y0I1000000J0D01*
    D11*
    X0Y2000000D03*
    M02*
    ```


    ---

    ## Example 2

    The example below shows a stream of Gerber extended commands.

    ```gerber
    %FSLAX26Y26*%
    %MOMM*%
    %AMDonut*
    1,1,$1,$2,$3*
    $4=$1x0.75*
    1,0,$4,$2,$3*
    %
    %ADD11Donut,0.30X0X0*%
    %ADD10C,0.1*%
    ```

    ---

    See section 3.3 of [The Gerber Layer Format Specification](https://www.ucamco.com/files/downloads/file_en/456/gerber-layer-format-specification-revision-2023-08_en.pdf#page=33)

    """  # noqa: E501

    def get_gerber_code_one_line_pretty_display(self) -> str:
        """Get gerber code represented by this token."""
        return f"%{self.get_gerber_code()}*%"

get_gerber_code_one_line_pretty_display 

get_gerber_code_one_line_pretty_display() -> str

Get gerber code represented by this token.

Source code in src/pygerber/gerberx3/tokenizer/tokens/bases/extended_command.py 
90
91
92
def get_gerber_code_one_line_pretty_display(self) -> str:
    """Get gerber code represented by this token."""
    return f"%{self.get_gerber_code()}*%"

Backend

Bases: ABC

Drawing backend interface.

Source code in src/pygerber/backend/abstract/backend_cls.py 
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
class Backend(ABC):
    """Drawing backend interface."""

    handles: list[PrivateApertureHandle]
    drawing_target: DrawingTarget
    bounding_box: BoundingBox
    coordinate_origin: Vector2D

    options_class: ClassVar[type[BackendOptions]] = BackendOptions

    def __init__(self, options: Optional[BackendOptions] = None) -> None:
        """Initialize backend."""
        self.options = self.options_class() if options is None else options
        self.handles = []

    def create_aperture_handle(self, aperture_id: ApertureID) -> PrivateApertureHandle:
        """Create new aperture handle."""
        handle = self.get_aperture_handle_cls()(
            aperture_id=aperture_id,
            private_id=len(self.handles),
            backend=self,
        )
        self.handles.append(handle)
        return handle

    def get_private_aperture_handle(
        self,
        public_aperture_handle: PublicApertureHandle,
    ) -> PrivateApertureHandle:
        """Get private aperture handle."""
        return self.handles[public_aperture_handle.private_id]

    def draw(self, draws: List[DrawCommand]) -> ResultHandle:
        """Execute all draw actions to create visualization."""
        self.draws = draws

        self.finalize_aperture_creation()
        self.bounding_box = self._get_draws_bounding_box(draws)
        self.coordinate_origin = self._get_coordinate_origin()
        self.drawing_target = self._create_drawing_target()
        self._pre_drawing_hook()

        with self.drawing_target:
            for draw_action in draws:
                draw_action.draw(self.drawing_target)

        self._post_drawing_hook()

        return self.get_result_handle()

    def finalize_aperture_creation(self) -> None:
        """Apply draw operations to aperture handles."""
        for handle in self.handles:
            handle.finalize_aperture_creation()

    def _get_draws_bounding_box(self, draws: List[DrawCommand]) -> BoundingBox:
        bbox = BoundingBox.NULL

        for draw in draws:
            bbox += draw.get_bounding_box()

        return bbox

    def _get_coordinate_origin(self) -> Vector2D:
        return self.bounding_box.get_min_vector()

    @abstractmethod
    def _create_drawing_target(self) -> DrawingTarget:
        """Create drawing target object."""

    def _pre_drawing_hook(self) -> None:  # noqa: B027
        """Perform custom actions before drawing."""

    def _post_drawing_hook(self) -> None:  # noqa: B027
        """Perform custom actions after drawing."""

    @abstractmethod
    def get_result_handle(self) -> ResultHandle:
        """Return result handle to visualization."""

    @abstractmethod
    def get_aperture_handle_cls(self) -> Type[PrivateApertureHandle]:
        """Get backend-specific implementation of aperture handle class."""

    @abstractmethod
    def get_draw_circle_cls(self) -> Type[DrawCircle]:
        """Get backend-specific implementation of aperture circle component class."""

    @abstractmethod
    def get_draw_rectangle_cls(self) -> Type[DrawRectangle]:
        """Get backend-specific implementation of aperture rectangle component class."""

    @abstractmethod
    def get_draw_polygon_cls(self) -> Type[DrawPolygon]:
        """Get backend-specific implementation of aperture polygon component class."""

    @abstractmethod
    def get_draw_commands_handle_cls(self) -> type[DrawCommandsHandle]:
        """Return backend-specific implementation of draw actions handle."""

    @abstractmethod
    def get_draw_paste_cls(self) -> type[DrawPaste]:
        """Return backend-specific implementation of draw paste."""

    @abstractmethod
    def get_draw_region_cls(self) -> type[DrawRegion]:
        """Return backend-specific implementation of draw action region."""

    @abstractmethod
    def get_draw_vector_line_cls(self) -> type[DrawVectorLine]:
        """Return backend-specific implementation of draw action line."""

    @abstractmethod
    def get_draw_arc_cls(self) -> type[DrawArc]:
        """Return backend-specific implementation of draw action arc."""

__init__ 

__init__(options: Optional[BackendOptions] = None) -> None

Initialize backend.

Source code in src/pygerber/backend/abstract/backend_cls.py 
61
62
63
64
def __init__(self, options: Optional[BackendOptions] = None) -> None:
    """Initialize backend."""
    self.options = self.options_class() if options is None else options
    self.handles = []

create_aperture_handle 

create_aperture_handle(
    aperture_id: ApertureID,
) -> PrivateApertureHandle

Create new aperture handle.

Source code in src/pygerber/backend/abstract/backend_cls.py 
66
67
68
69
70
71
72
73
74
def create_aperture_handle(self, aperture_id: ApertureID) -> PrivateApertureHandle:
    """Create new aperture handle."""
    handle = self.get_aperture_handle_cls()(
        aperture_id=aperture_id,
        private_id=len(self.handles),
        backend=self,
    )
    self.handles.append(handle)
    return handle

get_private_aperture_handle 

get_private_aperture_handle(
    public_aperture_handle: PublicApertureHandle,
) -> PrivateApertureHandle

Get private aperture handle.

Source code in src/pygerber/backend/abstract/backend_cls.py 
76
77
78
79
80
81
def get_private_aperture_handle(
    self,
    public_aperture_handle: PublicApertureHandle,
) -> PrivateApertureHandle:
    """Get private aperture handle."""
    return self.handles[public_aperture_handle.private_id]

draw 

draw(draws: List[DrawCommand]) -> ResultHandle

Execute all draw actions to create visualization.

Source code in src/pygerber/backend/abstract/backend_cls.py 
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def draw(self, draws: List[DrawCommand]) -> ResultHandle:
    """Execute all draw actions to create visualization."""
    self.draws = draws

    self.finalize_aperture_creation()
    self.bounding_box = self._get_draws_bounding_box(draws)
    self.coordinate_origin = self._get_coordinate_origin()
    self.drawing_target = self._create_drawing_target()
    self._pre_drawing_hook()

    with self.drawing_target:
        for draw_action in draws:
            draw_action.draw(self.drawing_target)

    self._post_drawing_hook()

    return self.get_result_handle()

finalize_aperture_creation 

finalize_aperture_creation() -> None

Apply draw operations to aperture handles.

Source code in src/pygerber/backend/abstract/backend_cls.py 
101
102
103
104
def finalize_aperture_creation(self) -> None:
    """Apply draw operations to aperture handles."""
    for handle in self.handles:
        handle.finalize_aperture_creation()

get_result_handle abstractmethod 

get_result_handle() -> ResultHandle

Return result handle to visualization.

Source code in src/pygerber/backend/abstract/backend_cls.py 
127
128
129
@abstractmethod
def get_result_handle(self) -> ResultHandle:
    """Return result handle to visualization."""

get_aperture_handle_cls abstractmethod 

get_aperture_handle_cls() -> Type[PrivateApertureHandle]

Get backend-specific implementation of aperture handle class.

Source code in src/pygerber/backend/abstract/backend_cls.py 
131
132
133
@abstractmethod
def get_aperture_handle_cls(self) -> Type[PrivateApertureHandle]:
    """Get backend-specific implementation of aperture handle class."""

get_draw_circle_cls abstractmethod 

get_draw_circle_cls() -> Type[DrawCircle]

Get backend-specific implementation of aperture circle component class.

Source code in src/pygerber/backend/abstract/backend_cls.py 
135
136
137
@abstractmethod
def get_draw_circle_cls(self) -> Type[DrawCircle]:
    """Get backend-specific implementation of aperture circle component class."""

get_draw_rectangle_cls abstractmethod 

get_draw_rectangle_cls() -> Type[DrawRectangle]

Get backend-specific implementation of aperture rectangle component class.

Source code in src/pygerber/backend/abstract/backend_cls.py 
139
140
141
@abstractmethod
def get_draw_rectangle_cls(self) -> Type[DrawRectangle]:
    """Get backend-specific implementation of aperture rectangle component class."""

get_draw_polygon_cls abstractmethod 

get_draw_polygon_cls() -> Type[DrawPolygon]

Get backend-specific implementation of aperture polygon component class.

Source code in src/pygerber/backend/abstract/backend_cls.py 
143
144
145
@abstractmethod
def get_draw_polygon_cls(self) -> Type[DrawPolygon]:
    """Get backend-specific implementation of aperture polygon component class."""

get_draw_commands_handle_cls abstractmethod 

get_draw_commands_handle_cls() -> type[DrawCommandsHandle]

Return backend-specific implementation of draw actions handle.

Source code in src/pygerber/backend/abstract/backend_cls.py 
147
148
149
@abstractmethod
def get_draw_commands_handle_cls(self) -> type[DrawCommandsHandle]:
    """Return backend-specific implementation of draw actions handle."""

get_draw_paste_cls abstractmethod 

get_draw_paste_cls() -> type[DrawPaste]

Return backend-specific implementation of draw paste.

Source code in src/pygerber/backend/abstract/backend_cls.py 
151
152
153
@abstractmethod
def get_draw_paste_cls(self) -> type[DrawPaste]:
    """Return backend-specific implementation of draw paste."""

get_draw_region_cls abstractmethod 

get_draw_region_cls() -> type[DrawRegion]

Return backend-specific implementation of draw action region.

Source code in src/pygerber/backend/abstract/backend_cls.py 
155
156
157
@abstractmethod
def get_draw_region_cls(self) -> type[DrawRegion]:
    """Return backend-specific implementation of draw action region."""

get_draw_vector_line_cls abstractmethod 

get_draw_vector_line_cls() -> type[DrawVectorLine]

Return backend-specific implementation of draw action line.

Source code in src/pygerber/backend/abstract/backend_cls.py 
159
160
161
@abstractmethod
def get_draw_vector_line_cls(self) -> type[DrawVectorLine]:
    """Return backend-specific implementation of draw action line."""

get_draw_arc_cls abstractmethod 

get_draw_arc_cls() -> type[DrawArc]

Return backend-specific implementation of draw action arc.

Source code in src/pygerber/backend/abstract/backend_cls.py 
163
164
165
@abstractmethod
def get_draw_arc_cls(self) -> type[DrawArc]:
    """Return backend-specific implementation of draw action arc."""

DrawCommand

Bases: ABC

Description of aperture component.

Source code in src/pygerber/backend/abstract/draw_commands/draw_command.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
class DrawCommand(ABC):
    """Description of aperture component."""

    backend: Backend
    polarity: Polarity

    def __init__(self, backend: Backend, polarity: Polarity) -> None:
        """Initialize draw command."""
        self.backend = backend
        self.polarity = polarity

    @abstractmethod
    def draw(self, target: DrawingTarget) -> None:
        """Apply aperture draw component to handle."""

    @abstractmethod
    def get_bounding_box(self) -> BoundingBox:
        """Return bounding box of draw operation."""

    def __str__(self) -> str:
        return f"{self.__class__.__qualname__}({self.polarity})"

__init__ 

__init__(backend: Backend, polarity: Polarity) -> None

Initialize draw command.

Source code in src/pygerber/backend/abstract/draw_commands/draw_command.py 
18
19
20
21
def __init__(self, backend: Backend, polarity: Polarity) -> None:
    """Initialize draw command."""
    self.backend = backend
    self.polarity = polarity

draw abstractmethod 

draw(target: DrawingTarget) -> None

Apply aperture draw component to handle.

Source code in src/pygerber/backend/abstract/draw_commands/draw_command.py 
23
24
25
@abstractmethod
def draw(self, target: DrawingTarget) -> None:
    """Apply aperture draw component to handle."""

get_bounding_box abstractmethod 

get_bounding_box() -> BoundingBox

Return bounding box of draw operation.

Source code in src/pygerber/backend/abstract/draw_commands/draw_command.py 
27
28
29
@abstractmethod
def get_bounding_box(self) -> BoundingBox:
    """Return bounding box of draw operation."""

State

Bases: FrozenGeneralModel

GerberX3 interpreter state.

Source code in src/pygerber/gerberx3/parser/state.py 
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
class State(FrozenGeneralModel):
    """GerberX3 interpreter state."""

    current_position: Vector2D = Vector2D(x=Offset.NULL, y=Offset.NULL)

    # MO | Mode | Sets the unit to mm or inch                           | 4.2.1
    draw_units: Optional[Unit] = None
    # FS | Format specification | Sets the coordinate format,           | 4.2.2
    #    |                      | e.g. the number of decimals
    coordinate_parser: Optional[CoordinateParser] = None
    # Dnn | (nn≥10) | Sets the current aperture to D code nn.           | 4.6
    current_aperture: Optional[PublicApertureHandle] = None
    # G01 | | Sets linear/circular mode to linear.                      | 4.7.1
    # G02 | | Sets linear/circular mode to clockwise circular           | 4.7.2
    # G03 | | Sets linear/circular mode to counterclockwise circular    | 4.7.3
    draw_mode: DrawMode = DrawMode.Linear
    # LP  | | Load polarity | Loads the polarity object transformation  | 4.9.2
    #                       parameter.
    polarity: Polarity = Polarity.Dark
    # LM  | | Load mirroring | Loads the mirror object transformation   | 4.9.3
    #                         parameter.
    mirroring: Mirroring = Mirroring.NoMirroring
    # LR  | Load rotation |  Loads the rotation object transformation   | 4.9.4
    #                       parameter.
    rotation: Decimal = Decimal("0.0")

    region_boundary_points: List[Vector2D] = Field(default_factory=list)
    """Points defining the shape of the region."""

    # LS  | Load scaling |   Loads the scale object transformation      | 4.9.5
    #                       parameter
    scaling: Decimal = Decimal("1.0")
    # G36 | |   Starts a region statement which creates a region by     | 4.10
    #     | |   defining its contours.
    # G37 | |   Ends the region statement.                              | 4.10
    is_region: bool = False
    # AB  | |   Aperture blockOpens a block aperture statement and      | 4.11
    #     | |   assigns its aperture number or closes a block aperture  |
    #     | |   statement.                                              |
    is_aperture_block: bool = False
    # SR  | |   Step and repeatOpen or closes a step and repeat         | 4.11
    #     | |   statement.                                              |
    is_step_and_repeat: bool = False
    # TF  | |   Attribute on fileSet a file attribute.                  | 5.3
    # TD  | |   Attribute deleteDelete one or all attributes in the     | 5.5
    #     | |   dictionary.                                             |
    file_attributes: Dict[str, str] = Field(default_factory=dict)
    # G75 | |   Sets multi quadrant mode
    # G74 | |   Sets single quadrant mode
    is_multi_quadrant: bool = False

    is_output_image_negation_required: bool = False
    """In Gerber specification deprecated IP command is mentioned.
    It can set image polarity to either positive, the usual one, or to negative.
    Under negative image polarity, image generation is different. Its purpose is to
    create a negative image, clear areas in a dark background. The entire image plane
    in the background is initially dark instead of clear. The effect of dark and clear
    polarity is toggled. The entire image is simply reversed, dark becomes white and
    vice versa.
    This effect can be achieved by simply inverting colors of output image.
    """

    apertures: Dict[ApertureID, PublicApertureHandle] = Field(default_factory=dict)
    """Collection of all apertures defined until given point in code."""

    macros: Dict[str, MacroDefinition] = Field(default_factory=dict)
    """Collection of all macros defined until given point in code."""

    def get_units(self) -> Unit:
        """Get drawing unit or raise UnitNotSetError."""
        if self.draw_units is None:
            raise UnitNotSetError
        return self.draw_units

    def get_coordinate_parser(self) -> CoordinateParser:
        """Get coordinate parser or raise CoordinateFormatNotSetError."""
        if self.coordinate_parser is None:
            raise CoordinateFormatNotSetError
        return self.coordinate_parser

    def get_current_aperture(self) -> PublicApertureHandle:
        """Get current aperture or raise ApertureNotSelectedError."""
        if self.current_aperture is None:
            raise ApertureNotSelectedError
        return self.current_aperture

    def parse_coordinate(self, coordinate: Coordinate) -> Offset:
        """Parse, include substitution with current and conversion to Offset."""
        if coordinate.coordinate_type == CoordinateType.MISSING_X:
            return self.current_position.x

        if coordinate.coordinate_type == CoordinateType.MISSING_Y:
            return self.current_position.y

        if coordinate.coordinate_type == CoordinateType.MISSING_I:
            return Offset.NULL

        if coordinate.coordinate_type == CoordinateType.MISSING_J:
            return Offset.NULL

        return Offset.new(
            self.get_coordinate_parser().parse(coordinate),
            unit=self.get_units(),
        )

region_boundary_points class-attribute instance-attribute 

region_boundary_points: List[Vector2D] = Field(
    default_factory=list
)

Points defining the shape of the region.

is_output_image_negation_required class-attribute instance-attribute 

is_output_image_negation_required: bool = False

In Gerber specification deprecated IP command is mentioned. It can set image polarity to either positive, the usual one, or to negative. Under negative image polarity, image generation is different. Its purpose is to create a negative image, clear areas in a dark background. The entire image plane in the background is initially dark instead of clear. The effect of dark and clear polarity is toggled. The entire image is simply reversed, dark becomes white and vice versa. This effect can be achieved by simply inverting colors of output image.

apertures class-attribute instance-attribute 

apertures: Dict[ApertureID, PublicApertureHandle] = Field(
    default_factory=dict
)

Collection of all apertures defined until given point in code.

macros class-attribute instance-attribute 

macros: Dict[str, MacroDefinition] = Field(
    default_factory=dict
)

Collection of all macros defined until given point in code.

get_units 

get_units() -> Unit

Get drawing unit or raise UnitNotSetError.

Source code in src/pygerber/gerberx3/parser/state.py 
95
96
97
98
99
def get_units(self) -> Unit:
    """Get drawing unit or raise UnitNotSetError."""
    if self.draw_units is None:
        raise UnitNotSetError
    return self.draw_units

get_coordinate_parser 

get_coordinate_parser() -> CoordinateParser

Get coordinate parser or raise CoordinateFormatNotSetError.

Source code in src/pygerber/gerberx3/parser/state.py 
101
102
103
104
105
def get_coordinate_parser(self) -> CoordinateParser:
    """Get coordinate parser or raise CoordinateFormatNotSetError."""
    if self.coordinate_parser is None:
        raise CoordinateFormatNotSetError
    return self.coordinate_parser

get_current_aperture 

get_current_aperture() -> PublicApertureHandle

Get current aperture or raise ApertureNotSelectedError.

Source code in src/pygerber/gerberx3/parser/state.py 
107
108
109
110
111
def get_current_aperture(self) -> PublicApertureHandle:
    """Get current aperture or raise ApertureNotSelectedError."""
    if self.current_aperture is None:
        raise ApertureNotSelectedError
    return self.current_aperture

parse_coordinate 

parse_coordinate(coordinate: Coordinate) -> Offset

Parse, include substitution with current and conversion to Offset.

Source code in src/pygerber/gerberx3/parser/state.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def parse_coordinate(self, coordinate: Coordinate) -> Offset:
    """Parse, include substitution with current and conversion to Offset."""
    if coordinate.coordinate_type == CoordinateType.MISSING_X:
        return self.current_position.x

    if coordinate.coordinate_type == CoordinateType.MISSING_Y:
        return self.current_position.y

    if coordinate.coordinate_type == CoordinateType.MISSING_I:
        return Offset.NULL

    if coordinate.coordinate_type == CoordinateType.MISSING_J:
        return Offset.NULL

    return Offset.new(
        self.get_coordinate_parser().parse(coordinate),
        unit=self.get_units(),
    )

ImagePolarity

Bases: ExtendedCommandToken

Wrapper for image polarity token.

The IP command is deprecated.

IP sets positive or negative polarity for the entire image. It can only be used once, at the beginning of the file.

See section 8.1.4 of The Gerber Layer Format Specification Revision 2023.03 - https://argmaster.github.io/pygerber/latest/gerber_specification/revision_2023_03.html

Source code in src/pygerber/gerberx3/tokenizer/tokens/ip_image_polarity.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
class ImagePolarity(ExtendedCommandToken):
    """Wrapper for image polarity token.

    The IP command is deprecated.

    IP sets positive or negative polarity for the entire image. It can only be used
    once, at the beginning of the file.

    See section 8.1.4 of The Gerber Layer Format Specification Revision 2023.03 - https://argmaster.github.io/pygerber/latest/gerber_specification/revision_2023_03.html
    """

    def __init__(
        self,
        string: str,
        location: int,
        image_polarity: ImagePolarityEnum,
    ) -> None:
        super().__init__(string, location)
        self.image_polarity = image_polarity

    @classmethod
    def new(cls, string: str, location: int, tokens: ParseResults) -> Self:
        """Create instance of this class.

        Created to be used as callback in `ParserElement.set_parse_action()`.
        """
        image_polarity = ImagePolarityEnum(tokens["image_polarity"])
        return cls(
            string=string,
            location=location,
            image_polarity=image_polarity,
        )

    def update_drawing_state(
        self,
        state: State,
        _backend: Backend,
    ) -> Tuple[State, Iterable[DrawCommand]]:
        """Set drawing polarity."""
        warn_deprecated_code("IP", "8.1.4")
        return (
            state.model_copy(
                update={
                    "is_output_image_negation_required": (
                        self.image_polarity == ImagePolarityEnum.NEGATIVE
                    ),
                },
            ),
            (),
        )

    def get_gerber_code(
        self,
        indent: str = "",
        endline: str = "\n",
    ) -> str:
        """Get gerber code represented by this token."""
        return f"IP{self.image_polarity.get_gerber_code(indent, endline)}"

new classmethod 

new(
    string: str, location: int, tokens: ParseResults
) -> Self

Create instance of this class.

Created to be used as callback in ParserElement.set_parse_action().

Source code in src/pygerber/gerberx3/tokenizer/tokens/ip_image_polarity.py 
41
42
43
44
45
46
47
48
49
50
51
52
@classmethod
def new(cls, string: str, location: int, tokens: ParseResults) -> Self:
    """Create instance of this class.

    Created to be used as callback in `ParserElement.set_parse_action()`.
    """
    image_polarity = ImagePolarityEnum(tokens["image_polarity"])
    return cls(
        string=string,
        location=location,
        image_polarity=image_polarity,
    )

update_drawing_state 

update_drawing_state(
    state: State, _backend: Backend
) -> Tuple[State, Iterable[DrawCommand]]

Set drawing polarity.

Source code in src/pygerber/gerberx3/tokenizer/tokens/ip_image_polarity.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def update_drawing_state(
    self,
    state: State,
    _backend: Backend,
) -> Tuple[State, Iterable[DrawCommand]]:
    """Set drawing polarity."""
    warn_deprecated_code("IP", "8.1.4")
    return (
        state.model_copy(
            update={
                "is_output_image_negation_required": (
                    self.image_polarity == ImagePolarityEnum.NEGATIVE
                ),
            },
        ),
        (),
    )

get_gerber_code 

get_gerber_code(
    indent: str = "", endline: str = "\n"
) -> str

Get gerber code represented by this token.

Source code in src/pygerber/gerberx3/tokenizer/tokens/ip_image_polarity.py 
72
73
74
75
76
77
78
def get_gerber_code(
    self,
    indent: str = "",
    endline: str = "\n",
) -> str:
    """Get gerber code represented by this token."""
    return f"IP{self.image_polarity.get_gerber_code(indent, endline)}"

warn_deprecated_code 

warn_deprecated_code(code: str, spec_section: str) -> None

Display warning about deprecated code.

Source code in src/pygerber/warnings.py 
 7
 8
 9
10
11
12
13
14
15
def warn_deprecated_code(code: str, spec_section: str) -> None:
    """Display warning about deprecated code."""
    logging.warning(
        "Detected deprecated code: %s. "
        "See section %s of The Gerber Layer Format Specification Revision "
        "2023.03 - https://argmaster.github.io/pygerber/latest/gerber_specification/revision_2023_03.html",
        code,
        spec_section,
    )