![]() |
Polygon Crucher SDK - Documentation
Documentation
|
CSceneOptimizer is the main entry to optimize a scene. There are various optimization modes and which includes keeping UV or not, keeping vertex colors or not... More...
CSceneOptimizer is the main entry to optimize a scene. There are various optimization modes and which includes keeping UV or not, keeping vertex colors or not...
Object optimization mode is set using CSCeneOptimizer::SetOptimizeMode. This is usually called once before calling CSceneOptimizer::Optimize. Changing it using the same optimizer requires to use the interactive mode.
The scene optimizer contains a set of C3DExtObject. You can convert an usual C3DScene to a scene usuable by CSceneOptimizer using C3DPolygonCruncherObjectCreator.
Optimization is a process that might requires a large amount of memory.
The scene optimizer can run itself in different mode that can be set using CSCeneOptimizer::SetFlag
SCENEOPTIMIZER_PROGRESSIVE_RATIO can be combined with theses modes. It offers to modulate the optimize ratio between the different objects of the CSceneOptimizer depending on their number of faces.
Doing this makes objects sorted by face number. Objects with many faces are optimized first, while objects with less faces begin to be optimized as the ratio decrease.
The goal is that CSceneOptimizer produces object with similar number of faces.
Memory requirements is the lowest for static mode and the highest for interactive mode.
CSceneOptimizer::Optimize will compute the optimization up to the provided ratio.
SCENEOPTIMIZER_TRACK_CHANGES record this computing giving you access to multiresolution scene where you can play with the ratio as you want, through an user interaction or camera distance for example. CSCeneOptimizer::GetScene gives you access to the result (static: OPTIMIZED_OBJECT_CLEANED, dynamic: OPTIMIZED_MULTIRESOLUTION_SCENE/OPTIMIZED_CLEANED_MULTIRESOLUTION_SCENE).
CSceneOptimizer (in dynamic/interactive mode) offers MagicCruncher feature, which allows computing automatically the best optimization ratio giving always appropriate results.
For example if you optimize some cubic objects which are not highly optimizable, MagicCruncher will stop optimization before object 'destruction' will occurs.
When the scene has several objects, MagicCruncher will set a different ratio, so that each object is properly optimized depending on its optimizable capabilities.
MagicCruncher can take a while, and if time is important, OPTIMIZE_USE_PREDICTIVE_RATIO with CSceneOptimizer::Optimize or CSceneOptimizer::SetMultiresolutionRatio is a faster but not optimal way to compute a reasonable and not destructive high ratio. CSceneOptimizer provides a default method for computing this empiric predictive ratio, but you can provide your own with CSceneOptimizer::SetPredictiveCallback
#include <SceneOptimizer.h>
Classes | |
struct | MagicCruncherParams |
struct | OptimizableObjectInfo |
Public Types | |
enum | ApplyTo { APPLY_TO_SCENE = 0x0 , APPLY_TO_SELECTED_NODES = 0x01 , EXCLUDE_LOCKED_NODES = 0x02 } |
enum | ModifySceneMode { BEGIN_SCENE_MODIFICATION = 0x01 , CANCEL_SCENE_MODIFICATION = 0x02 , APPLY_SCENE_MODIFICATION = 0x04 , VALIDATE_SCENE_MODIFICATION = 0x08 } |
enum | MagicCruncherMode { MAGICCRUNCHER_DEFAULT = 0x00 , MAGICCRUNCHER_INCLUDE_LOCKED_RATIO = 0x01 , MAGICCRUNCHER_INCLUDE_HIDDEN_NODE = 0x02 , MAGICCRUNCHER_INCLUDE_SELNODES_ONLY = 0x04 , MAGICCRUNCHER_INCLUDE_ALL_NODES = MAGICCRUNCHER_INCLUDE_LOCKED_RATIO|MAGICCRUNCHER_INCLUDE_HIDDEN_NODE , MAGICCRUNCHER_WHOLE_SCENE = 0x10 , MAGICCRUNCHER_ULTRA_MODE = 0x20 , MAGICCRUNCHER_DRAFT_DICHO = 0x100 , MAGICCRUNCHER_MEDIUM_DICHO = 0x200 , MAGICCRUNCHER_ACCURATE_DICHO = 0x400 , MAGICCRUNCHER_DICHO_LEVEL = MAGICCRUNCHER_DRAFT_DICHO | MAGICCRUNCHER_MEDIUM_DICHO | MAGICCRUNCHER_ACCURATE_DICHO } |
enum | MagicCruncherResult { MAGICCRUNCHER_VALID = 0x00 , MAGICCRUNCHER_ERROR = 0x01 , MAGICCRUNCHER_CANCEL = 0x02 , MAGICCRUNCHER_TIMEOUT = 0x04 } |
enum | MagicCruncherSimilarityCount { MAGICCRUNCHER_SIMILARITY_COUNT = 4 , MAGICCRUNCHER_DEFAULT_SIMILARITY_INDEX = 1 } |
enum | MultiresolutionInfo { MULTIRES_MIN_FACES = 0 , MULTIRES_MIN_POINTS , MULTIRES_MAX_FACES , MULTIRES_MAX_POINTS , MULTIRES_CUR_FACES , MULTIRES_CUR_POINTS } |
enum | LockRatioStatus { NONE_LOCKED = 0 , SOME_LOCKED , ALL_LOCKED } |
typedef struct CSceneOptimizer::OptimizableObjectInfo | OptimizableObjectInfo |
typedef enum CSceneOptimizer::ModifySceneMode | ModifySceneMode |
typedef enum CSceneOptimizer::MagicCruncherMode | MagicCruncherMode |
typedef enum CSceneOptimizer::MagicCruncherResult | MagicCruncherResult |
typedef struct CSceneOptimizer::MagicCruncherParams | MagicCruncherParams |
typedef double(* | PredictiveCallback) (C3DObject *object) |
typedef enum CSceneOptimizer::LockRatioStatus | LockRatioStatus |
Reaching the optimal results | |
The following flags determine how much close to the optimal object we want to be.
|
Public Member Functions | |
void | Clean () |
Delete input scene and multiresolution scene. | |
double | ComputePredictiveRatio (C3DObject *object) const |
return an heuristic ratio to be used to optimized the mesh. Comparatively to MagicCruncher the ratio is computed in a very fast way, but it gives a mesh optimization which is not optimal. | |
void | SetPredictiveCallback (PredictiveCallback callback) |
This method allows to provide you own predictive callback method when you use OPTIMIZE_USE_PREDICTIVE_RATIO. Giving an object, the callback returns the optimal ratio. | |
C3DScene * | DetachScene () |
The scene provided using SetScene, does not belong any more to the optimizer. | |
void | DeleteScene () |
The scene provided to the optimizer is deleted (only if it has been allowed using SetScene) | |
void | SetScene (C3DScene &scene, bool optimizerHandleDeletion) |
Sets the scene to optimize. If optimizerHandleDeletion = true, the optimizer will delete the scene at destroy, using DeleteScene or if another scene is provided using SetScene. | |
C3DScene * | GetScene (unsigned int optimizerResultFlags) |
Get the optimization result. | |
double | MagicCruncherOptimization (unsigned int magicMode, double similarityThreshold, ApplyTo applyTo=APPLY_TO_SCENE, MagicCruncherParams *params=NULL) |
Find optimal optimization with an optimal ratio for each objects, return the global ratio (1.0 is nothing done). magicMode is a combination of MagicCruncherMode flags. | |
bool | OptimizerHandleDeletion () const |
bool | IsNewScene () const |
bool | HasSameRatio (ApplyTo applyTo) const |
Return true if all the nodes concerned by applyTo has same optimization ratio. return true, if no multiresolution scene were computed. | |
double | GetMaxThresholdFromSelection (ApplyTo mode) const |
bool | IsProgressiveRatioEnabled () const |
Return true if SCENEOPTIMIZER_PROGRESSIVE_RATIO is set and if there is more than one node to optimize. | |
void | ModifyScene (ModifySceneMode mode) |
Advanced usage only. Provide a way to modify the internal scene for performing some changes on it (point welding, collapsing...) | |
int | Optimize (double ratio, bool &userCancel, unsigned int ratioMode=OPTIMIZE_TO_RATIO|OPTIMIZE_TO_FACE) |
double | GetObjectRatioFromGlobalRatio (double globalRatio, double objectProgressiveThreshold, unsigned int ratioMode, bool &leftUnoptimized) const |
Returns the progressive ratio value from the global ratio value for a given object. leftUnoptimized is return to true, if the ratio is above the thresholdRatio in case of progressive optimization. | |
bool | IsFlagSet (SCENEOPTIMIZER_FLAGS flag) const |
unsigned int | SaveFlags () const |
void | LoadFlags (unsigned int flags) |
void | SetFlags (unsigned int newflags, bool set) |
void | SetFlag (SCENEOPTIMIZER_FLAGS flag, bool set) |
int | LockOptimizeRatio (bool lock, ApplyTo mode=APPLY_TO_SCENE) |
Prevent multiresolution object ratio to be changed, by calling appropriate CMultiresolutionObject::LockRatio methods. Return the number of object which status changed (were unlocked, get lock or were locked, get unlocked). applyTo could be APPLY_TO_SCENE or APPLY_TO_SELECTED_NODES. | |
LockRatioStatus | GetLockedRatioStatus (ApplyTo mode=APPLY_TO_SCENE) const |
Node locking status. | |
bool | SetConstraintRatio (float constraint) |
This can be use to limit the optimization to a given constraint ratio. This is mainly for internal purpose. | |
float | GetConstraintRatio () const |
Retrieved the ratio set using. | |
bool | SetUVWTolerance (float tolerance) |
Set the UVW tolerance for all scene optimizer objects. | |
float | GetUVWTolerance () const |
Set the UVW tolerance for all scene optimizer objects. | |
bool | SetVCTolerance (int tolerance) |
Set the UVW tolerance for all scene optimizer objects. | |
int | GetVCTolerance () const |
Set the UVW tolerance for all scene optimizer objects. | |
bool | SetNormalThreshold (double radianThreshold) |
Set the UVW tolerance for all scene optimizer objects. | |
double | GetNormalThreshold () const |
Set the UVW tolerance for all scene optimizer objects. | |
bool | SetSymetryTolerance (float tolerance) |
Set the UVW tolerance for all scene optimizer objects. | |
float | GetSymetryTolerance () const |
Set the UVW tolerance for all scene optimizer objects. | |
bool | ContainMaterialFrontier () |
Returns true if at least one object has a material frontier. A material frontier means that one point of the object is connected to faces which have a different material. This allows to know if setting one of the OPTIMIZE_MATERIAL_FRONTIER_MASK optimization mode has some meaning. | |
bool | ContainUVWInfo (C3DScene *scene=NULL) |
Returns true if at least one of the object have UVW (UVW_CHANNEL). Check on the provided scene, otherwise check in the optimizer attached scene. This allows to know if setting one of the OPTIMIZE_UV_MASK optimization mode has some meaning. | |
bool | ContainVCInfo (C3DScene *scene=NULL) |
Returns true if at least one of the object have verter colors (VC_CHANNEL). The check is performed on the provided scene, otherwise check is done on scene optimizer. This allows to know if setting one of the OPTIMIZE_VC_MASK optimization mode has some meaning. | |
bool | ContainNormalInfo (C3DScene *scene=NULL) |
Returns true if at least one of the object have specified normals (SPEC_NORMAL_CHANNEL). The check is performed on the provided scene, otherwise check is done on scene optimizer. This allows to know if setting one of the OPTIMIZE_NORMALS_MASK optimization mode has some meaning. | |
int | GetSymetricPairsNumber () const |
Return the number of symetric points found, which is the sum of symetrical points of each optimizer objects. | |
bool | SelectMaterial (C3DExtObject *object, MaterialID id, bool optimised) |
bool | HasLockedNodes () const |
unsigned int | GetOptimizableObjects (CXArray< OptimizableObjectInfo > &objects, unsigned int applyToMode, bool onlyOptimizable=true) const |
Get ExtObject or CMultiresolutionObject from the scene (optimizable scene or multiresolution scene). | |
bool | CanOptimizeNode (const C3DSceneNode *node) const |
ApplyTo | GetApplyToMode () const |
return APPLY_TO_SCENE if none or all optimizable meshes are selected, APPLY_TO_SELECTION otherwise. | |
Working with the computed multiresolution scene | |
When using SCENEOPTIMIZER_TRACK_CHANGES, CSceneOptimizer::Optimize pre-compute optimization and allows dynamic access to optimization through a multiresolution scene (CMultiresolutionScene) These methods give access to the multiresolution scene which contains CMultiresolutionObject | |
void | CleanMultiresolutionScene () |
Delete an already computed multiresolution scene. This is automatically called on destroy but might be required on interactive optimization. Cf. usage in #OPTIMIZATION_INTERACTIVE. | |
bool | HasMultiresolutionScene () const |
bool | SetMultiresolutionRatio (double ratio, int requiredElement, unsigned int mode, ApplyTo applyTo=APPLY_TO_SCENE) |
Modify the ratio of the multiresolution scene (CMultiresolutionScene) by calling each CMultiresolutionObject::SetObjectRatio independently. | |
Object optimization mode | |
It's better to use LockInitialization, modify the optimization mode in the way you want then called UnlockInitialization to take avantage of multithreading. | |
longuint | GetOptimizeMode () const |
Return combination of OPTIMIZE_MODE used by the optimizer. As each object might have a different mode (if C3DExtObject::SetOptimizeMode has been called independently), it returns a combination of all C3DExtObject::GetOptimizeMode object flags. | |
longuint | GetOptimizeExtMode () const |
Return combination of OPTIMIZE_EXTMODE. Same remark than above. | |
bool | SetOptimizeExtMode (longuint optimizeExtModeFlags, bool cleanNotNeedParameters) |
Set one or more OPTIMIZE_EXTMODE flags of each scene optimizer objects. | |
bool | SetOptimizeMode (longuint optimizeModeFlags, bool cleanNotNeedParameters) |
Set one or more OPTIMIZE_MODE flags of each scene optimizer objects. | |
bool | SetOptimizeMode (C3DExtObject *object, OPTIMIZE_MODE newflag, bool set) |
Modify one OPTIMIZE_MODE flag one of each scene optimizer objects. | |
void | LockInitialization () |
As changing the object's optimisation mode can lead to a reset, LockInitialization and UnlockInitialization can be used to postpone this reset, reduce the calculations required and parallelise the process. | |
void | UnlockInitialization () |
Unlock a previously locked initalization. | |
Get point / face number information | |
Retrieve information on the removable (optimizable) point / face number and on the optimized point / face number.
| |
int | GetMultiresolutionInfo (MultiresolutionInfo info, ApplyTo applyMode=APPLY_TO_SCENE) const |
Get information on the number of optimized / optimizable / total points or faces number for the whole scene or the selection. applyTo could be any values. | |
int | GetInitialRemovableElementNumber (bool faceNbr) const |
Return number of removable faces (or points if !faceNbr) | |
int | GetRemovedElementNumber (bool faceNbr) const |
Return number of removed faces (or points if !faceNbr) | |
int | GetInitialRemovableFacesNumber () const |
Returns the number of faces that can be removed. | |
int | GetInitialRemovablePointsNumber () const |
Returns the number of points that can be removed. | |
int | GetRemovedFacesNumber () const |
Returns the number of faces that have been removed. | |
int | GetRemovedPointsNumber () const |
Returns the number of points that have been removed. | |
Callbacks | |
These method give a way to provide feedback to an user through a dialog box | |
void | SetProgressCallback (CruncherProgressCallback callback, void *data) |
Set a progress callback if you want to give some feedback to an user. | |
void | CancelProgress () |
Force progress to cancel. | |
bool | CheckCancelButton () |
void | SetMeshPos (unsigned int curmesh) |
void | AddProgressPos (unsigned int value) |
void | SetProgressPos (unsigned int pos) |
void | SetProgressMeshRange (unsigned int meshnbr) |
void | SetProgressRange (unsigned int min, unsigned int max) |
void | AddProgressRange (unsigned int value) |
void | SetProgressStatus (const CXString &status) |
void | ShowInformation (bool show, int textid=-1) |
Multithreading | |
These methods controls the number of thread allowed to the CSceneOptimizer. | |
void | SetMaxThreadCount (unsigned int count) |
Set the maximum parallel threads for task that are computed in parallel (ie MagicCruncher features) | |
unsigned int | GetMaxThreadCount () const |
Get the maximum parallel threads. | |
Static Public Member Functions | |
static double | ComputeProgressiveThreshold (int objectPtNbr, int maxSceneObjectPtNbr) |
Return the progressive threshold to be used. objectPtNbr is the object point nbr, and maxSceneObjectPtNbr is the maximum object point number among all objects in the scene. | |
static double | GetObjectRatioFromGlobalRatio (bool progressive, double globalRatio, double objectProgressiveThreshold, unsigned int ratioMode, bool &leftUnoptimized) |
Return the progressive ratio value from the global ratio value for a given object. | |
static double | DefaultPredictiveRatio (C3DObject *object) |
static double | GetDefaultSimilarity () |
Return a default similarity value that can be used as default for MagicCruncher. | |
static int | GetClosestSimilarityIndex (double similarity) |
Return the closest index in the GetDefaultSimilarityValues array based on the provide similarity value. | |
static const double * | GetDefaultSimilarityValues (int &size) |
Return #size default values to be use with MagicCruncherOptimization. These default are ordered from the lowest similarities to the highest one. | |
static double | MagicCruncherOptimization (const CXArray< CMultiresolutionObject * > *objects, unsigned int magicCruncherMode, double hausdorffThreshold, MagicCruncherParams *params=NULL) |
This method can be called when we only have CMultiresolutionObject* objets without the CSceneOptimizer that allow to compute it. | |
CSceneOptimizer::GetLockedRatioStatus allows to know if none, one or all the object have been locked using CMultiresolution::LockRatio
Flags defining the way MagicCruncher runs.
Enumerator | |
---|---|
MAGICCRUNCHER_INCLUDE_LOCKED_RATIO | By default mesh that are locked are excluded from the MagicCruncher process. Locking an object can be done using CMultiresolutionObject::LockRatio. |
MAGICCRUNCHER_INCLUDE_HIDDEN_NODE | By default mesh that are hidden are excluded from the MagicCruncher process. |
MAGICCRUNCHER_INCLUDE_SELNODES_ONLY | MagicCrunching is applied only to node which have SCENE_NODE_IS_SELECTED. This is a way to only apply MagicCruncher on a part of the scene. |
MAGICCRUNCHER_WHOLE_SCENE | Internal flag - MagicCrunching is applied to the whole scene instead of node by node. Other flags are ignored it this settings applied, and the optimizer mode is used (ie. SCENEOPTIMIZER_EXCLUDE_HIDDEN_NODES) |
MAGICCRUNCHER_ULTRA_MODE | Mode ultra: change the way hausdorff measure is normalized. |
Value return in MagicCruncherParams::resultCode after performing MagicCruncher
Advanced usage only
Allows to have an advanced control on MagicCruncher getting a progress callback or set a time out limit.
LockRatioStatus CSceneOptimizer::GetLockedRatioStatus | ( | ApplyTo | mode = APPLY_TO_SCENE | ) | const |
Node locking status.
When the multiresolution scene has been computed, this is possible to froze a multiresolution object, using CMultiresolution::LockRatio The following methods, check if none/some/all object are locked
Get the optimization result.
CLEAN modes removes any invalid faces that are progressively set while optimization occurs. When you ask for a cleaned scene you cannot used anymore CSceneOptimizer::Optimize or CSceneOptimize::SetMultiresolutionRatio, unless you use OPTIMIZED_COPY_SCENE.
In that case you'll have to delete the return scene when no longer need it.
When using OPTIMIZED_MULTIRESOLUTION_SCENE or OPTIMIZED_CLEANED_MULTIRESOLUTION_SCENE, the scene return has the CMultiresolutionScene class.
You can traverse the scene and set the ratio for each objects independently.
When using dynamic mode, you can delete the source scene using DeleteScene() once you have the multiresolution scene to reduce memory needs. You can also GetScene do this using OPTIMIZED_MULTIRESOLUTION_SCENE|OPTIMIZED_DELETE_ORIGINAL_SCENE. If you have set SCENEOPTIMIZER_INTERACTIVE_MODE, the source scene must be kept as a new optimization computation (CsceneOptimizer::Optimize) each time you modify SetOptimizeMode.
bool CSceneOptimizer::HasMultiresolutionScene | ( | ) | const |
Return true if a multiresolution scene is available (this occurs if GetScene(OPTIMIZED_MULTIRESOLUTION_SCENE) has been called.
int CSceneOptimizer::Optimize | ( | double | ratio, |
bool & | userCancel, | ||
unsigned int | ratioMode = OPTIMIZE_TO_RATIO|OPTIMIZE_TO_FACE |
||
) |
Optimize compute optimization up to ratio
bool CSceneOptimizer::SetMultiresolutionRatio | ( | double | ratio, |
int | requiredElement, | ||
unsigned int | mode, | ||
ApplyTo | applyTo = APPLY_TO_SCENE |
||
) |
Modify the ratio of the multiresolution scene (CMultiresolutionScene) by calling each CMultiresolutionObject::SetObjectRatio independently.
ratio | Define the target ratio if OPTIMIZE_TO_RATIO set. |
requiredElement | If OPTIMIZE_TO_NBR set, requiredElement is the target number of points (OPTIMIZE_TO_POINT) or faces (OPTIMIZE_TO_FACE). |
mode | Can be OPTIMIZE_TO_POINT|OPTIMIZE_TO_NBR, OPTIMIZE_TO_FACE|OPTIMIZE_TO_NBR, OPTIMIZE_TO_POINT|OPTIMIZE_TO_RATIO, OPTIMIZE_TO_FACE|OPTIMIZE_TO_RATIO |
applyTo | Could be APPLY_TO_SCENE or APPLY_TO_SELECTED_NODES. Object which ratio is locked is not taken into account, unless OPTIMIZE_UNLOCK_RATIO is defined. |