Probe


Functions

void TecUtilProbeAtFieldPositionX (ArgList_pa ArgList)
  Use this function in concert with TecUtilProbeInstallCallback and TecUtilProbeInstallCallbackX.
void TecUtilProbeAtFieldIndexX (ArgList_pa ArgList)
  Use this function in concert with TecUtilProbeInstallCallback and TecUtilProbeInstallCallbackX.
void TecUtilProbeAtLinePositionX (ArgList_pa ArgList)
  Use this function in concert with TecUtilProbeInstallCallback and TecUtilProbeInstallCallbackX.
void TecUtilProbeAtLineIndexX (ArgList_pa ArgList)
  Use this function in concert with TecUtilProbeInstallCallback and TecUtilProbeInstallCallbackX.
Boolean_t TecUtilProbeInstallCallback (ProbeDestination_pf ProbeDestination, const char *InformationLineText)
  Change the mouse mode to be the probe tool, and instruct Tecplot to call a different function when the user completes a probe operation in the work area.
Boolean_t TecUtilProbeInstallCallbackX (ArgList_pa ArgList)
  Change the mouse mode to be the probe tool, and instruct Tecplot to call a different function when the user completes a probe operation in the work area.
void TecUtilProbeAllowCOBs (void)
  Instructs Tecplot to include COBs (iso-surfaces, slices, streamtraces, and so forth) along with zones during a probe when an add-on has a callback registered with TecUtilProbeInstallCallback() and if the user is pressing the Alt key.
double TecUtilProbeLinePlotGetIndValue (void)
  Call this function from a probe destination callback to get the independent value from the previous probe event in an Line-plot.
Boolean_t TecUtilProbeLinePlotGetDepValue (EntIndex_t MapNum, double *DepValue)
  Call this function from a probe destination callback to get a dependent value from the previous probe event in an Line-plot.
EntIndex_t TecUtilProbeLinePlotGetSourceMap (void)
  Call this function from a probe destination callback to get the Line-map whose point was selected in the previous nearest-point probe.
char TecUtilProbeLinePlotGetIndAxisKind (void)
  Call this function from a probe destination callback to get the indepedent axis kind associated with the line probe.
int TecUtilProbeLinePlotGetIndAxisNumber (void)
  Call this function from a probe destination callback to get the indepedent axis number associated with the line probe.
LgIndex_t TecUtilProbeGetPointIndex (void)
  Call this function from a probe destination callback to get the point index from the previous nearest-point probe event in a field plot or an XY-plot.
CZType_e TecUtilProbeFieldGetCZType (void)
  Indicates type type of COB or zone that was selected during the probe event.
double TecUtilProbeFieldGetValue (EntIndex_t VarNum)
  Call this function from a probe destination callback to get a field variable value from the previous probe event in a field plot.
EntIndex_t TecUtilProbeFieldGetZone (void)
  Call this function from a probe destination callback to get the zone number from the previous probe event in a field plot.
IJKPlanes_e TecUtilProbeFieldGetPlane (void)
  Call this function from a probe destination callback to get the I-, J-, or K-plane from the previous probe event in a field plot.
SmInteger_t TecUtilProbeFieldGetFaceNumber (void)
  Call this function from a probe destination callback to get the face number from the previous probe event in a field plot.
LgIndex_t TecUtilProbeFieldGetFaceCell (void)
  Call this function from a probe destination callback to get the cell from the previous probe event in a field plot.
LgIndex_t TecUtilProbeFieldGetCell (void)
  Call this function from a probe destination callback to get the cell from the previous probe event in a field plot.
Boolean_t TecUtilProbeFieldGetName (char **Name)
  Call this function from a probe destination callback to get the name of the item that was probed.
FieldData_pa TecUtilProbeFieldGetNativeRef (EntIndex_t Var)
  Call this function from a probe destination callback to get a handle to the native data from the probed item for the specified variable.
FieldData_pa TecUtilProbeFieldGetReadableNativeRef (EntIndex_t Var)
  Call this function from a probe destination callback to get a read-only handle to the native data from the probed item for the specified variable.
FieldData_pa TecUtilProbeFieldGetReadableDerivedRef (EntIndex_t Var)
  Call this function from a probe destination callback to get a read-only handle to the derived data from the probed item for the specified variable.
FieldData_pa TecUtilProbeFieldGetReadableNLRef (EntIndex_t Var)
  Call this function from a probe destination callback to get a read-only handle to the node-located data from the probed item for the specified variable.
FieldData_pa TecUtilProbeFieldGetReadableCCRef (EntIndex_t Var)
  Call this function from a probe destination callback to get a read-only handle to the cell-centered data from the probed item for the specified variable.
void TecUtilProbeAtPosSequenceBeginX (ArgList_pa ArgList)
  Begin a sequence of calling TecUtilProbeAtPosition() many times.
void TecUtilProbeAtPosSequenceEnd (void)
  End a sequence of calling TecUtilProbeAtPosition() many times.
Boolean_t TecUtilProbeAtPosition (double X, double Y, double Z, LgIndex_t *ICell, LgIndex_t *JCell, LgIndex_t *KCell, IJKPlanes_e *Plane, EntIndex_t *CurZone, Boolean_t StartWithLocalCell, double *VValue_Array, Set_pa SourceZones, Boolean_t SearchVolume, Boolean_t GetZoneOnly, Boolean_t GetNearestPoint)
  Use Tecplot's probe capability to return field values at a specified X, Y, [Z] location.

