Mod5 – 用于MODTRAN 5的Matlab类封装器

下载地址：

derekjgriffith/matlab-modtran-5: Matlab Function Wrapper for MODTRAN 5 (github.com)

简介

MODTRAN (www.modtran.org) 是一个用于计算地球大气中电磁辐射传递的软件代码。通过使用严格格式的输入文本文件来控制MODTRAN。此文件被称为‘tape5’，可能具有.tp5或.ltn的扩展名。手动创建或编辑此文件很不方便，许多MODTRAN的用户都有软件工具来创建和编辑tape5。这些工具包括各种图形用户界面（GUIs），例如Ontar Corporation (www.ontar.com) 的PcModWin和Rese (www.rese.ch)的MODO。

这里描述的Matlab类封装器Mod5不是一个GUI。它提供了一组函数（在面向对象编程术语中称为“方法”），这些函数简化了MODTRAN案例的处理。这些方法包括将tape5文件格式读入Mod5类的“实例”或“对象”中，更改文件中描述的案例实例，将tape5格式写回文件，运行MODTRAN进行案例计算，并将各种结果从MODTRAN输出文件读回Matlab。还提供了许多绘图方法。

Mod5的要求

这个类封装器是为MODTRAN 5.2.0.0编写的，并要求使用Matlab 2009a或更高版本。MODTRAN本身不包括在分发中。MODTRAN可执行文件可以从Ontar Corporation获得。

许可

Mod5类软件处于测试级别，可能仍包含重大错误。使用条件由BSD许可证（The Mathworks公开贡献所使用的标准开源许可证）指定。有关详细信息，请查看下载存档中包含的BSDlicence.txt文件。请向作者(dgriffith@csir.co.za)报告任何错误和问题。

安装

在一个方便的目录中解压缩存档。将目录添加到你的Matlab路径。通过在Matlab编辑器中打开它来探索Mod5Examples脚本文件。

MODTRAN 输入

MODTRAN在tape5中有大量的输入，这些在MODTRAN 5用户手册中有详细描述。该手册可以在线找到，是各种MODTRAN输入意义的权威参考。

对于新用户来说，MODTRAN输入的数量可能令人望而却步。但是，为了运行您的第一个案例，实际上只需要一小部分的输入。

MODTRAN的主要输出（如下所述）是在输入描述的条件下，通过地球大气的视线（LOS或“路径”）的光谱透射率和光谱辐射度。MODTRAN还可以计算大气中某一点的直接正常太阳（或月球）辐照度（DNI）。太阳DNI对于太阳能应用等其他应用很有用。

MODTRAN的主要执行模式如下：

a) 计算LOS光谱传输。

b) 计算不包括散射的短波（太阳/月球）辐射的LOS辐射度。

c) 计算包括散射的短波（太阳/月球）辐射的LOS辐射度。

d) 计算太阳/月球DNI。

MODTRAN的输入（在tape5内）被组织成称为“卡片”的数据行，由于历史原因这样命名。上面提到的执行模式由出现在卡片1上的输入参数IEMSCT指定。

在LOS辐射度模式内，可以选择是否希望包括由来自太阳或月亮的路径辐射度贡献（c），或仅处理热发射部分（b）。还可以指定是否希望只计算单一散射的太阳/月球辐射，或包括多重散射组件。这些额外的组件可能来自地球的表面或大气组件，如气溶胶（在大气中悬浮的固体或液体颗粒）。

示例

使用Mod5封装器的示例可以在下载存档中包含的Matlab脚本文件Mod5Examples.m中找到。每个示例都在脚本文件的一个单元格内给出。通过点击示例并使用标准Matlab编辑器工具栏上的“评估单元格”按钮逐个运行示例。请注意，每个示例都会清除所有工作区变量并关闭所有图形。执行之前请查看示例中的代码。

首次在Mod实例上执行Run方法，即首次调用MODTRAN时，将出现一个对话框，要求您指向您的MODTRAN可执行文件（最好是MOD4v1r1.EXE），无论它安装在您的计算机上的哪个位置。这应该只需要一次，因为类将保存位置。但是，如果您移动MODTRAN或重新安装到另一个位置，您将不得不再次执行此操作。您可以通过调用静态方法明确指向Mod5到MODTRAN可执行文件：

>> Mod5.SetMODTRANExe;

MODTRAN 输出

