About

The PolygonReduction class allows to reduce the polygon count of a given PolygonObject while retaining its overall shape. The class gives access to the functionality used within the "Polygon Reduction" generator. It is defined in the lib_polygonreduction.h header file.

Allocation/Deallocation

A PolygonReduction object can be created with the usual tools, see Entity Creation and Destruction Manual (Classic).

PolygonReduction::Alloc(): Creates a new PolygonReduction object.
PolygonReduction::Free(): Deletes the given PolygonReduction object.

  // This example creates a new PolygonReduction object.
  AutoAlloc<PolygonReduction> polyReduction;
 
  if (polyReduction == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);

Init

A PolygonReduction object has to be initialized. It will pre-process the given PolygonObject.

PolygonReduction::PreProcess(): Pre-processes the PolygonObject defined in the given PolygonReductionData argument.

The PolygonReductionData argument has these members:

PolygonReductionData::_doc: The BaseDocument hosting the PolygonObject.
PolygonReductionData::_op: The target PolygonObject.
PolygonReductionData::_thread: The caller thread. If set to nullptr, the PolygonReduction object will pre-process the PolygonObject synchronously.
PolygonReductionData::_settings: A BaseContainer for further settings. See the parameter IDs in opolyreduxgen.h.

Note: In order to be able to abort the reduction operation and to retain the original mesh, it is advised to operate on a copy of the original PolygonObject.

  // This example configures the given PolygonReduction object and
  // reduces the given PolygonObject to 25%.
 
  // set polygon reduction settings
  BaseContainer settings;
  settings.SetBool(POLYREDUXOBJECT_PRESERVE_3D_BOUNDARY, true);
  settings.SetBool(POLYREDUXOBJECT_PRESERVE_UV_BOUNDARY, true);
 
  PolygonReductionData data;
  data._op  = polyObject;
  data._doc = doc;
  data._settings = settings;
  data._thread = nullptr; // synchronous pre-processing and reduction
 
  // pre process
  if (polyReduction->PreProcess(data) == false)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "The function exited unexpectedly during data pre-processing."_s);
 
  // reduce
  polyReduction->SetReductionStrengthLevel(0.75);
 
  // update
  polyObject->Message(MSG_UPDATE);

If the PolygonReductionData::_thread member is set the pre-process is running asynchronously in a background thread.

PolygonReduction::IsPreprocessing(): Returns true if the pre-process is running.
PolygonReduction::StopPreprocessing(): Aborts preprocessing.
PolygonReduction::Reset(): Aborts preprocessing and frees all temporary data.

Note: This asynchronous mode may be used e.g. in a generator object.

  // This example initializes the given PolygonReduction object asynchronously.
 
  PolygonReductionData data;
  data._op  = polyObject;
  data._doc = doc;
  data._settings = settings;
  data._thread = GeGetDummyThread();  // asynchronous pre-processing
 
  // pre process
  if (polyReduction->PreProcess(data) == false)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "The function exited unexpectedly during data pre-processing."_s);
 
  Int32 count = 0;
 
  // wait until preprocessing has finished
  while (polyReduction->IsPreprocessing())
  {
    ApplicationOutput("Pre Process...");
    GeSleep(100);
 
    count++;
 
    if (count > 100)
    {
      ApplicationOutput("Timeout!");
      polyReduction->StopPreprocessing();
      return maxon::UnknownError(MAXON_SOURCE_LOCATION);
    }
  }

After the pre-process the PolygonReduction object is ready:

PolygonReduction::IsValid(): Returns true if a valid object and a valid document are associated with the object.
PolygonReduction::GetData(): Returns the PolygonReductionData associated with the object.

Reduce

The linked PolygonObject can be reduced by defining the overall reduction strength or the target triangle, vertex or edge count.

PolygonReduction::GetMaxReductionStrengthLevel(): Returns the maximum reduction strength (1.0)
PolygonReduction::SetReductionStrengthLevel(): Sets the overall reduction strength.
PolygonReduction::GetReductionStrengthLevel(): Returns the current overall reduction strength.

The desired triangle count is defined with:

PolygonReduction::SetTriangleLevel(): Sets the desired triangle count.

Note

The desired triangle count must be between the Max and Min values retrieve with:
- PolygonReduction::GetMaxTriangleLevel(): Returns the maximum number of triangles possible.
- PolygonReduction::GetMinTriangleLevel(): Returns the minimum number of triangles possible.
The actual triangle count can be retrieve with:
- PolygonReduction::GetTriangleLevel(): Returns the actual current triangle count.

  // This example reduces the PolygonObject to the given triangle count.
 
  // return gracefully if the  specified triangle count is smaller than the minimum number of triangles after reduction pre-processing
  if (triTargetCount < polyReduction->GetMinTriangleLevel())
    return maxon::OK;
 
  // return gracefully if the specified triangle count is greater than the initial number of triangles
  if (triTargetCount > polyReduction->GetMaxTriangleLevel())
    return maxon::OK;
 
  polyReduction->SetTriangleLevel(triTargetCount);
 
  const Int32 realTriangleResult = polyReduction->GetTriangleLevel();
 
  ApplicationOutput("Triangle Result: @", realTriangleResult);

The vertex count is defined with:

PolygonReduction::SetVertexLevel(): Sets the desired vertex count.

Note

The desired vertex count must be between the Max and Min values retrieve with:
- PolygonReduction::GetMaxVertexLevel(): Returns the maximum number of vertices possible.
- PolygonReduction::GetMinVertexLevel(): Returns the minimum number of vertices possible.
The actual vertex count can be retrieve with:
- PolygonReduction::GetVertexLevel(): Returns the actual current vertex count.

  // This example reduces the PolygonObject to the given vertex count.
 
  // return gracefully if the  specified vertex count is smaller than the minimum number of vertexes after reduction pre-processing
  if (vertexTargetCount < polyReduction->GetMinVertexLevel())
    return maxon::OK;
 
  // return gracefully if the specified vertex count is greater than the initial number of vertexes
  if (vertexTargetCount > polyReduction->GetMaxVertexLevel())
    return maxon::OK;
 
  polyReduction->SetVertexLevel(vertexTargetCount);
 
  const Int32 realVertexResult = polyReduction->GetVertexLevel();
 
  ApplicationOutput("Vertex Result: @", realVertexResult);

Finally the edge count can be defined:

PolygonReduction::SetRemainingEdgesLevel(): Sets the desired edge count.

Note

The desired edge count must be less than the Max value retrieve with:
- PolygonReduction::GetMaxRemainingEdgesLevel(): Returns the number of remaining edges.
The actual edge count can be retrieve with:
- PolygonReduction::GetRemainingEdgesLevel(): Returns the actual edge count.

  // This example reduces the given PolygonObject to the given edge count.
 
  // return gracefully if the specified edges count is smaller than the remained number of edges after reduction pre-processing
  if (edgeTargetCount > polyReduction->GetMaxRemainingEdgesLevel())
    return maxon::OK;
 
  polyReduction->SetRemainingEdgesLevel(edgeTargetCount);
 
  const Int32 realEdgeResult = polyReduction->GetRemainingEdgesLevel();
 
  ApplicationOutput("Edge Result: @", realEdgeResult);

Table of Contents

About

Allocation/Deallocation

Init

Reduce

Further Reading