Example of Working with the Line Object

This example demonstrates displaying and modifying properties of a line object. This example uses a console menu that represents the following operations: getting and setting the start point [S], end point [E], normal [N], and thickness [T]; computing the features at a parameter [Z]; displaying the object properties, general properties, computed properties, and specific properties [P]; and modifying the general entity properties [M].

The PrintLineProperties() function requires a pointer to an existing line object and displays its specific properties. The function gets the specific properties using the startPoint(), endPoint(), normal(), and thickness() methods. The function uses the AboutPoint3d() function for converting the coordinates of the start and end points to a string value and the AboutVector3d() function for converting the coordinates of the normal to a string value. The AboutPoint3d() and AboutVector3d() functions require an instance of the three-dimensional point or three-dimensional vector to be converted as an argument and return a string containing the X,Y,Z coordinates.

The PrintLineProperties() function has the following implementation:


void PrintLineProperties(OdDbLine* pLine)
{
  wcout << L"\n  Normal = " << AboutVector3d(pLine->normal())
        << L"\n  Start point = " << AboutPoint3d(pLine->startPoint())
        << L"\n  End point = " << AboutPoint3d(pLine->endPoint())
        << L"\n  Thickness = " << pLine->thickness();
}

The PrintLineFeatures() function requires a pointer to an existing line object and displays the properties computed at a parameter (features). The function uses the getStartPoint(), getEndPoint(), getStartParam(), getEndParam(), getArea(), getDistAtParam(), getParamAtDist(), getPointAtParam(), getFirstDeriv(), getSecondDeriv(), and getPlane() methods, and also uses the AboutPoint3d() and AboutVector3d() functions. The parameter is the distance measured from the start point. The length is calculated as the distance from the start point to the end point computed at a parameter. The area is zero. The middle point is calculated at half-length. The first and second derivatives are vectors which are computed at the parameter and are constant for any point on the line. A line is an entity that has an arbitrary plane passed through it, and the function gets and displays the coefficients of the arbitrary plane using the AboutPlane() function.

The PrintLineFeatures() function has the following implementation:


void PrintLineFeatures(OdDbLine* pLine)
{
  OdGePlane plane;
  OdGePoint3d point;
  OdGeVector3d vector;
  OdDb::Planarity planarity;
  double value, start, end;

  pLine->getStartPoint(point);
  wcout << L"\n  Start point = " << AboutPoint3d(point);
  pLine->getEndPoint(point);
  wcout << L"\n  End point = " << AboutPoint3d(point);
  pLine->getStartParam(start);
  wcout << L"\n  Start parameter = " << start;
  pLine->getEndParam(end);
  wcout << L"\n  End parameter = " << end;

  pLine->getArea(value);
  wcout << L"\n  Area = " << value;
  pLine->getDistAtParam(end, value);
  wcout << L"\n  Length = " << value;
  pLine->getParamAtDist(value/2, value);
  wcout << L"\n  Parameter at half-length = " << value;

  pLine->getPointAtParam((end + start)/2, point);
  wcout << L"\n  Middle point = " << AboutPoint3d(point);
  pLine->getFirstDeriv((end + start)/2, vector);
  wcout << L"\n  First derivative in middle point = " << AboutVector3d(vector);
  pLine->getSecondDeriv((end + start)/2, vector);
  wcout << L"\n  Second derivative in middle point = " << AboutVector3d(vector);

  if(pLine->getPlane(plane, planarity) == eOk)
    wcout << L"\n  " << ((planarity == OdDb::kPlanar) ? L"Entity" : 
                         (planarity == OdDb::kLinear) ? L"Arbitrary" : L"Non")
          << L" Plane = " << AboutPlane(plane);
}

The ModifyLineProperties() function requires a pointer to an existing line object and implements the console menu for the listed operations. The function organizes a loop that inquires about the operation code and uses the switch statement to select whether the case must be performed. The function processes user actions in the loop until the user selects the [Q] operation. The function uses the EntryPoint3d() function for entering coordinates of a three-dimensional point and the EntryVector3d() function for entering coordinates of a three-dimensional vector. The EntryPoint3d() and EntryVector3d() functions require a reference to an instance of the three-dimensional point or three-dimensional vector to be modified as an argument and return True when the passed instance is modified successfully or False when the user cancels entry.

When the user selects [P], the function displays the common object properties using the PrintObjectProperties() function, general entity properties using the PrintEntityProperties() function, computed line properties using the PrintLineFeatures() function, and specific line properties using the PrintLineProperties() function. When the user selects the [p] operation, the function displays only specific line properties.

When the user selects [S], the function gets the start point using the startPoint() method, calls the EntryPoint3d() function for entry of its coordinates, and sets the returned point as the new start point using the setStartPoint() method if entry is successful.

