HiNC-2025-win-desktop-Deploy/App/wwwroot/HiAPI-docsite/anatomy/general-setup/background-coolant.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
      <title>Environment: Ambient Temperature / Coolant | HiAPI-C# 2025 </title>
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta name="title" content="Environment: Ambient Temperature / Coolant | HiAPI-C# 2025 ">
      
      
      <link rel="icon" href="../../img/HiAPI.favicon.ico">
      <link rel="stylesheet" href="../../public/docfx.min.css">
      <link rel="stylesheet" href="../../public/main.css">
      <meta name="docfx:navrel" content="../../toc.html">
      <meta name="docfx:tocrel" content="toc.html">
      
      <meta name="docfx:rel" content="../../">
      
      
      
      <meta name="loc:inThisArticle" content="In this article">
      <meta name="loc:searchResultsCount" content="{count} results for &quot;{query}&quot;">
      <meta name="loc:searchNoResults" content="No results for &quot;{query}&quot;">
      <meta name="loc:tocFilter" content="Filter by title">
      <meta name="loc:nextArticle" content="Next">
      <meta name="loc:prevArticle" content="Previous">
      <meta name="loc:themeLight" content="Light">
      <meta name="loc:themeDark" content="Dark">
      <meta name="loc:themeAuto" content="Auto">
      <meta name="loc:changeTheme" content="Change theme">
      <meta name="loc:copy" content="Copy">
      <meta name="loc:downloadPdf" content="Download PDF">

      <script type="module" src="./../../public/docfx.min.js"></script>

      <script>
        const theme = localStorage.getItem('theme') || 'auto'
        document.documentElement.setAttribute('data-bs-theme', theme === 'auto' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : theme)
      </script>

  </head>

  <body class="tex2jax_ignore" data-layout="" data-yaml-mime="">
    <header class="bg-body border-bottom">
      <nav id="autocollapse" class="navbar navbar-expand-md" role="navigation">
        <div class="container-xxl flex-nowrap">
          <a class="navbar-brand" href="../../index.html">
            <img id="logo" class="svg" src="../../img/HiAPI.logo.png" alt="">
            
          </a>
          <button class="btn btn-lg d-md-none border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navpanel" aria-controls="navpanel" aria-expanded="false" aria-label="Toggle navigation">
            <i class="bi bi-three-dots"></i>
          </button>
          <div class="collapse navbar-collapse" id="navpanel">
            <div id="navbar">
              <form class="search" role="search" id="search">
                <i class="bi bi-search"></i>
                <input class="form-control" id="search-query" type="search" disabled placeholder="Search" autocomplete="off" aria-label="Search">
              </form>
            </div>
          </div>
        </div>
      </nav>
    </header>

    <main class="container-xxl">
      <div class="toc-offcanvas">
        <div class="offcanvas-md offcanvas-start" tabindex="-1" id="tocOffcanvas" aria-labelledby="tocOffcanvasLabel">
          <div class="offcanvas-header">
            <h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
            <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#tocOffcanvas" aria-label="Close"></button>
          </div>
          <div class="offcanvas-body">
            <nav class="toc" id="toc"></nav>
          </div>
        </div>
      </div>

      <div class="content">
        <div class="actionbar">
          <button class="btn btn-lg border-0 d-md-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#tocOffcanvas" aria-controls="tocOffcanvas" aria-expanded="false" aria-label="Show table of contents">
            <i class="bi bi-list"></i>
          </button>

          <nav id="breadcrumb"></nav>
        </div>

        <article data-uid="Anatomy-BackgroundCoolant">
          <h1 id="environment-ambient-temperature--coolant">Environment: Ambient Temperature / Coolant</h1>