Function Documentation

void TecUtilProbeAllowCOBs ( void   ) 

Instructs Tecplot to include COBs (iso-surfaces, slices, streamtraces, and so forth) along with zones during a probe when an add-on has a callback registered with TecUtilProbeInstallCallback() and if the user is pressing the Alt key.

By default the Alt key is ignored for an add-on's installed probe callback. This function should be called after TecUtilProbeInstallCallback().

Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    SUBROUTINE TecUtilProbeAllowCOBs()

Python Syntax:

  Results = TecUtil.ProbeAllowCOBs()

  Output:
    Results[0]    ReturnVal            NONE

void TecUtilProbeAtFieldIndexX ( ArgList_pa  ArgList  ) 

Use this function in concert with TecUtilProbeInstallCallback and TecUtilProbeInstallCallbackX.

Calling this function will call the most recently installed probe callback.

Parameters:
ArgList Set of Arglist entries. This is built using calls to TecUtilArgListAppendXXXX functions.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

ArgList Argument list must be valid.



Arglist Values

SV_I
Type: LgIndex_t
Arg Function: TecUtilArgListAppendInt()
Default: 1
Required: No
Notes: I-Index at which to probe.

SV_J
Type: LgIndex_t
Arg Function: TecUtilArgListAppendInt()
Default: 1
Required: No
Notes: J-Index at which to probe.

SV_K
Type: LgIndex_t
Arg Function: TecUtilArgListAppendInt()
Default: 1
Required: No
Notes: K-Index at which to probe.

SV_ZONE
Type: EntIndex_t
Arg Function: TecUtilArgListAppendInt()
Required: Yes
Notes: The zone for this to perform the probe


Python Syntax:

  Results = TecUtil.ProbeAtFieldIndexX(ArgList)

  Input:
                  ArgList              dictionary
  Output:
    Results[0]    ReturnVal            NONE

See also:
TecUtilProbeInstallCallback, TecUtilProbeInstallCallbackX, TecUtilProbeAtFieldPositionX

void TecUtilProbeAtFieldPositionX ( ArgList_pa  ArgList  ) 

Use this function in concert with TecUtilProbeInstallCallback and TecUtilProbeInstallCallbackX.

Calling this function will call the most recently installed probe callback.

Parameters:
ArgList Set of Arglist entries. This is built using calls to TecUtilArgListAppendXXXX functions.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

ArgList Argument list must be valid or NULL.



Arglist Values

SV_X
Type: double
Arg Function: TecUtilArgListAppendDouble()
Required: Yes
Notes: X-position at which to probe.

SV_Y
Type: double
Arg Function: TecUtilArgListAppendDouble()
Required: Yes
Notes: Y-position at which to probe.

SV_Z
Type: double
Arg Function: TecUtilArgListAppendDouble()
Default: 0.0
Required: No
Notes: The Z-position at which to probe. Only required if plot type is 3D.

SV_ZONESET
Type: Set_pa
Arg Function: TecUtilArgListAppendSet()
Default: NULL
Required: No
Notes: The set of zones to which to limit the search. If not supplied all zones will be searched.

SV_SEARCHVOLUME
Type: Boolean_t
Arg Function: TecUtilArgListAppendInt()
Default: TRUE
Required: No
Notes: Set to TRUE if the XYZ coordinates represent a data point inside of a 3-D volume zone. Set to FALSE to use the XY coordinates only which will return a point on the surface of a zone. Ignored when plot type is 2D Cartesian

SV_PROBEATFIELDPOSITIONRESULT
Type: ArbParam_t
Arg Function: TecUtilArgListAppendArbParam()
Default: 0
Required: No
Notes: Pass the address of a Boolean_t variable which will receive the result of the 3D probe. The result will be TRUE if probe succeeded, FALSE otherwise.


Python Syntax:

  Results = TecUtil.ProbeAtFieldPositionX(ArgList)

  Input:
                  ArgList              dictionary
  Output:
    Results[0]    ReturnVal            NONE


   // Install the probe callback
   ArgList_pa argList = TecUtilArgListAlloc();
   TecUtilArgListAppendFunction(argList, SV_CALLBACKFUNCTION, MyProbeCallback);
   TecUtilArgListAppendString(argList, SV_STATUSLINETEXT, "My probe information text");
   TecUtilArgListAppendArbParam(argList, SV_CLIENTDATA, 0);
   TecUtilProbeInstallCallbackX(argList);

   // Clear the argument list to ready it for TecUtilProbeAtFieldPositionX
   TecUtilArgListClear(argList);

   // Do the probe
   TecUtilArgListAppendDouble(argList, SV_X, 0.5);
   TecUtilArgListAppendDouble(argList, SV_Y, 0.2);
   TecUtilProbeAtFieldPositionX(argList);
   TecUtilArgListDealloc(&argList);

   // This function is called by TecUtilProbeAtFieldPositionX
   void MyProbeCallback(Boolean_t  wasSuccessful,
                                Boolean_t  isNearestPoint,
                                ArbParam_t clientData)
   {
     TecUtilLockStart(AddOnID);
     if ( wasSuccessful )
       {
         ...
         Call TecUtilProbeXXXGetXXX functions to extract probe information
         ...
       }
     TecUtilLockFinish(AddOnID);
   }

