Fixturing offset

See also

Reference:

McalAlloc McalDraw McalFixture McalRelativeOrigin McalSetCoordinateSystem MmodControl MpatControl

Availability

Not available in MIL-Lite

Available in MIL

When fixturing, you might need to offset the relative coordinate system from the default reference location that you can automatically establish from analysis/processing. There are different ways to apply a fixturing offset depending on the reason that you want to apply an offset:

Fixturing offset for convenience.
Fixturing offset to decouple the reference location from the object to analyze.

Fixturing offset for convenience

If placing the relative coordinate system at the default reference location is not convenient, you can have MIL automatically apply a required offset to the default reference location. This can be useful, for example, if the default reference location would cause you to deal with negative coordinates during analysis. In this case, there are two ways to automatically apply a fixturing offset.

If using a model occurrence to displace the relative coordinate system, you can offset the reference location of the model to the required location prior to searching for occurrences of it.
If using McalFixture() to move the relative coordinate system to a specific location, regardless of how you pass the reference location, you can use a fixturing offset object.

Moving the reference location prior to searching

If using a model occurrence to displace the relative coordinate system and you need to apply an offset from the occurrence's center, you can move the reference location of the model so that the returned location of each occurrence is at the required offset from the occurrence.

To move the reference location of a pattern matching model, use MpatControl() with M_REFERENCE.... To move the reference location of a Model Finder model, use MmodControl() with M_REFERENCE_X, M_REFERENCE_Y, and M_REFERENCE_ANGLE.

The following code snippet shows how to move the reference location of a model and then place the relative coordinate system at the reference location of a model occurrence:

/* Set up phase. */

/* Set the model reference location
   (model 0 in Model Finder context ModContextId). */
MmodControl(ModContextId, 0, M_REFERENCE_X, ReferenceX);
MmodControl(ModContextId, 0, M_REFERENCE_Y, ReferenceY);
MmodControl(ModContextId, 0, M_REFERENCE_ANGLE, ReferenceAngle);

/* Critical loop. */
while (!Stop)
   {
   /* Acquire image. */
   /* ... */

   /* Find the model in GrabbedImageId. */
   MmodFind(ModContextId, GrabbedImageId, ModResultId);
   
   /* Loop on all model occurences. */
   MmodGetResult(ModResultId, M_GENERAL, M_NUMBER+M_TYPE_MIL_INT, &Number);

   for (ResultIndex = 0; ResultIndex < Number; ResultIndex++)
      {
      /* Move the relative coordinate system to the reference location
         of the found model. */
      McalFixture(GrabbedImageId, M_NULL, M_MOVE_RELATIVE, M_RESULT_MOD, 
                  ModResultId, ResultIndex,
                  M_DEFAULT, M_DEFAULT, M_DEFAULT);

      /* Do some analysis. */
      /* ... */
      }
   }

Note that moving the relative coordinate system using this technique can result in the returned locations being far from the actual occurrences of the model. This might not be ideal when using the locations not only to place the relative coordinate system, but also to, for example, draw the locations of the occurrences.

Moving the relative coordinate system to a logical offset from a reference location

You can also add a fixturing offset to the reference location using a fixturing offset object. Besides being useful if you are not using a model occurrence, it can also be useful if using a model occurrence. In the latter case, a fixturing offset object offers the advantage of keeping the model's reference location at its original location, while specifying an offset for the relative coordinate system. A fixturing offset object is a MIL object that stores a positional and angular offset.

You can use the following steps to allocate and set up a fixturing offset object:

Allocate a fixturing offset object using McalAlloc() with M_FIXTURING_OFFSET.
In a training image, ensure that the relative coordinate system is at a required location in the image; if it isn't, move it using McalRelativeOrigin() or McalSetCoordinateSystem(). Typically, you would place the relative coordinate system at the required offset from a location that you can automatically establish in the training image (the reference location).
Establish a location in the training image that has the required positional and angular offset from the relative coordinate system. This is typically the reference location in the training image.
Call McalFixture() with M_LEARN_OFFSET, the fixturing offset object, the training image, and the established location. MIL will learn the positional and angular offset that the established location has from the relative coordinate system, and will save it in the fixturing offset object.
At runtime, call McalFixture() with M_MOVE_RELATIVE and the fixturing offset object.

