PolygonReduction Manual

Table of Contents

• About
• Allocation/Deallocation
• Init
• Reduce
• Further Reading

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 (Cinema API).

• 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);

Further Reading

• Modeling
• BaseDocument Manual
• BaseContainer Manual
• PolygonObject