See also:
TecUtilProbeInstallCallback, TecUtilProbeInstallCallbackX

void TecUtilProbeAtLineIndexX ( ArgList_pa  ArgList  ) 

Use this function in concert with TecUtilProbeInstallCallback and TecUtilProbeInstallCallbackX.

Calling this function will call the most recently installed probe callback.

Parameters:
ArgList Set of Arglist entries. This is built using calls to TecUtilArgListAppendXXXX functions.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

ArgList Argument list must be valid.



Arglist Values

SV_I
Type: LgIndex_t
Arg Function: TecUtilArgListAppendInt()
Default: 1
Required: No
Notes: I-Index at which to probe.

SV_J
Type: LgIndex_t
Arg Function: TecUtilArgListAppendInt()
Default: 1
Required: No
Notes: J-Index at which to probe.

SV_K
Type: LgIndex_t
Arg Function: TecUtilArgListAppendInt()
Default: 1
Required: No
Notes: K-Index at which to probe.

SV_LINEMAP
Type: EntIndex_t
Arg Function: TecUtilArgListAppendInt()
Required: Yes
Notes: The line-map on which to probe


Python Syntax:

  Results = TecUtil.ProbeAtLineIndexX(ArgList)

  Input:
                  ArgList              dictionary
  Output:
    Results[0]    ReturnVal            NONE

See also:
TecUtilProbeInstallCallback, TecUtilProbeInstallCallbackX, TecUtilProbeAtFieldIndexX

void TecUtilProbeAtLinePositionX ( ArgList_pa  ArgList  ) 

Use this function in concert with TecUtilProbeInstallCallback and TecUtilProbeInstallCallbackX.

Calling this function will call the most recently installed probe callback.

Parameters:
ArgList Set of Arglist entries. This is built using calls to TecUtilArgListAppendXXXX functions.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

ArgList Argument list must be valid.



Arglist Values

SV_POSITION
Type: double
Arg Function: TecUtilArgListAppendDouble()
Required: Yes
Notes: Position along the line at which to probe

SV_AXIS
Type: char
Arg Function: TecUtilArgListAppendInt()
Required: Yes
Notes: 'X' or 'Y' for XY-Line plots 'T' or 'R' for Polar-Line plots

SV_AXISNUM
Type: EntIndex_t
Arg Function: TecUtilArgListAppendInt()
Default: 1
Required: No
Notes: If the plot type is PlotType_XYLine there are up to 5 X- and Y- axes. This parameter specifies the axis index on which to probe.


Python Syntax:

  Results = TecUtil.ProbeAtLinePositionX(ArgList)

  Input:
                  ArgList              dictionary
  Output:
    Results[0]    ReturnVal            NONE

See also:
TecUtilProbeInstallCallback, TecUtilProbeInstallCallbackX, TecUtilProbeAtFieldPositionX

Boolean_t TecUtilProbeAtPosition ( double  X,
double  Y,
double  Z,
LgIndex_t *  ICell,
LgIndex_t *  JCell,
LgIndex_t *  KCell,
IJKPlanes_e *  Plane,
EntIndex_t *  CurZone,
Boolean_t  StartWithLocalCell,
double *  VValue_Array,
Set_pa  SourceZones,
Boolean_t  SearchVolume,
Boolean_t  GetZoneOnly,
Boolean_t  GetNearestPoint 
)

Use Tecplot's probe capability to return field values at a specified X, Y, [Z] location.

The current frame must have an attached data set when this function is called and the frame must be in 2D or 3D. This function is Thread Safe.

Parameters:
X The X-position at which to probe.
Y The Y-position at which to probe.
Z The Z-position at which to probe. Only required if plot type is 3D. If the frame mode is 3D and SearchVolume is FALSE, then only X and Y are used and they are assumed to be the XY coordinates in the eye coordinate system. The returned probe will be the location on the first surface encountered in the eye coordinate system
ICell For Ordered data this returns the I-Index of the cell in which the data point was found. If StartWithLocalCell is TRUE, then this must be pre-set to the I-index of the cell in which to start looking.
For Finite-Element data and GetNearestPoint is TRUE this returns the node number of the probed point. If GetNearestPoint is FALSE this value should be ignored.

Parameters:
JCell For Ordered data this returns the J-Index of the cell in which the data point was found. If StartWithLocalCell is TRUE, then this must be pre-set to the J-index of the cell in which to start looking.
For Finite-Element data this returns the element number of the cell in which the probe occurred.

Parameters:
KCell Returns the K-Index of the cell in which the data point was found. If StartWithLocalCell is TRUE, then this must be pre-set to the K-index of the cell in which to start looking.
For Finite-Element data this value should be ignored.