MODTRAN根据某些输入参数写入多个输出文件，包括以下内容：

tape6

正常的MODTRAN运行总是会产生tape6（或.tp6）输出文件。此文件包含关于运行、大气剖面以及辐射度和透射率结果的大量信息。应检查此文件以确保您的MODTRAN运行如预期那样执行。目前Mod5中没有功能从tape6读取数据。

tape7

tape7（或.tp7）文件仅包含辐射度、透射率或辐照度结果，每次运行一个块，从有关运行的标题信息开始，以值-9999结束。当使用Run方法运行案例时，tape7数据被读回到Mod5实例中，进入一个名为tp7的属性。这是一个结构，具有一组取决于MODTRAN已写入tape7文件的数据的字段。

tape7.scn

tape7.scn（或.7sc）文件（如果MODTRAN写入）包含光谱卷积数据，即其光谱分辨率已降低的数据。此数据将被读回到Mod5实例中，进入一个名为sc7的属性。

channels.out

如果已将光谱通道滤波器附加到案例，则会写入channels.out（或.chn）文件。如果是这样，该文件的内容会被读入名为chn的类属性。

其他MODTRAN输出文件

目前Mod5中没有方法从tape6和clrates（冷却率）读取输出。

Mod5 方法

方法是用于创建和操纵Mod5对象的函数。

构造方法

有两种方法可以创建Mod5实例。这些是从tape5格式文件读取案例（.ltn和.tp5文件遵循此格式）或从头开始创建案例。要从当前目录中的文件读取案例，构造函数方法的调用如下：

>> MyCase = Mod5('AnExistingCase.tp5');

要获取文件选择对话框，请使用空字符串调用构造函数：

>> MyCase = Mod5(' ');

从头开始创建案例，例如在示例2中，首先需要获得一个空的Mod5对象。这是通过调用没有任何参数的构造函数来完成的：

>> MyEmptyCase = Mod5;

一旦你有了一个空白案例，案例实例中的MODTRAN变量可以按照MODTRAN规则进行设置（参见示例2）。

超级案例和子案例

文档经常会提到“子案例”或“超级案例”。一个“超级案例”只是一个包含多个子案例的Mod5对象（即它是一个子案例的向量或矩阵）。当使用Run方法时，Mod5实例中的所有子案例都将在MODTRAN的单次运行中被执行。一个标量的Mod5实例有一个单独的子案例。

可以使用Replicate方法复制一个Mod5实例以创建一个超级案例。不要使用内置的repmat Matlab函数。要创建5个相同子案例的行向量，请使用以下方法：

>> MyReplicatedCase = MyCase.Replicate([1 5]);

一旦你有了子案例的向量，你可以使用标准的Matlab索引为这5个子案例中的每一个更改选定的MODTRAN输入。

也可以使用Extract方法从超级案例中提取子案例的子集，例如以下将提取子案例2和3：

>> MySelectedCase = MyCase.Extract([2 3]);

不要在Mod5对象上使用水平或垂直连接，因为这将导致一个内部索引和IRPT标志错误的超级案例。相反，使用Merge方法。

>> MySuperCase = MyCase1.Merge(MyCase2);

写案例

要写出一个tape5格式的文件，请使用：

>> MyCase.Write('MyCaseFile.tp5');

或者要获取一个文件/保存对话框，简单地：

>> MyCase.Write;

设置MODTRAN参数

MODTRAN的输入参数都可以作为Mod5属性使用。子案例的属性使用标准的Matlab语法进行设置，例如：

>> MyCase(iSubCase).MODTRN = ‘M’; % 设置MODTRAN光谱带模型

为单个子案例设置多个MODTRAN变量，可以使用Set方法在一个函数调用中完成。参见示例3了解此方法的使用。 运行MODTRAN 一旦构建了一个Mod5实例（无论是标量案例还是超级案例），就可以简单地在该案例上运行MODTRAN。

MyCase = MyCase.Run;

Run方法

第一次执行时，Mod5将呈现一个文件选择对话框，您必须选择要使用的MODTRAN可执行文件。Mod5是为MODTRAN 5.2.0开发和测试的。其他版本可能不适用于这个封装器。

