Adapt find_new_position is WIP. Cleaning up comments.

src/libslic3r/ModelArrange.hpp

@@ -1,16 +1,14 @@
 #ifndef MODELARRANGE_HPP
 #define MODELARRANGE_HPP
 
-//#include "Model.hpp"
 #include "Polygon.hpp"
 #include "BoundingBox.hpp"
 
 namespace Slic3r {
 
-class Model;
-
 namespace arr {
 
+/// A geometry abstraction for a circular print bed. Similarly to BoundingBox.
 class CircleBed {
     Point center_;
     double radius_;
@@ -24,6 +22,7 @@ public:
     inline operator bool() { return !std::isnan(radius_); }
 };
 
+/// Types of print bed shapes.
 enum class BedShapeType {
     BOX,
     CIRCLE,
@@ -31,6 +30,7 @@ enum class BedShapeType {
     WHO_KNOWS
 };
 
+/// Info about the print bed for the arrange() function.
 struct BedShapeHint {
     BedShapeType type = BedShapeType::WHO_KNOWS;
     /*union*/ struct {  // I know but who cares... TODO: use variant from cpp17?
@@ -40,13 +40,19 @@ struct BedShapeHint {
     } shape;
 };
 
+/// Get a bed shape hint for arrange() from a naked Polyline.
 BedShapeHint bedShape(const Polyline& bed);
 
+/**
+ * @brief Classes implementing the Arrangeable interface can be used as input 
+ * to the arrange function.
+ */
 class Arrangeable {
 public:
     
     virtual ~Arrangeable() = default;
     
+    /// Apply the result transformation calculated by the arrangement.
     virtual void apply_arrange_result(Vec2d offset, double rotation_rads) = 0;
     
     /// Get the 2D silhouette to arrange and an initial offset and rotation
@@ -58,56 +64,48 @@ using Arrangeables = std::vector<Arrangeable*>;
 /**
  * \brief Arranges the model objects on the screen.
  *
- * The arrangement considers multiple bins (aka. print beds) for placing all
- * the items provided in the model argument. If the items don't fit on one
- * print bed, the remaining will be placed onto newly created print beds.
- * The first_bin_only parameter, if set to true, disables this behavior and
- * makes sure that only one print bed is filled and the remaining items will be
- * untouched. When set to false, the items which could not fit onto the
- * print bed will be placed next to the print bed so the user should see a
- * pile of items on the print bed and some other piles outside the print
- * area that can be dragged later onto the print bed as a group.
+ * The arrangement considers multiple bins (aka. print beds) for placing
+ * all the items provided in the model argument. If the items don't fit on
+ * one print bed, the remaining will be placed onto newly created print
+ * beds. The first_bin_only parameter, if set to true, disables this
+ * behavior and makes sure that only one print bed is filled and the
+ * remaining items will be untouched. When set to false, the items which
+ * could not fit onto the print bed will be placed next to the print bed so
+ * the user should see a pile of items on the print bed and some other
+ * piles outside the print area that can be dragged later onto the print
+ * bed as a group.
+ *
+ * \param items Input which are object pointers implementing the
+ * Arrangeable interface.
+ *
+ * \param min_obj_distance The minimum distance which is allowed for any
+ * pair of items on the print bed in any direction.
+ *
+ * \param bedhint Info about the shape and type of the
+ * bed. remaining items which do not fit onto the print area next to the
+ * print bed or leave them untouched (let the user arrange them by hand or
+ * remove them).
+ *
+ * \param progressind Progress indicator callback called when
+ * an object gets packed. The unsigned argument is the number of items
+ * remaining to pack.
  *
- * \param model The model object with the 3D content.
- * \param dist The minimum distance which is allowed for any pair of items
- * on the print bed  in any direction.
- * \param bb The bounding box of the print bed. It corresponds to the 'bin'
- * for bin packing.
- * \param first_bin_only This parameter controls whether to place the
- * remaining items which do not fit onto the print area next to the print
- * bed or leave them untouched (let the user arrange them by hand or remove
- * them).
- * \param progressind Progress indicator callback called when an object gets
- * packed. The unsigned argument is the number of items remaining to pack.
  * \param stopcondition A predicate returning true if abort is needed.
  */
-//bool arrange(Model &model,
-//             WipeTowerInfo& wipe_tower_info,
-//             coord_t min_obj_distance,
-//             const Slic3r::Polyline& bed,
-//             BedShapeHint bedhint,
-//             bool first_bin_only,
-//             std::function<void(unsigned)> progressind,
-//             std::function<bool(void)> stopcondition);
-
 bool arrange(Arrangeables &items,
              coord_t min_obj_distance,
-             BedShapeHint bedhint,
+             const BedShapeHint& bedhint,
              std::function<void(unsigned)> progressind,
              std::function<bool(void)> stopcondition);
 
-/// This will find a suitable position for a new object instance and leave the
-/// old items untouched.
-//void find_new_position(const Model& model,
-//                       ModelInstancePtrs instances_to_add,
-//                       coord_t min_obj_distance,
-//                       const Slic3r::Polyline& bed,
-//                       WipeTowerInfo& wti);
-void find_new_position(Arrangeables &items,
-                       const Arrangeables &instances_to_add,
-                       coord_t min_obj_distance,
-                       BedShapeHint bedhint);
-
+/// Same as the previous, only that it takes unmovable items as an
+/// additional argument.
+bool arrange(Arrangeables &items,
+             const Arrangeables &excludes,
+             coord_t min_obj_distance,
+             const BedShapeHint& bedhint,
+             std::function<void(unsigned)> progressind,
+             std::function<bool(void)> stopcondition);
 
 }   // arr
 }   // Slic3r