Parameters:
Plane If the current frame is 3D, the plane of the cell in which the data point was found is returned. (Ignore if SearchVolume is TRUE.) Plane must be pre-set if the current frame is 2D and StartWithLocalCell is TRUE and the zone is not finite element. Plane can be one of: IJKPlanes_I IJKPlanes_J IJKPlanes_K
CurZone Returns the zone of the cell in which the data point was found
StartWithLocalCell TRUE if the search should be started in the area of cell *ICell,*JCell,*KCell. FALSE if the search should not be started in any particular cell
VValue_Array An array of doubles which is the size of the number of variables in the data set. The array must be allocated by the calling function. If TecUtilProbeAtPosition() returns TRUE and GetZoneOnly is FALSE, the array will be filled with the values of each variable at the probed position
SourceZones The set of zones to which to limit the search. Set to NULL to search all zones
SearchVolume Set to TRUE if the XYZ coordinates represent a data point inside of a 3-D volume zone. Set to FALSE to use the XY coordinates only which will return a point on the surface of a zone
GetZoneOnly Set to TRUE to do the minimal work necessary to only update the CurZone variable
GetNearestPoint TRUE to return values for the nearest grid point, FALSE to return interpolated values for the exact XYZ coordinates. A value of TRUE will cause this function to return FALSE if the initial probe does not fall within a cell
Returns:
TRUE if successful, FALSE otherwise. FALSE usually indicates that the data point could not be found however it could also mean that the probe was interrupted by the user or failed to load variables. You can check for interrupt by calling TecUtilInterruptCheck() or if you are using the status line family of functions, TecUtilStatusXxxxPercentDone, during the probe then calling TecUtilStatusCheckPercentDone() will tell you if Tecplot was interrupted, thereby providing more complete information about why TecUtilProbeAtPosition() returned FALSE.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

ICell Pointer must be a valid address and non-NULL.

JCell Pointer must be a valid address and non-NULL.

KCell Pointer must be a valid address and non-NULL.

Plane Pointer must be a valid address and non-NULL.

CurZone Pointer must be a valid address and non-NULL.

VALID_REF(VValue) Pointer must be a valid address and non-NULL.

SourceZones Pointer must be a valid address or NULL.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeAtPosition(
   &                   X,
   &                   Y,
   &                   Z,
   &                   ICell,
   &                   JCell,
   &                   KCell,
   &                   Plane,
   &                   CurZone,
   &                   StartWithLocalCell,
   &                   VValue_Array,
   &                   SourceZonesPtr,
   &                   SearchVolume,
   &                   GetZoneOnly,
   &                   GetNearestPoint)
    REAL*8          X
    REAL*8          Y
    REAL*8          Z
    INTEGER*4       ICell
    INTEGER*4       JCell
    INTEGER*4       KCell
    INTEGER*4       Plane
    INTEGER*4       CurZone
    INTEGER*4       StartWithLocalCell
    REAL*8          VValue_Array
    POINTER         (SourceZonesPtr, SourceZones)
    INTEGER*4       SearchVolume
    INTEGER*4       GetZoneOnly
    INTEGER*4       GetNearestPoint

Python Syntax:

    This function is not supported in Python.

Assuming a 2-D plot, probe at the location (3.2, 1.45):

   LgIndex_t    ICell, JCell, KCell;
   IJKPlanes_e  Plane;
   EntIndex_t   SourceZone;
   EntIndex_t   NumVars;
   double      *VValues;

   TecUtilDataSetGetInfo((char **)NULL,
                         (EntIndex_t *)NULL,
                          &NumVars);

   VValues = (double *)malloc(NumVars*sizeof(double));

   if (TecUtilProbeAtPosition(3.2, 1.45, 0.0,
                              &ICell,
                              &JCell,
                              &KCell,
                              &Plane,
                              &SourceZone,
                              FALSE,
                              VValues,
                              (Set_pa )NULL,
                              FALSE,
                              FALSE,
                              FALSE))
      {
        // Look at VValues[VarNum-1] to find the
        // value for a particular variable.

        LgIndex_t PointIndex;
        if ( TecUtilZoneIsOrdered(SourceZone) )
          {
            // Determine the primary point for the cell that was probed
            LgIndex_t IMax, JMax, KMax;
            TecUtilZoneGetIJK(SourceZone, &IMax, &JMax, &KMax);
            PointIndex = 1 + (ICell-1) + (JCell-1)*IMax + (KCell-1)*IMax*JMax;
          }
        else
          {
            // Determine the node number for the 1st corner of the probed element
            PointIndex = TecUtilDataNodeGetByZone(SourceZone, JCell, 1);
            // If we'd done a NearestPoint probe:
            // PointIndex = ICell;
          }
      }
    free(VValues);

void TecUtilProbeAtPosSequenceBeginX ( ArgList_pa  ArgList  ) 

Begin a sequence of calling TecUtilProbeAtPosition() many times.

The following rules must be obeyed between TecUtilProbeAtPosSequenceBeginX() and TecUtilProbeAtPosSequenceEnd() calls: 

     - Do not make any calls that will change the style of the plot.
     - Do not make any calls that will re-order or replace zones in
       the underlying dataset (i.e. push or pop frames, load data, delete
       zones etc.).
     - Once a sequence has been started you MUST end the sequence
       even if there was a failure of any sort in the intervening code.