如果从命令行运行，MODTRAN会输出一些文本，表示计算的进度。遗憾的是，这些输出在实时内不可用于Matlab。但是，其中的一些文本（至少是最后部分）将被捕获在Mod5属性MODSays中。如果运行似乎已经中止，Run方法会发出一个警告。应检查MODTRAN的tape6（或CaseName.tp6）文件以确定出了什么问题。MODSays输出只附加到超级案例的第一个子案例。

tape5 (.tp5)以及与Mod5实例关联的所有MODTRAN输出文件都将写入与MODTRAN可执行文件位于的同一目录。这可能导致随着时间的推移，该目录中积累了大量的文件。

要将输入(.tp5)和所有输出数据保存到特定目录，请使用以下方法：

>> MyCase.Save(SaveDirectory);

这也将保存一个包含Mod5对象的.mat文件。如果没有指定目录，文件将被移动到使用SetCasePath方法设置的目录。要保存到您当前的工作目录，请使用：

>> MyCase.Save(pwd);

要删除与特定案例关联的MODTRAN可执行目录中创建的文件，请使用Purge方法。

>> MyCase.Purge;

绘制结果

有几种方法可以绘制各种数据项，包括MODTRAN的输出。请参考以下绘图方法：

>> MyCase.PlotTp7 - 绘制可选的MODTRAN tape7输出

>> MyCase.PlotSc7 - 绘制已经卷积的可选的MODTRAN tape7输出

>> MyCase.PlotChn - 绘制通道（.chn）MODTRAN输出 MyCase.PlotAtm - 绘制用户定义的大气数据

还有静态方法可以绘制反照率（lambertian反射）数据和滤波器数据。请参阅下面的相关部分。

帮助

可以使用以下命令获取关于类、属性和方法的更详细的文档：

>> doc Mod5

请注意，doc生成的文档会按字母顺序列出属性（而不是MODTRAN Card的顺序）。所有大写的属性都是MODTRAN的输入。方法列表出现在底部的表格中，带有指向方法帮助文本的超链接。

光谱响应滤波器和通道

在许多应用中，例如地球观测，传感器或相机只对某些波长做出响应。传感器可能对光的相当广泛的光谱波长有反应，但通常对某些波长更敏感。另一方面，原始的MODTRAN结果具有非常高的光谱分辨率。MODTRAN可以计算所谓的“带辐射度”或与可能具有多个光谱通道的相机相关的带平均透射率。示例2说明了传感器光谱响应滤波器（SRF）的创建以及获取MODTRAN为每个滤波器计算的带辐射度。重要的是要区分SRF概念和MODTRAN用来降低透射和辐射度结果的光谱分辨率的卷积（或“狭缝”）仪器函数。在示例中应该可以清楚地看到区别。

通过在SRF上创建小的变化，可以探索相机输出对通道滤波器变化的敏感性。

以下静态方法可用于处理光谱通道滤波器。静态方法是与类关联但不以类实例为输入的方法。静态函数必须使用类的名称作为前缀调用。

Mod5.ReadFlt - 读取MODTRAN .flt光谱滤波器文件

Mod5.CreateFlt – 创建一组合成的光谱滤波器

Mod5.WriteFlt - 输出

MODTRAN .flt滤波器集

Mod5.PlotFlt - 绘制一组MODTRAN光谱通道滤波器

Mod5.ReadFltFromSensorML – 从SensorML文件（传感器标记语言）中提取一组光谱通道定义

从.flt文件中读取的滤波器集，或使用CreateFlt创建的滤波器集可以使用以下方法附加到Mod5实例：

>> MyCase = MyCase.AttachFlt(MyFilter);

这应该足以让MODTRAN执行带计算，当运行MODTRAN时，结果将附加到类实例（在属性‘chn’中）。

警告：

如果可能的话，在运行案例之前附加通道滤波器和反照率数据（参见下一节）应该是最后一件要做的事情。如果在将滤波器数据附加到案例之后使用Replicate, Extract或Merge，可能会出现不正确或意外的结果。

使用反照率数据

MODTRAN可以模拟目标或边界表面的不同lambertian光谱反射（反照率）的效果。这在辐射度案例中使用（IEMSCT = 1 或 2），通过将Card 1上的SURREF属性设置为‘LAMBER’，然后指向MODTRAN的光谱反照率文件（Card 4L1上的属性SALBFL），并使用Card 4L2上的CSALB属性选择文件中包含的反照率曲线。有一些Mod5方法可以处理光谱反照率数据，如下：