When the user selects [E], the function gets the end point using the endPoint() method, calls the EntryPoint3d() function for entry of its coordinates, and sets the returned point as the new end point using the setEndPoint() method if entry is successful.

When the user selects [N], the function gets the normal to the plane of the line using the normal() method, calls the EntryVector3d() function for entry of its coordinates, and sets the returned vector as a new normal using the setNormal() method if entry is successful.

When the user selects [T], the function gets the current thickness using the thickness() method and requests a double value. If an entered value is incorrect, the function displays an error message and breaks to the console menu. If an entered value is correct, the function sets the new thickness using the setThickness() method.

When the user selects [Z], the function requests a parameter as a double value. If an entered value is correct, the function computes the coordinates of the point on the line corresponding to the specified parameter using the getPointAtParam() method, computes the distance from the start point to the computed point using the getDistAtParam() method, and computes the first and second derivatives in the computed point using the getFirstDeriv() and getSecondDeriv() methods.

When the user selects [M], the function calls the ModifyEntityProperties() function and passes to it the pointer to the line object for modifying its general entity properties. After modification, the function displays all line properties using the [P] operation.

When the user selects [Q], the function ends the loop and returns in the calling function.

The ModifyLineProperties() function has the following implementation:


#include "..\Common\DemoMain.h"
#include "DbLine.h"
#include <iostream>
using namespace std;

OdString AboutPoint3d(const OdGePoint3d& point);
bool EntryPoint3d(OdGePoint3d& point);

OdString AboutVector3d(const OdGeVector3d& vector);
bool EntryVector3d(OdGeVector3d& vector);

void PrintEntityProperties(OdDbEntity *pEntity);
void ModifyEntityProperties(OdDbEntity *pEntity);

void ModifyLineProperties(OdDbLine* pLine)
{
  wchar_t ch = L'\0';
  double value, param;
  OdGePoint3d point;
  OdGeVector3d vector;

  wcout << L"\n\nStart modifying of the line properties";

  do {
    switch(ch)
    {
      case L'M':          // Modify the general properties
      case L'm':
        ModifyEntityProperties(pLine);


      case L'P':          // Print the whole properties
        wcout << L"\nH=" << pLine->handle().ascii();
        wcout << L"\n  ------ Common Object Properties";
        PrintObjectProperties(pLine);
        wcout << L"\n  ------ General Entity Properties";
        PrintEntityProperties(pLine);
        wcout << L"\n  ------ Computed Line Properties";
        PrintLineFeatures(pLine);


      case L'p':          // Print the specific properties
        wcout << L"\n  ------ Specific Line Properties";
        PrintLineProperties(pLine);
        wcout << L"\n";        
        break;


      case L'N':          // Set the normal
      case L'n':
        wcout << L"Entry the normal";
        vector = pLine->normal();
        
        if(EntryVector3d(vector))
        {
          pLine->setNormal(vector);
          wcout << L"Normal is set to " << AboutVector3d(pLine->normal()) << L"\n";
        }
        break;


      case L'S':          // Set the start point
      case L's':
        wcout << L"Entry the start point";
        point = pLine->startPoint();
        
        if(EntryPoint3d(point))
        {
          pLine->setStartPoint(point);
          wcout << L"Start point is set to " << AboutPoint3d(pLine->startPoint()) << L"\n";
        }
        break;


      case L'E':          // Set the end point
      case L'e':
        wcout << L"Entry the end point";
        point = pLine->endPoint();
        
        if(EntryPoint3d(point))
        {
          pLine->setEndPoint(point);
          wcout << L"End point is set to " << AboutPoint3d(pLine->endPoint()) << L"\n";
        }
        break;


      case L'T':          // Set the thickness
      case L't':
        wcout << L"\nCurrent thickness = " << pLine->thickness()
              << L"\nEntry a new thickness [t>0-along normal|t<0-opposite normal]:>";
        wcin >> value;

        if(!wcin.fail() && wcin.peek() == 10)
        {
            pLine->setThickness(value);
            wcout << L"Thickness is set to: " << pLine->thickness() << L"\n";
        }
        else { wcin.clear();  wcin.sync();  wcout << L"Error: Invalid entered value\n"; }
        break;


      case L'Z':          // Compute the features at parameter
      case L'z':
        wcout << L"\nEntry a parameter:>";
        wcin >> param;

        if(!wcin.fail() && wcin.peek() == 10)
        {
          wcout << L"Compute at (" << param << L"):";
          if(pLine->getDistAtParam(param, value) == eOk)
            wcout << L"\nDistance = " << value;
          if(pLine->getPointAtParam(param, point) == eOk)
            wcout << L"\nPoint on = " << AboutPoint3d(point);
          if(pLine->getFirstDeriv(param, vector) == eOk)
            wcout << L"\n1-Derivative = " << AboutVector3d(vector);
          if(pLine->getSecondDeriv(param, vector) == eOk)
            wcout << L"\n2-Derivative = " << AboutVector3d(vector);
          wcout << L"\n--at--";
        }
        else { wcin.clear();  wcin.sync();  wcout << L"Error: Invalid entered value\n"; }
        break;


      case L'\0':         // Skip an action
        break;

      default:
        wcout << L"Error: Incorrect operation\n";
    }
    wcout << L"\nN. Set the normal";
    wcout << L"\nT. Set the thickness";
    wcout << L"\nE. Set the end point";
    wcout << L"\nS. Set the start point";
    wcout << L"\nP. Print the whole properties";
    wcout << L"\np. Print the specific properties";
    wcout << L"\nM. Modify the general properties";
    wcout << L"\nZ. Compute the features at parameter";
    wcout << L"\nQ. Quit";
    wcout << L"\nSelect operation:>";
    wcin >> ch;
  }
  while(ch != L'Q' && ch != L'q');

  wcout << L"Stop modifying of the line properties\n";
}

