From 4f3c745790d58fb78e3c7af1d59d5d22764ae021 Mon Sep 17 00:00:00 2001 From: Matthias Koefferlein Date: Wed, 20 Dec 2017 22:11:42 +0100 Subject: [PATCH] Updated the wording of some documentation texts and fixed some errors there. --- src/db/db/gsiDeclDbBox.cc | 85 +++++++++++--------- src/lay/lay/doc/programming/geometry_api.xml | 20 +++-- 2 files changed, 58 insertions(+), 47 deletions(-) diff --git a/src/db/db/gsiDeclDbBox.cc b/src/db/db/gsiDeclDbBox.cc index 844ea22df..6cbfb1d38 100644 --- a/src/db/db/gsiDeclDbBox.cc +++ b/src/db/db/gsiDeclDbBox.cc @@ -105,10 +105,14 @@ struct box_defs { return constructor ("new", &new_v, - "@brief Default constructor: creates an empty (invalid) box" + "@brief Creates an empty (invalid) box\n" + "\n" + "Empty boxes don't modify a box when joined with it. The intersection between an empty and any other " + "box is also an empty box. The width, height, p1 and p2 attributes of an empty box are undefined. " + "Use \\empty? to get a value indicating whether the box is empty.\n" ) + constructor ("new", &new_lbrt, - "@brief Constructor with four coordinates\n" + "@brief Creates a box with four coordinates\n" "\n" "@args left, bottom, right, top\n" "\n" @@ -117,63 +121,63 @@ struct box_defs "swapped." ) + constructor ("new", &new_pp, - "@brief Constructor with two points\n" + "@brief Creates a box from two points\n" "\n" "@args lower_left, upper_right\n" "\n" - "Two points are given to create a new box. If the coordinates " + "Two points are given to create a new box. If the coordinates " "are not provided in the correct order (i.e. right < left), these are " "swapped." ) + method ("p1", &C::p1, - "@brief The lower left point of the box\n" + "@brief Gets the lower left point of the box\n" ) + method ("p2", &C::p2, - "@brief The upper right point of the box\n" + "@brief Gets the upper right point of the box\n" ) + method ("center", &C::center, - "@brief The center of the box\n" + "@brief Gets the center of the box\n" ) + method ("left", &C::left, - "@brief The left coordinate of the box\n" + "@brief Gets the left coordinate of the box\n" ) + method ("right", &C::right, - "@brief The right coordinate of the box\n" + "@brief Gets the right coordinate of the box\n" ) + method ("bottom", &C::bottom, - "@brief The bottom coordinate of the box\n" + "@brief Gets the bottom coordinate of the box\n" ) + method ("top", &C::top, - "@brief The top coordinate of the box\n" + "@brief Gets the top coordinate of the box\n" ) + method ("width", &C::width, - "@brief The width of the box\n" + "@brief Gets the width of the box\n" ) + method ("height", &C::height, - "@brief The height of the box\n" + "@brief Gets the height of the box\n" ) + method ("left=", &C::set_left, - "@brief Set the left coordinate of the box\n" + "@brief Sets the left coordinate of the box\n" "@args c\n" ) + method ("right=", &C::set_right, - "@brief Set the right coordinate of the box\n" + "@brief Sets the right coordinate of the box\n" "@args c\n" ) + method ("bottom=", &C::set_bottom, - "@brief Set the bottom coordinate of the box\n" + "@brief Sets the bottom coordinate of the box\n" "@args c\n" ) + method ("top=", &C::set_top, - "@brief Set the top coordinate of the box\n" + "@brief Sets the top coordinate of the box\n" "@args c\n" ) + method ("p1=", &C::set_p1, - "@brief Set the lower left point of the box\n" + "@brief Sets the lower left point of the box\n" "@args p\n" ) + method ("p2=", &C::set_p2, - "@brief Set the upper right point of the box\n" + "@brief Sets the upper right point of the box\n" "@args p\n" ) + method_ext ("contains?", &box_defs::contains, @@ -199,40 +203,41 @@ struct box_defs "@return true if the point is inside the box.\n" ) + method ("empty?", &C::empty, - "@brief Empty predicate\n" + "@brief Returns a value indicating whether the box is empty\n" "\n" "An empty box may be created with the default constructor for example. " "Such a box is neutral when combining it with other boxes and renders empty boxes " "if used in box intersections and false in geometrical relationship tests. " ) + method ("inside?", &C::inside, - "@brief Test if this box is inside the argument box\n" + "@brief Tests if this box is inside the argument box\n" "\n" "@args box\n" "\n" "Returns true, if this box is inside the given box, i.e. the box intersection renders this box" ) + method ("touches?", &C::touches, - "@brief Test if this box touches the argument box\n" + "@brief Tests if this box touches the argument box\n" "\n" "@args box\n" "\n" - "Returns true, if this box has at least one point common with the argument box" + "Two boxes touch if they overlap or their boundaries share at least one common point. " + "Touching is equivalent to a non-empty intersection ('!(b1 & b2).empty?')." ) + method ("overlaps?", &C::overlaps, - "@brief Test if this box overlaps the argument box\n" + "@brief Tests if this box overlaps the argument box\n" "\n" "@args box\n" "\n" "Returns true, if the intersection box of this box with the argument box exists and has a non-vanishing area" ) + method ("area", &C::double_area, - "@brief Compute the box area\n" + "@brief Computes the box area\n" "\n" "Returns the box area or 0 if the box is empty" ) + method ("is_point?", &C::is_point, - "@brief Return true, if the box is a single point\n" + "@brief Returns true, if the box is a single point\n" ) + method ("perimeter", &C::perimeter, "@brief Returns the perimeter of the box\n" @@ -242,7 +247,7 @@ struct box_defs "This method has been introduced in version 0.23." ) + method_ext ("+", &box_defs::join_with_point, - "@brief Join box with a point\n" + "@brief Joins box with a point\n" "\n" "@args point\n" "\n" @@ -254,7 +259,7 @@ struct box_defs "@return The box joined with the point\n" ) + method ("+", &C::joined, - "@brief Joining of boxes\n" + "@brief Joins two boxes\n" "\n" "@args box\n" "\n" @@ -269,7 +274,7 @@ struct box_defs "@return The joined box\n" ) + method ("&", &C::intersection, - "@brief Intersection of boxes\n" + "@brief Returns the intersection of this box with another box\n" "\n" "@args box\n" "\n" @@ -285,7 +290,7 @@ struct box_defs "@return The intersection box\n" ) + method ("*", &C::convolved, - "@brief Convolve boxes\n" + "@brief Returns the convolution product from this box with another box\n" "\n" "@args box\n" "\n" @@ -300,7 +305,7 @@ struct box_defs "@return The convolved box\n" ) + method ("*", &C::scaled, - "@brief Scale box\n" + "@brief Returns the scaled box\n" "\n" "@args scale_factor\n" "\n" @@ -396,7 +401,7 @@ struct box_defs "@return A reference to this box.\n" ) + method ("enlarged", &C::enlarged, - "@brief Enlarges the box by a certain amount.\n" + "@brief Returns the enlarged box.\n" "\n" "@args enlargement\n" "\n" @@ -414,7 +419,7 @@ struct box_defs "@return The enlarged box.\n" ) + method ("transformed", &C::template transformed, - "@brief Transforms the box with the given simple transformation\n" + "@brief Returns the box transformed with the given simple transformation\n" "\n" "@args t\n" "\n" @@ -422,7 +427,7 @@ struct box_defs "@return The transformed box\n" ) + method ("transformed", &C::template transformed, - "@brief Transforms the box with the given complex transformation\n" + "@brief Returns the box transformed with the given complex transformation\n" "\n" "@args t\n" "\n" @@ -430,17 +435,17 @@ struct box_defs "@return The transformed box (a DBox now)\n" ) + method ("<", &C::less, - "@brief Less operator\n" + "@brief Returns true if this box is 'less' than another box\n" "@args box\n" "Returns true, if this box is 'less' with respect to first and second point (in this order)" ) + method ("==", &C::equal, - "@brief Equality\n" + "@brief Returns true if this box is equal to the other box\n" "@args box\n" "Returns true, if this box and the given box are equal " ) + method ("!=", &C::not_equal, - "@brief Inequality\n" + "@brief Returns true if this box is not equal to the other box\n" "@args box\n" "Returns true, if this box and the given box are not equal " ) + @@ -451,14 +456,16 @@ struct box_defs "This method has been introduced in version 0.25.\n" ) + constructor ("from_s", &from_string, - "@brief Creates an object from a string\n" + "@brief Creates a box object from a string\n" "@args s\n" "Creates the object from a string representation (as returned by \\to_s)\n" "\n" "This method has been added in version 0.23.\n" ) + method ("to_s", (std::string (C::*) () const) &C::to_string, - "@brief Convert to a string\n" + "@brief Returns a string representing this box\n" + "\n" + "This string can be turned into a box again by using \\from_s\n" ); } }; diff --git a/src/lay/lay/doc/programming/geometry_api.xml b/src/lay/lay/doc/programming/geometry_api.xml index 409c87cc4..8e56a87da 100644 --- a/src/lay/lay/doc/programming/geometry_api.xml +++ b/src/lay/lay/doc/programming/geometry_api.xml @@ -131,7 +131,7 @@

  • - transformed_cplx(ICplxTrans): returns the box transformed with the given complex, integer-based transformation (see ). + transformed(ICplxTrans): returns the box transformed with the given complex, integer-based transformation (see ). Note, that if the complex transformation includes a rotation by a non-90-degree angle (for example 45 degree), this operation does not return a rotated box, because by definition a box has edges which are parallel to the axes. Hence the general solution is to convert the box to a polygon: @@ -139,15 +139,15 @@ 

    # Wrong result
 box = RBA::Box::new(0, 0, 100, 200)
