plane.H

Go to the documentation of this file.

/*---------------------------------------------------------------------------*\
  =========                 |
  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   \\    /   O peration     |
    \\  /    A nd           | www.openfoam.com
     \\/     M anipulation  |
-------------------------------------------------------------------------------
    Copyright (C) 2011-2016 OpenFOAM Foundation
    Copyright (C) 2017-2022 OpenCFD Ltd.
-------------------------------------------------------------------------------
License
    This file is part of OpenFOAM.

    OpenFOAM is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
    for more details.

    You should have received a copy of the GNU General Public License
    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.

Class
    Foam::plane

Description
    Geometric class that creates a 3D plane and can return the intersection
    point between a line and the plane.

    Construction from a dictionary is driven by the \c planeType.
    If \c planeType is missing, \c pointAndNormal is used and the
    \c pointAndNormalDict becomes optional.

    For \c planeType as \c pointAndNormal :
    \verbatim
    pointAndNormalDict
    {
        point   <point>;   // basePoint (1612 and earlier)
        normal  <vector>;  // normalVector (1612 and earlier)
    }
    \endverbatim

    For \c planeType as \c embeddedPoints :
    \verbatim
    embeddedPointsDict
    {
        point1  <point>;
        point2  <point>;
        point3  <point>;
    }
    \endverbatim

    For \c planeType with \c planeEquation coefficients
    \f$ ax + by + cz + d = 0 \f$ :

    \verbatim
    planeEquationDict
    {
       a   <scalar>;
       b   <scalar>;
       c   <scalar>;
       d   <scalar>;
    }
    \endverbatim

SourceFiles
    planeI.H
    plane.C

\*---------------------------------------------------------------------------*/

#ifndef Foam_plane_H
#define Foam_plane_H

#include "point.H"
#include "scalarList.H"
#include "line.H"

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

namespace Foam
{

// Forward Declarations
class dictionary;

/*---------------------------------------------------------------------------*\
                            Class plane Declaration
\*---------------------------------------------------------------------------*/

class plane
{
public:

    // Public Data Types

        //- Side of the plane
        enum side
        {
            FRONT = 1,  
            BACK  = -1, 
            NORMAL = FRONT,   
            FLIP   = BACK     
        };


    // Public Classes

        //- A reference point and direction
        class ray
        {
            point  point_;
            vector dir_;

        public:

            //- Construct from reference point and direction
            ray(const point& p, const vector& dir)
            :
                point_(p),
                dir_(dir)
            {}

            //- Return the reference point
            const point& refPoint() const noexcept { return point_; }

            //- Return the direction
            const vector& dir() const noexcept { return dir_; }
        };


private:

    // Private Data

        //- The unit normal of the plane
        vector normal_;

        //- The origin or reference point for the plane
        point origin_;


    // Private Member Functions

        //- Normalise normal_ and emit error if its mag is less than VSMALL
        //  Optionally pass as test only, without normalisation.
        void makeUnitNormal
        (
            const char * const caller,
            const bool notTest = true
        );

        //- Calculates point and normal given plane coefficients.
        void calcFromCoeffs
        (
            const scalar a,
            const scalar b,
            const scalar c,
            const scalar d,
            const char * const caller
        );

        //- Calculates point and normal vector given three points
        //- Normal vector determined using right hand rule
        void calcFromEmbeddedPoints
        (
            const point& point1,
            const point& point2,
            const point& point3,
            const char * const caller
        );


public:

    // Constructors

        //- Construct zero-initialised.
        inline plane();

        //- Construct from normal vector through the origin.
        //  The vector is normalised to a unit vector on input.
        explicit plane(const vector& normalVector);

        //- Construct from normal vector and point in plane.
        //  By default, the vector is normalised to a unit vector on input.
        plane
        (
            const point& originPoint,
            const vector& normalVector,
            const bool doNormalise = true
        );