The following animation offers a visual representation of the above steps.

In the example above, we want to obtain the exact location and angle of the bar code with respect to the board because we want to check if the location and angle are correct compared to the schematics.

The following code snippet illustrates how to move the relative coordinate system to a preestablished offset from the reference location of a model occurrence, without moving the model's default reference location:

/* Set up phase. */

/* Optionally, move the relative coordinate system at the required 
   location in the image. 
   No need to move if relative is already at the required location. */
if (MoveRelativeInTrainingImage)
   {
   McalRelativeOrigin(TrainingImageId, 
                      TrainingX, TrainingY, 0, TrainingAngle,
                      M_DEFAULT);
   }
                      
/* Find the model contained in the Model Finder context ContextId
   in the training image. */
MmodFind(ModContextId, TrainingImageId, ModResultId);

/* Make sure the model is found. */
/* ... */

/* Learn the location of the model reference location in the
   relative coordinate system of the training image. */
McalFixture(M_NULL, FixturingOffsetId, M_LEARN_OFFSET, M_RESULT_MOD,
            ModResultId, 0, /* Model finder result and occurrence index. */
            M_DEFAULT, M_DEFAULT, M_DEFAULT);

/* Critical loop. */
while (!Stop)
   {
   /* Acquire image. */
   /* ... */

   /* Find the model in GrabbedImageId. */
   MmodFind(ModContextId, GrabbedImageId, ModResultId);
  
   /* Make sure the model is found. */
   /* ... */

   /* Move the relative coordinate system of GrabbedImageId, 
      with the learned offset,
      according to the location of the occurrence of the model. */
   McalFixture(GrabbedImageId, FixturingOffsetId, M_MOVE_RELATIVE, M_RESULT_MOD,
               ModResultId, 0, /* Model finder result and occurrence index. */
               M_DEFAULT, M_DEFAULT, M_DEFAULT);

   /* Do some analysis. */
   /* ... */
   }

Fixturing offset to decouple the reference location from the object to analyze

You can also use a fixturing offset object to decouple the reference location from the location of the object to analyze. This might be useful, for example, if you are testing which is the best model to use to establish the reference location. In this case, when setting up the fixturing offset object, you can keep the relative coordinate system fixed at an arbitrary location from the object to analyze, while you try setting up the fixturing offset object on the different reference locations. By keeping the relative coordinate system fixed, you don't have to keep updating the region in which the object to analyze is located with respect to the new relative coordinate system; you just have to learn the offset from the new reference location. While setting up the fixturing offset object, leave the relative coordinate system at its current position or place it at any arbitrary location. This assumes that the actual location of the relative coordinate system is not crucial to the analysis process as long as it is at a fixed location from the object to analyze (for example, you want to fixture the location from which to read a bar code but you don't need to compare the location of the bar code against specifications).

For this case, you can use the following steps to allocate and set up a fixturing offset object:

Allocate a fixturing offset object using McalAlloc() with M_FIXTURING_OFFSET.
Without moving the relative coordinate system, establish a location in the training image. Typically, this is a location that you can automatically establish in the training image (the reference location). This can be, for example, the reference location of a model or a pattern, or the center of gravity of a blob.
Call McalFixture() with M_LEARN_OFFSET, the fixturing offset object, the training image, and the established location. MIL will learn the positional and angular offset that the established location has from the relative coordinate system, and saves it in the fixturing offset object.
At runtime, call McalFixture() with M_MOVE_RELATIVE and the fixturing offset object.

The following animation offers a visual representation of the above steps.

In the example above, we want to read the bar code but we don't care about its precise location on the board; we just want to be able to find the bar code and read it, regardless of its angle or location with respect to the board.

/* Set up phase. */

/* Find the model contained in the Model Finder context ContextId
in the training image. */
MmodFind(ModContextId, TrainingImageId, ModResultId);

/* Make sure the model is found. */
/* ... */

