From fb30939e8fc395afb0ebbcbba2fa26a38f1e96d4 Mon Sep 17 00:00:00 2001 From: marioalexis Date: Sun, 12 Jun 2022 15:03:52 -0300 Subject: [PATCH] Base: Improve docstrings in BoundBoxPy.xml --- src/Base/BoundBoxPy.xml | 192 +++++++++++++++++++++++-------------- src/Base/BoundBoxPyImp.cpp | 49 +++++----- 2 files changed, 144 insertions(+), 97 deletions(-) diff --git a/src/Base/BoundBoxPy.xml b/src/Base/BoundBoxPy.xml index 2dd7417d75..a7244eabb4 100644 --- a/src/Base/BoundBoxPy.xml +++ b/src/Base/BoundBoxPy.xml @@ -14,196 +14,244 @@ This is the BoundBox export class - Bound box class -A bounding box is an orthographic cube which is a way to describe outer boundaries. -You get a bounding box from a lot of 3D types. It is often used to check if a 3D -entity lies in the range of another object. Checking for bounding interference first -can save a lot of computing time! - -Constructor: -App.BoundBox([Xmin,Ymin,Zmin,Xmax,Ymax,Zmax]) -App.BoundBox(Tuple, Tuple) -App.BoundBox(Vector, Vector) -App.BoundBox(BoundBox) - + Base.BoundBox class.\n +This class represents a bounding box. +A bounding box is a rectangular cuboid which is a way to describe outer +boundaries and is obtained from a lot of 3D types. +It is often used to check if a 3D entity lies in the range of another object. +Checking for bounding interference first can save a lot of computing time! +An invalid BoundBox is represented by inconsistent values at each direction: +The maximum float value of the system at the minimum coordinates, and the +opposite value at the maximum coordinates.\n +The following constructors are supported:\n +BoundBox() +Empty constructor. Returns an invalid BoundBox.\n +BoundBox(boundBox) +Copy constructor. +boundBox : Base.BoundBox\n +BoundBox(xMin, yMin=0, zMin=0, xMax=0, yMax=0, zMax=0) +Define from the minimum and maximum values at each direction. +xMin : float\n Minimum value at x-coordinate. +yMin : float\n Minimum value at y-coordinate. +zMin : float\n Minimum value at z-coordinate. +xMax : float\n Maximum value at x-coordinate. +yMax : float\n Maximum value at y-coordinate. +zMax : float\n Maximum value at z-coordinate.\n +App.BoundBox(min, max) +Define from two containers representing the minimum and maximum values of the +coordinates in each direction. +min : Base.Vector, tuple\n Minimum values of the coordinates. +max : Base.Vector, tuple\n Maximum values of the coordinates. - method setVoid() -Invalidate the bounding box + setVoid() -> None\n +Invalidate the bounding box. - method isValid() -Checks if the bounding box is valid + isValid() -> bool\n +Checks if the bounding box is valid. - method add(BoundBox) -Add (enlarge) the given BoundBox + add(minMax) -> None +add(x, y, z) -> None\n +Increase the maximum values or decrease the minimum values of this BoundBox by +replacing the current values with the given values, so the bounding box can grow +but not shrink.\n +minMax : Base.Vector, tuple\n Values to enlarge at each direction. +x : float\n Value to enlarge at x-direction. +y : float\n Value to enlarge at y-direction. +z : float\n Value to enlarge at z-direction. - method getPoint(Int) -Get the point of the given index. The index must be in the range of [0,7] - + getPoint(index) ->Base.Vector\n +Get the point of the given index. +The index must be in the range of [0, 7].\n +index : int - method getEdge(Int) -Get the edge points of the given index. The index must be in the range of [0,11] - + getEdge(index) -> tuple of Base.Vector\n +Get the edge points of the given index. +The index must be in the range of [0, 11].\n +index : int - method closestPoint(Vector) -Get the closest point of the bounding box to the given point - + closestPoint(point) -> Base.Vector +closestPoint(x, y, z) -> Base.Vector\n +Get the closest point of the bounding box to the given point.\n +point : Base.Vector, tuple\n Coordinates of the given point. +x : float\n X-coordinate of the given point. +y : float\n Y-coordinate of the given point. +z : float\n Z-coordinate of the given point. - method intersect(BoundBox|Vector Base, Vector Dir) -Checks if the given object intersects with the BoundBox. That can be: -- Another BoundBox -- A line, specified by Base and Dir - + intersect(boundBox2) -> bool +intersect(base, dir) -> bool\n +Checks if the given object intersects with this bounding box. That can be +another bounding box or a line specified by base and direction.\n +boundBox2 : Base.BoundBox +base : Base.Vector, tuple +dir : Base.Vector, tuple - method intersected(BoundBox) -Returns the intersection of this and the given bounding box. - + intersected(boundBox2) -> Base.BoundBox\n +Returns the intersection of this and the given bounding box.\n +boundBox2 : Base.BoundBox - method united(BoundBox) -Returns the union of this and the given bounding box. - + united(boundBox2) -> Base.BoundBox\n +Returns the union of this and the given bounding box.\n +boundBox2 : Base.BoundBox - method enlarge(Float) -Enlarge the BoundBox by the given value in each direction. -A negative value shrinks the box. + enlarge(variation) -> None\n +Decrease the minimum values and increase the maximum values by the given value. +A negative value shrinks the bounding box.\n +variation : float - method Vector getIntersectionPoint(Vector Base, Vector Dir, [float epsilon=0.0001]) -Calculate the intersection point of a line with the BoundBox -The Base point must lie inside the bounding box, if not an -exception is thrown. - + getIntersectionPoint(base, dir, epsilon=0.0001) -> Base.Vector\n +Calculate the intersection point of a line with the bounding box. +The base point must lie inside the bounding box, if not an exception is thrown.\n +base : Base.Vector\n Base point of the line. +dir : Base.Vector\n Direction of the line. +epsilon : float\n Bounding box size tolerance. - method move(Vector) -Move the BoundBox by the given vector - + move(displacement) -> None +move(x, y, z) -> None\n +Move the bounding box by the given values.\n +displacement : Base.Vector, tuple\n Displacement at each direction. +x : float\n Displacement at x-direction. +y : float\n Displacement at y-direction. +z : float\n Displacement at z-direction. - method scale(x,y,z) -Scale the BoundBox by the given values in x, y and z - + scale(factor) -> None +scale(x, y, z) -> None\n +Scale the bounding box by the given values.\n +factor : Base.Vector, tuple\n Factor scale at each direction. +x : float\n Scale at x-direction. +y : float\n Scale at y-direction. +z : float\n Scale at z-direction. - method transformed(Matrix) -Return a new bounding box with the transformed corner of this bounding box - + transformed(matrix) -> Base.BoundBox\n +Returns a new BoundBox containing the transformed rectangular cuboid +represented by this BoundBox.\n +matrix : Base.Matrix\n Transformation matrix. - method bool isCutPlane(Vector Base, Vector Normal) -Check if the plane specified by Base and Normal intersects (cuts) the BoundBox + isCutPlane(base, normal) -> bool\n +Check if the plane specified by base and normal intersects (cuts) this bounding +box.\n +base : Base.Vector +normal : Base.Vector - - method bool isInside(Vector Base|BoundBox box) -Check if the point or bounding box is inside this bounding box - + isInside(object) -> bool +isInside(x, y, z) -> bool\n +Check if a point or a bounding box is inside this bounding box.\n +object : Base.Vector, Base.BoundBox\n Object to check if it is inside this bounding box. +x : float\n X-coordinate of the point to check. +y : float\n Y-coordinate of the point to check. +z : float\n Z-coordinate of the point to check. - Center point of the bounding box + Center point of the bounding box. - The maximum x boundary position + The maximum x boundary position. - The maximum y boundary position + The maximum y boundary position. - The maximum z boundary position + The maximum z boundary position. - The minimum x boundary position + The minimum x boundary position. - The minimum y boundary position + The minimum y boundary position. - The minimum z boundary position + The minimum z boundary position. - Length of the BoundBox in x direction + Length of the bounding box in x direction. - Length of the BoundBox in y direction + Length of the bounding box in y direction. - Length of the BoundBox in z direction + Length of the bounding box in z direction. - Diagonal length of the BoundBox + Diagonal length of the bounding box. diff --git a/src/Base/BoundBoxPyImp.cpp b/src/Base/BoundBoxPyImp.cpp index f4d6e1918c..41642252fa 100644 --- a/src/Base/BoundBoxPyImp.cpp +++ b/src/Base/BoundBoxPyImp.cpp @@ -311,23 +311,22 @@ PyObject* BoundBoxPy::getIntersectionPoint(PyObject *args) { PyObject *object,*object2; double epsilon=0.0001; - if (PyArg_ParseTuple(args,"O!O!|d:Need base and direction vector", - &(Base::VectorPy::Type), &object,&(Base::VectorPy::Type), &object2, &epsilon)) { - Base::Vector3d point; - bool ok = getBoundBoxPtr()->IntersectionPoint( - *(static_cast(object)->getVectorPtr()), - *(static_cast(object2)->getVectorPtr()), - point, epsilon); - if (ok) { - return new VectorPy(point); - } - else { - PyErr_SetString(Base::PyExc_FC_GeneralError, "No intersection"); - return nullptr; - } - } - else + if (!PyArg_ParseTuple(args,"O!O!|d;Need base and direction vector", + &(Base::VectorPy::Type), &object,&(Base::VectorPy::Type), &object2, &epsilon)) return nullptr; + + Base::Vector3d point; + bool ok = getBoundBoxPtr()->IntersectionPoint( + *(static_cast(object)->getVectorPtr()), + *(static_cast(object2)->getVectorPtr()), + point, epsilon); + if (ok) { + return new VectorPy(point); + } + else { + PyErr_SetString(Base::PyExc_FC_GeneralError, "No intersection"); + return nullptr; + } } PyObject* BoundBoxPy::move(PyObject *args) @@ -344,13 +343,13 @@ PyObject* BoundBoxPy::move(PyObject *args) } PyErr_Clear(); - if (PyArg_ParseTuple(args,"O!:Need vector to move",&PyTuple_Type, &object)) { + if (PyArg_ParseTuple(args,"O!",&PyTuple_Type, &object)) { vec = getVectorFromTuple(object); break; } PyErr_Clear(); - if (PyArg_ParseTuple(args,"O!:Need vector to move",&(Base::VectorPy::Type), &object)) { + if (PyArg_ParseTuple(args,"O!",&(Base::VectorPy::Type), &object)) { vec = *(static_cast(object)->getVectorPtr()); break; } @@ -382,13 +381,13 @@ PyObject* BoundBoxPy::scale(PyObject *args) } PyErr_Clear(); - if (PyArg_ParseTuple(args,"O!:Need vector to scale",&PyTuple_Type, &object)) { + if (PyArg_ParseTuple(args,"O!",&PyTuple_Type, &object)) { vec = getVectorFromTuple(object); break; } PyErr_Clear(); - if (PyArg_ParseTuple(args,"O!:Need vector to scale",&(Base::VectorPy::Type), &object)) { + if (PyArg_ParseTuple(args,"O!",&(Base::VectorPy::Type), &object)) { vec = *(static_cast(object)->getVectorPtr()); break; } @@ -429,14 +428,14 @@ PyObject* BoundBoxPy::isCutPlane(PyObject *args) return nullptr; } - if (PyArg_ParseTuple(args,"O!O!:Need base and normal vector of a plane", + if (!PyArg_ParseTuple(args,"O!O!;Need base and normal vector of a plane", &(Base::VectorPy::Type), &object,&(Base::VectorPy::Type), &object2)) - retVal = getBoundBoxPtr()->IsCutPlane( - *(static_cast(object)->getVectorPtr()), - *(static_cast(object2)->getVectorPtr())); - else return nullptr; + retVal = getBoundBoxPtr()->IsCutPlane( + *(static_cast(object)->getVectorPtr()), + *(static_cast(object2)->getVectorPtr())); + return Py::new_reference_to(retVal); }