Parameters:
ArgList Set of Arglist entries. THIS PARAMETER IS RESERVED FOR FUTURE USE AND IS CURRENTLY NOT USED. YOU MUST SET THIS TO NULL.
Assuming a 2-D plot, probe at 100 locations with Y = 1.45 and X varying between 1.0 and 100.0. Assume that once a "hit" is discovered in a zone that the next hit will be nearby in that same zone. 
   LgIndex_t    ICell, JCell, KCell;
   IJKPlanes_e  Plane;
   Boolean_t    StartWithLocalCell = FALSE;
   EntIndex_t   SourceZone;
   EntIndex_t   NumVars;
   double      *VValues;
   int          IX;

   TecUtilDataSetGetInfo((char **)NULL,
                         (EntIndex_t *)NULL,
                          &NumVars);

   VValues = (double *)malloc(NumVars*sizeof(double));

   TecUtilProbeAtPosSequenceBeginX((ArgList_pa)NULL);

   for (IX = 1; IX <= 100; IX++)
     {
       if (TecUtilProbeAtPosition((double)IX,
                                  1.45,
                                  0.0,
                                  &ICell,
                                  &JCell,
                                  &KCell,
                                  &Plane,
                                  &SourceZone,
                                  StartWithLocalCell,
                                  VValues,
                                  (Set_pa )NULL,
                                  FALSE,
                                  FALSE,
                                  FALSE))

         {
             // Look at VValues[VarNum-1] to find the
             // value for a particular variable.

            StartWithLocalCell = TRUE;
         }
       else
         StartWithLocalCell = FALSE;
     }

    TecUtilProbeAtPosSequenceEnd();

Fortran Syntax:

    SUBROUTINE TecUtilProbeAtPosSequenceBeginX(ArgListPtr)
    POINTER (ArgListPtr, ArgList)

Python Syntax:

  Results = TecUtil.ProbeAtPosSequenceBeginX(ArgList)

  Input:
                  ArgList              dictionary
  Output:
    Results[0]    ReturnVal            NONE

void TecUtilProbeAtPosSequenceEnd ( void   ) 

End a sequence of calling TecUtilProbeAtPosition() many times.

See TecUtilProbeAtPosSequenceEnd() for an details and an example.

Fortran Syntax:

    SUBROUTINE TecUtilProbeAtPosSequenceEnd()

Python Syntax:

  Results = TecUtil.ProbeAtPosSequenceEnd()

  Output:
    Results[0]    ReturnVal            NONE

LgIndex_t TecUtilProbeFieldGetCell ( void   ) 

Call this function from a probe destination callback to get the cell from the previous probe event in a field plot.

Note:
For all zone types other than ordered volume data this function returns the same information as TecUtilProbeFieldGetFaceCell(). For ordered volume data the distinction is that this function returns the volume cell whereas TecUtilProbeFieldGetFaceCell() returns the face cell.
Returns:
The index of the cell which was probed. For ordered data, this is equivalent to the index value of the node in the lowest indexed corner of the cell. For finite-element data, this is the element number.
A return value of zero indicates that no cell was probed. This may occur on nearest point probes.

Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeFieldGetCell()

Python Syntax:

  Results = TecUtil.ProbeFieldGetCell()

  Output:
    Results[0]    ReturnVal            int

CZType_e TecUtilProbeFieldGetCZType ( void   ) 

Indicates type type of COB or zone that was selected during the probe event.

Returns:
Type of COB selected by the probe. This can be one of seven values: CZType_FieldDataZone CZType_FEBoundaryCOB CZType_IsoSurfaceCOB CZType_SliceCOB CZType_StreamtraceCOB CZType_StreamtraceMarkerCOB CZType_StreamtraceArrowheadCOB.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeFieldGetCZType()

Python Syntax:

  Results = TecUtil.ProbeFieldGetCZType()

  Output:
    Results[0]    ReturnVal            CZType_e  (defined in TecVals.py)

LgIndex_t TecUtilProbeFieldGetFaceCell ( void   ) 

Call this function from a probe destination callback to get the cell from the previous probe event in a field plot.

Note:
For all zone types other than ordered volume data this function returns the same information as TecUtilProbeFieldGetCell(). For ordered volume data the distinction is that this function returns the face cell whereas TecUtilProbeFieldGetCell() returns the volume cell.
Returns:
The index of the cell which was probed. For ordered data, this is equivalent to the index value of the node in the lowest indexed corner of the face cell. For finite-element data, this is the element number.
A return value of zero indicates that no face was probed. This may occur on nearest point probes.

Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeFieldGetFaceCell()

Python Syntax:

  Results = TecUtil.ProbeFieldGetFaceCell()

  Output:
    Results[0]    ReturnVal            int

SmInteger_t TecUtilProbeFieldGetFaceNumber ( void   ) 

Call this function from a probe destination callback to get the face number from the previous probe event in a field plot.

Returns:
The face number of the cell that was probed. For ordered volume and FE brick data the value is between 1 and 6. For ordered surface, FE tetra, and FE quandrangle data the value is between 1 and 4. For FE triangular data the value is between 1 and 3. For ordered or FE linear data the value is 0.
A return value of zero indicates that no face was probed. This may occur on nearest point probes.

Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeFieldGetFaceNumber()