Mod5.ReadAlb - 读取MODTRAN格式的光谱反照率文件

Mod5.CreateAlb – 创建光谱反照率曲线

Mod5.WriteAlb - 输出MODTRAN光谱反照率文件

Mod5.PlotAlb - 绘制一组光谱反照率曲线

Mod5.ReadAlbFromASD – 从ASD文本文件读取反照率数据 Mod5.ReadAlbFromUSGS – 从USGS文件读取反照率数据

Mod5.MixAlb - 混合几个反照率得到加权平均值

Mod5.InterpAlb – 将反照率数据插值到其他波长

Mod5.AttachAlb – 将反照率数据附加到子案例

MODTRAN有一个名为MWVSRF的编译时参数，定义了反照率光谱点的最大数量。从外部来源读取反照率数据时，必须注意不要超过这个最大值。通常，MWVSRF = 50，需要重新编译MODTRAN来增加这个最大值。使用InterpAlb函数减少数据中的点数。确保插值完全捕获反照率曲线中的光谱细节。可以通过使用PlotAlb绘制原始数据和减少的数据来完成（参见示例6）。

警告：

如果可能的话，在运行案例之前附加反照率数据和通道滤波器（参见前一节）应该是最后一件要做的事情。如果在将反照率数据附加到案例之后使用Replicate, Extract或Merge，可能会出现不正确或意外的结果。

灵敏度研究

灵敏度研究是MODTRAN的最重要应用之一。例如，您可能希望知道当大气条件发生波动时，辐射传输会发生什么变化。您会设定一系列的MODTRAN运行（一个灵敏度系列），在感兴趣的输入发生变化时比较MODTRAN的结果。

Mod5包括一个叫做CreateSeries的函数，它便于生成此类系列。例如，假设您想知道当您缩放水汽柱（即将所有高度的水汽含量乘以某个因子）时，大气传输会变化多少。假设您还希望了解增加的湿度可能对于由于颗粒增长而产生的气溶胶传输的影响。MODTRAN有一个名为H2OSTR的字符串输入，允许缩放水汽柱，和一个名为H2OAER的标志，用来控制气溶胶是否受到水汽变化的影响。假设您还对10%的水汽减少、10%的增加和20%的增加感兴趣。以下命令将基于名为BaseCase的现有Mod5实例（它必须是标量）创建一个适当的系列。

>> WatVapSeries = BaseCase.CreateSeries('H2OSTR', {'0.9','1.1','1.2'}, … 'H2OAER', {'t', 'f'});

需要注意的是，CreateSeries生成的是输入参数的所有组合。上述示例创建了一个3x2的子案例数组，其中H2OSTR的水汽缩放因子按列变化，而H2OAER标志从第一列的't'变为第二列的'f'。

可以指定超过两个参数，对于每个参数，子案例的矩阵都会增加一个额外的维度。子案例的总数是给定每个参数的值的乘积，所以随着参数和值的增加，子案例的数量迅速增加。

注解

以下是重要的注意事项：

a) 如果某个案例需要特定的卡片，那么必须设置该卡片上的所有参数，即使不使用相关的参数。这是封装器本身的限制，在未来的版本中，希望可以去除这个限制。

b) MODTRAN有大量的输入参数，且对封装器类的全面测试是不可能的。可能仍然存在重大的错误，用户必须对输出结果非常严格。请将您发现的任何错误报告给作者。

c) 封装器仅在Windows XP下的PC上进行了测试。在其他操作系统上，封装器可能无法正常工作。

致谢

CreateFlt方法使用了Jason Brazile编写的srf_generate函数。Meena Lysko、Tami Mudau和其他人协助测试了这个封装器。

如果您发现任何错误或希望做出贡献，请通知作者。 Derek Griffith dgriffith@csir.co.za

给Windows Vista和Windows 7用户的注意事项

Windows Vista和Windows 7对文件权限实施了更严格的控制。默认情况下，MODTRAN 5将安装在Program Files区域的Spectral Sciences目录中。可能需要为Spectral Sciences目录中的相关MODTRAN 5目录（例如，MODTRAN 5.2的32位Windows安装目录Mod5.2.0.0_32）的所有用户提供完全的读/写权限。作为具有管理员权限的用户，右键点击目录，选择属性，然后在安全标签上为所有用户设置完全控制权限。