Halcon C#.net 编程指导(3): 元组(Tuples)的使用

1. 使用单个值或元组调用函数

你可以从参考手册（refrence manual）里查看算子是否可以处理元组（tuples）。例如下面列出了AreaCenter和GenRectangle1算子的说明。

static void HOperatorSet.AreaCenter (HObject regions, out HTuple area, out HTuple row,out HTuple column)   //方法的声明
HTuple HRegion.AreaCenter (out HTuple row, out HTuple column)
int HRegion.AreaCenter (out double row, out double column)

regions (input_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . region(-array) ; HRegion
area (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .integer(-array) ; HTuple (int)
row (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . point.y(-array) ; HTuple (double)
column (output_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . point.x(-array) ; HTuple (double)

static void HOperatorSet.GenRectangle1 (out HObject rectangle, HTuple row1, HTuple column1,HTuple row2, HTuple column2)
public HRegion (HTuple row1, HTuple column1, HTuple row2, HTuple column2)
public HRegion (double row1, double column1, double row2, double column2)
void HRegion.GenRectangle1 (HTuple row1, HTuple column1, HTuple row2, HTuple column2)
void HRegion.GenRectangle1 (double row1, double column1, double row2, double column2)

rectangle (output_object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . region(-array) ; HRegion
row1 (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.origin.y(-array) ; HTuple (double)
column1 (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.origin.x(-array) ; HTuple (double)
row2 (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.corner.y(-array) ; HTuple (double)
column2 (input_control) . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle.corner.x(-array) ; HTuple (doubl)

我们可以看到像HRegion这样的图形类（iconic classes）自动处理多个值；这个参数是否可以接受或者返回多个值？我们不可以直接在函数体（signature）里看到，但是我们可以从参数部分看到：我们可以从第一个例子看出一个附加的appended（-array）标志着参数可以包含一个或者多个值。

我们还可以看出，控制参数（control）通过他们的数据类型直接显示了他们是否可以包含一个活或者多个值（HTuple类型），在第一个GenRectangle1例子中，参数使用基础的double数据类型，在第二个GenRectangle1例子中使用HALCON/.NET的HTuple类。因此，你可以使用两种方法通过HRegion调用GenRectangle1，通过传doules和HTuples值（这里使用构造函数的形式）：

HRegion SingleRegion = new HRegion(10.0, 10.0, 50.0, 50.0);
HRegion MultipleRegions = new HRegion(new HTuple(20.0, 30.0), new HTuple(20.0, 30.0),new HTuple(60.0, 70.0), new HTuple(60.0, 70.0));

同样，AreaCenter也可以通过两种方法调用：

double Area, Row, Column;
HTuple Areas, Rows, Columns;
Area = SingleRegion.AreaCenter(out Row, out Column);
Areas = MultipleRegions.AreaCenter(out Rows, out Columns);

2. 图形元组（Iconic Tuples）

图形类HImage，HRegion和HXLD可以包含一个或者多个类（objects）。为了处理所有的元组的元素，首先我们就要使用CountOBj算子查询元素的个数

int NumRegions = MultipleRegions.CountObj();

然后访问这些元素，在HALCON里使用SelectOBj，在C#中使用[]:

for (int i=1; i<=NumRegions; i++)
{
HRegion Region = MultipleRegions[i];
...
}

值得我们注意的是图形元组元素下标从1开始！

如果你想创建或者增加图形元组中的元素的话可以使用ConcatOBj算子(HALCON中)：

HRegion ThreeRegions = SingleRegion.ConcatObj(MultipleRegions);

3. 控制元组与HTuple类（Control Tuples and the Class HTuple）

3.1 访问元组元素

为了控制元组，HALCON/.NET 提供了HTuple类。HTuple的实例既可以只包含double，int，string类型的元素。也可以包含它们的混合元素。那么怎样访问元组元素呢？

为了访问其中所有的元组，第一步就是通过Length属性获得它的长度，和图形元组获得的方式基本相同

int TupleLength = Areas.Length;

访问方式：

for (int i=0; i<TupleLength; i++)

{

double Element = Areas[i];

...

}

如果你视图读取一个不存在的元组元素或者如果你不转换（cast）类型直接赋值给其他类型的元素或出现异常（exception）。

3.2 创建Tuples 

类HTuple提供许多不同的构造器（见VS的对象浏览器列表）。下面的语句是创建一个只有单元素的int型的元组。

Htuple Tuple1 = new HTuple(1);

下面的语句创建一个double型的元组(tuple)：

 HTuple Tuple2 = new HTuple(1.0);

也可以对构造器传送多个值。但是注意如果传送的值里有int类型的值，也有double类型的值，默认创建的是double类型的元组。

HTuple Tuple3 = new Htuple(1.0,2);

当创建的元组中包含字符创string类型时，就创建了一个混合类型的tuple，下面的语句中第二个值是int类型的：

HTuple Tuple4 = new HTuple(1.0, 2, “s”);

一个元组或者一个元组元素的类型可以通过它的属性类型获得：

HTupleTypleTupleType = Tuple4.Type;

HTupleTypeTupleElementType = Tuple4[1].Type;

你可以通过一个构造器简单的进行元组的连接：

HTupleTuple5 = new HTuple(Tuple2, Tuple3);

还可以往元组里没有值的元素中通过追加一个值：

Tuple3[2]= 3;

3.3 类型转换中模棱两可，意想不到的结果

类HTuplet提供许多隐式的转换方法，你可以在大部分的地方直接使用在基础的数据类型上。例如：

double Element = Areas[i];

自动转换元素类型，实际上是把一个HTuple Element类转换成了double类型。相似的，基础类型可以自动转换成HTuple实例。类型转换的缺点是编译器往往不能确定你想用基础的数据类型还是算子的元组版本,结果就会报错。例如，你使用下面的语句，其中的数值既可以理解为从int转换成double，也可以理 解为从int转换成HTuple：

HRegion SingleRegion = new HRegion(10,10,50,50);

你可以通过在数据后面添加.0来解决这个争议。

HRegion SingleRegion = new HRegion(10.0,10.0,50.0,50.0);

例子Matching包含其它两种情况的歧义，都是由于基础数据类型和HTuple类型参数在同一个函数中调用。第一种情况是通过明确地把double类型参数转换（casting）成HTuple实例：

              private double Row, Column;

       HTuple RowCheck, ColumnCheck, AngleCheck, Score;

       HHomMat2D Matrix = new HHomMat2D();

Matrix.VectorAngleToRigid(new HTuple(Row), new HTuple(Column), new HTuple(0.0),RowCheck,ColumnCheck, AngleCheck);

第二种情况，HTuple实例（只包含一个数值）通过HTuple的D属性明确地转换成double类型，这个方法返回HTuple中第一个元素值为double类型（事实上，这是tuple[0].D的简写）：

       private double RectPhi, RectLength1, RectLength2;

       HTuple Rect1RowCheck, Rect1ColCheck;

       Rectangle1.GenRectangle2(Rect1RowCheck.D,Rect1ColCheck.D, RectPhi+ AngleCheck.D,RectLength1, RectLength2);

通过相似的属性转换，你可以把tuple类型转换成其他的基础类型。如果你试图转换成一个“错误”的类型，将会出现exception。

和输入参数相比，输出参数不可以自动转换类型。有时，这会导致意想不到的结果。在下面的代码中，doubles被用来作为输出参数类型，但是返回值是区域元组类型。

  HRegion MultipleRegions = new HRegion(new HTuple(20.0, 30.0), new HTuple(20.0, 30.0),newHTuple(60.0, 70.0), new HTuple(60.0, 70.0));

 double Area, Row, Column;

 HTuple Areas, Rows, Columns;

Area =MultipleRegions.AreaCenter(out Row, out Column);

因此，只有第一个区域的面积和中心被返回。如果这输出参数仍然是doubles类型，你把返回值赋给HTuple类型得到的结果一样。

              Areas =MultipleRegions.AreaCenter(out Row, out Column);

       相比之下，如果输出参数是HTuple类型，并且返回值赋值给一个double类型，算子会返回所有区域的中心，但是只有第一个区域的面积。

              Area =MultipleRegions.AreaCenter(out Rows, out Columns);

3.4  处理元组的HALCON算子

       HALCON提供了许多处理元组的算子，可以在算子参考手册（reference_hdevelop）中Tuple章节中找到。在HDevelopUser’s Guide中第七张256页有这些算子的简介。HDevelop中相应的函数名字代替了算子的名字，它省略了Tuple并且使用小写字母，例如rad代替了TupleRad。

3.5  操作符重载

       对于基础的算术算子，HAlCON/.NET提供算子重载。例如，算子+自动调用HALCON算子TupleAdd.