<p>Ambient Temperature and Coolant are the two leaves of the General Setup page's <strong>Environment</strong> root
(<code>/general-setup?tree=equipment/background/environment-temperature</code>,
<code>/general-setup?tree=equipment/background/coolant</code> — the root's id <code>equipment/background</code> and the
routes keep the legacy <code>background</code> spelling; since 2026-09-15 Environment is one of the page's four
roots beside Mechanism, Spindle Capability and Controller, and the pre-regroup <code>equipment/coolant</code> id
migrates). They are tree items rather than a page, so the older <code>/equipment/background-coolant</code> path
redirects onto the Environment root. Both leaves are served by one panel component, which branches
on the selected node's role path.</p>
<p>They edit the thermal condition on the project's authored equipment face,
<a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html">SetupEquipment</a>, reached as
<a class="xref" href="../../api/Hi.MachiningProcs.LocalProjectService.html#Hi_MachiningProcs_LocalProjectService_SetupEquipment">SetupEquipment</a>:</p>
<ul>
<li><a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_AmbientTemperature_C">AmbientTemperature_C</a> (Ambient
leaf)</li>
<li>the whole <a class="xref" href="../../api/Hi.Physics.CoolantHeatCondition.html">CoolantHeatCondition</a> (Coolant leaf) — file-first, see below</li>
</ul>
<p>Key Model: <a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html">SetupEquipment</a> (+ its
<a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_CoolantHeatCondition">CoolantHeatCondition</a>).</p>
<h2 id="layout">Layout</h2>
<ul>
<li>Ambient Temperature leaf — <code>equipment/background/environment-temperature</code>, item type <code>ThermalCondition</code>
<ul>
<li>Ambient Temperature NumberField (°C) —
<a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_AmbientTemperature_C">AmbientTemperature_C</a>.</li>
</ul>
</li>
<li>Coolant leaf — <code>equipment/coolant</code>, the same item type and the same panel (file pick on top,
properties below, as on the workpiece material leaf)
<ul>
<li>&ldquo;Not attached&rdquo; badge — visible until the first coolant-related save (see <em>Lazy
CoolantHeatCondition creation</em> below).</li>
<li><strong>File row</strong> — <code>FilePathInput</code> (<code>.CoolantHeatCondition</code>, resource subfolder
<code>CoolantHeatCondition</code>): a <strong>Select</strong> dropdown button whose menu holds <strong>Browse&hellip;</strong>,
<strong>Browse Resource&hellip;</strong> and — only while a file is set — <strong>Clear</strong>, beside a read-only path
input; it loads a saved condition by named root. A <strong>Save As&hellip;</strong> button follows it, prompting
for a project-relative file to export the current condition to. Tracked in
<a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_CoolantHeatConditionFile">CoolantHeatConditionFile</a>. The three
standard cooling types ship as ready-made files in <code>HiNc-Resource</code>
(<code>Resource/CoolantHeatCondition/StandardForcedAir.default.CoolantHeatCondition</code>,
<code>StandardOilBasedCoolant.default.CoolantHeatCondition</code> and
<code>StandardWaterSolubleCoolant.default.CoolantHeatCondition</code>), so <strong>Browse Resource&hellip;</strong> starts
populated like the workpiece-material picker — picking a shipped file <em>is</em> the cooling-type
selection.</li>
<li>Name / Note — read-only mirror of the loaded condition.</li>
<li>Property fields (always visible, under Name / Note):
<ul>
<li>Coolant Temperature (°C) — <code>CoolantTemperature_C</code>.</li>
<li>Flood Convection Coefficient (W/(m²·K)) — <code>CoolantConvectionCoefficient_Wdm2K</code>, <code>min: 0</code>.</li>
<li>Mist / Flood Ratio — <code>MistFloodConvectionRatio</code>, <code>min: 0</code>.</li>
<li>Off (Air) Convection Coefficient (W/(m²·K)) — <code>OffConvectionCoefficient_Wdm2K</code>, <code>min: 0</code>.</li>
</ul>
</li>
</ul>
</li>
<li>Both leaves, with no project open: every control is disabled and a &ldquo;no project — open one first&rdquo;
caption is shown. The panel fetches the snapshot itself on mount and gates on its <code>hasEquipment</code>
flag, so the tree host holds no state for either leaf.</li>
</ul>
<h2 id="behavior">Behavior</h2>
<ul>
<li><strong>File-based conditions (WorkpieceMaterial pattern).</strong> Picking a <code>.CoolantHeatCondition</code> file
installs it as the whole condition (<code>XFactory.GenByFile</code>); <strong>Save As&hellip;</strong> exports the current
values and renames the condition after the file (<code>IPreferredFileName</code>). While
<a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_CoolantHeatConditionFile">CoolantHeatConditionFile</a> is set, the
project save externalizes the condition as
<code>&lt;CoolantHeatCondition&gt;&lt;XmlSource&gt;relPath&lt;/XmlSource&gt;&lt;/CoolantHeatCondition&gt;</code> and regenerates the
side-file (a resource pick is copied into the project on save); with no file the bare inline shape
is kept byte-compatible. Coefficient edits tune <em>this project's</em> copy. The static presets on
<a class="xref" href="../../api/Hi.Physics.CoolantHeatCondition.html">CoolantHeatCondition</a> (<code>StandardPresets</code> / <code>ApplyPreset</code> /
<code>MatchStandardPreset</code>) are the API-side source the shipped files are authored from.</li>
<li><strong>The file row's Clear entry does nothing here.</strong> <code>FilePathInput</code> reports a clear by emitting
<code>update:modelValue(null)</code>, and this panel binds the widget's value one-way and listens only for
<code>picked</code> — so the entry is rendered, is clickable while a file is set, and drops nothing. Clearing
the tracked file is therefore not reachable from this leaf at all; the reference changes only by
loading another file or by a Save As.</li>
<li><strong>The <code>.default</code> marker never survives a user save.</strong> The shipped resource files carry a
<code>.default</code> ownership marker in their names. The Save As&hellip; prompt strips it from its prefill, and
the controller strips it again from the name it stamps on the condition, so a user save cannot
mint a file that masquerades as a shipped default.</li>
<li><strong>The &ldquo;not attached&rdquo; badge is unreachable, and the lazy creation behind it never fires.</strong>
<a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html">SetupEquipment</a> initializes
<a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_CoolantHeatCondition">CoolantHeatCondition</a> at its declaration
and nothing assigns null to it — the project-XML read replaces the instance only when the element
is present — so the controller's <code>hasCoolant</code>, which is a null test on that property, is true
whenever a project is open. The badge is therefore rendered only in the no-equipment case the
panel already covers with its own caption, and the null branch each scalar PUT carries is
defensive rather than reached. What a fresh project actually carries is the class defaults, which
are the water-soluble preset's values.</li>
<li><strong>Celsius is the wire format.</strong> <a class="xref" href="../../api/Hi.Physics.CoolantHeatCondition.html">CoolantHeatCondition</a> stores Kelvin internally
but exposes <code>_C</code> accessors that handle the conversion, and the DTO carries Celsius.</li>
<li><strong>Finite values only.</strong> Every field handler drops a null or non-finite entry before any request is
made, so <code>Infinity</code> 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 are clamped to <code>min: 0</code>.</li>
<li><strong>The run sees it at once.</strong> 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 — including
the lazily created condition, which otherwise would exist only on the authored side.</li>
</ul>
<h2 id="source-code-path">Source Code Path</h2>
<p>See <a class="xref" href="../index.html">HiNC App Anatomy</a> for git repository links.</p>
<h3 id="web-application">Web Application</h3>
<p>HiNC-2025-webservice (Quasar CLI SPA):</p>
<ul>
<li><code>wwwroot-src/src/components/controlTree/ThermalConditionPanel.vue</code> — 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.</li>
<li><code>wwwroot-src/src/components/controlTree/useControlTreeHost.ts</code> — declares the two
<code>ThermalCondition</code> leaves (<code>equipment/background</code>, <code>equipment/coolant</code>) under the General Setup
group, with no host-level init state.</li>
<li><code>wwwroot-src/src/components/controlTree/itemTypes.ts</code> — registers the <code>ThermalCondition</code> item type
against that panel: no child tree, no geometry-cache chain.</li>
<li><code>wwwroot-src/src/components/widgets/FilePathInput.vue</code> — the file row widget: Browse&hellip; /
Browse Resource&hellip; (opening at the <code>CoolantHeatCondition</code> resource subfolder) / Clear.</li>
<li><code>wwwroot-src/src/components/widgets/NumericInput.vue</code> — the numeric field used by every value on
both leaves, and the source of the <code>min: 0</code> clamp on the three convection fields.</li>
<li><code>wwwroot-src/src/api/backgroundCoolant.ts</code> — typed client for <code>/api/mech/background-coolant/*</code>:
the flat snapshot, the load / save-as pair, and the five scalar PUTs.</li>
<li><code>wwwroot-src/src/router/routes.ts</code> — carries the <code>equipment/background-coolant</code> redirect, which
lands on <code>general-setup?tree=equipment/background</code>.</li>
<li><code>Mech/BackgroundCoolantController.cs</code> — REST surface at <code>/api/mech/background-coolant</code> over the
authored equipment face (the route, the PUT path and the snapshot field keep their legacy
<code>background</code> wire names; only the C# member behind them is renamed):
<ul>
<li><code>GET /</code> — flat snapshot <code>{ hasEquipment, backgroundTemperature_C, hasCoolant, coolantTemperature_C, coolantConvectionCoefficient_Wdm2K, mistFloodConvectionRatio, offConvectionCoefficient_Wdm2K, coolantName, coolantNote, coolantHeatConditionFile }</code>.</li>
<li><code>POST /load</code>, <code>POST /save-as</code> — <code>{ rootName, relFile }</code>: install a <code>.CoolantHeatCondition</code> 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
<a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_CoolantHeatConditionFile">CoolantHeatConditionFile</a> as a
project-relative path when it lands under the project. Save-as appends the extension when it is
missing and renames the condition after the file (<code>IPreferredFileName</code>) with the <code>.default</code>
marker stripped.</li>
<li><code>PUT /background-temperature-c</code> — set
<a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.SetupEquipment.html#Hi_Machining_MachiningEquipmentUtils_SetupEquipment_AmbientTemperature_C">AmbientTemperature_C</a>.</li>
<li><code>PUT /coolant-temperature-c</code>, <code>PUT /coolant-convection-coefficient-wdm2k</code>,
<code>PUT /mist-flood-convection-ratio</code>, <code>PUT /off-convection-coefficient-wdm2k</code> — the four condition
scalars, all through one helper that lazy-creates the condition when absent, writes it, and
forwards to the runtime face.</li>
</ul>
</li>
</ul>
<h3 id="hiapi-engine">HiAPI Engine</h3>
<ul>
<li><code>HiMech/Physics/CoolantHeatCondition.cs</code> — the model: Kelvin storage with <code>_C</code> accessors, the
flood / mist-ratio / off convection coefficients, Name and Note with <code>PreferredFileName</code>, and the
<code>StandardPresets</code> / <code>ApplyPreset</code> / <code>MatchStandardPreset</code> statics behind the shipped resource
files.</li>
<li><code>HiMech/Machining/MachiningEquipmentUtils/SetupEquipment.cs</code> — 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.</li>
</ul>
<h2 id="see-also">See Also</h2>
<ul>
<li><a class="xref" href="spindle-capability.html">Spindle Capability</a> — sibling equipment editor, editing the same authored equipment face.</li>
<li><a href="../../manual/setup/coolant.html">Coolant (manual)</a> — the end-user task: picking a cooling type in the application.</li>
<li><a class="xref" href="../../technique/milling-physics/coolant-model.html">Coolant Model</a> — what the values on this panel mean, which one a running program applies, and how the condition is stored.</li>
</ul>

</article>

        <div class="contribution d-print-none">
        </div>

        <div class="next-article d-print-none border-top" id="nextArticle"></div>

      </div>

      <div class="affix">
        <nav id="affix"></nav>
      </div>
    </main>

    <div class="container-xxl search-results" id="search-results"></div>

    <footer class="border-top text-secondary">
      <div class="container-xxl">
        <div class="flex-fill">
          <span> Copyright © 2025 <a href='https://superhightech.com.tw'>Tech Coordinate</a>. All rights reserved. <a href='https://superhightech.com.tw'>超級高科技股份有限公司</a> © 2025 版權所有 </span>
        </div>
      </div>
    </footer>
  </body>
</html>