Patchworks Under Wine

This guide documents the supported Linux-through-Wine command path for Patchworks Matrix Builder.

The current known-good day-to-day operator workflow is still native Windows on a workstation that already has a valid local Patchworks installation and system-level licensing configured. Use the Wine path only when you intentionally need the Linux/Wine runtime seam.

Prerequisites

  • A local Patchworks install bundle, including patchworks.jar.

  • A working Wine runtime (wine64 or wine on PATH).

  • Java callable inside Wine context (wine64 cmd /c java -version).

  • A valid ForestModel XML and fragments DBF generated by FEMIC export.

  • UBC VPN connectivity if Patchworks license validation requires campus IP.

  • SPSHOME must point to the Patchworks install root in a Wine-visible Windows path (for example Z:\\...).

  • If patchworks.use_xvfb: true, xvfb-run must be installed on PATH.

Config File

Use config/patchworks.runtime.yaml:

patchworks:
  jar_path: reference/Patchworks/patchworks.jar
  wine_prefix: null
  license_env: SPS_LICENSE_SERVER
  license_value: <sps_user>@auth.spatial.ca
  spshome: Z:\\Program Files\\Spatial Planning Systems\\Patchworks
  use_xvfb: false

matrix_builder:
  fragments_path: output/patchworks_k3z_validated/fragments/fragments.dbf
  output_dir: output/patchworks_k3z_validated/tracks
  forestmodel_xml_path: output/patchworks_k3z_validated/forestmodel.xml
  accounts_exclude_regex: []  # optional regex filters for proto/accounts rows

CLI Workflow

  1. Run preflight checks:

    PYTHONPATH=src python -m femic patchworks preflight --config config/patchworks.runtime.yaml

  2. Launch Matrix Builder directly:

    PYTHONPATH=src python -m femic patchworks matrix-build --config config/patchworks.runtime.yaml

  3. Optional interactive launcher mode:

    PYTHONPATH=src python -m femic patchworks matrix-build \
  --config config/patchworks.runtime.yaml \
  --interactive

Generated Runtime Artifacts

Each run writes:

  • runtime/logs/patchworks_matrixbuilder_stdout-<run_id>.log

  • runtime/logs/patchworks_matrixbuilder_stderr-<run_id>.log

  • runtime/logs/patchworks_matrixbuilder_manifest-<run_id>.json

For non-interactive matrix builds, FEMIC now also promotes tracks/protoaccounts.csv to tracks/accounts.csv when present. If accounts.csv already exists, it is moved to a timestamped backup (accounts_backup_YYYYMMDD_HHMMSS.csv) before replacement. If matrix_builder.accounts_exclude_regex is configured, matching rows are removed during promotion (based on ATTRIBUTE/ACCOUNT) and the manifest captures both the applied patterns and excluded row count.

The manifest includes command string, return code, config paths, and log paths. Matrix runs now fail hard when fatal runtime signatures are detected in process output (for example licensing/native-library failures) or when matrix output artifacts are missing/empty.

Notes

  • Patchworks binaries are proprietary and should remain outside published docs artifacts and repository source control.

  • <sps_user> is a template token, not a literal production value. On known good Windows workstations, prefer the existing system-level SPS_LICENSE_SERVER configuration instead of overriding it in FEMIC runtime config.

  • FEMIC preflight validates environment/config only; Patchworks performs license server checks during launch.

  • When running in headless Linux, set patchworks.use_xvfb: true to wrap Wine invocation in xvfb-run -a.

  • Wine path translation uses the Z: drive mapping (for example /path/to/workspace/... -> Z:\\path\\to\\workspace\\...).