Python Syntax:

  Results = TecUtil.ProbeFieldGetFaceNumber()

  Output:
    Results[0]    ReturnVal            int

Boolean_t TecUtilProbeFieldGetName ( char **  Name  ) 

Call this function from a probe destination callback to get the name of the item that was probed.

This may return a zone name if a zone was probed, or a COB name if TecUtilProbeAllowCOBs was called when the probe destination callback was installed.

Parameters:
Name Receives the name of the last-probed item. You must free the returned string with TecUtilStringDealloc().
Returns:
TRUE if successful, FALSE if not. FALSE usually indicates the Name string was unable to be allocated.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Name Pointer must be a valid address and non-NULL.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeFieldGetName(
   &                   Name,
   &                   NameLength)
    CHARACTER*(*)   ZName
    INTEGER*4       ZNameLength

Python Syntax:

  Results = TecUtil.ProbeFieldGetName()

  Output:
    Results[0]    ReturnVal            boolean
    Results[1]    Name                 string

FieldData_pa TecUtilProbeFieldGetNativeRef ( EntIndex_t  Var  ) 

Call this function from a probe destination callback to get a handle to the native data from the probed item for the specified variable.

Note that no attempt is made to make the data readable; if data access is needed, use TecUtilProbeFieldGetReadableNativeRef instead. This method can be used to query for information about the variable without causing the data to be loaded.

This function is Thread Safe.