-transformed_box = box.transformed_cplx(RBA::ICplxTrans::new(1, 45, false, RBA::Vector::new))
+transformed_box = box.transformed(RBA::ICplxTrans::new(1, 45, false, RBA::Vector::new))
 # -> (-141,0;71,212)
 
 # Correct result
-transformed_box_as_polygon = RBA::Polygon::new(box).transformed_cplx(RBA::ICplxTrans::new(1, 45, false, RBA::Vector::new))
+transformed_box_as_polygon = RBA::Polygon::new(box).transformed(RBA::ICplxTrans::new(1, 45, false, RBA::Vector::new))
 # -> (0,0;-141,141;-71,212;71,71)
    • -
  • transformed_cplx(CplxTrans): behaves like the previous "transformed_cplx" method but returns a +
  • transformed(CplxTrans): behaves like the previous "transformed" method but returns a floating-point coordinate object which is the target coordinate type of the CplxTrans object (see ).
    • @@ -163,6 +163,10 @@ box = RBA::Box::new(dbox) # -> (2,3;11,12)

    An integer box can be turned into a floating-point unit box using

    + +

    Floating-point boxes can be transformed using the , the or the + transformations. The latter delivers an integer-type box and provides the reverse flavour transformation to "CplxTrans". +

    The SimplePolygon class

    @@ -197,7 +201,7 @@ box = RBA::Box::new(dbox) reflecting edges (spikes) as well. returns true, if a given point is inside the polygon. computes the Minkowsky sum between a polygon and another object in various flavors. will displace the polygon by the distance given by the Point argument. will return the moved polygon without modifying the - polygon it is called on (out-of-place operation). and will return the + polygon it is called on (out-of-place operation). will return the transformed polygon, either with a simple or a complex transformation (see the description of the Box object and the section about transformations below for a discussion of transformations). Finally, will apply a corner rounding to a copy of the polygon and return that copy without modifying the polygon. @@ -293,7 +297,7 @@ box = RBA::Box::new(dbox)

    returns the polygon representing the path's hull. returns a SimplePolygon - object that represents the hull. , , and basically work + object that represents the hull. , and basically work like for the other objects.

    @@ -332,7 +336,7 @@ box = RBA::Box::new(dbox)

    - , , and basically work + , and basically work like for the other objects. The class method creates a integer-coordinate type Text object from a floating-point coordinate type DText object (see below). The floating-point coordinates are rounded to the nearest integer coordinates. @@ -371,7 +375,7 @@ box = RBA::Box::new(dbox)

    - , , and basically work + , and basically work like for the other objects. The class method creates a integer-coordinate type Edge object from a floating-point coordinate type DEdge object (see below). The floating-point coordinates are rounded to the nearest integer coordinates.