diff --git a/.gitignore b/.gitignore index 2b97d60..3b167d1 100644 --- a/.gitignore +++ b/.gitignore @@ -48,4 +48,9 @@ Thumbs.db # 其他 *.swp *.*~ -project.lock.json \ No newline at end of file +project.lock.json + +# 文档 +_site/ +_site_pdf/ +api/ diff --git a/api_doc.pdf b/api_doc.pdf new file mode 100644 index 0000000..93e5ea0 Binary files /dev/null and b/api_doc.pdf differ diff --git a/docfx.json b/docfx.json new file mode 100644 index 0000000..73d8816 --- /dev/null +++ b/docfx.json @@ -0,0 +1,63 @@ +{ + "metadata": [ + { + "src": [ + { + "files": [ + "src/**.csproj" + ] + } + ], + "dest": "api", + "disableGitFeatures": false, + "disableDefaultFilter": false + } + ], + "build": { + "content": [ + { + "files": [ + "api/**.yml", + "api/index.md" + ] + }, + { + "files": [ + "docs/**.md", + "docs/**/toc.yml", + "toc.yml", + "*.md" + ] + } + ], + "resource": [ + { + "files": [ + "images/**" + ] + } + ], + "overwrite": [ + { + "files": [ + "apidoc/**.md" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + } + ], + "dest": "_site", + "globalMetadataFiles": [], + "fileMetadataFiles": [], + "template": [ + "default" + ], + "postProcessors": [], + "noLangKeyword": false, + "keepFileLink": false, + "cleanupCacheHistory": false, + "disableGitFeatures": false + } +} \ No newline at end of file diff --git a/docfx.pdf.json b/docfx.pdf.json new file mode 100644 index 0000000..0f59aff --- /dev/null +++ b/docfx.pdf.json @@ -0,0 +1,28 @@ +{ + "pdf": { + "content": [ + { + "files": [ + "api/**.yml", + "docs/usage_examples.md" + ], + "exclude": [ + "**/toc.yml", + "**/toc.md" + ] + } + ], + "name": "AirTransmission-API-Doc", + "title": "大气传输计算库 API 文档", + "coverPage": { + "title": "大气传输计算库", + "author": "田建勇", + "version": "v1.0.0", + "date": "2024年3月" + }, + "wkhtmltopdf": { + "additionalArguments": "--enable-local-file-access" + }, + "outputFolder": "_site_pdf" + } +} \ No newline at end of file diff --git a/docs/custom.css b/docs/custom.css new file mode 100644 index 0000000..3a80fb0 --- /dev/null +++ b/docs/custom.css @@ -0,0 +1,43 @@ +/* 隐藏目录切换按钮 */ +.sideaffix, +.sidetoc, +.toc-filter, +#toc_filter_input, +.toc-toggle, +button[data-toggle="toc"] { + display: none !important; +} + +/* 隐藏导航按钮 */ +.mobile-hide { + display: none !important; +} + +/* 隐藏顶部导航栏 */ +.navbar { + display: none !important; +} + +/* 隐藏面包屑导航 */ +.subnav { + display: none !important; +} + +/* 移除文档内容的左边距 */ +.article { + margin-left: 0 !important; +} + +/* 隐藏页脚 */ +.footer { + display: none !important; +} + +/* 隐藏所有导航相关元素 */ +.nav, +.nav-tabs, +.navigation, +.pull-right, +.toggle-mode { + display: none !important; +} \ No newline at end of file diff --git a/docs/generate_pdf.md b/docs/generate_pdf.md new file mode 100644 index 0000000..7be4526 --- /dev/null +++ b/docs/generate_pdf.md @@ -0,0 +1,145 @@ +# 生成 API 文档 PDF 指南 + +本文档说明如何将 API 文档转换为 PDF 格式。 + +## 前提条件 + +1. 安装 DocFX + + ```bash + dotnet tool install -g docfx + ``` + +2. 安装 wkhtmltopdf +从官方网站下载并安装： + +## 生成步骤 + +1. 首先生成 API 文档的 HTML 文件： + + ```bash + docfx build docfx.json + ``` + + 这会在 `_site` 目录下生成 HTML 文档。 + +2. 使用 wkhtmltopdf 将 HTML 文件转换为 PDF： + + ```bash + wkhtmltopdf --enable-local-file-access \ + _site/api/AirTransmission.html \ + _site/api/AirTransmission.WeatherType.html \ + _site/api/AirTransmission.WeatherCondition.html \ + _site/api/AirTransmission.AtmosphericTransmittanceCalculator.html \ + api_doc.pdf + ``` + +## PDF 格式优化选项 + +如果需要优化 PDF 输出效果，可以添加以下 wkhtmltopdf 参数： + +1. 页面大小和方向： + + ```bash + --page-size A4 --orientation Portrait + ``` + +2. 页边距（单位：毫米）： + + ```bash + --margin-top 20 --margin-bottom 20 --margin-left 20 --margin-right 20 + ``` + +3. 添加页眉页脚： + + ```bash + --header-center "[page]/[topage]" \ + --header-line \ + --footer-center "大气传输计算库 API 文档" \ + --footer-line \ + --footer-spacing 10 \ + --footer-font-size 8 + ``` + +4. 封面和目录： + + ```bash + cover _site/docs/introduction.html \ + toc --toc-header-text "目录" + ``` + +5. 自定义样式： + + ```bash + --user-style-sheet docs/custom.css + ``` + + 自定义样式文件 `custom.css` 的内容： + ```css + /* 隐藏目录切换按钮 */ + .sideaffix { + display: none !important; + } + + /* 隐藏导航按钮 */ + .mobile-hide { + display: none !important; + } + + /* 隐藏顶部导航栏 */ + .navbar { + display: none !important; + } + + /* 隐藏面包屑导航 */ + .subnav { + display: none !important; + } + + /* 移除文档内容的左边距 */ + .article { + margin-left: 0 !important; + } + + /* 隐藏页脚 */ + .footer { + display: none !important; + } + ``` + +完整的优化命令示例： + +```bash +wkhtmltopdf \ + --enable-local-file-access \ + --page-size A4 \ + --orientation Portrait \ + --margin-top 20 \ + --margin-bottom 20 \ + --margin-left 20 \ + --margin-right 20 \ + --header-center "[page]/[topage]" \ + --header-line \ + --footer-center "大气传输计算库 API 文档" \ + --footer-line \ + --footer-spacing 10 \ + --footer-font-size 8 \ + --user-style-sheet docs/custom.css \ + cover _site/docs/introduction.html \ + toc --toc-header-text "目录" \ + _site/docs/usage_examples.html \ + _site/api/AirTransmission.html \ + _site/api/AirTransmission.WeatherType.html \ + _site/api/AirTransmission.WeatherCondition.html \ + _site/api/AirTransmission.AtmosphericTransmittanceCalculator.html \ + api_doc.pdf +``` + +## 注意事项 + +1. 确保所有的 HTML 文件都已经正确生成 +2. 如果遇到路径问题，请使用完整的文件路径 +3. 如果文档包含中文，确保系统安装了相应的中文字体 +4. 生成的 PDF 文件默认保存在当前目录下 +5. 封面页不会显示页眉和页脚 +6. 自定义样式可以隐藏不需要的 HTML 元素 diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000..a7ad935 --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,40 @@ +# 大气传输计算库 + +## 简介 + +大气传输计算库（AirTransmission）是一个用于计算大气传输特性的 .NET 类库。它提供了一系列工具和模型，用于计算不同天气条件下的大气透过率和大气湍流影响。 + +### 主要功能 + +1. 大气透过率计算 + - 支持多种波长范围（紫外、可见光、红外、毫米波） + - 考虑多种天气条件（晴天、多云、雨天等） + - 计算不同传输距离的影响 + +2. 大气湍流模型 + - 计算大气湍流强度 + - 评估湍流对传输的影响 + +3. 天气条件模型 + - 温度、湿度、气压等参数的综合影响 + - 能见度和天气类型的影响 + +### 适用场景 + +- 激光传输系统设计 +- 光电设备性能评估 +- 大气光学研究 +- 气象影响分析 + +### 技术特点 + +- 基于 .NET 8.0 开发 +- 支持跨平台运行 +- 提供 C# 原生支持 +- 通过 C++/CLI 包装器支持 C++ 调用 +- 完整的 API 文档和使用示例 + +### 版本信息 + +- 版本：1.0.0 +- 发布日期：2024年10月 diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 0000000..0fae9eb --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,25 @@ +- name: 使用示例 + href: usage_examples.md +- name: 大气透过率计算器 + href: api/AirTransmission.AtmosphericTransmittanceCalculator.yml +- name: 天气条件 + href: api/AirTransmission.WeatherCondition.yml +- name: 传输模型 + items: + - name: 基础模型 + href: api/AirTransmission.TransmittanceModel.yml + - name: 激光传输模型 + href: api/AirTransmission.LaserTransmittanceModel.yml + - name: 红外传输模型 + href: api/AirTransmission.IRTransmittanceModel.yml + - name: 紫外传输模型 + href: api/AirTransmission.UVTransmittanceModel.yml + - name: 毫米波传输模型 + href: api/AirTransmission.MillimeterWaveTransmittanceModel.yml +- name: 大气湍流模型 + href: api/AirTransmission.AtmosphericTurbulenceModel.yml +- name: API 文档 + href: api/ + homepage: api/AirTransmission.html +- name: PDF 生成指南 + href: generate_pdf.md \ No newline at end of file diff --git a/docs/usage_examples.md b/docs/usage_examples.md new file mode 100644 index 0000000..8a41a32 --- /dev/null +++ b/docs/usage_examples.md @@ -0,0 +1,165 @@ +# 使用示例 + +本文档提供了使用大气传输计算库的 C# 和 C++ 示例代码。 + +## C# 示例 + +### 基本使用 + +```csharp +using AirTransmission; + +// 创建天气条件 +var weather = new WeatherCondition +{ + Temperature = 20, // 温度（摄氏度） + Humidity = 0.65, // 相对湿度（0-1） + Pressure = 101.325, // 大气压力（kPa） + Visibility = 10000, // 能见度（米） + WeatherType = WeatherType.Clear // 天气类型 +}; + +// 创建大气透过率计算器 +var calculator = new AtmosphericTransmittanceCalculator(); + +// 计算激光透过率 +double wavelength = 1.064; // 波长（微米） +double distance = 1000; // 传输距离（米） +double transmittance = calculator.CalculateTransmittance(wavelength, distance, weather); + +Console.WriteLine($"激光透过率: {transmittance:P2}"); +``` + +### 高级用法 + +```csharp +// 计算不同天气条件下的透过率 +var weatherConditions = new[] +{ + new WeatherCondition { WeatherType = WeatherType.Clear, Temperature = 20, Humidity = 0.65 }, + new WeatherCondition { WeatherType = WeatherType.Cloudy, Temperature = 18, Humidity = 0.8 }, + new WeatherCondition { WeatherType = WeatherType.Rain, Temperature = 15, Humidity = 0.95 } +}; + +var calculator = new AtmosphericTransmittanceCalculator(); +double wavelength = 1.064; // 微米 +double distance = 1000; // 米 + +foreach (var weather in weatherConditions) +{ + var transmittance = calculator.CalculateTransmittance(wavelength, distance, weather); + Console.WriteLine($"天气: {weather.WeatherType}, 透过率: {transmittance:P2}"); +} + +// 计算大气湍流影响 +var turbulence = calculator.CalculateAtmosphericTurbulence(wavelength, distance, weather); +Console.WriteLine($"大气湍流强度: {turbulence:E2}"); +``` + +## C++ 调用说明 + +由于 AirTransmission 是 .NET 动态库，C++ 程序需要通过 C++/CLI 包装器来调用。 + +### C++/CLI 包装器使用方法 + +1. 创建包装器项目（由库作者提供）： + + ```cpp + // AirTransmissionWrapper.h + #pragma once + + namespace AirTransmissionWrapper { + public enum class WeatherType { + Clear = 0, + Cloudy = 1, + Rain = 2 + }; + + public ref class WeatherCondition { + public: + property double Temperature; + property double Humidity; + property double Pressure; + property double Visibility; + property WeatherType Type; + }; + + public ref class Calculator { + public: + Calculator(); + double CalculateTransmittance(double wavelength, double distance, WeatherCondition^ weather); + double CalculateAtmosphericTurbulence(double wavelength, double distance, WeatherCondition^ weather); + }; + } + ``` + +2. 在 C++ 代码中使用包装器： + + ```cpp + #include + #include "AirTransmissionWrapper.h" + + int main() { + using namespace AirTransmissionWrapper; + + // 创建天气条件 + WeatherCondition^ weather = gcnew WeatherCondition(); + weather->Temperature = 20.0; // 温度（摄氏度） + weather->Humidity = 0.65; // 相对湿度（0-1） + weather->Pressure = 101.325; // 大气压力（kPa） + weather->Visibility = 10000.0; // 能见度（米） + weather->Type = WeatherType::Clear; + + // 创建计算器 + Calculator^ calculator = gcnew Calculator(); + + // 计算透过率 + double wavelength = 1.064; // 波长（微米） + double distance = 1000.0; // 传输距离（米） + double transmittance = calculator->CalculateTransmittance(wavelength, distance, weather); + + std::cout << "透过率: " << transmittance * 100.0 << "%" << std::endl; + return 0; + } + ``` + +## 项目配置 + +### C# 项目 + +1. 在 Visual Studio 中创建新的 .NET 项目 +2. 通过 NuGet 包管理器添加 AirTransmission 包： + +```bash +dotnet add package AirTransmission +``` + +### C++ 项目 + +1. 在 Visual Studio 中创建新的 C++ 项目 +2. 项目配置： + - 包含目录：添加 AirTransmissionWrapper.h 所在目录 + - 库目录：添加 AirTransmissionWrapper.lib 所在目录 + - 链接器输入：添加 AirTransmissionWrapper.lib +3. 确保以下 DLL 在可执行文件的同一目录下： + - AirTransmissionWrapper.dll + - AirTransmission.dll + +## 注意事项 + +1. 所有浮点数输入都使用 double 类型 +2. 波长单位为微米（μm） +3. 距离单位为米（m） +4. 温度单位为摄氏度（℃） +5. 压力单位为千帕（kPa） +6. 相对湿度范围为 0-1 +7. 确保输入参数在合理范围内： + - 波长：0.2-20 μm + - 距离：> 0 m + - 温度：-40 到 +60 ℃ + - 相对湿度：0-1 + - 压力：80-120 kPa +8. C++ 调用注意事项： + - 使用 `^` 符号声明托管对象 + - 使用 `gcnew` 创建托管对象 + - 包装器类中的所有对象都需要使用托管引用 diff --git a/filterConfig.yml b/filterConfig.yml new file mode 100644 index 0000000..88e7a59 --- /dev/null +++ b/filterConfig.yml @@ -0,0 +1,10 @@ +apiRules: + - include: + uidRegex: ^AirTransmission + type: Namespace + - include: + uidRegex: ^AirTransmission\..* + type: Type + - include: + uidRegex: ^AirTransmission\..* + type: Member \ No newline at end of file diff --git a/log.txt b/log.txt new file mode 100644 index 0000000..e69de29 diff --git a/src/AirTransmission/AirTransmission.xml b/src/AirTransmission/AirTransmission.xml index 5968676..b5ab102 100644 --- a/src/AirTransmission/AirTransmission.xml +++ b/src/AirTransmission/AirTransmission.xml @@ -6,8 +6,16 @@ - 大气透过率计算器 + 大气透过率计算器，提供各种电磁波在大气中传输的透过率计算方法 + + 支持以下电磁波类型的透过率计算： + - 激光（包含湍流效应） + - 红外线 + - 紫外线 + - 毫米波 + 可以处理各种天气条件和烟雾环境 + @@ -96,6 +104,21 @@ 大气湍流模型类，用于计算大气湍流对光传输的影响 + + 主要功能： + - 计算大气折射率结构常数 + - 计算湍流引起的光束抖动 + - 计算闪烁指数 + - 评估湍流对光传输的综合影响 + + + + + 波数常量，单位：m^-1 + + + 基于1.06微米波长（常用的Nd:YAG激光器波长）计算：k = 2π/λ + @@ -168,37 +191,174 @@ - 红外线传输模型类，用于计算红外线在大气中的传输特性 + 红外线透过率计算模型，用于计算红外线在大气中的传输特性 + + 主要功能： + - 计算红外线在不同天气条件下的透过率 + - 使用光谱模型法进行计算 + - 考虑大气分子吸收（主要是水汽和CO2） + - 计算各种天气条件（雨、雪、雾、沙尘）的衰减效应 + + + + + 红外波段最小波长，单位：微米 + + + + + 红外波段最大波长，单位：微米 + + + + + 光谱分段数 + + + + + 主要计算波长，单位：微米 + + + 选择10μm作为主要计算波长，因为这是大气窗口区 + + + + + 计算给定距离的红外线透过率 + + 传输距离，单位：米 + 红外线透过率，范围：0-1 + + 计算过程： + 1. 将光谱分为多个波段 + 2. 对每个波段计算衰减 + 3. 考虑天气条件的影响 + 4. 综合得到最终透过率 + + + + + 计算特定波长的波段衰减 + + 波长，单位：微米 + 波段衰减系数，单位：km^-1 + + 包含三种衰减机制： + - 瑞利散射（Rayleigh散射） + - 米氏散射（Mie散射） + - 分子吸收 + + + + + 计算瑞利散射系数 + + 波长，单位：微米 + 瑞利散射系数，单位：km^-1 + + 使用改进的瑞利散射公式，考虑温度和压力的影响 + + + + + 计算米氏散射系数 + + 波长，单位：微米 + 米氏散射系数，单位：km^-1 + + 基于能见度和气溶胶密度计算米氏散射 + + + + + 计算分子吸收系数 + + 波长，单位：微米 + 分子吸收系数，单位：km^-1 + + 主要考虑水汽和CO2的吸收 + + + + + 获取特定波长的光谱权重 + + 波长，单位：微米 + 光谱权重，范围：0-1 + + 根据黑体辐射理论计算光谱权重 + + + + + 计算天气效应对透过率的影响 + + 传输距离，单位：米 + 天气影响因子，范围：0-1 + + 综合考虑： + - 降水（雨、雪）的影响 + - 雾的衰减效应 + - 沙尘的影响 + - 激光传输模型类，用于计算激光在大气中的传输特性 + 激光透过率计算模型，用于计算激光在大气中的传输特性 + + 主要功能： + - 计算激光在不同天气条件下的透过率 + - 考虑大气湍流效应 + - 处理烟雾对激光传输的影响 + - 计算各种天气条件（雨、雪、雾、沙尘）的衰减效应 + - 激光传输模型类，用于计算激光在大气中的传输特性 + 激光透过率计算模型，用于计算激光在大气中的传输特性 + + 主要功能： + - 计算激光在不同天气条件下的透过率 + - 考虑大气湍流效应 + - 处理烟雾对激光传输的影响 + - 计算各种天气条件（雨、雪、雾、沙尘）的衰减效应 + - 激光波长（微米） + 激光波长常量，单位：微米 + + 默认使用1.06μm波长，对应Nd:YAG激光器的基频输出 + 计算给定距离的激光透过率 - 传输距离（米） - 激光透过率（0到1之间的值） + 传输距离，单位：米 + 激光透过率，范围：0-1 + + 计算过程考虑： + - 分子散射和吸收 + - 气溶胶散射 + - 降水（雨、雪）衰减 + - 雾和沙尘的影响 + 计算考虑湍流效应的激光透过率 - 传输距离（米） - 考虑湍流效应的激光透过率 + 传输距离，单位：米 + 考虑湍流效应后的透过率，范围：0-1 + + 使用大气湍流模型计算湍流对激光传输的影响 + @@ -272,26 +432,48 @@ - 毫米波传输模型类，用于计算毫米波在大气中的传输特性 + 毫米波透过率计算模型，用于计算毫米波在大气中的传输特性 + + 主要功能： + - 计算毫米波在不同天气条件下的透过率 + - 考虑大气分子散射和吸收 + - 处理水汽和氧气的吸收 + - 计算各种天气条件（雨、雪、雾、沙尘）的衰减效应 + - 毫米波波长（毫米） + 毫米波波长常量，单位：毫米 + + 默认使用3.19mm波长，对应94GHz频率 + 该频率是毫米波雷达常用工作频率 + 计算给定距离的毫米波透过率 - 传输距离（米） - 毫米波透过率（0到1之间的值） + 传输距离，单位：米 + 毫米波透过率，范围：0-1 + + 计算过程考虑： + - 分子散射和吸收 + - 水汽吸收 + - 氧气吸收 + - 降水（雨、雪）衰减 + - 雾和沙尘的影响 + 计算分子散射系数 - 分子散射系数（km^-1） + 分子散射系数，单位：km^-1 + + 使用修正的瑞利散射公式，考虑温度和压力的影响 + @@ -326,38 +508,58 @@ - 大气透过率模型的抽象基类，提供了各种大气条件下的透过率计算方法 + 大气透过率计算的基础模型类，提供了各种大气条件下的透过率计算方法 + + 包含以下主要衰减机制的计算： + - 分子散射和吸收 + - 气溶胶散射和吸收 + - 降水（雨、雪）衰减 + - 沙尘和雾的衰减 + - 大气透过率模型的抽象基类，提供了各种大气条件下的透过率计算方法 + 大气透过率计算的基础模型类，提供了各种大气条件下的透过率计算方法 + + 包含以下主要衰减机制的计算： + - 分子散射和吸收 + - 气溶胶散射和吸收 + - 降水（雨、雪）衰减 + - 沙尘和雾的衰减 + - 标准大气透过率 + 标准大气透过率常量 + + 在标准大气条件下（23km能见度，1013.25hPa气压，20℃温度）的透过率值 + - 标准能见度（公里） + 标准能见度常量，单位：千米 - 标准气溶胶密度（粒子/立方厘米） + 标准气溶胶密度常量，单位：粒子/立方厘米 - 当前天气条件 + 当前天气条件对象 - 温度（开尔文） + 温度，单位：开尔文 + + 由摄氏度转换而来：K = ℃ + 273.15 + @@ -487,18 +689,92 @@ - 紫外线传输模型类，用于计算紫外线在大气中的传输特性 + 紫外线透过率计算模型，用于计算紫外线在大气中的传输特性 + + 主要功能： + - 计算紫外线在不同天气条件下的透过率 + - 使用光谱模型法进行计算 + - 考虑臭氧层吸收 + - 计算各种天气条件（雨、雪、雾、沙尘）的衰减效应 + + + + + 紫外波段最小波长，单位：微米 + + + + + 紫外波段最大波长，单位：微米 + + + + + 光谱分段数 + + + + + 主要计算波长，单位：微米 + + + 选择0.308μm作为主要计算波长，这是XeCl准分子激光器的输出波长 + + + + + 计算给定距离的紫外线透过率 + + 传输距离，单位：米 + 紫外线透过率，范围：0-1 + + 计算过程： + 1. 将光谱分为多个波段 + 2. 对每个波段计算衰减 + 3. 考虑天气条件的影响 + 4. 综合得到最终透过率 + - 天气条件类 + 天气条件类，用于描述大气传输计算所需的天气参数 + + 包含以下主要天气参数： + - 天气类型（晴天、雨天、雪天等） + - 温度 + - 相对湿度 + - 能见度 + - 降水量 + - CO2浓度 + + 天气类型 + 温度（摄氏度） + 相对湿度（百分比） + 能见度（公里） + 降水量（毫米/小时），可选 + 二氧化碳浓度（ppm），默认415ppm - 天气条件类 + 天气条件类，用于描述大气传输计算所需的天气参数 + + 包含以下主要天气参数： + - 天气类型（晴天、雨天、雪天等） + - 温度 + - 相对湿度 + - 能见度 + - 降水量 + - CO2浓度 + + 天气类型 + 温度（摄氏度） + 相对湿度（百分比） + 能见度（公里） + 降水量（毫米/小时），可选 + 二氧化碳浓度（ppm），默认415ppm @@ -534,12 +810,41 @@ 打印天气信息 - 天气条件 + 天气条件对象 + + 输出格式： + 天气类型: [类型], 温度: [温度]°C, 相对湿度: [湿度]%, 能见度: [能见度]km, 降水量: [降水量]mm/h + 天气类型枚举 + + + 晴朗天气 + + + + + 雨天 + + + + + 雪天 + + + + + 雾天 + + + + + 沙尘天气 + + diff --git a/src/AirTransmission/AtmosphericTransmittanceCalculator.cs b/src/AirTransmission/AtmosphericTransmittanceCalculator.cs index c8ec098..3da905d 100644 --- a/src/AirTransmission/AtmosphericTransmittanceCalculator.cs +++ b/src/AirTransmission/AtmosphericTransmittanceCalculator.cs @@ -7,8 +7,16 @@ namespace AirTransmission { /// - /// 大气透过率计算器 + /// 大气透过率计算器，提供各种电磁波在大气中传输的透过率计算方法 /// + /// + /// 支持以下电磁波类型的透过率计算： + /// - 激光（包含湍流效应） + /// - 红外线 + /// - 紫外线 + /// - 毫米波 + /// 可以处理各种天气条件和烟雾环境 + /// public static class AtmosphericTransmittanceCalculator { /// diff --git a/src/AirTransmission/AtmosphericTurbulenceModel.cs b/src/AirTransmission/AtmosphericTurbulenceModel.cs index ba624a0..05ec0a0 100644 --- a/src/AirTransmission/AtmosphericTurbulenceModel.cs +++ b/src/AirTransmission/AtmosphericTurbulenceModel.cs @@ -9,9 +9,21 @@ namespace AirTransmission /// /// 大气湍流模型类，用于计算大气湍流对光传输的影响 /// + /// + /// 主要功能： + /// - 计算大气折射率结构常数 + /// - 计算湍流引起的光束抖动 + /// - 计算闪烁指数 + /// - 评估湍流对光传输的综合影响 + /// internal class AtmosphericTurbulenceModel { - // 波数，假设波长为1.06微米（常用的激光波长） + /// + /// 波数常量，单位：m^-1 + /// + /// + /// 基于1.06微米波长（常用的Nd:YAG激光器波长）计算：k = 2π/λ + /// private const double k = 2 * Math.PI / 1.06e-6; /// diff --git a/src/AirTransmission/IRTransmittanceModel.cs b/src/AirTransmission/IRTransmittanceModel.cs index 0afe64c..bd072e5 100644 --- a/src/AirTransmission/IRTransmittanceModel.cs +++ b/src/AirTransmission/IRTransmittanceModel.cs @@ -7,18 +7,51 @@ namespace AirTransmission { /// - /// 红外线传输模型类，用于计算红外线在大气中的传输特性 + /// 红外线透过率计算模型，用于计算红外线在大气中的传输特性 /// + /// + /// 主要功能： + /// - 计算红外线在不同天气条件下的透过率 + /// - 使用光谱模型法进行计算 + /// - 考虑大气分子吸收（主要是水汽和CO2） + /// - 计算各种天气条件（雨、雪、雾、沙尘）的衰减效应 + /// internal class IRTransmittanceModel : TransmittanceModel { - // 光谱分段参数 + /// + /// 红外波段最小波长，单位：微米 + /// private const double MIN_WAVELENGTH = 3.0; // 红外波段最小波长（微米） + /// + /// 红外波段最大波长，单位：微米 + /// private const double MAX_WAVELENGTH = 12.0; // 红外波段最大波长（微米） + /// + /// 光谱分段数 + /// private const int SPECTRAL_BANDS = 100; // 光谱分段数 + /// + /// 主要计算波长，单位：微米 + /// + /// + /// 选择10μm作为主要计算波长，因为这是大气窗口区 + /// private const double IR_WAVELENGTH = 10.0; // 主要计算波长（微米） public IRTransmittanceModel(WeatherCondition weather) : base(weather) { } + /// + /// 计算给定距离的红外线透过率 + /// + /// 传输距离，单位：米 + /// 红外线透过率，范围：0-1 + /// + /// 计算过程： + /// 1. 将光谱分为多个波段 + /// 2. 对每个波段计算衰减 + /// 3. 考虑天气条件的影响 + /// 4. 综合得到最终透过率 + /// public override double CalculateTransmittance(double distance) { // 将距离转换为千米 @@ -47,6 +80,17 @@ namespace AirTransmission return Math.Max(0, Math.Min(1, finalTransmittance)); } + /// + /// 计算特定波长的波段衰减 + /// + /// 波长，单位：微米 + /// 波段衰减系数，单位：km^-1 + /// + /// 包含三种衰减机制： + /// - 瑞利散射（Rayleigh散射） + /// - 米氏散射（Mie散射） + /// - 分子吸收 + /// private double CalculateBandAttenuation(double wavelength) { // 进一步增加衰减系数 @@ -57,6 +101,14 @@ namespace AirTransmission return rayleighScattering + mieScattering + molecularAbsorption; } + /// + /// 计算瑞利散射系数 + /// + /// 波长，单位：微米 + /// 瑞利散射系数，单位：km^-1 + /// + /// 使用改进的瑞利散射公式，考虑温度和压力的影响 + /// private double CalculateRayleighScattering(double wavelength) { // Rayleigh散射系数计算（km^-1） @@ -65,6 +117,14 @@ namespace AirTransmission return 0.02735 * Math.Pow(wavelengthMicrons, -4.08) * (Pressure / 1013.25) * (288.15 / Temperature); } + /// + /// 计算米氏散射系数 + /// + /// 波长，单位：微米 + /// 米氏散射系数，单位：km^-1 + /// + /// 基于能见度和气溶胶密度计算米氏散射 + /// private double CalculateMieScattering(double wavelength) { // Mie散射系数计算（km^-1） @@ -74,6 +134,14 @@ namespace AirTransmission return beta * alpha * (AerosolDensity / STANDARD_AEROSOL_DENSITY) * 3.5; // 从2.0改为3.5 } + /// + /// 计算分子吸收系数 + /// + /// 波长，单位：微米 + /// 分子吸收系数，单位：km^-1 + /// + /// 主要考虑水汽和CO2的吸收 + /// private double CalculateMolecularAbsorption(double wavelength) { // 分子吸收系数计算（km^-1） @@ -123,7 +191,15 @@ namespace AirTransmission return 0.16 * (CO2Concentration / 400.0); // 从0.08改为0.16 } - private double GetSpectralWeight(double wavelength) + /// + /// 获取特定波长的光谱权重 + /// + /// 波长，单位：微米 + /// 光谱权重，范围：0-1 + /// + /// 根据黑体辐射理论计算光谱权重 + /// + private static double GetSpectralWeight(double wavelength) { // 调整权重分布 if (wavelength >= 3.0 && wavelength <= 5.0) @@ -134,6 +210,17 @@ namespace AirTransmission return 0.2; // 从0.3改为0.2 } + /// + /// 计算天气效应对透过率的影响 + /// + /// 传输距离，单位：米 + /// 天气影响因子，范围：0-1 + /// + /// 综合考虑： + /// - 降水（雨、雪）的影响 + /// - 雾的衰减效应 + /// - 沙尘的影响 + /// private double CalculateWeatherEffect(double distance) { // 降低天气效应的影响 diff --git a/src/AirTransmission/LaserTransmittanceModel.cs b/src/AirTransmission/LaserTransmittanceModel.cs index 97d12d7..0614af2 100644 --- a/src/AirTransmission/LaserTransmittanceModel.cs +++ b/src/AirTransmission/LaserTransmittanceModel.cs @@ -7,20 +7,37 @@ namespace AirTransmission { /// - /// 激光传输模型类，用于计算激光在大气中的传输特性 + /// 激光透过率计算模型，用于计算激光在大气中的传输特性 /// + /// + /// 主要功能： + /// - 计算激光在不同天气条件下的透过率 + /// - 考虑大气湍流效应 + /// - 处理烟雾对激光传输的影响 + /// - 计算各种天气条件（雨、雪、雾、沙尘）的衰减效应 + /// internal class LaserTransmittanceModel(WeatherCondition weather) : TransmittanceModel(weather) { /// - /// 激光波长（微米） + /// 激光波长常量，单位：微米 /// + /// + /// 默认使用1.06μm波长，对应Nd:YAG激光器的基频输出 + /// private const double LASER_WAVELENGTH = 1.06; /// /// 计算给定距离的激光透过率 /// - /// 传输距离（米） - /// 激光透过率（0到1之间的值） + /// 传输距离，单位：米 + /// 激光透过率，范围：0-1 + /// + /// 计算过程考虑： + /// - 分子散射和吸收 + /// - 气溶胶散射 + /// - 降水（雨、雪）衰减 + /// - 雾和沙尘的影响 + /// public override double CalculateTransmittance(double distance) { double attenuationFactor = CalculateAttenuationFactor(); @@ -41,8 +58,11 @@ namespace AirTransmission /// /// 计算考虑湍流效应的激光透过率 /// - /// 传输距离（米） - /// 考虑湍流效应的激光透过率 + /// 传输距离，单位：米 + /// 考虑湍流效应后的透过率，范围：0-1 + /// + /// 使用大气湍流模型计算湍流对激光传输的影响 + /// public double CalculateTransmittanceWithTurbulence(double distance) { double transmittance = CalculateTransmittance(distance); diff --git a/src/AirTransmission/MillimeterWaveTransmittanceModel.cs b/src/AirTransmission/MillimeterWaveTransmittanceModel.cs index 412cfd9..506c26b 100644 --- a/src/AirTransmission/MillimeterWaveTransmittanceModel.cs +++ b/src/AirTransmission/MillimeterWaveTransmittanceModel.cs @@ -7,13 +7,24 @@ namespace AirTransmission { /// - /// 毫米波传输模型类，用于计算毫米波在大气中的传输特性 + /// 毫米波透过率计算模型，用于计算毫米波在大气中的传输特性 /// + /// + /// 主要功能： + /// - 计算毫米波在不同天气条件下的透过率 + /// - 考虑大气分子散射和吸收 + /// - 处理水汽和氧气的吸收 + /// - 计算各种天气条件（雨、雪、雾、沙尘）的衰减效应 + /// internal class MillimeterWaveTransmittanceModel : TransmittanceModel { /// - /// 毫米波波长（毫米） + /// 毫米波波长常量，单位：毫米 /// + /// + /// 默认使用3.19mm波长，对应94GHz频率 + /// 该频率是毫米波雷达常用工作频率 + /// private const double MILLIMETER_WAVE_WAVELENGTH = 3.19; // 毫米（对应94 GHz） public MillimeterWaveTransmittanceModel(WeatherCondition weather) : base(weather) { } @@ -21,8 +32,16 @@ namespace AirTransmission /// /// 计算给定距离的毫米波透过率 /// - /// 传输距离（米） - /// 毫米波透过率（0到1之间的值） + /// 传输距离，单位：米 + /// 毫米波透过率，范围：0-1 + /// + /// 计算过程考虑： + /// - 分子散射和吸收 + /// - 水汽吸收 + /// - 氧气吸收 + /// - 降水（雨、雪）衰减 + /// - 雾和沙尘的影响 + /// public override double CalculateTransmittance(double distance) { // 计算各种衰减机制 @@ -49,7 +68,10 @@ namespace AirTransmission /// /// 计算分子散射系数 /// - /// 分子散射系数（km^-1） + /// 分子散射系数，单位：km^-1 + /// + /// 使用修正的瑞利散射公式，考虑温度和压力的影响 + /// private double CalculateMolecularScattering() { // 分子散射系数计算（km^-1） diff --git a/src/AirTransmission/TransmittanceModel.cs b/src/AirTransmission/TransmittanceModel.cs index d4e20e9..e85c836 100644 --- a/src/AirTransmission/TransmittanceModel.cs +++ b/src/AirTransmission/TransmittanceModel.cs @@ -7,33 +7,44 @@ namespace AirTransmission { /// - /// 大气透过率模型的抽象基类，提供了各种大气条件下的透过率计算方法 + /// 大气透过率计算的基础模型类，提供了各种大气条件下的透过率计算方法 /// + /// + /// 包含以下主要衰减机制的计算： + /// - 分子散射和吸收 + /// - 气溶胶散射和吸收 + /// - 降水（雨、雪）衰减 + /// - 沙尘和雾的衰减 + /// internal abstract class TransmittanceModel(WeatherCondition weather) { - // 常量 /// - /// 标准大气透过率 + /// 标准大气透过率常量 /// + /// + /// 在标准大气条件下（23km能见度，1013.25hPa气压，20℃温度）的透过率值 + /// protected const double STANDARD_TRANSMITTANCE = 0.975; // 标准大气透过率 /// - /// 标准能见度（公里） + /// 标准能见度常量，单位：千米 /// protected const double STANDARD_VISIBILITY = 23.0; // 标准能见度 (km) /// - /// 标准气溶胶密度（粒子/立方厘米） + /// 标准气溶胶密度常量，单位：粒子/立方厘米 /// protected const double STANDARD_AEROSOL_DENSITY = 100.0; // 标准气溶胶密度 (particles/cm³) - /// - /// 当前天气条件 + /// 当前天气条件对象 /// protected WeatherCondition weatherCondition = weather; // 大气模型参数 /// - /// 温度（开尔文） + /// 温度，单位：开尔文 /// + /// + /// 由摄氏度转换而来：K = ℃ + 273.15 + /// protected double Temperature { get; set; } = weather.Temperature + 273.15; /// /// 大气压力（百帕） diff --git a/src/AirTransmission/UVTransmittanceModel.cs b/src/AirTransmission/UVTransmittanceModel.cs index 4785002..254dc99 100644 --- a/src/AirTransmission/UVTransmittanceModel.cs +++ b/src/AirTransmission/UVTransmittanceModel.cs @@ -7,18 +7,54 @@ namespace AirTransmission { /// - /// 紫外线传输模型类，用于计算紫外线在大气中的传输特性 + /// 紫外线透过率计算模型，用于计算紫外线在大气中的传输特性 /// + /// + /// 主要功能： + /// - 计算紫外线在不同天气条件下的透过率 + /// - 使用光谱模型法进行计算 + /// - 考虑臭氧层吸收 + /// - 计算各种天气条件（雨、雪、雾、沙尘）的衰减效应 + /// internal class UVTransmittanceModel : TransmittanceModel { - // 光谱分段参数 + /// + /// 紫外波段最小波长，单位：微米 + /// private const double MIN_WAVELENGTH = 0.2; // 紫外波段最小波长（微米） + + /// + /// 紫外波段最大波长，单位：微米 + /// private const double MAX_WAVELENGTH = 0.4; // 紫外波段最大波长（微米） + + /// + /// 光谱分段数 + /// private const int SPECTRAL_BANDS = 100; // 光谱分段数 + + /// + /// 主要计算波长，单位：微米 + /// + /// + /// 选择0.308μm作为主要计算波长，这是XeCl准分子激光器的输出波长 + /// private const double UV_WAVELENGTH = 0.308; // 主要计算波长（微米） public UVTransmittanceModel(WeatherCondition weather) : base(weather) { } + /// + /// 计算给定距离的紫外线透过率 + /// + /// 传输距离，单位：米 + /// 紫外线透过率，范围：0-1 + /// + /// 计算过程： + /// 1. 将光谱分为多个波段 + /// 2. 对每个波段计算衰减 + /// 3. 考虑天气条件的影响 + /// 4. 综合得到最终透过率 + /// public override double CalculateTransmittance(double distance) { // 将距离转换为千米 diff --git a/src/AirTransmission/WeatherCondition.cs b/src/AirTransmission/WeatherCondition.cs index 415f91a..d64ac1b 100644 --- a/src/AirTransmission/WeatherCondition.cs +++ b/src/AirTransmission/WeatherCondition.cs @@ -3,8 +3,23 @@ using System; namespace AirTransmission { /// - /// 天气条件类 + /// 天气条件类，用于描述大气传输计算所需的天气参数 /// + /// + /// 包含以下主要天气参数： + /// - 天气类型（晴天、雨天、雪天等） + /// - 温度 + /// - 相对湿度 + /// - 能见度 + /// - 降水量 + /// - CO2浓度 + /// + /// 天气类型 + /// 温度（摄氏度） + /// 相对湿度（百分比） + /// 能见度（公里） + /// 降水量（毫米/小时），可选 + /// 二氧化碳浓度（ppm），默认415ppm public class WeatherCondition(WeatherType type, double temperature, double relativeHumidity, double visibility, double? precipitation = null, double co2Concentration = 415) { /// @@ -35,7 +50,11 @@ namespace AirTransmission /// /// 打印天气信息 /// - /// 天气条件 + /// 天气条件对象 + /// + /// 输出格式： + /// 天气类型: [类型], 温度: [温度]°C, 相对湿度: [湿度]%, 能见度: [能见度]km, 降水量: [降水量]mm/h + /// public static void PrintWeatherInfo(WeatherCondition weather){ Console.WriteLine($"---天气类型: {weather.Type}, 温度: {weather.Temperature}°C, 相对湿度: {weather.RelativeHumidity}%, 能见度: {weather.Visibility}km, 降水量: {weather.Precipitation ?? 0}mm/h"); } @@ -46,10 +65,25 @@ namespace AirTransmission /// public enum WeatherType { + /// + /// 晴朗天气 + /// 晴天, // 晴朗天气 + /// + /// 雨天 + /// 雨天, // 雨天 + /// + /// 雪天 + /// 雪天, // 雪天 + /// + /// 雾天 + /// 雾天, // 雾天 + /// + /// 沙尘天气 + /// 沙尘 // 沙尘 } } \ No newline at end of file diff --git a/src/AirTransmissionConsole/Program.cs b/src/AirTransmissionConsole/Program.cs index 4751819..d96df44 100644 --- a/src/AirTransmissionConsole/Program.cs +++ b/src/AirTransmissionConsole/Program.cs @@ -1,9 +1,4 @@ -/* - * 版本历史： - * 1.0.0 (2024-10-13): 初始版本，实现基本的大气透过率计算和测试功能。作者：田建勇 - */ - -using AirTransmission; +using AirTransmission; class Program { diff --git a/toc.yml b/toc.yml new file mode 100644 index 0000000..aa5f299 --- /dev/null +++ b/toc.yml @@ -0,0 +1,2 @@ +- name: API 文档 + href: docs/ \ No newline at end of file