Parameters:
Var Number of the variable for which to get the field data
Returns:
A field data handle to the native data for the probed item and specified variable.
Since:
12.0-1-5558
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    SUBROUTINE TecUtilProbeFieldGetNativeRef(
   &           Var,
   &           ResultPtr)
    INTEGER*4       Var
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.ProbeFieldGetNativeRef(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    ReturnVal            opaque pointer

IJKPlanes_e TecUtilProbeFieldGetPlane ( void   ) 

Call this function from a probe destination callback to get the I-, J-, or K-plane from the previous probe event in a field plot.

Returns:
The plane which was probed. This can be one of IJKPlanes_I, IJKPlanes_J, or IJKPlanes_K.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeFieldGetPlane()

Python Syntax:

  Results = TecUtil.ProbeFieldGetPlane()

  Output:
    Results[0]    ReturnVal            IJKPlanes_e  (defined in TecVals.py)

FieldData_pa TecUtilProbeFieldGetReadableCCRef ( EntIndex_t  Var  ) 

Call this function from a probe destination callback to get a read-only handle to the cell-centered data from the probed item for the specified variable.

This function is Thread Safe.

Parameters:
Var Number of the variable for which to get the field data
Returns:
A read-only field data handle to the cell-centered data for the probed item and specified variable, or NULL if Tecplot was not able to load the data.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    SUBROUTINE TecUtilProbeFieldGetReadableCCR(
   &           Var,
   &           ResultPtr)
    INTEGER*4       Var
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.ProbeFieldGetReadableCCRef(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    ReturnVal            opaque pointer

FieldData_pa TecUtilProbeFieldGetReadableDerivedRef ( EntIndex_t  Var  ) 

Call this function from a probe destination callback to get a read-only handle to the derived data from the probed item for the specified variable.

This function is Thread Safe.

Parameters:
Var Number of the variable for which to get the field data
Returns:
A read-only field data handle to the derived data for the probed item and specified variable, or NULL if Tecplot was not able to load the data.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    SUBROUTINE TecUtilProbeFieldGetReadableDer(
   &           Var,
   &           ResultPtr)
    INTEGER*4       Var
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.ProbeFieldGetReadableDerivedRef(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    ReturnVal            opaque pointer

FieldData_pa TecUtilProbeFieldGetReadableNativeRef ( EntIndex_t  Var  ) 

Call this function from a probe destination callback to get a read-only handle to the native data from the probed item for the specified variable.

This function is Thread Safe.

Parameters:
Var Number of the variable for which to get the field data
Returns:
A read-only field data handle to the native data for the probed item and specified variable, or NULL if Tecplot was not able to load the data.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    SUBROUTINE TecUtilProbeFieldGetReadableNat(
   &           Var,
   &           ResultPtr)
    INTEGER*4       Var
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.ProbeFieldGetReadableNativeRef(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    ReturnVal            opaque pointer

FieldData_pa TecUtilProbeFieldGetReadableNLRef ( EntIndex_t  Var  ) 

Call this function from a probe destination callback to get a read-only handle to the node-located data from the probed item for the specified variable.

This function is Thread Safe.

Parameters:
Var Number of the variable for which to get the field data
Returns:
A read-only field data handle to the node-located data for the probed item and specified variable, or NULL if Tecplot was not able to load the data.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    SUBROUTINE TecUtilProbeFieldGetReadableNLR(
   &           Var,
   &           ResultPtr)
    INTEGER*4       Var
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.ProbeFieldGetReadableNLRef(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    ReturnVal            opaque pointer

double TecUtilProbeFieldGetValue ( EntIndex_t  VarNum  ) 

Call this function from a probe destination callback to get a field variable value from the previous probe event in a field plot.

Parameters:
VarNum The variable number for which to get the field value.
Returns:
The value for variable VarNum at the previous probe data point.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    REAL*8 FUNCTION TecUtilProbeFieldGetValue(VarNum)
    INTEGER*4 VarNum

Python Syntax:

  Results = TecUtil.ProbeFieldGetValue(VarNum)

  Input:
                  VarNum               int
  Output:
    Results[0]    ReturnVal            double

EntIndex_t TecUtilProbeFieldGetZone ( void   ) 

Call this function from a probe destination callback to get the zone number from the previous probe event in a field plot.

Returns:
The number of the zone which was probed.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeFieldGetZone()

Python Syntax:

  Results = TecUtil.ProbeFieldGetZone()

  Output:
    Results[0]    ReturnVal            int

LgIndex_t TecUtilProbeGetPointIndex ( void   ) 

Call this function from a probe destination callback to get the point index from the previous nearest-point probe event in a field plot or an XY-plot.

In order to use this function, the value passed to the probe destination callback must have been TRUE, indicating a nearest-point probe.

Returns:
The index of the data point selected in the previous nearest point probe.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeGetPointIndex()

Python Syntax:

  Results = TecUtil.ProbeGetPointIndex()

  Output:
    Results[0]    ReturnVal            int

Boolean_t TecUtilProbeInstallCallback ( ProbeDestination_pf  ProbeDestination,
const char *  InformationLineText 
)

Change the mouse mode to be the probe tool, and instruct Tecplot to call a different function when the user completes a probe operation in the work area.

This function callback will remain in effect until the mouse mode is changed. In order to call this function, the current plot type must not be Sketch.

Note that by default, probes on COBs (iso-surfaces, slices, streamtraces, and so forth) will not trigger a callback. To obtain this behavior, call TecUtilProbeAllowCOBs() after installing the callback.

Parameters:
ProbeDestination Function to call when the probe event takes place.
InformationLineText Text to write on the status line when the override is in effect.
Returns:
TRUE if successfully installed.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

InformationLineText Pointer must be a valid address or NULL.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeInstallCallback(
   &                   ProbeDestination,
   &                   InformationLineText)
    EXTERNAL        ProbeDestination
    CHARACTER*(*)   InformationLineText

Python Syntax:

    This function is not supported in Python.

Override the behavior of the probe tool in Tecplot. When a probe occurs, just print out the results of the probe to simulate some of the capabilities of the probe dialogs in Tecplot. The task is to provide a mechanism whereby your own probe callback overrides the default behavior when a probe event occurs in Tecplot. One way to do this is to add an option to the Tools menu in Tecplot. The callback function assigned to the menu option would then turn around and install the probe callback with the following code: .

   .
   TecUtilProbeInstallCallback(MyProbeCallback,
                       "Click to print out my probe information");
   .
   TecUtilProbeAllowCOBs()
   .

   The function MyProbeCallback is then defined as:
   void MyProbeCallback(Boolean_t IsNearestPoint)
   {
     FrameMode_e FrameMode;
     TecUtilLockStart(AddOnID);
     FrameMode = TecUtilFrameGetMode();

     if (FrameMode == Frame_XY)
       {
         printf("XY Probe, Independent value is: %G\n",
                TecUtilProbeLinePlotGetIndValue());
         if (IsNearestPoint)
           {
             double DepValue;
             TecUtilProbeXYGetDepValue(1,&DepValue);
             printf("Nearest Point:  Dependent Value = %G\n",
                    DepValue);
             printf("                Source LineMap    = %d\n",
                    TecUtilProbeLinePlotGetMap());
             printf("                Point Index     = %d\n",
                    TecUtilProbeGetPointIndex());
           }
         else
           {
             EntIndex_t M;
             for (M = 1; M <= TecUtilLineMapGetCount(); M++)
               {
                 double DepValue;
                 printf("LineMap = %02d, Dependent Value = ",M);
                 if (TecUtilProbeLinePlotGetDepValue(M,&DepValue))
                   printf("%G\n",DepValue);
                 else
                   printf("Unknown\n");
               }
           }
       }
     else
       {
         EntIndex_t  SourceZone = TecUtilProbeFieldGetZone();
         ZoneType_e  ZoneType   = TecUtilZoneGetType(SourceZone);
         IJKPlanes_e Plane      = TecUtilProbeFieldGetPlane();
         EntIndex_t  V;
         EntIndex_t  NumVars;

         TecUtilDataSetGetInfo((char **)NULL,
                               (EntIndex_t *)NULL,
                               &NumVars);

         if (IsNearestPoint)
           printf("Nearest point probe:\n");
         else
          {
            LgIndex_t ProbeCell = TecUtilProbeFieldGetCell();
            printf("Interpolated  probe:(Cell = %d)\n",ProbeCell);
          }

         for (V = 1; V <= NumVars; V++)
           {
             char *VName;
             if (TecUtilVarGetName(V,&VName))
               {
                 printf("%20s : ",VName);
                 TecUtilStringDealloc(&VName);
               }
             else
               printf("<Unknown>            : ");
             printf("%G\n",TecUtilProbeFieldGetValue(V));
           }
       }
     TecUtilLockFinish(AddOnID);
   }
   A complete example can be found in the probtest sample add-on included in the distribution.

See also:
TecUtilProbeInstallCallbackX, TecUtilProbeAllowCOBs

Boolean_t TecUtilProbeInstallCallbackX ( ArgList_pa  ArgList  ) 

Change the mouse mode to be the probe tool, and instruct Tecplot to call a different function when the user completes a probe operation in the work area.

This function callback will remain in effect until the mouse mode is changed. In order to call this function, the current plot type must not be Sketch.

Note that, unlike TecUtilProbeInstallCallback, installing a callback via this function will always allows probes on COBs (iso-surfaces, slices, streamtraces, and so forth). So TecUtilProbeAllowCOBs need not be called afterwards.

Parameters:
ArgList Set of Arglist entries. This is built using calls to TecUtilArgListAppendXXXX functions.


Arglist Values

SV_CALLBACKFUNCTION
Type: ProbeDestinationX_pf
Arg Function: TecUtilArgListAppendFunction()
Required: Yes
Notes: Function to call when the probe event takes place.

SV_STATUSLINETEXT
Type: char*
Arg Function: TecUtilArgListAppendString()
Default: NULL
Required: No
Notes: Text to write on the status line when the override is in effect.

SV_CLIENTDATA
Type: ArbParam_t
Arg Function: TecUtilArgListAppendArbParam()
Default: 0
Required: No
Notes: Client data to be sent to the callback as a parameter.


Returns:
TRUE if successfully installed.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

ArgList Argument list must be valid.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeInstallCallback(
   &                   ProbeDestination,
   &                   InformationLineText)
    EXTERNAL        ProbeDestination
    CHARACTER*(*)   InformationLineText

Python Syntax:

    This function is not supported in Python.

See also:
TecUtilProbeInstallCallback

Boolean_t TecUtilProbeLinePlotGetDepValue ( EntIndex_t  MapNum,
double *  DepValue 
)

Call this function from a probe destination callback to get a dependent value from the previous probe event in an Line-plot.

Parameters:
MapNum Number of the Line-map to query for its dependent value at the previous probe.
DepValue Dependent value resulting from previous probe. This parameter is ignored if the previous probe was a nearest-point probe.
Returns:
TRUE if the dependent value for the selected Line-map number is valid, otherwise FALSE. A dependent value can be invalid if a probe occurs outside the range of the independent variable for a given Line-map.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

DepValue Pointer must be a valid address and non-NULL.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeLinePlotGetDepValue(
   &                   MapNum,
   &                   DepValue)
    INTEGER*4       MapNum
    REAL*8          DepValue

Python Syntax:

  Results = TecUtil.ProbeLinePlotGetDepValue(MapNum)

  Input:
                  MapNum               int
  Output:
    Results[0]    ReturnVal            boolean
    Results[1]    DepValue             double

char TecUtilProbeLinePlotGetIndAxisKind ( void   ) 

Call this function from a probe destination callback to get the indepedent axis kind associated with the line probe.

Together with TecUtilProbeLinePlotGetIndAxisNumber, this allows one to determine the axis associated with the value returned from TecUtilProbeLinePlotGetDepValue.

Returns:
The axis kind, either 'X', 'Y', 'T' (theta), or 'R' (radial).
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeLinePlotGetIndAxisK()

Note:
IMPORTANT! Note that the FORTRAN Name for this function is truncated to 31 characters!
Python Syntax:
  Results = TecUtil.ProbeLinePlotGetIndAxisKind()

  Output:
    Results[0]    ReturnVal            int

int TecUtilProbeLinePlotGetIndAxisNumber ( void   ) 

Call this function from a probe destination callback to get the indepedent axis number associated with the line probe.

Together with TecUtilProbeLinePlotGetIndAxisKind, this allows one to determine the axis associated with the value returned from TecUtilProbeLinePlotGetDepValue.

Returns:
The axis number. For Polar Line plots, this will always be one. For XY Line plots, this will be a number between MaxXAxes or MaxYAxes.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeLinePlotGetIndAxisN()

Note:
IMPORTANT! Note that the FORTRAN Name for this function is truncated to 31 characters!
Python Syntax:
  Results = TecUtil.ProbeLinePlotGetIndAxisNumber()

  Output:
    Results[0]    ReturnVal            int

double TecUtilProbeLinePlotGetIndValue ( void   ) 

Call this function from a probe destination callback to get the independent value from the previous probe event in an Line-plot.

Returns:
The independent value from the previous probe event.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    REAL*8 FUNCTION TecUtilProbeLinePlotGetIndValue()

Python Syntax:

  Results = TecUtil.ProbeLinePlotGetIndValue()

  Output:
    Results[0]    ReturnVal            double

EntIndex_t TecUtilProbeLinePlotGetSourceMap ( void   ) 

Call this function from a probe destination callback to get the Line-map whose point was selected in the previous nearest-point probe.

In order to use this function, the value passed to the probe destination callback must have been TRUE, indicating a nearest-point probe.

Returns:
The number of the Line-map.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilProbeLinePlotGetSourceMap()

Note:
IMPORTANT! Note that the FORTRAN Name for this function is truncated to 31 characters!
Python Syntax:
  Results = TecUtil.ProbeLinePlotGetSourceMap()

  Output:
    Results[0]    ReturnVal            int

Generated on Wed Oct 7 14:56:17 2009 for Tecplot by  doxygen 1.5.5