/* Learn the location of the model reference location in the
relative coordinate system of the training image. */
McalFixture(M_NULL, FixturingOffsetId, M_LEARN_OFFSET, M_RESULT_MOD,
  ModResultId, 0, /* Model finder result and occurrence index. */
  M_DEFAULT, M_DEFAULT, M_DEFAULT);

/* Critical loop. */
while (!Stop)
{
  /* Acquire image. */
  /* ... */

  /* Find the model in GrabbedImageId. */
  MmodFind(ModContextId, GrabbedImageId, ModResultId);

  /* Make sure the model is found. */
  /* ... */

  /* Move the relative coordinate system of GrabbedImageId,
  with the learned offset,
  according to the location of the occurrence of the model. */
  McalFixture(GrabbedImageId, FixturingOffsetId, M_MOVE_RELATIVE, M_RESULT_MOD,
    ModResultId, 0, /* Model finder result and occurrence index. */
    M_DEFAULT, M_DEFAULT, M_DEFAULT);

  /* Do some analysis. */
  /* ... */
}

Establishing the positional and angular offset for the fixturing offset object

As mentioned above, to establish the positional and angular offset for the fixturing offset object, you must call McalFixture() with M_LEARN_OFFSET, the fixturing offset object in the training image, and the established reference location that has the required positional and angular offset from the relative coordinate system. There are several ways of specifying the reference location such as:

You can define a Model Finder or Pattern Matching model in the training image, and then pass the Model Finder/Pattern Matching context and model index to McalFixture(). MIL will extract the offset of the reference location of the model from the relative coordinate system of the training image.
You can search for a Model Finder or Pattern Matching model in the training image, and then pass the Model Finder/Pattern Matching result buffer and model occurrence index to McalFixture(). MIL will extract the offset of the model occurrence from the relative coordinate system of the training image.
You can establish the location of the Metrology reference frame in the training image and then pass the identifier of a Metrology result buffer and the index of a Metrology reference frame feature to McalFixture(). MIL will extract the offset and angle of the reference frame feature from the relative coordinate system of the training image.
You can pass the training image and a preestablished position and angle in this image to McalFixture(). MIL will extract the offset of the preestablished position and angle from the relative coordinate system of the training image.

/* First way to learn a fixturing offset. */

/* Define models. */
/* ... */

/* Learn the offset from a Pattern Matching model or from a Model Finder model. */
McalFixture(M_NULL, FixturingOffset1Id, M_LEARN_OFFSET, M_MODEL_PAT, 
            PatContextId, ImageModelDefinitionId,
      0, /* Pattern Matching model index. */ M_DEFAULT, M_DEFAULT);
McalFixture(M_NULL, FixturingOffset2Id, M_LEARN_OFFSET, M_MODEL_MOD, 
            ModContextId, 0, /* Model finder context and model index. */ 
            M_DEFAULT, M_DEFAULT, M_DEFAULT);

/* Second way to learn a fixturing offset. */

/* Find the models in a training image. */
/* ... */

/* Learn the offset from a Pattern Matching result or from a Model Finder result. */
McalFixture(M_NULL, FixturingOffset3Id, M_LEARN_OFFSET, M_RESULT_PAT, 
            PatResultId, 0, /* Pattern matching result and occurrence index. */
            M_DEFAULT, M_DEFAULT, M_DEFAULT);
McalFixture(M_NULL, FixturingOffset4Id, M_LEARN_OFFSET, M_RESULT_MOD, 
            ModResultId, 0, /* Model finder result and occurrence index. */
            M_DEFAULT, M_DEFAULT, M_DEFAULT);

/* Third way to learn a fixturing offset. */

/* Learn the offset from a preestabilished position and angle
   expressed in the relative coordinate system of ImageId. */
McalFixture(M_NULL, FixturingOffset5Id, M_LEARN_OFFSET, M_POINT_AND_ANGLE, 
            ImageId, X, Y, Angle, M_DEFAULT);

To ensure that the appropriate offset has been established, you can draw a line from the current origin of the relative coordinate system to the position that must have been passed to establish the offset. To do so, use McalDraw() with the fixturing offset object and M_DRAW_FIXTURING_OFFSET. This also draws a small arrow at this position, which illustrates the angle that must have been passed.