i92iSrSSKrSSKrSSKJr SSKJrJrJr SS0r Sr \ S5r \\ \ \R4r\ \ \R4rS@S jrS r"S S \"S S \4S\4S\4S\\4/55rS\ S'S\ S'S\ S'S\ S'S\ S'"SS\"SS\4S\\4/55rS\ S'S\ S'S\ S'"S S!\"S!S"\4S#\4S$\4S%\4S\\4/55rS\ S&'S'\ S('S)\ S*'S+\ S,'S-\ S.'S\ S/'SAS0jrSAS1jrSBS2jrSAS3jrS4rS5r"S6S7\5r"S8S9\5rS\ S:'S\ S;'S\ S<'S\ S='S\ S>'S\ S?'g)Ca$ Core drawing primitives for fpdf2. This module defines the fundamental data structures used throughout the drawing API, including: - Color models: ``DeviceRGB``, ``DeviceGray``, ``DeviceCMYK`` - Geometric primitives: ``Point`` - Transformation matrices: ``Transform`` These classes are intentionally lightweight and self-contained so they can be safely imported from any other drawing-related module without creating circular dependencies. All higher-level drawing features (paths, patterns, gradients, etc.) build on top of these primitives. N)Sequence) NamedTupleOptionalUnionforce_nodocumentFc,S[UR'U$)zQA decorator that forces pdoc not to document the decorated item (class or method)F__pdoc__ __qualname__items Q/home/james-whalen/.local/lib/python3.13/site-packages/fpdf/drawing_primitives.pyrrs"'HT   Kc,S[UR'U$)zMA decorator that forces pdoc to document the decorated item (class or method)Tr r s rforce_documentr#s#'HT   KrcJXs=::aU::dO [USUSUS35eU$)Nz not in range [z, ]) ValueError)valueminimummaximums r check_ranger.s0  &w &E7/'"WIQGHH LrcFUSRS5RS5$)z Convert a decimal number to a minimal string representation (no trailing 0 or .). Args: number (Number): the number to be converted to a string. Returns: The number's string representation. z.4f0.)rstrip)numbers r number_to_strr5s$S\ ! !# & - -c 22rc|^\rSrSrSrSrS U4Sjjr\S5r\S5r S\ 4Sjr S\ 4S jr S S jrS rU=r$) DeviceRGBKz+A class representing a PDF DeviceRGB color.rgc|>Ub [U5 [TU] U[U5[U5[U5U5$Nrsuper__new__)clsrgba __class__s rr'DeviceRGB.__new__ds4 = NwsKNKNKPQNTUVVrc USS$)zVThe color components as a tuple in order `(r, g, b)` with alpha omitted, in range 0-1.Nselfs rcolorsDeviceRGB.colorsjCRyrc:[SUR55$)XThe color components as a tuple in order `(r, g, b)` with alpha omitted, in range 0-255.c3,# UH nSU-v M g7fNr1.0vs r &DeviceRGB.colors255..r2kS1Wktupler4r2s r colors255DeviceRGB.colors255o2dkk222rreturncfSRSUR55SUR3-$)N c38# UHn[U5v M g7fr$rr=vals rr?&DeviceRGB.serialize..uBks c**kjoinr4OPERATORr2s r serializeDeviceRGB.serializet+xxBdkkBBqEXXXrc[URUR- 5S:=(a% [URUR- 5S:$)Ng& .>)absr)r*r+r2s r is_achromaticDeviceRGB.is_achromaticws9466DFF?#d*Js466DFF?/Cd/JJrcr[SUR-SUR--SUR--5$)Ngz6?g,C?g]m{?) DeviceGrayr)r*r+r2s rto_grayDeviceRGB.to_gray{s/&466/FTVVO;ftvvoMNNrr1r$)rHr])__name__ __module__r __firstlineno____doc__rTr'propertyr4rEstrrUboolrZr^__static_attributes__ __classcell__r-s@rr r Ksh 6 HFW 33Y3YKtKOOrr r)r*r+r,zDeviceRGB.OPERATORz8The red color component. Must be in the interval [0, 1].z DeviceRGB.rz:The green color component. Must be in the interval [0, 1].z DeviceRGB.gz9The blue color component. Must be in the interval [0, 1].z DeviceRGB.baD The alpha color component (i.e. opacity). Must be `None` or in the interval [0, 1]. An alpha value of 0 makes the color fully transparent, and a value of 1 makes it fully opaque. If `None`, the color will be interpreted as not specifying a particular transparency rather than specifying fully transparent or fully opaque. z DeviceRGB.acd^\rSrSrSrSrS U4Sjjr\S5r\S5r S\ 4Sjr S r U=r $) r]z,A class representing a PDF DeviceGray color.r*cT>Ub [U5 [TU] U[U5U5$r$r%)r(r*r,r-s rr'DeviceGray.__new__s& = NwsKNA66rcHURURUR4$)zTThe color components as a tuple in order (r, g, b) with alpha omitted, in range 0-1.)r*r2s rr4DeviceGray.colorssvvtvvtvv%%rc:[SUR55$)r8c3,# UH nSU-v M g7fr:r1r<s rr?'DeviceGray.colors255..rArBrCr2s rrEDeviceGray.colors255rGrrHcJ[UR5SUR3$)NrJ)rr*rTr2s rrUDeviceGray.serializes!'($--99rr1r$)r`rar rbrcrTr'rdr4rErerUrgrhris@rr]r]sN 7HF7 &&33:3::rr]zDeviceGray.OPERATORz} The gray color component. Must be in the interval [0, 1]. A value of 0 represents black and a value of 1 represents white. z DeviceGray.gz DeviceGray.acT^\rSrSrSrSrS U4Sjjr\S5rS\ 4Sjr Sr U=r $) DeviceCMYKz,A class representing a PDF DeviceCMYK color.kc >Ub [U5 [TU] U[U5[U5[U5[U5U5$r$r%)r(cmyryr,r-s rr'DeviceCMYK.__new__s> = Nw QQQQQR  rc USS$)zWThe color components as a tuple in order (c, m, y, k) with alpha omitted, in range 0-1.Nr0r1r2s rr4DeviceCMYK.colorsr6rrHcfSRSUR55SUR3-$)NrJc38# UHn[U5v M g7fr$rLrMs rr?'DeviceCMYK.serialize..rPrQrRr2s rrUDeviceCMYK.serializerWrr1r$) r`rar rbrcrTr'rdr4rerUrgrhris@rrwrws=7HF Y3YYrrwr{r|r}ryzDeviceCMYK.OPERATORz9The cyan color component. Must be in the interval [0, 1].z DeviceCMYK.czc[U[5(d[US35eURSS5nUR S5(aUR S5(d[ US35eUSSnURS 5n[U5S :Xa%[UVs/sHn[U5PM snS S 06$[U5S:Xa"[UVs/sHn[U5PM sn6$[ US 35es snfs snf)z Parse an RGB color from a css-style rgb(R, G, B, A) color string. Args: rgbstr (str): of the form `rgb(R, G, B)` or `rgb(R, G, B, A)`. Returns: DeviceRGB representation of the color. rrJzrgb()z- does not follow the expected rgb(...) formatrr0,r,Nz6 could not be interpreted as a rgb(R, G, B[, A]) color) rrerreplacerendswithrsplitrrr)rgbstrr4r{s rcolor_from_rgb_stringrvs fc " "6("5677 ^^C $F   V $ $FOOC,@,@F8#PQRR Ab\F \\# F 6{af-fc!ff-666 6{af-fc!ff-.. xUV WW ..s C9C>c \rSrSr%Sr\\S'\\S'S\4SjrSSS\4Sjr SSS\4S jr S\4S jr \ SS j5r \ SS j5r\ SS j5r\ SSj5r\r\ S\SS4Sj5r\ S\SS4Sj5r\ SSj5rS\4SjrSrg)PointizE An x-y coordinate pair within the two-dimensional coordinate frame. xr}rHc\[UR5S[UR53$)z=Render the point to the string `"x y"` for emitting to a PDF.rJrrr}r2s rrender Point.renders) '(-*?)@AArotherc[U[5(d[SU<35eURUR-URUR--$)z Compute the dot product of two points. Args: other (Point): the point with which to compute the dot product. Returns: The scalar result of the dot product computation. Raises: TypeError: if `other` is not a `Point`. zcannot dot with )rrrrr}r3rs rdot Point.dotsI%''.ui89 9vv$&&577"222rc [U[5(d[SU<35eURUR-URUR-- nUS:US:- nUR 5UR 5-S:XagU[ R"[URU5UR 5UR 5-- S55-$)a} Compute the angle between two points (interpreted as vectors from the origin). The return value is in the interval (-pi, pi]. Sign is dependent on ordering, with clockwise angle travel considered to be positive due to the orientation of the coordinate frame basis vectors (i.e. the angle between `(1, 0)` and `(0, 1)` is `+pi/2`, the angle between `(1, 0)` and `(0, -1)` is `-pi/2`, and the angle between `(0, -1)` and `(1, 0)` is `+pi/2`). Args: other (Point): the point to compute the angle sweep toward. Returns: The scalar angle between the two points **in radians**. Raises: TypeError: if `other` is not a `Point`. zcannot compute angle with r) rrrrr}magmathacosroundr)r3r signifiersigns rangle Point.angles(%''8 BC CVVegg%$&&577*:; Q9q=1 88: #q (diidhhuoeiik9Q&RTU VWWWrcFURS-URS--S-$)z Compute the Cartesian distance from this point to the origin This is the same as computing the magnitude of the vector represented by this point. Returns: The scalar result of the distance computation. rg?rr}r2s rr Point.mags$ DFFAI%#--rc[U[5(a8[URUR-URUR-S9$[$)a. Produce the sum of two points. Adding two points is the same as translating the source point by interpreting the other point's x and y coordinates as distances. Args: other (Point): right-hand side of the infix addition operation Returns: A Point which is the sum of the two source points. rrrrr}NotImplementedrs r__add__ Point.__add__s> eU # #466EGG+tvv/?@ @rc[U[5(a8[URUR- URUR- S9$[$)z Produce the difference between two points. Unlike addition, this is not a commutative operation! Args: other (Point): right-hand side of the infix subtraction operation Returns: A Point which is the difference of the two source points. rrrs r__sub__ Point.__sub__s> eU # #466EGG+tvv/?@ @rcB[UR*UR*S9$)z Produce a point by negating this point's coordinates. Returns: A Point whose coordinates are this points coordinates negated. r)rrr}r2s r__neg__ Point.__neg__sw466'**rc[U[5(a&[URU-URU-5$[ $)z Multiply a point by a scalar value. Args: other (Number): the scalar value by which to multiply the point's coordinates. Returns: A Point whose coordinates are the result of the multiplication. )r NumberClassrrr}rrs r__mul__ Point.__mul__s4 e[ ) )%%8 8rc[U[5(a8[UR[ U5- UR [ U5- 5$[ $)aV Divide a point by a scalar value. .. note:: Because division is not commutative, `Point / scalar` is implemented, but `scalar / Point` is nonsensical and not implemented. Args: other (Number): the scalar value by which to divide the point's coordinates. Returns: A Point whose coordinates are the result of the division. rrrrfloatr}rrs r __truediv__Point.__truediv__"s> e[ ) )%,.u0EF Frc[U[5(a8[UR[ U5-UR [ U5-5$[ $)ao Divide a point by a scalar value using integer division. .. note:: Because division is not commutative, `Point // scalar` is implemented, but `scalar // Point` is nonsensical and not implemented. Args: other (Number): the scalar value by which to divide the point's coordinates. Returns: A Point whose coordinates are the result of the division. rrs r __floordiv__Point.__floordiv__7s> e[ ) )5</5<1GH HrcD[U[5(a[URUR-UR UR --UR-URUR-URUR --UR-S9$[$)ad Transform a point with the given transform matrix. .. note:: This operator is only implemented for Transforms. This transform is not commutative, so `Point @ Transform` is implemented, but `Transform @ Point` is not implemented (technically speaking, the current implementation is commutative because of the way points and transforms are represented, but if that representation were to change this operation could stop being commutative) Args: other (Transform): the transform to apply to the point Returns: A Point whose coordinates are the result of applying the transform. r) r Transformrr,rr{r}er+dfrrs r __matmul__Point.__matmul__Ns|& eY ' '''DFF"UWWtvv%55?''DFF"UWWtvv%55?  rc`S[UR5S[UR5S3$)Nz(x=z, y=rrr2s r__str__ Point.__str__is+]466*+4 dff0E/FaHHrr1N)rrrHr)rHr)rrrHr)r`rar rbrcr__annotations__rerrrrrrrrr__rmul__Numberrrrrrgr1rrrrs H$ H$BB 33U3$X7XuX: .U .$"++ HG(&W,4IIrrc\rSrSr%Sr\\S'\\S'\\S'\\S'\\S'\\S'\S-S j5r\S \ S \ S S4S j5r \S.S \ S \ \ S S4Sjj5r \S\ S S4Sj5r \S\ S S4Sj5r\S.S \ S \ \ S S4Sjj5r\S/S\ S\ \ S S4Sjj5r\S/S\ S\ \ S S4Sjj5rS \ S \ S S4SjrS.S \ S \ \ S S4SjjrS\ S S4SjrS\ S S4SjrS.S \ S \ \ S S4SjjrS/S\ S\ \ S S4S jjrS/S\ S\ \ S S4S!jjrS \ S \ S S4S"jrS-S#jr\S$\ S S4S%j5r\r\S0S&j5rS'S(S \\ S(44S)jr!S \ 4S*jr"S \\\44S+jr#S,r$g)1rima A representation of an affine transformation matrix for 2D shapes. The actual matrix is: ``` [ a b 0 ] [x' y' 1] = [x y 1] [ c d 0 ] [ e f 1 ] ``` Complex transformation operations can be composed via a sequence of simple transformations by performing successive matrix multiplication of the simple transformations. For example, scaling a set of points around a specific center point can be represented by a translation-scale-translation sequence, where the first translation translates the center to the origin, the scale transform scales the points relative to the origin, and the second translation translates the points back to the specified center point. Transform multiplication is performed using python's dedicated matrix multiplication operator, `@` The semantics of this representation mean composed transformations are specified left-to-right in order of application (some other systems provide transposed representations, in which case the application order is right-to-left). For example, to rotate the square `(1,1) (1,3) (3,3) (3,1)` 45 degrees clockwise about its center point (which is `(2,2)`) , the translate-rotate-translate process described above may be applied: ```python rotate_centered = ( Transform.translation(-2, -2) @ Transform.rotation_d(45) @ Transform.translation(2, 2) ) ``` Instances of this class provide a chaining API, so the above transform could also be constructed as follows: ```python rotate_centered = Transform.translation(-2, -2).rotate_d(45).translate(2, 2) ``` Or, because the particular operation of performing some transformations about a specific point is pretty common, ```python rotate_centered = Transform.rotation_d(45).about(2, 2) ``` By convention, this class provides class method constructors following noun-ish naming (`translation`, `scaling`, `rotation`, `shearing`) and instance method manipulations following verb-ish naming (`translate`, `scale`, `rotate`, `shear`). r,r+r{rrrrHcU"SSSSSS5$)z] Create a transform representing the identity transform. The identity transform is a no-op. rrr1)r(s ridentityTransform.identitys1aAq!$$rrr}c @U"SSSS[U5[U55$)a Create a transform that performs translation. Args: x (Number): distance to translate points along the x (horizontal) axis. y (Number): distance to translate points along the y (vertical) axis. Returns: A Transform representing the specified translation. rrrr(rr}s r translationTransform.translations!1aAuQxq22rNcJUcUnU"[U5SS[U5SS5$)a Create a transform that performs scaling. Args: x (Number): scaling ratio in the x (horizontal) axis. A value of 1 results in no scale change in the x axis. y (Number): optional scaling ratio in the y (vertical) axis. A value of 1 results in no scale change in the y axis. If this value is omitted, it defaults to the value provided to the `x` argument. Returns: A Transform representing the specified scaling. rrrs rscalingTransform.scalings+ 9A58Q58Q22rthetacU"[R"U5[R"U5[R"U5*[R"U5SS5$)z Create a transform that performs rotation. Args: theta (Number): the angle **in radians** by which to rotate. Positive values represent clockwise rotations. Returns: A Transform representing the specified rotation. r)rcossin)r(rs rrotationTransform.rotationsC HHUOTXXe_txx.>QRTU  rtheta_dcLUR[R"U55$)z Create a transform that performs rotation **in degrees**. Args: theta_d (Number): the angle **in degrees** by which to rotate. Positive values represent clockwise rotations. Returns: A Transform representing the specified rotation. )rrradians)r(rs r rotation_dTransform.rotation_ds||DLL122rcJUcUnU"S[U5[U5SSS5$)aX Create a transform that performs shearing (not of sheep). Args: x (Number): The amount to shear along the x (horizontal) axis. y (Number): Optional amount to shear along the y (vertical) axis. If omitted, this defaults to the value provided to the `x` argument. Returns: A Transform representing the specified shearing. rrrrs rshearingTransform.shearings+ 9A1eAha!Q22raxayc UcUnU"S[R"[U55[R"[U55SSS5$)a Create a skew (shear) transform using angles **in radians**. Args: ax (Number): skew angle along the X axis (radians). Positive ax produces x' = x + tan(ax) * y ay (Number): optional skew angle along the Y axis (radians). Positive ay produces y' = y + tan(ay) * x If omitted, defaults to the value of `ax`. Returns: A Transform representing the specified skew. rr)rtanr)r(rrs rskewingTransform.skewings= :B1dhhuRy)488E"I+>1aHHrax_day_dcPUcUn[R"[U55n[R"[U55nSn[[R"U55U:d#[[R"U55U:a [ S5eUR X45$)ub Create a skew (shear) transform using angles **in degrees**. Args: ax_d (Number): skew angle along X in degrees. ay_d (Number): optional skew angle along Y in degrees. If omitted, defaults to ax_d. Returns: A Transform representing the specified skew. Raises: ValueError: if an angle is too close to 90° + k·180° (infinite shear). g-q=u:Skew angle produces infinite shear (near 90° + k·180°).)rrrrYrrr )r(r r rrepss r skewing_dTransform.skewing_d&s{ <D \\%+ & \\%+ & txx| s "c$((2,&7#&=YZ Z{{2""rc2U[RX5-$)a Produce a transform by composing the current transform with a translation. .. note:: Transforms are immutable, so this returns a new transform rather than mutating self. Args: x (Number): distance to translate points along the x (horizontal) axis. y (Number): distance to translate points along the y (vertical) axis. Returns: A Transform representing the composed transform. rrr3rr}s r translateTransform.translate?si++A111rc2U[RX5-$)aH Produce a transform by composing the current transform with a scaling. .. note:: Transforms are immutable, so this returns a new transform rather than mutating self. Args: x (Number): scaling ratio in the x (horizontal) axis. A value of 1 results in no scale change in the x axis. y (Number): optional scaling ratio in the y (vertical) axis. A value of 1 results in no scale change in the y axis. If this value is omitted, it defaults to the value provided to the `x` argument. Returns: A Transform representing the composed transform. )rrrs rscaleTransform.scalePs$i''---rc2U[RU5-$)ao Produce a transform by composing the current transform with a rotation. .. note:: Transforms are immutable, so this returns a new transform rather than mutating self. Args: theta (Number): the angle **in radians** by which to rotate. Positive values represent clockwise rotations. Returns: A Transform representing the composed transform. )rr)r3rs rrotateTransform.rotatedsi((///rc2U[RU5-$)a Produce a transform by composing the current transform with a rotation **in degrees**. .. note:: Transforms are immutable, so this returns a new transform rather than mutating self. Args: theta_d (Number): the angle **in degrees** by which to rotate. Positive values represent clockwise rotations. Returns: A Transform representing the composed transform. )rr)r3rs rrotate_dTransform.rotate_dus i**7333rc2U[RX5-$)a Produce a transform by composing the current transform with a shearing. .. note:: Transforms are immutable, so this returns a new transform rather than mutating self. Args: x (Number): The amount to shear along the x (horizontal) axis. y (Number): Optional amount to shear along the y (vertical) axis. If omitted, this defaults to the value provided to the `x` argument. Returns: A Transform representing the composed transform. )rrrs rshearTransform.shears i((...rc2U[RX5-$)zCompose with a skew (radians).)rr )r3rrs rskewTransform.skewsi''///rc2U[RX5-$)zCompose with a skew (degrees).)rr)r3r r s rskew_dTransform.skew_dsi))$555rcd[RU*U*5U-[RX5-$)aM Bracket the given transform in a pair of translations to make it appear about a point that isn't the origin. This is a useful shorthand for performing a transform like a rotation around the center point of an object that isn't centered at the origin. .. note:: Transforms are immutable, so this returns a new transform rather than mutating self. Args: x (Number): the point along the x (horizontal) axis about which to transform. y (Number): the point along the y (vertical) axis about which to transform. Returns: A Transform representing the composed transform. rrs raboutTransform.abouts0&$$aR!,t3i6K6KA6QQQrc URUR-URUR-- nUS:Xa [ S5e[ URU- UR*U- UR*U- URU- URUR -URUR-- U- URUR-URUR -- U- S9$)z Produce a transform that is the inverse of this transform. Returns: A Transform representing the inverse of this transform. Raises: ValueError: if the transform is not invertible. rzTransform is not invertibler,r+r{rrr)r,rr+r{rrrr)r3dets rinverseTransform.inversesfftvvo/ !8:; ;ffslvvgmvvgmffslvv$&&0C7vv$&&0C7   rrc [U[5(ag[U5n[URU-UR U-UR U-URU-URU-URU-S9$[$)z Multiply the individual transform parameters by a scalar value. Args: other (Number): the scalar value by which to multiply the parameters Returns: A Transform with the modified parameters. r-) rrrrr,r+r{rrrrrs rrTransform.__mul__sq e[ ) )%LE&&5.&&5.&&5.&&5.&&5.&&5.  rc [U[5(GaTURURUR-URUR --URUR-URUR --UR UR-UR UR --UR UR-UR UR --URUR-URUR --UR-URUR-URUR --UR-S9$[$)z Compose two transforms into a single transform. Args: other (Transform): the right-hand side transform of the infix operator. Returns: A Transform representing the composed transform. r-) rrr-r,r+r{rrrrrs rrTransform.__matmul__s  eY ' '>>&&577"TVVegg%55&&577"TVVegg%55&&577"TVVegg%55&&577"TVVegg%55&&577"TVVegg%55?&&577"TVVegg%55? " r last_item Renderablec [UR5S[UR5S[UR5S[UR5S[UR 5S[UR 5S3 U4$)z Render the transform to its PDF output representation. Args: last_item: the last path element this transform applies to Returns: A tuple of `(str, last_item)`. `last_item` is returned unchanged. rJz cmrr,r+r{rrr)r3r5s rrTransform.renders|TVV$%Q}TVV'<&=QTVV$%Q}TVV'<&=QTVV$%Q}TVV'<&=S B    rcS[UR5S[UR5S[UR5S[UR5S[UR 5S[UR 5S3 $)Nz transform: [rJz 0; z 1]r8r2s rrTransform.__str__ssTVV$%Q}TVV'<&=TTVV$%Q}TVV'<&=TTVV$%Q}TVV'<&=S B rc[R"URUR5[R"URUR 54$)u% Returns (sqrt(a² + c²), sqrt(b² + d²)), i.e. the Euclidean norms of those rows. These values bound how much the transform can stretch geometry along the device X and Y axes, respectively, and are useful for inflating axis-aligned bounding boxes to account for stroke width under the CTM. )rhypotr,r{r+rr2s r row_normsTransform.row_normss5 466466*DJJtvvtvv,FGGrr1)rHrr$)rN)rrrHr)%r`rar rbrcrr classmethodrrrrrrrrr rrrrrr!r$r'r*r/rrrrrDrerrr>rgr1rrrrms7r H H H H H H%% 3F 3v 3+ 3 3338F#33{33& V    3 3K 3 333HV$43 33"II&)9I[II$#V#x/?#;##0262f22".v.(6"2.k.(0F0{0"44;4$/v/(6"2/k/$0v0x'70;0666Xf-=66RvR&R[R* .V 0H,  sL7H1I "  H5.Hrrz Transform.az Transform.bz Transform.cz Transform.dz Transform.ez Transform.f)rg?r$)r0r0)rcdecimalrcollections.abcrtypingrrrr rrrrDecimalrrrrr r]rwrrrrrrrrr1rrrEsY$ %..  &  sE7??* +E7??+  3,2O vf V}sHV#(   Y &M &M &M &M (6" #   YD#( VB YW 94$, 0E0%RPX