Environment: Ambient Temperature / Coolant

Ambient Temperature and Coolant are the two leaves of the Equipment page's Environment root (/equipment?tree=equipment/background/environment-temperature, /equipment?tree=equipment/background/coolant — the root's id equipment/background and the routes spell it background behind the Environment label). Environment is one of the page's roots beside Mechanism, Spindle Capability and Controller, built — like Spindle Capability — only while the Preference menu's Show Physics Options is on; an equipment/coolant link resolves onto the Coolant leaf through migrateLegacyTreeId. They are tree items rather than a page, so the /equipment/background-coolant path redirects onto the Environment root. Both leaves are served by one panel component, which branches on the selected node's role path.

They edit the thermal condition on the project's authored equipment face, SetupEquipment, reached as SetupEquipment:

AmbientTemperature_C (Ambient leaf)
the whole CoolantHeatCondition (Coolant leaf) — file-first, see below

Key Model: SetupEquipment (+ its CoolantHeatCondition).

Layout

Environment root — equipment/background, item type Group: the group's intro (the thermal boundary conditions of the cut) and a clickable list of the two leaves below, each row selecting its leaf.
Ambient Temperature leaf — equipment/background/environment-temperature, item type ThermalCondition
- Ambient Temperature NumberField (°C) — AmbientTemperature_C.
Coolant leaf — equipment/background/coolant, the same item type and the same panel (file pick on top, properties below, as on the workpiece material leaf)
- “Not attached” badge — rendered only while the snapshot reports no condition: the zero-filled no-equipment DTO, and the instant before the first fetch resolves; a well-formed loaded project always carries one (see the note below), and the badge's tooltip says so.
- File row — FilePathInput (.CoolantHeatCondition, resource subfolder CoolantHeatCondition): a Select dropdown button whose menu holds Browse…, Browse Resource… and — only while a file is set — Clear, beside a read-only path input whose placeholder reads that no coolant file is set and the condition is saved inline; it loads a saved condition by named root. A Save As… button follows it, prompting for a project-relative file to export the current condition to. Tracked in CoolantHeatConditionFile. The three standard cooling types ship as ready-made files in HiNc-Resource (Resource/CoolantHeatCondition/StandardForcedAir.default.CoolantHeatCondition, StandardOilBasedCoolant.default.CoolantHeatCondition and StandardWaterSolubleCoolant.default.CoolantHeatCondition), so Browse Resource… starts populated like the workpiece-material picker — picking a shipped file is the cooling-type selection.
- Name / Note — read-only mirror of the loaded condition.
- Property fields (always visible, under Name / Note):
  - Coolant Temperature (°C) — CoolantTemperature_C.
  - Flood Convection Coefficient (W/(m²·K)) — CoolantConvectionCoefficient_Wdm2K, min: 0.
  - Mist / Flood Ratio — MistFloodConvectionRatio, min: 0.
  - Off (Air) Convection Coefficient (W/(m²·K)) — OffConvectionCoefficient_Wdm2K, min: 0.
Both leaves, with no project open: every editable control is disabled and a “no project — open one first” caption is shown. The panel fetches the snapshot itself on mount and gates on its hasEquipment flag, so the tree host holds no state for either leaf.

Behavior

File-based conditions (WorkpieceMaterial pattern). Picking a .CoolantHeatCondition file installs it as the whole condition (XFactory.GenByFile); Save As… exports the current values and renames the condition after the file (IPreferredFileName). While CoolantHeatConditionFile is set, the project save externalizes the condition as <CoolantHeatCondition><XmlSource>relPath</XmlSource></CoolantHeatCondition> and regenerates the side-file (a pick from outside the project is copied into it the moment it is loaded); with no file the bare inline shape is kept byte-compatible. Coefficient edits tune this project's copy. The static presets on CoolantHeatCondition (StandardPresets: StandardForcedAir, StandardWaterSolubleCoolant, StandardOilBasedCoolant) are the API-side source the shipped files are authored from; the instance methods MatchStandardPreset and ApplyPreset match a condition against them and copy one in place.
The file row's Clear entry untracks the file. FilePathInput reports a clear by emitting update:modelValue(null); the panel answers with POST /untrack, which drops CoolantHeatConditionFile and keeps the condition and its values, so the next project save writes the condition inline (the legacy bare shape) instead of to the side-file. Name / Note and the four fields do not change; only the path row empties. Loading another file or a Save As tracks a file again.
A user save sheds the .default marker from its suggestion and its name. The shipped resource files carry a .default ownership marker in their names. The Save As… prompt strips it from its prefill, and the controller strips it from the name it stamps on the condition, so neither the suggested file name nor the saved condition's name carries the marker; a path typed with the marker is still written as typed.
On a well-formed project the “not attached” badge is unreachable, and the lazy creation behind it never fires. SetupEquipment initializes CoolantHeatCondition at its declaration, and the project-XML read replaces the instance only when the element is present — it yields null only for a side-file whose root element is another type — so the controller's hasCoolant, which is a null test on that property, is true whenever a well-formed project is open. The badge is therefore rendered only in the no-equipment case the panel already covers with its own caption, and the fallback each scalar PUT carries (a default condition in place of a null) is defensive. What a fresh project actually carries is the class defaults, which are the water-soluble preset's values.
Celsius is the wire format. CoolantHeatCondition stores Kelvin internally but exposes _C accessors that handle the conversion, and the DTO carries Celsius.
Finite values only. Every field handler drops a null or non-finite entry before any request is made, so Infinity never reaches these endpoints even though the numeric widget can parse it. Ambient and coolant temperatures accept negatives (e.g. -40 °C for cryogenic coolant); the three convection fields carry min: 0, so a negative entry shows a “Must be ≥ 0” error and is never committed.
The run sees it at once. The ambient-temperature write, all four condition scalars and the file load each end in the project service's ForwardSetupEnvironmentToExecution, which stamps the ambient temperature and the condition reference onto the runtime equipment face.

