From af6b094d29b00b80640308d2440a6e6a75482e2c Mon Sep 17 00:00:00 2001 From: Daniel Goldman Date: Mon, 29 May 2017 23:06:57 -0400 Subject: [PATCH] Doxygen Documentation for Layer.hpp, Layer.cpp, LayerRegion.cpp, LayerRegionFill.cpp (#3979) * Migrated comments in Layer.hpp * Comments for Layer Class * Comments for LayerRegion * Comments for LayerRegionFill --- xs/src/libslic3r/Layer.cpp | 59 +++++++++++------- xs/src/libslic3r/Layer.hpp | 93 +++++++++++++++++++--------- xs/src/libslic3r/LayerRegion.cpp | 18 ++++-- xs/src/libslic3r/LayerRegionFill.cpp | 23 +++---- 4 files changed, 127 insertions(+), 66 deletions(-) diff --git a/xs/src/libslic3r/Layer.cpp b/xs/src/libslic3r/Layer.cpp index 721df879d..fe9636d62 100644 --- a/xs/src/libslic3r/Layer.cpp +++ b/xs/src/libslic3r/Layer.cpp @@ -5,6 +5,8 @@ namespace Slic3r { +/// Initialises upper_layer, lower_layer to NULL +/// Initialises slicing_errors to false Layer::Layer(size_t id, PrintObject *object, coordf_t height, coordf_t print_z, coordf_t slice_z) : upper_layer(NULL), @@ -20,6 +22,7 @@ Layer::Layer(size_t id, PrintObject *object, coordf_t height, coordf_t print_z, { } +/// Removes references to self and clears regions Layer::~Layer() { // remove references to self @@ -34,25 +37,28 @@ Layer::~Layer() this->clear_regions(); } +/// Getter for this->_id size_t Layer::id() const { return this->_id; } +/// Setter for this->_id void Layer::set_id(size_t id) { this->_id = id; } - +/// Getter for this->regions.size() size_t Layer::region_count() const { return this->regions.size(); } +/// Deletes all regions using this->delete_region() void Layer::clear_regions() { @@ -60,6 +66,7 @@ Layer::clear_regions() this->delete_region(i); } +/// Creates a LayerRegion from a PrintRegion and adds it to this->regions LayerRegion* Layer::add_region(PrintRegion* print_region) { @@ -68,6 +75,7 @@ Layer::add_region(PrintRegion* print_region) return region; } +/// Deletes an individual region void Layer::delete_region(int idx) { @@ -77,7 +85,8 @@ Layer::delete_region(int idx) delete item; } -// merge all regions' slices to get islands +/// Merge all regions' slices to get islands +//TODO: is this right? void Layer::make_slices() { @@ -115,6 +124,7 @@ Layer::make_slices() this->slices.expolygons.push_back(slices[o]); } +/// Iterates over all of the LayerRegion and invokes LayerRegion->merge_slices() void Layer::merge_slices() { @@ -123,6 +133,7 @@ Layer::merge_slices() } } +/// Uses LayerRegion->slices.any_internal_contains(item) template bool Layer::any_internal_region_slice_contains(const T &item) const @@ -134,6 +145,7 @@ Layer::any_internal_region_slice_contains(const T &item) const } template bool Layer::any_internal_region_slice_contains(const Polyline &item) const; +/// Uses LayerRegion->slices.any_bottom_contains(item) template bool Layer::any_bottom_region_slice_contains(const T &item) const @@ -145,10 +157,8 @@ Layer::any_bottom_region_slice_contains(const T &item) const } template bool Layer::any_bottom_region_slice_contains(const Polyline &item) const; - -// Here the perimeters are created cummulatively for all layer regions sharing the same parameters influencing the perimeters. -// The perimeter paths and the thin fills (ExtrusionEntityCollection) are assigned to the first compatible layer region. -// The resulting fill surface is split back among the originating regions. +/// The perimeter paths and the thin fills (ExtrusionEntityCollection) are assigned to the first compatible layer region. +/// The resulting fill surface is split back among the originating regions. void Layer::make_perimeters() { @@ -232,6 +242,8 @@ Layer::make_perimeters() } } +/// Iterates over all of the LayerRegion and invokes LayerRegion->make_fill() +/// Asserts that the fills created are not NULL void Layer::make_fills() { @@ -249,15 +261,15 @@ Layer::make_fills() } } -// This function analyzes slices of a region (SurfaceCollection slices). -// Each region slice (instance of Surface) is analyzed, whether it is supported or whether it is the top surface. -// Initially all slices are of type S_TYPE_INTERNAL. -// Slices are compared against the top / bottom slices and regions and classified to the following groups: -// S_TYPE_TOP - Part of a region, which is not covered by any upper layer. This surface will be filled with a top solid infill. -// S_TYPE_BOTTOMBRIDGE - Part of a region, which is not fully supported, but it hangs in the air, or it hangs losely on a support or a raft. -// S_TYPE_BOTTOM - Part of a region, which is not supported by the same region, but it is supported either by another region, or by a soluble interface layer. -// S_TYPE_INTERNAL - Part of a region, which is supported by the same region type. -// If a part of a region is of S_TYPE_BOTTOM and S_TYPE_TOP, the S_TYPE_BOTTOM wins. +/// Analyzes slices of a region (SurfaceCollection slices). +/// Each region slice (instance of Surface) is analyzed, whether it is supported or whether it is the top surface. +/// Initially all slices are of type S_TYPE_INTERNAL. +/// Slices are compared against the top / bottom slices and regions and classified to the following groups: +/// S_TYPE_TOP - Part of a region, which is not covered by any upper layer. This surface will be filled with a top solid infill. +/// S_TYPE_BOTTOMBRIDGE - Part of a region, which is not fully supported, but it hangs in the air, or it hangs losely on a support or a raft. +/// S_TYPE_BOTTOM - Part of a region, which is not supported by the same region, but it is supported either by another region, or by a soluble interface layer. +/// S_TYPE_INTERNAL - Part of a region, which is supported by the same region type. +/// If a part of a region is of S_TYPE_BOTTOM and S_TYPE_TOP, the S_TYPE_BOTTOM wins. void Layer::detect_surfaces_type() { @@ -270,7 +282,7 @@ Layer::detect_surfaces_type() // unless internal shells are requested // We call layer->slices or layerm->slices on these neighbor layers - // and we convert them into Polygons so we only care about their total + // and we convert them into Polygons so we only care about their total // coverage. We only write to layerm->slices so we can read layer->slices safely. Layer* const &upper_layer = this->upper_layer; Layer* const &lower_layer = this->lower_layer; @@ -315,7 +327,7 @@ Layer::detect_surfaces_type() if (lower_layer != NULL) { // If we have soluble support material, don't bridge. The overhang will be squished against a soluble layer separating // the support from the print. - const SurfaceType surface_type_bottom = + const SurfaceType surface_type_bottom = (object.config.support_material.value && object.config.support_material_contact_distance.value == 0) ? stBottom : stBottomBridge; @@ -323,7 +335,7 @@ Layer::detect_surfaces_type() // Any surface lying on the void is a true bottom bridge (an overhang) bottom.append( offset2_ex( - diff(layerm_slices_surfaces, lower_layer->slices, true), + diff(layerm_slices_surfaces, lower_layer->slices, true), -offs, offs ), surface_type_bottom @@ -332,7 +344,7 @@ Layer::detect_surfaces_type() // if user requested internal shells, we need to identify surfaces // lying on other slices not belonging to this region if (object.config.interface_shells) { - // non-bridging bottom surfaces: any part of this layer lying + // non-bridging bottom surfaces: any part of this layer lying // on something else, excluding those lying on our own region const LayerRegion* lower_layerm = lower_layer->get_region(region_id); boost::lock_guard l(lower_layerm->_slices_mutex); @@ -340,9 +352,9 @@ Layer::detect_surfaces_type() offset2_ex( diff( intersection(layerm_slices_surfaces, lower_layer->slices), // supported - lower_layerm->slices, + lower_layerm->slices, true - ), + ), -offs, offs ), stBottom @@ -355,7 +367,7 @@ Layer::detect_surfaces_type() // if we have raft layers, consider bottom layer as a bridge // just like any other bottom surface lying on the void - const SurfaceType surface_type_bottom = + const SurfaceType surface_type_bottom = (object.config.raft_layers.value > 0 && object.config.support_material_contact_distance.value > 0) ? stBottomBridge : stBottom; @@ -405,7 +417,7 @@ Layer::detect_surfaces_type() { /* Fill in layerm->fill_surfaces by trimming the layerm->slices by the cummulative layerm->fill_surfaces. - Note: this method should be idempotent, but fill_surfaces gets modified + Note: this method should be idempotent, but fill_surfaces gets modified in place. However we're now only using its boundaries (which are invariant) so we're safe. This guarantees idempotence of prepare_infill() also in case that combine_infill() turns some fill_surface into VOID surfaces. */ @@ -423,6 +435,7 @@ Layer::detect_surfaces_type() } } +///Iterates over all LayerRegions and invokes LayerRegion->process_external_surfaces void Layer::process_external_surfaces() { diff --git a/xs/src/libslic3r/Layer.hpp b/xs/src/libslic3r/Layer.hpp index 29405258e..bf7aa7544 100644 --- a/xs/src/libslic3r/Layer.hpp +++ b/xs/src/libslic3r/Layer.hpp @@ -31,97 +31,126 @@ class LayerRegion PrintRegion* region() { return this->_region; }; const PrintRegion* region() const { return this->_region; }; - // collection of surfaces generated by slicing the original geometry - // divided by type top/bottom/internal + /// Collection of surfaces generated by slicing the original geometry + /// Divided by type top/bottom/internal SurfaceCollection slices; - - // collection of extrusion paths/loops filling gaps + + /// Collection of extrusion paths/loops filling gaps ExtrusionEntityCollection thin_fills; - // collection of surfaces for infill generation + /// Collection of surfaces for infill generation SurfaceCollection fill_surfaces; - // collection of expolygons representing the bridged areas (thus not - // needing support material) + /// Collection of expolygons representing the bridged areas (thus not + /// needing support material) Polygons bridged; - // collection of polylines representing the unsupported bridge edges + /// Collection of polylines representing the unsupported bridge edges PolylineCollection unsupported_bridge_edges; - // ordered collection of extrusion paths/loops to build all perimeters - // (this collection contains only ExtrusionEntityCollection objects) + /// Ordered collection of extrusion paths/loops to build all perimeters + /// (this collection contains only ExtrusionEntityCollection objects) ExtrusionEntityCollection perimeters; - // ordered collection of extrusion paths to fill surfaces - // (this collection contains only ExtrusionEntityCollection objects) + /// Ordered collection of extrusion paths to fill surfaces + /// (this collection contains only ExtrusionEntityCollection objects) ExtrusionEntityCollection fills; + /// Flow object which provides methods to predict material spacing. Flow flow(FlowRole role, bool bridge = false, double width = -1) const; + /// Merges this->slices void merge_slices(); + /// Preprocesses fill surfaces void prepare_fill_surfaces(); + /// Generates and stores the perimeters and thin fills void make_perimeters(const SurfaceCollection &slices, SurfaceCollection* fill_surfaces); + /// Generate infills for a LayerRegion. void make_fill(); + /// Processes external surfaces for bridges and top/bottom surfaces void process_external_surfaces(); + /// Gets the smallest fillable area double infill_area_threshold() const; private: + /// Pointer to associated Layer Layer *_layer; + /// Pointer to associated PrintRegion PrintRegion *_region; + /// Mutex object for slices. mutable boost::mutex _slices_mutex; + ///Constructor LayerRegion(Layer *layer, PrintRegion *region) : _layer(layer), _region(region) {}; + ///Destructor ~LayerRegion() {}; }; - +/// A std::vector of LayerRegion Pointers typedef std::vector LayerRegionPtrs; class Layer { friend class PrintObject; public: + /// ID number size_t id() const; + /// Setter for this->_id void set_id(size_t id); + /// Getter for _object PrintObject* object() { return this->_object; }; const PrintObject* object() const { return this->_object; }; - Layer *upper_layer; - Layer *lower_layer; - LayerRegionPtrs regions; - bool slicing_errors; - coordf_t slice_z; // Z used for slicing in unscaled coordinates - coordf_t print_z; // Z used for printing in unscaled coordinates - coordf_t height; // layer height in unscaled coordinates - - // collection of expolygons generated by slicing the original geometry; - // also known as 'islands' (all regions and surface types are merged here) - ExPolygonCollection slices; + Layer *upper_layer; ///< Pointer to layer above + Layer *lower_layer; ///< Pointer to layer below + LayerRegionPtrs regions; ///< Vector of pointers to the LayerRegions of this layer + bool slicing_errors; ///< Presence of slicing errors + coordf_t slice_z; ///< Z used for slicing in unscaled coordinates + coordf_t print_z; ///< Z used for printing in unscaled coordinates + coordf_t height; ///< layer height in unscaled coordinates + ExPolygonCollection slices; ///< collection of expolygons generated by slicing the original geometry; + ///< also known as 'islands' (all regions and surface types are merged here) + /// Returns the number of regions size_t region_count() const; + /// Gets a region at a specific id LayerRegion* get_region(size_t idx) { return this->regions.at(idx); }; + /// Gets a region at a specific id as const const LayerRegion* get_region(size_t idx) const { return this->regions.at(idx); }; - LayerRegion* add_region(PrintRegion* print_region); + /// Adds a PrintRegion + LayerRegion* add_region(PrintRegion* print_region); + /// Merge all regions' slices to get islands void make_slices(); + /// Merges all of the LayerRegions' slices void merge_slices(); + /// Template which iterates over all of the LayerRegion for internally containing the argument template bool any_internal_region_slice_contains(const T &item) const; + /// Template which iterates over all of the LayerRegion for containing on the bottom the argument template bool any_bottom_region_slice_contains(const T &item) const; + /// Creates the perimeters cummulatively for all layer regions sharing the same parameters influencing the perimeters. void make_perimeters(); + /// Makes fills for all the LayerRegion void make_fills(); + /// Determines the type of surface (top/bottombridge/bottom/internal) each region is void detect_surfaces_type(); + /// Processes the external surfaces void process_external_surfaces(); protected: - size_t _id; // sequential number of layer, 0-based - PrintObject* _object; - + size_t _id; ///< sequential number of layer, 0-based + PrintObject* _object; ///< Associated PrintObject + + /// Constructor Layer(size_t id, PrintObject *object, coordf_t height, coordf_t print_z, coordf_t slice_z); + /// Destructor virtual ~Layer(); + /// Deletes all regions void clear_regions(); + /// Deletes a specific region void delete_region(int idx); }; @@ -130,14 +159,22 @@ class SupportLayer : public Layer { friend class PrintObject; public: + /// Collection of support islands. + /// Populated in SupportMaterial.pm in sub generate_toolpaths ExPolygonCollection support_islands; + /// Collection of support fills. + /// Populated in SupportMaterial.pm in sub generate_toolpaths ExtrusionEntityCollection support_fills; + /// Collection of support interface fills. + /// Populated in SupportMaterial.pm in sub generate_toolpaths ExtrusionEntityCollection support_interface_fills; protected: + /// Constructor SupportLayer(size_t id, PrintObject *object, coordf_t height, coordf_t print_z, coordf_t slice_z) : Layer(id, object, height, print_z, slice_z) {}; + /// Destructor virtual ~SupportLayer() {}; }; diff --git a/xs/src/libslic3r/LayerRegion.cpp b/xs/src/libslic3r/LayerRegion.cpp index 9ba33d236..bf9b856ae 100644 --- a/xs/src/libslic3r/LayerRegion.cpp +++ b/xs/src/libslic3r/LayerRegion.cpp @@ -8,6 +8,7 @@ namespace Slic3r { +/// Creates a new Flow object with the arguments and the variables of this LayerRegion Flow LayerRegion::flow(FlowRole role, bool bridge, double width) const { @@ -21,6 +22,7 @@ LayerRegion::flow(FlowRole role, bool bridge, double width) const ); } +/// Merges this->slices with union_ex, and then repopulates this->slices.surfaces void LayerRegion::merge_slices() { @@ -33,6 +35,8 @@ LayerRegion::merge_slices() this->slices.surfaces.push_back(Surface(stInternal, *expoly)); } +/// Creates a new PerimeterGenerator object +/// Which will return the perimeters by its construction void LayerRegion::make_perimeters(const SurfaceCollection &slices, SurfaceCollection* fill_surfaces) { @@ -66,8 +70,11 @@ LayerRegion::make_perimeters(const SurfaceCollection &slices, SurfaceCollection* g.process(); } -// This function reads layer->slices and lower_layer->slices -// and writes this->bridged and this->fill_surfaces, so it's thread-safe. +/// Processes bridges with holes which are internal features. +/// Detects same-orientation bridges and merges them. +/// Processes and groups top and bottom surfaces +/// This function reads layer->slices and lower_layer->slices +/// and writes this->bridged and this->fill_surfaces, so it's thread-safe. void LayerRegion::process_external_surfaces() { @@ -79,7 +86,7 @@ LayerRegion::process_external_surfaces() if (this->layer()->lower_layer != NULL && surfaces[j].is_bridge()) { // If this bridge has one or more holes that are internal surfaces - // (thus not visible from the outside), like a slab sustained by + // (thus not visible from the outside), like a slab sustained by // pillars, include them in the bridge in order to have better and // more continuous bridging. for (int i = 0; i < surfaces[j].expolygon.holes.size(); ++i) { @@ -132,7 +139,7 @@ LayerRegion::process_external_surfaces() if (this->layer()->object()->config.support_material) { append_to(this->bridged, bd.coverage()); - this->unsupported_bridge_edges.append(bd.unsupported_edges()); + this->unsupported_bridge_edges.append(bd.unsupported_edges()); } } } @@ -220,6 +227,8 @@ LayerRegion::process_external_surfaces() this->fill_surfaces = std::move(new_surfaces); } +/// If no solid layers are requested, turns top/bottom surfaces to internal +/// Turns too small internal regions into solid regions according to the user setting void LayerRegion::prepare_fill_surfaces() { @@ -259,6 +268,7 @@ LayerRegion::prepare_fill_surfaces() } } +/// Gets smallest area by squaring the Flow's scaled spacing double LayerRegion::infill_area_threshold() const { diff --git a/xs/src/libslic3r/LayerRegionFill.cpp b/xs/src/libslic3r/LayerRegionFill.cpp index d6b567ceb..8690434d4 100644 --- a/xs/src/libslic3r/LayerRegionFill.cpp +++ b/xs/src/libslic3r/LayerRegionFill.cpp @@ -8,23 +8,24 @@ namespace Slic3r { +/// Struct for the main attributes of a Surface +/// Used for comparing properties struct SurfaceGroupAttrib { SurfaceGroupAttrib() : is_solid(false), fw(0.f), pattern(-1) {} + /// True iff all all three attributes are the same bool operator==(const SurfaceGroupAttrib &other) const { return is_solid == other.is_solid && fw == other.fw && pattern == other.pattern; } - bool is_solid; - float fw; - // pattern is of type InfillPattern, -1 for an unset pattern. - int pattern; + bool is_solid; ///< if a solid infill should be used + float fw; ///< flow Width + int pattern; ///< pattern is of type InfillPattern, -1 for an unset pattern. }; -// Generate infills for a LayerRegion. -// The LayerRegion at this point of time may contain -// surfaces of various types (internal/bridge/top/bottom/solid). -// The infills are generated on the groups of surfaces with a compatible type. -// Fills an array of ExtrusionPathCollection objects containing the infills generated now -// and the thin fills generated by generate_perimeters(). +/// The LayerRegion at this point of time may contain +/// surfaces of various types (internal/bridge/top/bottom/solid). +/// The infills are generated on the groups of surfaces with a compatible type. +/// Fills an array of ExtrusionPathCollection objects containing the infills generated now +/// and the thin fills generated by generate_perimeters(). void LayerRegion::make_fill() { @@ -210,7 +211,7 @@ LayerRegion::make_fill() // calculate flow spacing for infill pattern generation bool using_internal_flow = false; if (!surface.is_solid() && !is_bridge) { - // it's internal infill, so we can calculate a generic flow spacing + // it's internal infill, so we can calculate a generic flow spacing // for all layers, for avoiding the ugly effect of // misaligned infill on first layer because of different extrusion width and // layer height