// ===============================================================
// helper function: given a solid, find a planar 
//Extrusion实体，给一个实体，给一个方向，找到与此方向一致的面。
// face with the given normal (version 2)
// this is a slightly enhaced version of the previous 
// version and checks if the face is on the given reference plane.
// ===============================================================
PlanarFace findFace(Application app, Extrusion pBox, XYZ normal, ReferencePlane refPlane)
{
    // get the geometry object of the given element
    //
    Options op = new Options();
    op.ComputeReferences = true;
    GeometryObjectArray geomObjs = pBox.get_Geometry(op).Objects;

    // loop through the array and find a face with the given normal
    //
    foreach (GeometryObject geomObj in geomObjs)
    {
        if (geomObj is Solid)  // solid is what we are interested in.
        {
            Solid pSolid = geomObj as Solid;
            FaceArray faces = pSolid.Faces;
            foreach (Face pFace in faces)
            {
                PlanarFace pPlanarFace = (PlanarFace)pFace;
                // check to see if they have same normal
                //face.Normal是面的向量。IsAlmostEqualTo();
                if ((pPlanarFace != null) && pPlanarFace.Normal.IsAlmostEqualTo(normal))
                {
                    // additionally, we want to check if the face is on the reference plane
                    //还要判断面是否在参考平面上。
                    XYZ p0 = refPlane.BubbleEnd;//终点?
                    XYZ p1 = refPlane.FreeEnd;//起点?
                    Line pCurve = app.Create.NewLineBound(p0, p1);
                    if (pPlanarFace.Intersect(pCurve) == SetComparisonResult.Subset)//子集
                    {
                        return pPlanarFace; // we found the face
                    }
                }
            }
        }

        // will come back later as needed.
        //
        //else if (geomObj is Instance)
        //{
        //}
        //else if (geomObj is Curve)
        //{
        //}
        //else if (geomObj is Mesh)
        //{
        //}
    }

    // if we come here, we did not find any.
    return null;
}