Source Code Path

See HiNC App Anatomy for git repository links.

Web Application

HiNC-2025-webservice (Quasar CLI SPA):

wwwroot-src/src/components/controlTree/ThermalConditionPanel.vue — the one panel both leaves share, branching on the node's last role-path segment: Ambient Temperature renders the single temperature field, Coolant the not-attached badge, the file row, the read-only Name / Note and the four property fields.
wwwroot-src/src/components/controlTree/GroupInfoPanel.vue — the Environment root's panel: the group intro and the clickable child list.
wwwroot-src/src/components/controlTree/useControlTreeHost.ts — declares the two ThermalCondition leaves (equipment/background/environment-temperature and equipment/background/coolant) under the Environment Group root, with no host-level init state, and returns that root only while Show Physics Options is on.
wwwroot-src/src/components/controlTree/itemTypes.ts — registers the ThermalCondition item type against that panel: no child tree, no geometry-cache chain.
wwwroot-src/src/components/widgets/FilePathInput.vue — the file row widget: Browse… / Browse Resource… (opening at the CoolantHeatCondition resource subfolder) / Clear.
wwwroot-src/src/components/widgets/NumericInput.vue — the numeric field used by every value on both leaves, and the source of the min: 0 check on the three convection fields (an entry below the minimum is flagged on blur and not emitted).
wwwroot-src/src/api/backgroundCoolant.ts — typed client for /api/mech/background-coolant/*: the flat snapshot, the load / save-as pair, untrack, and the five scalar PUTs.
wwwroot-src/src/router/routes.ts — carries the equipment/background-coolant redirect, which lands on equipment?tree=equipment/background.
Mech/BackgroundCoolantController.cs — REST surface at /api/mech/background-coolant over the authored equipment face (the route, the PUT path and the snapshot field spell it background on the wire, while the C# member behind them is AmbientTemperature_C):
- GET / — flat snapshot { hasEquipment, backgroundTemperature_C, hasCoolant, coolantTemperature_C, coolantConvectionCoefficient_Wdm2K, mistFloodConvectionRatio, offConvectionCoefficient_Wdm2K, coolantName, coolantNote, coolantHeatConditionFile }.
- POST /untrack — no body: drop the side-file reference only; the condition and its values stay and are saved inline again. Returns { success, name, note, relFile: "" }.
- POST /load, POST /save-as — { rootName, relFile }: install a .CoolantHeatCondition file / export the current condition. Both resolve the path under the named root and refuse anything that escapes it, and both record the result in CoolantHeatConditionFile as a project-relative path: a file outside the project is first written into it — a shipped resource under its resource-relative path, any other file under its own name — and referenced there (Common/ProjectFileRef.cs). Save-as appends the extension when it is missing and renames the condition after the file (IPreferredFileName) with the .default marker stripped.
- PUT /background-temperature-c — set AmbientTemperature_C.
- PUT /coolant-temperature-c, PUT /coolant-convection-coefficient-wdm2k, PUT /mist-flood-convection-ratio, PUT /off-convection-coefficient-wdm2k — the four condition scalars, all through one helper that writes the equipment's live condition (its null guard is unreachable from a well-formed project) and forwards to the runtime face.

HiAPI Engine

HiMech/Physics/CoolantHeatCondition.cs — the model: Kelvin storage with _C accessors, the flood / mist-ratio / off convection coefficients, Name and Note with PreferredFileName, the static StandardPresets (StandardForcedAir / StandardWaterSolubleCoolant / StandardOilBasedCoolant) behind the shipped resource files, and the MatchStandardPreset / ApplyPreset instance helpers over them.
HiMech/Machining/MachiningEquipmentUtils/SetupEquipment.cs — the authored equipment face that owns the ambient temperature, the condition and its file reference, and externalizes the condition to the side-file when that reference is set.