Testing gives the following results:


Start modifying of the line properties

N. Set the normal
T. Set the thickness
E. Set the end point
S. Set the start point
P. Print the whole properties
p. Print the specific properties
M. Modify the general properties
Z. Compute the features at parameter
Q. Quit
Select operation:>

When the operation is p-"Print the specific properties":


------ Specific Line Properties
Normal = (0,0,1)
Start point = (0,0,0)
End point = (0,0,0)
Thickness = 0

When the operation is S-"Set the start point":


Entry the start point
Current coordinates: (0,0,0)
Entry X-coordinate:>2.5
Entry Y-coordinate:>3.1
Entry Z-coordinate:>1.4
Start point is set to (2.5,3.1,1.4)

When the operation is E-"Set the end point":


Entry the end point
Current coordinates: (0,0,0)
Entry X-coordinate:>6.7
Entry Y-coordinate:>8.5
Entry Z-coordinate:>4.9
End point is set to (6.7,8.5,4.9)

When the operation is N-"Set the normal":


Entry the normal
Current vector directions: (0,0,1)
Entry X-direction:>0.25
Entry Y-direction:>1.45
Entry Z-direction:>0.89
Normal is set to (0.145381,0.843209,0.517556)

When the operation is T-"Set the thickness":


Current thickness = 0
Entry a new thickness [t>0-along normal|t<0-opposite normal]:>2.1
Thickness is set to: 2.1

When the operation is Z-"Compute the features at parameter":


Entry a parameter:>2.5
Compute at (2.5):
Distance = 2.5
Point on = (3.8664,4.85681,2.53867)
1-Derivative = (4.2,5.4,3.5)
2-Derivative = (0,0,0)
--at--
                             // parameter outs the range
Entry a parameter:>10.1      // error for point
Compute at (10.1):
Distance = 10.1
1-Derivative = (4.2,5.4,3.5)
2-Derivative = (0,0,0)
--at--

When the operation is P-"Print all properties":


H=40
  ------ Common Object Properties
  Type: AcDbLine
  Status: unerased,resident,modified,forRead,forWrite
  Database: c:\test.dwg
  ------ General Entity Properties
  Block: [1F-"*Model_Space"-Block]
  Layer: [10-"0"-Layer]
  Material: [3C-"ByLayer"-Material]
  Linetype: [15-"ByLayer"-Linetype]
  Lineweight: [kLnWtByLayer]
  Transparency: [byLayer]
  Visual style: [Db:kNull]
  PlotStyleName: ByLayer
  Linetype scale: 1
  Color: [byLayer], Index = 256
  State: Planar, Visible, Cast Shadows, Receive Shadows
  ------ Computed Line Properties
  Start point = (2.5,3.1,1.4)
  End point = (6.7,8.5,4.9)
  Start parameter = 0
  End parameter = 7.6844
  Area = 0
  Length = 7.6844
  Parameter at half-length = 3.8422
  Middle point = (4.6,5.8,3.15)
  First derivative in middle point = (4.2,5.4,3.5)
  Second derivative in middle point = (0,0,0)
  Arbitrary Plane = (0.145381 * X + 0.843209 * Y + 0.517556 * Z + -3.70198)  
  ------ Specific Line Properties
  Normal = (0.145381,0.843209,0.517556)
  Start point = (2.5,3.1,1.4)
  End point = (6.7,8.5,4.9)
  Thickness = 2.1

Use the Q-"Quit" operation to exit:


Stop modifying of the line properties

See Also