"""Write the `.gbrjob` job file (spec 2020.08, JSON schema 2023.06).
The job file is the glue that lets CAM import a file set without guessing,
so it is written from the first release rather than treated as an extra.
Its `Path` values are the final resolved filenames, which means naming runs
before this writer does and the caller hands over the resolved set rather
than anything here re-deriving a name.
"""
from __future__ import annotations
import json
import uuid
from dataclasses import dataclass, field
from enum import StrEnum
from .model import FileMeta, FileFunction, FileKind, FilePolarity
[docs]
class StackupType(StrEnum):
"""`MaterialStackup` row types.
Soldermask and legend rows exist so a stackup layer that declares itself
one is not mislabeled dielectric, which is what a "everything that is
not a conductor is a dielectric" walk produces.
"""
COPPER = "Copper"
DIELECTRIC = "Dielectric"
SOLDERMASK = "SolderMask"
LEGEND = "Legend"
SURFACE_FINISH = "SurfaceFinish"
[docs]
@dataclass(frozen=True)
class StackupRow:
"""One `MaterialStackup` entry, top to bottom. Thickness in mm."""
type: StackupType
thickness: float | None = None
name: str | None = None
material: str | None = None
dielectric_constant: float | None = None
loss_tangent: float | None = None
[docs]
@dataclass(frozen=True)
class FileEntry:
"""One `FilesAttributes` entry.
Args:
path: the resolved filename, as written to disk.
file_format: `XNC` for a drill file; omitted for Gerber, whose
format is implied.
"""
path: str
function: FileFunction
polarity: FilePolarity | None = None
file_format: str | None = None
[docs]
@dataclass
class JobFile:
"""The job file model.
Args:
size: board extent (X, Y) in mm, from the profile bounding box.
conductors: `LayerNumber`, the conductor count.
thickness: `BoardThickness` in mm, summed over the stackup where
every material declares one.
"""
size: tuple[float, float]
conductors: int
thickness: float | None = None
stackup: list[StackupRow] = field(default_factory=list)
files: list[FileEntry] = field(default_factory=list)
[docs]
def project_guid(name: str) -> str:
"""A stable GUID for a design name.
uuid5 gives determinism across reruns, but the spec requires an RFC 4122
version 1 or 4 GUID and a uuid5 carries a version 5 nibble, so the
version and variant nibbles are forced to v4 afterwards.
"""
derived = uuid.uuid5(uuid.NAMESPACE_URL, f"urn:jitx:design:{name}")
return str(uuid.UUID(int=derived.int, version=4))
[docs]
def emit_jobfile(job: JobFile, meta: FileMeta) -> str:
"""The complete text of the `.gbrjob` file."""
content: dict[str, object] = {
"Header": {
# an object here, unlike the flat TF.GenerationSoftware string
"GenerationSoftware": {
"Vendor": meta.software.vendor,
"Application": meta.software.application,
"Version": meta.software.version,
},
"CreationDate": meta.creation_date,
},
"GeneralSpecs": _general_specs(job, meta),
}
if job.stackup:
content["MaterialStackup"] = [_stackup_row(row) for row in job.stackup]
content["FilesAttributes"] = [_file_entry(entry) for entry in job.files]
return json.dumps(content, indent=2, ensure_ascii=True) + "\n"
def _general_specs(job: JobFile, meta: FileMeta) -> dict[str, object]:
specs: dict[str, object] = {
"ProjectId": {
"Name": meta.project.name,
"GUID": meta.project.guid,
"Revision": meta.project.revision,
},
"Size": {"X": round(job.size[0], 6), "Y": round(job.size[1], 6)},
"LayerNumber": job.conductors,
}
if job.thickness is not None:
specs["BoardThickness"] = round(job.thickness, 6)
return specs
def _stackup_row(row: StackupRow) -> dict[str, object]:
out: dict[str, object] = {"Type": str(row.type)}
optional = (
("Thickness", row.thickness),
("Name", row.name),
("Material", row.material),
("DielectricConstant", row.dielectric_constant),
("LossTangent", row.loss_tangent),
)
for key, value in optional:
if value is not None:
out[key] = round(value, 6) if isinstance(value, float) else value
return out
def _file_entry(entry: FileEntry) -> dict[str, object]:
out: dict[str, object] = {"Path": entry.path}
if entry.function.kind is not FileKind.JOB:
out["FileFunction"] = entry.function.render()
if entry.polarity is not None:
out["FilePolarity"] = str(entry.polarity)
if entry.file_format is not None:
out["FileFormat"] = entry.file_format
return out