        //- Construct from three points in plane
        plane
        (
            const point& point1,
            const point& point2,
            const point& point3
        );

        //- Construct from coefficients for the plane equation:
        //- ax + by + cz + d = 0
        explicit plane(const UList<scalar>& coeffs);

        //- Construct from coefficients for the plane equation:
        //- ax + by + cz + d = 0
        explicit plane(const FixedList<scalar,4>& coeffs);

        //- Construct from dictionary
        explicit plane(const dictionary& dict);

        //- Construct from Istream. Assumes (normal) (origin) input.
        explicit plane(Istream& is);


    // Member Functions

        //- The plane unit normal
        inline const vector& normal() const noexcept;

        //- The plane base point
        inline const point& origin() const noexcept;

        //- The plane base point, for modification
        inline point& origin() noexcept;

        //- Flip the plane by reversing the normal
        inline void flip();

        //- Return coefficients for the plane equation:
        //- ax + by + cz + d = 0
        FixedList<scalar, 4> planeCoeffs() const;

        //- Return nearest point in the plane for the given point
        inline point nearestPoint(const point& p) const;

        //- Return distance (magnitude) from the given point to the plane
        inline scalar distance(const point& p) const;

        //- Return distance from the given point to the plane
        inline scalar signedDistance(const point& p) const;

        //- Return cut coefficient for plane and line defined by
        //- origin and direction
        scalar normalIntersect(const point& pnt0, const vector& dir) const;

        //- Return cut coefficient for plane and ray
        scalar normalIntersect(const ray& r) const
        {
            return normalIntersect(r.refPoint(), r.dir());
        }

        //- Return the cutting point between the plane and
        //- a line passing through the supplied points
        template<class PointType, class PointRef>
        scalar lineIntersect(const line<PointType, PointRef>& l) const
        {
            return normalIntersect(l.start(), l.vec());
        }

        //- Return the cutting line between this plane and another.
        //  Returned as direction vector and point line goes through.
        ray planeIntersect(const plane& plane2) const;

        //- Return the cutting point between this plane and two other planes
        point planePlaneIntersect
        (
            const plane& plane2,
            const plane& plane3
        )
        const;

        //- Return a point somewhere on the plane, a distance from the base
        point somePointInPlane(const scalar dist = 1e-3) const;

        //- Return the side of the plane that the point is on.
        //  If the point is on the plane, then returns FRONT.
        //  \return
        //  - +1 (FRONT): above or on plane (front-side)
        //  - -1 (BACK):  below plane (back-side)
        inline side whichSide(const point& p) const;

        //- The sign for the side of the plane that the point is on.
        //  Uses the supplied tolerance for rounding around zero.
        //  \return
        //  -  0: on plane
        //  - +1 (FRONT): above plane (front-side)
        //  - -1 (BACK):  below plane (back-side)
        inline int sign(const point& p, const scalar tol = SMALL) const;

        //- Mirror the supplied point in the plane. Return the mirrored point.
        point mirror(const point& p) const;

        //- Write to dictionary
        void writeDict(Ostream& os) const;


    // Housekeeping

        //- The plane base point (same as origin)
        const point& refPoint() const noexcept { return origin_; }

        //- Same as whichSide()
        side sideOfPlane(const point& p) const { return whichSide(p); }
};


// * * * * * * * * * * * * * * * IOstream Operators  * * * * * * * * * * * * //

//- Write plane normal, origin
Ostream& operator<<(Ostream& os, const plane& pln);


// * * * * * * * * * * * * * * * Global Operators  * * * * * * * * * * * * * //

//- Test for equality of origin and normal
inline bool operator==(const plane& a, const plane& b);

//- Test for inequality of origin or normal
inline bool operator!=(const plane& a, const plane& b);

//- Compare origin
inline bool operator<(const plane& a, const plane& b);


// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

} // End namespace Foam

#include "planeI.H"

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

#endif

// ************************************************************************* //