CVL Class Reference

Cognex MVS-8000 Series
CVL Class Reference
CVL 6.7
April 2009
The software described in this document is furnished under license, and may be used or copied only in accordance with
the terms of such license and with the inclusion of the copyright notice shown on this page. Neither the software, this
document, nor any copies thereof may be provided to or otherwise made available to anyone other than the licensee. Title
to and ownership of this software remains with Cognex Corporation or its licensor.
Cognex Corporation assumes no responsibility for the use or reliability of its software on equipment that is not supplied by
Cognex Corporation. Cognex Corporation makes no warranties, either express or implied, regarding the described
software, its merchantability or its fitness for any particular purpose.
The information in this document is subject to change without notice and should not be construed as a commitment by
Cognex Corporation. Cognex Corporation is not responsible for any errors that may be present in either this document or
the associated software.
Copyright © 2009 Cognex Corporation
All Rights Reserved
Printed in U.S.A.
This document may not be copied in whole or in part, nor transferred to any other media or language, without the written
permission of Cognex Corporation.
Portions of the hardware and software provided by Cognex may be covered by one or more of the U.S. and foreign
patents listed below as well as pending U.S. and foreign patents. Such pending U.S. and foreign patents issued after the
date of this document are listed on Cognex web site at http://www.cognex.com/patents.
5495537, 5548326, 5583954, 5602937, 5640200, 5751853, 5768443, 5825913, 5850466, 5872870, 5901241, 5943441,
5978080, 5978521, 5987172, 6005978, 6039254, 6064388, 6075881, 6137893, 6141033, 6167150, 6215915, 6324299,
6381366, 6381375, 6411734, 6421458, 6459820, 6490375, 6516092, 6563324, 6658145, 6687402, 6690842, 6697535,
6718074, 6748110, 6771808, 6804416, 6836567, 6850646, 6856698, 6920241, 6959112, 6973207, 6975764, 6985625,
6993177, 6993192, 7006712, 7016539, 7043081, 7058225, 7065262, 7088862, 7164796, 7190834, 7242801, 7251366,
EP0713593, JP3522280, JP3927239
The following are registered trademarks of Cognex Corporation:
acuCoder
acuFinder
acuReader
acuWin
BGAII
Checkpoint
Cognex
Cognex, Vision for Industry
CVC-1000
CVL
DisplayInspect
ID Expert
PasteInspect
PatFind
PatInspect
PatMax
PatQuick
PixelProbe
SMD4
Virtual Checksum VisionLinx
VisionPro
VisionX
Other Cognex products, tools, or other trade names may be considered common law trademarks of Cognex Corporation.
These trademarks may be marked with a "™". Other product and company names mentioned herein may be the
trademarks of their respective owners.
Contents
Preface ....................................................................................................................... 29
.......................................................................................................... 33
cc1394DCAM
cc1Xform
................................................................................................................. 41
cc2Matrix
................................................................................................................. 47
cc2Point
.................................................................................................................. 57
cc2Rigid
.................................................................................................................. 65
cc2Vect
.................................................................................................................... 77
.......................................................................................................... 85
cc2Wireframe
cc2Xform
................................................................................................................. 95
...................................................................................................... 105
cc2XformBase
cc2XformCalib2
.................................................................................................... 109
cc2XformDeform
.................................................................................................. 119
cc2XformLinear
.................................................................................................... 123
cc2XformPerspective
........................................................................................... 135
cc2XformPoly
....................................................................................................... 141
cc3AngleVect
........................................................................................................ 145
cc3PlanePel
.......................................................................................................... 149
cc3PlanePelBuffer
................................................................................................ 151
cc3PlanePelBuffer_const
cc3Vect
.................................................................................... 155
.................................................................................................................. 157
cc4200VideoMan
.................................................................................................. 165
cc8100
................................................................................................................... 173
cc8100c
................................................................................................................. 175
cc8100d .................................................................................................................... 181
cc8100l
cc8100m
CVL Class Reference
.................................................................................................................. 189
................................................................................................................ 195
3
Contents
cc8120
................................................................................................................... 203
cc8200
................................................................................................................... 217
cc8500l .................................................................................................................... 227
cc8501
................................................................................................................... 235
cc8504
................................................................................................................... 243
cc8600 ..................................................................................................................... 251
cc8BitInputLutProp ................................................................................................ 259
ccAccelerator
....................................................................................................... 263
ccAcqFailure
......................................................................................................... 267
ccAcqFifo
.............................................................................................................. 275
.......................................................................................................... 295
ccAcqImage
...................................................................................................... 301
ccAcqProblem
........................................................................................... 305
ccAcqPropertyQuery
.......................................................................................................... 309
ccAcqProps
ccAcuBarCodeCalibrationResult
ccAcquireInfo
....................................................................................................... 315
.............................................................................................. 319
ccAcuBarCodeDefs
.......................................................................................... 323
ccAcuBarCodeResult
ccAcuBarCodeRunParams
ccAcuBarCodeTuneParams
................................................................................ 349
............................................................................................................ 355
ccAcuReadDefs
.................................................................................................... 363
ccAcuReadFont
.................................................................................................... 367
ccAcuReadResult
................................................................................................. 371
ccAcuReadResultSet
ccAcuReadRunParams
4
................................................................................. 327
.............................................................................................. 335
ccAcuBarCodeTool
ccAcuRead
........................................................................ 311
........................................................................................... 375
........................................................................................ 379
CVL Class Reference
Contents
ccAcuReadTuneParams
...................................................................................... 397
ccAcuSymbolDataMatrixDefs
............................................................................. 411
ccAcuSymbolDataMatrixLearnParams ................................................................. 413
ccAcuSymbolDataMatrixTool ................................................................................ 421
ccAcuSymbolDefs
................................................................................................ 431
ccAcuSymbolFinderParams
............................................................................... 435
ccAcuSymbolLearnParams
................................................................................. 441
ccAcuSymbolQRCodeDefs
................................................................................. 447
ccAcuSymbolQRCodeLearnParams ..................................................................... 449
ccAcuSymbolQRCodeTool .................................................................................... 455
ccAcuSymbolResult .............................................................................................. 465
ccAcuSymbolTool ................................................................................................... 471
ccAcuSymbolTuneParams
.................................................................................. 477
ccAcuSymbolTuneResult
.................................................................................... 485
ccAffineRectangle
................................................................................................ 489
ccAffineSamplingParams
ccAlphaColorProp
.................................................................................... 503
................................................................................................ 509
ccAnalogAcqProps ................................................................................................ 515
ccAngle8
............................................................................................................... 517
ccAngle16
............................................................................................................. 525
ccAngleRange
...................................................................................................... 533
ccAnnulus
............................................................................................................. 537
ccArchive
.............................................................................................................. 545
ccAtapiZipDrive
ccAutoSelectDefs
.................................................................................................... 557
................................................................................................. 561
ccAutoSelectParams
........................................................................................... 563
ccAutoSelectResult ............................................................................................... 571
CVL Class Reference
5
Contents
...................................................................................................... 573
ccBezierCurve
ccBlob
................................................................................................................... 587
ccBlobDefs
........................................................................................................... 611
ccBlobParams
...................................................................................................... 613
ccBlobResults
...................................................................................................... 631
..................................................................................... 635
ccBlobSceneDescription
ccBoard
................................................................................................................. 655
ccBoundary
.......................................................................................................... 661
ccBoundaryDefs
................................................................................................... 667
ccBoundaryInspector
.......................................................................................... 675
............................................................................... 685
ccBoundaryInspectorResult
ccBoundaryInspectorTrainParams
.................................................................... 687
ccBoundarySet
..................................................................................................... 691
ccBoundaryTol
..................................................................................................... 697
ccBoundaryTrackerDefs
...................................................................................... 703
ccBoundaryTrackerPoint
.................................................................................... 705
ccBoundaryTrackerResult
.................................................................................. 707
ccBoundaryTrackerRunParams
ccCADFile
......................................................................... 713
............................................................................................................. 727
ccCalib2ParamsExtrinsic
.................................................................................... 737
ccCalib2ParamsIntrinsic
..................................................................................... 739
ccCalib2VertexFeatureDefs
................................................................................. 745
ccCalib2VertexFeatureParams
ccCalibDefs
........................................................................... 751
........................................................................................................... 755
ccCaliperBaseResultSet
ccCaliperBaseRunParams
...................................................................................... 757
.................................................................................. 763
ccCaliperCircleFinderAutoRunParams
6
.............................................................. 769
CVL Class Reference
Contents
ccCaliperCircleFinderManualRunParams
.......................................................... 777
............................................................................... 781
ccCaliperCircleFinderResult
........................................................................... 785
ccCaliperCorrelationResultSet
ccCaliperCorrelationRunParams
........................................................................ 787
....................................................................................................... 797
ccCaliperDefs
ccCaliperDesiredEdge ........................................................................................... 801
............................................................ 805
ccCaliperEllipseFinderAutoRunParams
ccCaliperEllipseFinderManualRunParams
ccCaliperEllipseFinderResult
............................................................................. 817
............................................................... 821
ccCaliperFinderBaseAutoRunParams
ccCaliperFinderBaseManualRunParams
ccCaliperFinderBaseResult
........................................................... 829
................................................................................ 833
ccCaliperFinderBaseRunParams
....................................................................... 837
ccCaliperLineFinderAutoRunParams
................................................................. 843
ccCaliperLineFinderManualRunParams
ccCaliperLineFinderResult
........................................................ 813
............................................................ 851
.................................................................................. 855
ccCaliperOneResult ............................................................................................... 857
ccCaliperProjectionParams
........................................................................................... 865
ccCaliperResultEdge
ccCaliperResultSet
................................................................................ 859
.............................................................................................. 867
ccCaliperRunParams
........................................................................................... 869
ccCaliperScanParams
......................................................................................... 875
ccCaliperScore
..................................................................................................... 879
ccCallback
............................................................................................................ 881
ccCallback1
.......................................................................................................... 883
ccCallback2
.......................................................................................................... 885
ccCameraBandwidthProp
CVL Class Reference
................................................................................... 887
7
Contents
....................................................................................... 891
ccCameraLocationProp
....................................................................................................... 893
ccCameraPort
ccCameraPortProp ................................................................................................. 897
.............................................................................................. 899
ccCameraTestProp
............................................................................................................. 903
ccCDBFile
....................................................................................................... 917
ccCDBRecord
ccCdcCameraCalibrationProp
ccCircle
............................................................................ 925
................................................................................................................. 931
..................................................................................................... 939
ccCircleFitDefs
ccCircleFitParams
................................................................................................ 941
ccCircleFitResults
................................................................................................ 945
ccCircularLabeledProjectionModel
ccClassifierFeatureScore
.................................................................................... 957
ccClassifierFeatureScoreIgnore
......................................................................... 959
ccClassifierFeatureScoreOneSided
................................................................... 961
ccClassifierFeatureScoreTwoSided
................................................................... 965
ccClassifierFeatureVector
................................................................................... 971
................................................................................................... 973
ccClassifierRule
ccClassifierRuleTable
.......................................................................................... 975
..................................................................................................... 977
ccClippingProp
ccCnlSearchDefs
.................................................................................................. 981
ccCnlSearchModel
............................................................................................... 985
ccCnlSearchResult
............................................................................................. 1009
ccCnlSearchResultSet
....................................................................................... 1013
ccCnlSearchRunParams
................................................................................... 1015
ccCnlSearchTrainParams
.................................................................................. 1023
ccCogDevice
8
.................................................................... 947
....................................................................................................... 1029
CVL Class Reference
Contents
ccCogLinkCamera
.............................................................................................. 1031
ccCogLinkChanSet
............................................................................................ 1033
ccCogLinkDevice
............................................................................................... 1037
.................................................................................. 1039
ccCogLinkFrameGrabber
ccColor
................................................................................................................ 1041
ccColorMatchDefs
ccColorMatchResult
.............................................................................................. 1047
.......................................................................................... 1049
................................................................................. 1051
ccColorMatchRunParams
ccColorRange
..................................................................................................... 1055
ccColorSpaceDefs
............................................................................................. 1059
ccColorStatisticsParams
................................................................................... 1061
ccColorStatisticsResult
..................................................................................... 1065
ccColorValue
...................................................................................................... 1067
ccCompleteCallbackProp
.................................................................................. 1069
ccCompositeColorMatchRunParams
ccCompositeColorMatchTool
........................................................................... 1075
ccCompositeColorMatchTrainParams
ccConStream
............................................................... 1073
............................................................. 1083
...................................................................................................... 1085
ccContourTree ...................................................................................................... 1093
ccContrastBrightnessProp
ccConvolveParams
ccCoordAxes
............................................................................... 1105
............................................................................................ 1113
...................................................................................................... 1117
ccCriticalSection .................................................................................................. 1121
ccCriticalSectionLock .......................................................................................... 1123
ccCross ................................................................................................................. 1125
ccCtiProp
............................................................................................................ 1129
ccCubicSpline
CVL Class Reference
.................................................................................................... 1133
9
Contents
.................................................................................................... 1153
ccCustomProp
...................................................................................... 1155
ccCustomPropertyBag
ccDcamBusEventInfo .......................................................................................... 1159
................................................................................................. 1161
ccDeBoorSpline
ccDegree
............................................................................................................. 1171
.......................................................................................................... 1177
ccDiagDefs
ccDiagIncrementLevel
....................................................................................... 1179
ccDiagObject
...................................................................................................... 1181
ccDiagRecord
..................................................................................................... 1185
ccDiagServer
...................................................................................................... 1191
ccDIB
................................................................................................................... 1193
ccDigitalCameraControlProp
ccDimTol
............................................................................................................. 1199
...................................................................................... 1211
ccDiscretePelRootPool
ccDisplay
............................................................................................................ 1215
ccDisplayConsole
ccEdgelet
............................................................................ 1197
.............................................................................................. 1259
............................................................................................................ 1267
ccEdgeletChainFilter
......................................................................................... 1271
ccEdgeletChainFilterLength
............................................................................. 1277
ccEdgeletChainFilterMagnitudeHysteresis
ccEdgeletChainFilterShape
ccEdgeletParams
ccEdgeletSet
............................................................................... 1283
............................................................................................... 1287
....................................................................................................... 1289
ccEllipse
.............................................................................................................. 1293
ccEllipse2
............................................................................................................ 1295
ccEllipseAnnulus
............................................................................................... 1311
ccEllipseAnnulusSection
10
..................................................... 1279
.................................................................................. 1319
CVL Class Reference
Contents
ccEllipseArc
........................................................................................................ 1337
ccEllipseArc2
...................................................................................................... 1339
................................................................................................. 1349
ccEllipseFitDefs
ccEllipseFitParams
............................................................................................ 1351
ccEllipseFitResults
............................................................................................ 1355
.......................................................................................... 1357
ccEmbeddedDisplay
...................................................................................... 1373
ccEncoderControlProp
................................................................................................... 1377
ccEncoderProp
ccEvent
............................................................................................................... 1393
ccException
........................................................................................................ 1395
...................................................................................... 1399
ccExceptionWithString
ccExposureProp
ccFeaturelet
................................................................................................. 1401
........................................................................................................ 1403
........................................................................................ 1409
ccFeatureletChainSet
ccFeatureletFilter
............................................................................................... 1425
ccFeatureletFilterBoundary
.............................................................................. 1431
ccFeatureletFilterComposite
............................................................................. 1437
ccFeatureletFilterLength
................................................................................... 1439
ccFeatureletFilterMagnitudeHysteresis
ccFeatureletFilterRegion
........................................................... 1441
................................................................................... 1445
ccFeatureParams ................................................................................................. 1447
ccFeatureSegment
ccFileArchive
............................................................................................. 1451
...................................................................................................... 1453
ccFileSystemSelect
............................................................................................ 1455
ccFilterConvolveParams
................................................................................... 1459
ccFilterConvolveKernel
..................................................................................... 1461
ccFilterDefs
CVL Class Reference
......................................................................................................... 1463
11
Contents
............................................................................................ 1465
ccFilterMaskKernel
....................................................................................... 1469
ccFilterMedianParams
ccFilterMorphologyStructuringElement ............................................................. 1471
ccFilterMorphologyDefs
.................................................................................... 1475
ccFilterMorphologyParams
......................................................................................... 1479
ccFirstPelOffsetProp
ccFLine
............................................................................... 1477
................................................................................................................ 1481
...................................................................................... 1491
ccFrameAverageBuffer
........................................................................................ 1497
ccFrameAverageDefs
................................................................................................ 1499
ccFrameGrabber
ccGaussSampleParams
.................................................................................... 1505
.................................................................................................... 1511
ccGenAnnulus
......................................................................................... 1519
ccGeneralShapeTree
ccGenPoly
........................................................................................................... 1523
ccGenRect
.......................................................................................................... 1549
ccGigEVisionCamera
......................................................................................... 1559
ccGMorph3x3Element
....................................................................................... 1567
.................................................................................................... 1573
ccGMorphDefs
............................................................................................. 1577
ccGMorphElement
ccGraphic
............................................................................................................ 1583
ccGraphicBuiltin
................................................................................................ 1587
ccGraphicCross
................................................................................................. 1589
ccGraphicEllipseAnnulusSection
ccGraphicList
..................................................................................................... 1595
ccGraphicPointIcon
12
..................................................................... 1591
........................................................................................... 1599
ccGraphicProps
................................................................................................. 1601
ccGraphicSimple
................................................................................................ 1613
CVL Class Reference
Contents
.................................................................................................... 1617
ccGraphicText
............................................................................................... 1621
ccGraphicWithFill
.................................................................................................... 1625
ccGreyAcqFifo
ccGreyVideoFormat .............................................................................................. 1629
ccGridCalibParams
............................................................................................ 1631
ccGridCalibResults
............................................................................................ 1635
ccGUI
................................................................................................................... 1641
................................................................................................. 1643
ccHermiteSpline
....................................................................................................... 1653
ccHistoStats
ccHorizAdjustProp
ccHost
............................................................................................. 1657
................................................................................................................. 1661
ccIDDecodeParams
............................................................................................ 1663
ccIDDecodeResult
.............................................................................................. 1671
ccIDDefs
.............................................................................................................. 1677
.................................................................................................. 1681
ccIDQualityDefs
ccIDQualityResult
ccIDResult
.............................................................................................. 1685
........................................................................................................... 1687
ccIDResultSet
..................................................................................................... 1691
ccIDSearchParams
............................................................................................. 1693
ccIDSearchResult
............................................................................................... 1697
ccIDSubResult
.................................................................................................... 1701
ccImageWarp
...................................................................................................... 1705
ccImageStitch
..................................................................................................... 1715
ccImageStitchDefs
ccImagingDevice
ccIndexChain
................................................................................................ 1727
...................................................................................................... 1731
ccIndexChainList
CVL Class Reference
............................................................................................. 1725
............................................................................................... 1735
13
Contents
......................................................................................................... 1737
ccInputLine
ccInterpSpline
ccIO8100
.................................................................................................... 1741
............................................................................................................. 1751
ccIO8500l .............................................................................................................. 1753
ccIO8501
............................................................................................................. 1755
ccIO8504
............................................................................................................. 1757
ccIO8600DualLVDS .............................................................................................. 1759
ccIO8600LVDS ...................................................................................................... 1763
ccIO8600TTL ......................................................................................................... 1767
ccIOConfig
.......................................................................................................... 1771
ccIOExternal8500l ................................................................................................ 1775
ccIOExternal8501
............................................................................................... 1777
ccIOExternal8504
............................................................................................... 1779
............................................................................................ 1781
ccIOExternalOption
........................................................................................ 1783
ccIOLightControl8100
ccIOLightControlOption
.................................................................................... 1785
ccIOMultiChannel8100d
..................................................................................... 1787
ccIOMultiChannelExternal8100d
ccIOSingleChannel8100d
...................................................................... 1789
.................................................................................. 1791
ccIOSingleChannelExternal8100d
.................................................................... 1793
ccIOSplit8500l ....................................................................................................... 1795
ccIOSplit8501 ........................................................................................................ 1797
ccIOSplit8504
...................................................................................................... 1799
ccIOStandardOption
ccKeyboardEvent
.......................................................................................... 1801
............................................................................................... 1803
ccLabeledProjection
.......................................................................................... 1809
ccLabeledProjectionModel
14
................................................................................ 1811
CVL Class Reference
Contents
........................................................................................................ 1815
ccLightProp
ccLine
.................................................................................................................. 1827
...................................................................................................... 1837
ccLineFitDefs
ccLineFitParams
................................................................................................ 1839
ccLineFitResults
................................................................................................ 1843
........................................................................................................... 1845
ccLineSeg
........................................................................................... 1853
ccLiveDisplayProps
ccLock
................................................................................................................. 1863
.................................................................................................... 1865
ccLSLineFitter
ccLSPointToLineFitter
....................................................................................... 1869
ccLSPointToPointFitter
..................................................................................... 1877
ccMemoryArchive
.............................................................................................. 1881
....................................................................................................... 1883
ccMouseBite
.................................................................................................... 1885
ccMouseEvent
ccMovePartCallbackProp
........................................................................................................ 1893
ccMSMouse
ccMutex
.................................................................................. 1889
............................................................................................................... 1895
.................................................................................................... 1897
ccOCAlphabet
ccOCKeySet
ccOCLine
........................................................................................................ 1909
............................................................................................................ 1917
ccOCLineArrangement
...................................................................................... 1927
ccOCModel
......................................................................................................... 1937
ccOCVDefs
.......................................................................................................... 1945
ccOCVLineResult
............................................................................................... 1947
ccOCVLineRunParams
ccOCVPosResult
................................................................................................ 1955
ccOCVPosRunParams
CVL Class Reference
...................................................................................... 1951
....................................................................................... 1959
15
Contents
...................................................................................................... 1963
ccOCVResult
............................................................................................. 1965
ccOCVRunParams
.......................................................................................................... 1975
ccOCVTool
............................................................................................ 1981
ccOffsetClampProp
...................................................................................................... 1985
ccOutputLine
ccOverrunCallbackProp
.................................................................................... 1989
ccPackedRGB16Pel
........................................................................................... 1993
ccPackedRGB32Pel
........................................................................................... 1997
ccPair
.................................................................................................................. 2001
ccParallelIO
......................................................................................................... 2007
................................................................................................. 2011
ccPDF417Result
ccPelBuffer
......................................................................................................... 2015
.............................................................................................. 2021
ccPelBuffer_const
ccPelFunc ............................................................................................................. 2027
ccPelRect
............................................................................................................ 2031
ccPelRoot
............................................................................................................ 2035
.................................................................................................... 2039
ccPelRootPool
............................................................................................ 2041
ccPelRootPoolProp
ccPelTraits
.......................................................................................................... 2043
ccPerimPos
......................................................................................................... 2045
ccPersistent
........................................................................................................ 2047
ccPMAlignDefs
................................................................................................... 2057
ccPMAlignPattern
.............................................................................................. 2059
ccPMAlignResult
................................................................................................ 2079
ccPMAlignResultSet
ccPMAlignRunParams
ccPMFlexResult
16
.......................................................................................... 2081
....................................................................................... 2085
.................................................................................................. 2087
CVL Class Reference
Contents
......................................................................................... 2089
ccPMFlexRunParams
ccPMInspectAbsenceData
................................................................................ 2095
ccPMInspectBoundaryData
............................................................................... 2097
ccPMInspectBP
.................................................................................................. 2101
............................................................................................... 2103
ccPMInspectDefs
.................................................................................... 2107
ccPMInspectMatchedBP
ccPMInspectMatchedFeature
............................................................................ 2109
ccPMInspectPattern
........................................................................................... 2111
ccPMInspectRegion
........................................................................................... 2151
ccPMInspectResult
............................................................................................ 2159
....................................................................................... 2167
ccPMInspectResultSet
................................................................................... 2169
ccPMInspectRunParams
ccPMInspectSimpleBoundaryDiffData ............................................................... 2171
ccPMInspectStatTrainParams
........................................................................... 2173
ccPMInspectUnmatchedFeature ......................................................................... 2175
ccPoint
................................................................................................................ 2177
............................................................................................... 2179
ccPointingDevice
ccPointMatcher
.................................................................................................. 2185
ccPointMatcherDefs
........................................................................................... 2191
ccPointMatcherResult
....................................................................................... 2193
.................................................................................. 2195
ccPointMatcherResultSet
ccPointMatcherRunParams
ccPointSet
.............................................................................. 2197
........................................................................................................... 2207
ccPolarSamplingParams
................................................................................... 2211
ccPolarTransDefs ................................................................................................. 2219
ccPolygon
........................................................................................................... 2221
ccPolyline
........................................................................................................... 2223
CVL Class Reference
17
Contents
........................................................................................................ 2243
ccPtrHandle
............................................................................................. 2247
ccPtrHandle_const
................................................................................................... 2251
ccPVEReceiver
ccRadian
............................................................................................................. 2259
ccRange
.............................................................................................................. 2265
...................................................................................................... 2271
ccRangeDefs
........................................................................................... 2273
ccRasterizationDefs
ccReadoutDirectionProp
ccRect
................................................................................... 2275
................................................................................................................. 2279
ccRectangle .......................................................................................................... 2287
..................................................................................................... 2297
ccRegionTree
............................................................................................... 2315
ccRemoteDisplay
ccRemoteDisplayServer
ccRemoteHostDisplay
ccRepBase
ccRGB
....................................................................................... 2325
.......................................................................................................... 2331
................................................................................................................. 2333
ccRGB16AcqFifo
................................................................................................ 2337
ccRGB32AcqFifo
................................................................................................ 2341
....................................................................................................... 2345
ccRLEBuffer
ccRoiProp
........................................................................................................... 2367
ccRSIDefs
........................................................................................................... 2371
ccRSIModel
......................................................................................................... 2375
ccRSIResult
........................................................................................................ 2387
ccRSIResultSet
18
.................................................................................... 2323
................................................................................................... 2391
ccRSIRunParams
............................................................................................... 2393
ccRSITrainParams
............................................................................................. 2405
ccSampleParams
............................................................................................... 2415
CVL Class Reference
Contents
.................................................................................................... 2421
ccSampleProp
................................................................................................. 2425
ccSampleResult
............................................................................. 2431
ccSceneAngleFinderIIResult
ccSceneAngleFinderIIResultSet ......................................................................... 2433
ccSceneAngleFinderIIRunParams
ccSceneAngleFinderResult
.................................................................... 2435
............................................................................... 2441
ccSceneAngleFinderResultSet
ccSceneAngleFinderRunParams
......................................................................... 2443
...................................................................... 2445
ccScoreContrast
................................................................................................ 2451
ccScoreOneSided
.............................................................................................. 2453
................................................................................................. 2457
ccScorePosition
.......................................................................................... 2459
ccScorePositionNeg
ccScorePositionNorm
........................................................................................ 2461
ccScorePositionNormNeg
ccScoreSizeDiffNorm
................................................................................. 2463
......................................................................................... 2465
ccScoreSizeDiffNormAsym
............................................................................... 2469
............................................................................................... 2473
ccScoreSizeNorm
................................................................................................. 2477
ccScoreStraddle
ccScoreTwoSided
.............................................................................................. 2479
ccSecurityInfo
.................................................................................................... 2487
ccSemaphore
...................................................................................................... 2491
ccSensor
............................................................................................................. 2493
ccSerialIO .............................................................................................................. 2495
ccSettlingTimeProp
........................................................................................... 2511
ccShape ................................................................................................................ 2515
ccShapeInfo
........................................................................................................ 2535
ccShapeMaskValue
CVL Class Reference
............................................................................................ 2539
19
Contents
.................................................................................................... 2543
ccShapeModel
ccShapeModelProps
.......................................................................................... 2551
ccShapeModelTemplate<> .................................................................................. 2557
............................................................................................. 2563
ccShapePerimData
................................................................................... 2567
ccShapePerimDataTable
ccShapeTolStats
................................................................................................ 2571
......................................................................... 2581
ccShapeTolStatsModelParams
................................................................................... 2585
ccShapeTolStatsParams
ccShapeTree
....................................................................................................... 2589
ccSharpnessParams
ccSocket
.......................................................................................... 2603
............................................................................................................. 2609
ccStdGreyAcqFifo
.............................................................................................. 2613
ccStdGreyVideoFormat
..................................................................................... 2615
ccStdRGB16AcqFifo
.......................................................................................... 2617
ccStdRGB32AcqFifo
.......................................................................................... 2619
ccStdVideoFormat
............................................................................................. 2621
ccStrobeDelayProp
............................................................................................ 2631
ccStrobeProp
...................................................................................................... 2635
ccSymbologyParamsUPCEAN
.......................................................................... 2639
ccSymbologyParamsCodabar
.......................................................................... 2643
ccSymbologyParamsCode39
............................................................................ 2647
ccSymbologyParamsCode93
............................................................................ 2651
ccSymbologyParamsCode128
.......................................................................... 2653
ccSymbologyParamsComposite
ccSymbologyParamsI2of5
ccSymbologyParamsPDF417
ccSymbologyParamsPostal
20
...................................................................... 2655
................................................................................ 2659
............................................................................ 2663
.............................................................................. 2665
CVL Class Reference
Contents
ccSymbologyParamsRSS
...................................................................................................... 2673
ccSyncModel
........................................................................................................ 2679
ccSyncProp
ccTemperatureSensor
....................................................................................... 2683
.......................................................................................................... 2687
ccThreadID
.................................................................................................... 2691
ccThreadLocal
............................................................................................. 2693
ccThresholdResult
........................................................................................................... 2695
ccTimeout
................................................................................................... 2697
ccTimeoutProp
ccTimer
................................................................................. 2669
............................................................................................................... 2701
ccTransferArchive
.............................................................................................. 2705
ccTriggerFilterProp
............................................................................................ 2707
.................................................................................................. 2715
ccTriggerModel
ccTriggerProp
..................................................................................................... 2725
ccUIAffineRect
.................................................................................................... 2731
............................................................................................................ 2737
ccUICircle
.................................................................................................. 2741
ccUICoordAxes
.......................................................................................................... 2751
ccUIEllipse
ccUIEllipseAnnulusSection .................................................................................. 2755
ccUIEventProcessor
.......................................................................................... 2763
......................................................................................................... 2769
ccUIFormat
ccUIGDShape
..................................................................................................... 2773
ccUIGenAnnulus
................................................................................................ 2781
ccUIGenPoly
....................................................................................................... 2789
ccUIGenRect
....................................................................................................... 2801
ccUIIcon
.............................................................................................................. 2809
ccUILabel
............................................................................................................ 2813
CVL Class Reference
21
Contents
ccUILine
.............................................................................................................. 2819
........................................................................................................ 2825
ccUILineSeg
.................................................................................................... 2831
ccUIManShape
ccUIObject
.......................................................................................................... 2835
ccUIPointIcon
..................................................................................................... 2871
ccUIPointSet
....................................................................................................... 2875
ccUIPointShapeBase
......................................................................................... 2881
ccUIRectangle
.................................................................................................... 2883
ccUIRLEBuffer
.................................................................................................... 2887
ccUIShapes
......................................................................................................... 2893
ccUISketch
.......................................................................................................... 2907
ccUISketchMark
ccUITablet
................................................................................................. 2911
........................................................................................................... 2913
ccVersion .............................................................................................................. 2963
................................................................................................... 2969
ccVideoFormat
ccVp8100PelRootPool
ccWaferPreAlign
....................................................................................... 2975
................................................................................................ 2979
ccWaferPreAlignDefs
......................................................................................... 2987
ccWaferPreAlignResult
..................................................................................... 2989
ccWaferPreAlignRunParams
ccWin32Display
............................................................................ 2997
.................................................................................................. 3005
ccWorkerThreadManager
.................................................................................. 3021
ccWorkerThreadManagerDefs
.......................................................................... 3023
ccWorkerThreadManagerParams
cc_FeatureRange
cc_PelBuffer
cc_PelRoot
22
..................................................................... 3025
............................................................................................... 3029
....................................................................................................... 3031
.......................................................................................................... 3047
CVL Class Reference
Contents
cc_PMDefs
.......................................................................................................... 3049
cc_PMInspectFeature
........................................................................................ 3053
cc_PMPattern
..................................................................................................... 3055
cc_PMResult
....................................................................................................... 3067
cc_PMRunParams
.............................................................................................. 3073
cc_PMStageResult
............................................................................................. 3089
cfAffineTransformImage() ................................................................................... 3091
cfAutoSelect() ....................................................................................................... 3097
cfAutoTrigger() ...................................................................................................... 3103
cfBlobAnalysis() ................................................................................................... 3105
cfBoundaryTracker() ............................................................................................ 3107
cfCalib2VertexFeatureExtract() ........................................................................... 3109
cfCalibrationRun() ................................................................................................ 3111
cfCaliperFindCircle() ............................................................................................ 3113
cfCaliperFindEllipse() .......................................................................................... 3115
cfCaliperFindLine() .............................................................................................. 3117
cfCaliperFindShape() ........................................................................................... 3119
cfCaliperRun() ...................................................................................................... 3121
cfCircleFit() ........................................................................................................... 3131
cfColorMatch() ...................................................................................................... 3133
cfConvertCDBtoVDB() ......................................................................................... 3139
cfConvertDisplayFormat2ImageFormat() ............................................................ 3141
cfConvertPel() ........................................................................................................ 3143
cfConvertString() ................................................................................................... 3151
cfConvertToFeaturelet() ....................................................................................... 3157
cfConvertToFeaturelets() ..................................................................................... 3159
cfConvertToFeatures() .......................................................................................... 3161
CVL Class Reference
23
Contents
cfConvertVDBtoCDB() ......................................................................................... 3167
cfConvolve() ......................................................................................................... 3169
cfCreateThread() .................................................................................................. 3173
cfCreateThreadCVL() ........................................................................................... 3175
cfCreateThreadMFC() ........................................................................................... 3177
cfDefaultPelRootPool() ........................................................................................ 3179
cfDefaultPelRootPoolSize() ................................................................................. 3181
cfDetectMouseBites() .......................................................................................... 3183
cfDetectSceneAngle() .......................................................................................... 3185
cfDrawSynthetic() ................................................................................................. 3187
cfEdgeDetect() ...................................................................................................... 3189
cfEllipseFit() .......................................................................................................... 3207
cfEqualize_1() ....................................................................................................... 3209
cfFilterConvolve .................................................................................................() 3211
cfFilterEdgeletChains() ......................................................................................... 3213
cfFilterMedian .....................................................................................................() 3219
cfFilterMorphology.............................................................................................() 3223
cfFreeRunTrigger() ................................................................................................ 3227
cfGaussSample() .................................................................................................. 3229
cfGenerateOcrChecksum() .................................................................................. 3233
cfGetColorRangeFromImage() ............................................................................. 3235
cfGetColorRangeFromImageRegion() ................................................................. 3239
cfGetColorStatisticsFromImage() ........................................................................ 3241
cfGetColorStatisticsFromImageRegion() ............................................................ 3243
cfGetCompileTimeCvlVersion() .......................................................................... 3245
cfGetCurrentThreadID() ....................................................................................... 3247
cfGetRunTimeCvlVersion() ................................................................................. 3249
24
CVL Class Reference
Contents
cfGetThreadPriority() ........................................................................................... 3251
cfGetSimpleColorFromImage() ............................................................................ 3253
cfGetSimpleColorFromImageRegion() ................................................................ 3255
cfHysteresisThreshold() ...................................................................................... 3257
cfIDDecode() ......................................................................................................... 3261
cfImageSharpness() ............................................................................................. 3263
cfImageSharpnessFocusSearch() ...................................................................... 3271
cfInitializeDisplayResources() ............................................................................ 3275
cfLabelHistogram() .............................................................................................. 3277
cfLabelProject() .................................................................................................... 3281
cfLabelProjectNorm() ........................................................................................... 3283
cfLabelProjectRaw() ............................................................................................. 3285
cfLineFit() .............................................................................................................. 3287
cfManualTrigger() .................................................................................................. 3289
cfOCChangeCurrentKey() .................................................................................... 3291
cfOCChangeCurrentKeys() .................................................................................. 3293
cfPDF417Decode() ............................................................................................... 3295
cfPelAdd() ............................................................................................................. 3297
cfPelClear() ........................................................................................................... 3301
cfPelCopy() ........................................................................................................... 3303
cfPelDivideByVal() ............................................................................................... 3305
cfPelEqual() .......................................................................................................... 3307
cfPelExpand() ....................................................................................................... 3309
cfPelFlipH() ........................................................................................................... 3313
cfPelFlipV() ........................................................................................................... 3315
cfPelHistogram() .................................................................................................. 3317
cfPelMap() ............................................................................................................. 3319
CVL Class Reference
25
Contents
cfPelMax() ............................................................................................................. 3321
cfPelMedian3x3() .................................................................................................. 3323
cfPelMin() .............................................................................................................. 3325
cfPelMinmax() ....................................................................................................... 3327
cfPelMult() ............................................................................................................. 3329
cfPelMultAdd() ...................................................................................................... 3333
cfPelNoShare() ..................................................................................................... 3337
cfPelPrint() ............................................................................................................ 3339
cfPelSample() ....................................................................................................... 3341
cfPelSet() ............................................................................................................... 3343
cfPelSpatialAvg() .................................................................................................. 3345
cfPelSub() ............................................................................................................. 3349
cfPelTranspose() .................................................................................................. 3353
cfPMInspectDisplayFeatures() ............................................................................ 3355
cfPolarTransformImage() .................................................................................... 3357
cfPolylineShapeModel() ....................................................................................... 3359
cfPolySetNearestPoints() .................................................................................... 3361
cfProjectImage() ................................................................................................... 3363
cfRasterize() .......................................................................................................... 3367
cfRasterizeContour() ............................................................................................ 3373
cfRealEq() ............................................................................................................. 3375
cfRegionize() ......................................................................................................... 3379
cfRGBExtract() ..................................................................................................... 3383
cfRGBPack() ......................................................................................................... 3385
cfRGBSeparateColorPlanes() ............................................................................. 3387
cfSampledImageWarp() ....................................................................................... 3389
cfSegmentColorImage ......................................................................................... 3391
26
CVL Class Reference
Contents
cfSegmentFeature() ............................................................................................. 3395
cfSemiTrigger() ...................................................................................................... 3397
cfSetLanguage() .................................................................................................... 3399
cfSqr() .................................................................................................................... 3401
cfSetThreadPriority() ........................................................................................... 3403
cfSlaveTrigger() .................................................................................................... 3405
cfSystemTimeGet() .............................................................................................. 3407
cfSystemTimeSet() ............................................................................................... 3409
cfThreadCleanup() ............................................................................................... 3411
cfThresholdWGV() ................................................................................................ 3413
cfTruePeak() ......................................................................................................... 3415
cfVerifyOcrChecksum() ....................................................................................... 3417
cfVerifyOcrString() ............................................................................................... 3419
cfWaitForContinue() ............................................................................................. 3421
cfWaitForThreadTermination() ............................................................................ 3423
CompleteArgs ....................................................................................................... 3425
Index ....................................................................................................................... 3431
CVL Class Reference
27
Contents
28
CVL Class Reference
Preface
This manual contains reference information for the Cognex Vision Library (CVL). CVL is
a powerful C++ class library you can use to write machine vision applications for the
Cognex MVS-8000 family of frame grabbers and vision processors.
CVL Class Reference
29
Preface
Style Conventions Used in This Manual
This manual uses the style conventions described in this section for text and software
diagrams.
Text Style Conventions
This manual uses the following style conventions for text:
boldface
Used for C/C++ keywords, function names,
class names, structures, enumerations,
types, and macros. Also used for user
interface elements such as button names,
dialog box names, and menu choices.
italic
Used for names of variables, data members,
arguments, enumerations, constants,
program names, file names. Used for names
of books, chapters, and sections.
Occasionally used for emphasis.
courier
Used for C/C++ code examples and for
examples of program output.
bold courier
Used in illustrations of command sessions to
show the commands that you would type.
<italic>
When enclosed in angle brackets, used to
indicate keyboard keys such as <Tab> or
<Enter>.
Microsoft Windows Support
Cognex CVL software runs on Windows 2000 and Windows XP operating systems. In
this documentation set, these are abbreviated to Windows unless there is a feature
specific to one of the variants. Consult the Getting Started manual for your CVL release
for details on the operating systems, hardware, and software supported by that release.
30
CVL Class Reference
Preface
Software Diagramming Conventions
This manual uses the following symbols in class diagrams:
•
Classes are shown as a box with the class name centered inside the box. For
example, a class A with the C++ declaration
class A{};
is shown graphically as follows:
A
•
Inheritance relationships between classes are shown using solid-line arrows from
the derived class to the base class with a large, hollow triangle pointing toward the
base class. For example, a class B that inherits from a class A with the declaration
class B : public A {};
is shown graphically as follows:
B
A
CVL Class Reference
31
Preface
•
Template classes are shown as a class box with a smaller, dotted-line rectangle
representing the template parameter superimposed on the upper right corner of the
class box. For example, a template class C with a parameter of type class T with
the declaration:
template <class T>
class C{};
is shown graphically as follows:
T
C
These symbols are based on the Unified Modeling Language (UML), a standard
graphical notation for object-oriented analysis and design. See the latest OMG Unified
Modeling Language Specification (available from the Object Management Group at
http://www.omg.org) for more information.
Cognex Offices
Cognex Corporation serves its customers from the following locations:
32
Corporate Headquarters
Cognex Corporation
Corporate Headquarters
One Vision Drive
Natick, MA 01760-2059
(508) 650-3000
Web Site
http://www.cognex.com
CVL Class Reference
cc1394DCAM
#include <ch_cvl/vpdcam.h>
class cc1394DCAM : public ccUnknownFG;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes an individual IEEE 1394 DCAM-compliant camera connected to a
computer system. There is one instance of this class for each connected camera. You
use the static get() function to obtain a specific instance.
cc1394DCAM& fwCam = cc1394DCAM::get(0);
Calling the name() function (a member of ccBoard, from which this class is derived)
returns the name of the particular camera, formatted as shown below:
1394DCAM: <camera_vendor>: <camera_model>
Constructors/Destructors
A single instance of this class is created automatically for each IEEE 1394 DCAM
camera connected to your system.
Enumerations
enum
enum { ceSpeedFlag100 = 0x01, ceSpeedFlag200 = 0x02,
ceSpeedFlag400 = 0x04, ceSpeedFlag800 = 0x08,
ceSpeedFlag1600 = 0x10, ceSpeedFlag3200 = 0x20 };
IEEE 1394 bus speed flag values:
CVL Class Reference
Value
Meaning
ceSpeedFlag100 = 0x01
100 MBits/Sec, 1394a and 1394b
ceSpeedFlag200 = 0x02
200 MBits/Sec, 1394a and 1394b
ceSpeedFlag400 = 0x04
400 MBits/Sec, 1394a(max) and 1394b
ceSpeedFlag800 = 0x08
800 MBits/Sec, 1394b(max)
33
cc1394DCAM
OrderingMode
Value
Meaning
ceSpeedFlag1600 = 0x10
Reserved for future use
ceSpeedFlag3200 = 0x20
Reserved for future use
enum OrderingMode { eLegacy, ePhysicalID };
The camera ordering mode. This determines how multiple IEEE 1394 cameras are
assigned index values.
Value
Meaning
eLegacy
Cameras are ordered by unique camera identifier. A
given set of cameras will appear in a fixed order
regardless of how they are connected.
Replacing a camera is likely to change the camera
order.
ePhysicalID
Cameras are ordered by 1394 physical id, such that
their order is determined solely by their location in the
1394 topology.
Replacing a camera is guaranteed not to change the
camera order.
Public Member Functions
count
static c_Int32 count();
Returns The number of IEEE 1394 DCAM cameras connected to this system.
get
static cc1394DCAM& get(c_Int32 i = 0);
Returns a cc1394DCAM object that represents the specified camera. The association
between specific IEEE 1394 DCAM cameras and their index values is undefined. You
can use the name() and serialNumber() functions to identify the camera returned by
this function.
Parameters
i
The index of the camera to get.
Throws
ccBoard::BadParams
i is less than zero or greater than or equal to count().
34
CVL Class Reference
cc1394DCAM
Notes
For any given index value, the object returned by this function and the object
returned by calling ccBoard::get() with the same index may not refer to the same
device, since ccBoard::get() returns references to all devices, such as Cognex
frame grabbers, not just IEEE 1394 DCAM cameras.
serialNumber
virtual ccCvlString serialNumber() const;
Returns the serial number of the IEEE 1394 DCAM camera. The format of the returned
string is specific to the camera type.
busNumber
c_Int32 busNumber() const;
Returns the 10-bit bus number that identifies the IEEE 1394 bus to which the device is
connected.
Notes
Under Microsoft Windows this function always returns bus 1023 (0x3FF).
nodeNumber
c_Int32 nodeNumber() const;
Returns the 6-bit node address that identifies the IEEE 1394 DCAM.
unit_sw_version
c_UInt32 unit_sw_version() const;
Returns the contents of the unit_sw_version register in the camera configuration ROM.
Returned values have the following meanings:
CVL Class Reference
Returned Value
Meaning
0x100
The camera interface version is DCAM 1.04.
0x101
The camera interface version is DCAM 1.20.
0x102
The camera interface version is at least DCAM 1.30. You must call
unit_sub_sw_version() below to find the exact IIDC interface
version used.
35
cc1394DCAM
unit_sub_sw_version
c_UInt32 unit_sub_sw_version() const;
Returns the contents of the unit_sub_sw_version register in the camera configuration
ROM.
Returned values have the following meanings:
Returned Value
Meaning
0x00
The camera interface version is IIDC 1.30 or less.
0x10
The camera interface version is IIDC 1.31.
> 0x10
Values greater than 0x10 are reserved for future use.
Notes
If unit_sw_version() returns 0x100 or 0x101, this function will return 0x0. The
values in the table above are only valid when unit_sw_version() returns 0x102.
Refer to the official IEEE 1394 DCAM and IIDC specifications for more information.
ieee1394ControllerID
ccCvlString ieee1394ControllerID() const;
Returns the IEEE 1394 host controller ID to which the DCAM camera is connected.
vendorID
c_UInt32 vendorID() const;
Returns the vendor ID of the camera from its configuration ROM.
readRegister
bool readRegister(c_UInt32 addr, c_UInt32& value) const;
Reads a register from the specified address in the camera’s register space. Returns true
if the function succeeded and false otherwise. Each register contains 4 bytes (a
quadlet).
Parameters
addr
value
36
The camera register to read.
Contains the register value after a successful read.
CVL Class Reference
cc1394DCAM
Notes
An address (addr) with a leading 0xF (0xF0000000) will be interpreted as an
absolute offset in the camera’s register space. If there is no leading 0xF the address
is added to the camera’s Configuration and Status Register (CSR) offset.
For example, the following two addresses both reference the same camera register
(BASIC_FUNC_INQ).
0x400 (CSR offset)
0xF0F00400 (Absolute address)
writeRegister
bool writeRegister(c_UInt32 addr, c_UInt32 value) const;
Writes to a register in the camera’s register space. Returns true if the function
succeeded and false otherwise.
Parameters
addr
value
The address of the camera register to write.
The new value to write into the register.
Notes
An address (addr) with a leading 0xF (0xF0000000) will be interpreted as an
absolute offset in the camera’s register space. If there is no leading 0xF the address
is added to the camera’s Configuration and Status Register (CSR) offset.
connectionSpeed
c_UInt32 connectionSpeed() const;
Returns the IEEE 1394 bus speed supported between the DCAM camera and its
adapter. The reported speed will be the highest common speed supported by the
adapter, the camera, and any hub(s) in use.
Returns a numerical value representing an IEEE 1394 bus speed. See enum on page 33.
CVL Class Reference
37
cc1394DCAM
busEventCallback
void busEventCallback(const ccCallbackDcamBusEventPtrh&);
const ccCallbackDcamBusEventPtrh& busEventCallback()
const;
•
void busEventCallback(const ccCallbackDcamBusEventPtrh&);
Gets the callback function that is invoked when an IEEE 1394 bus reset occurs or when
a camera is unplugged. Returns NULL if there is no callback function associated with
this camera.
•
const ccCallbackDcamBusEventPtrh& busEventCallback()
const;
Sets the callback function that is invoked when an IEEE 1394 bus reset occurs or when
a camera is unplugged.
The callback function is a one-argument function that takes reference to a
ccDcamBusEventInfo object as an argument:
void myBusResetCallback(ccDcamBusEventInfo& e);
When the callback is invoked, its ccDcamBusEventInfo parameter is filled in with
information about the corresponding bus event. See ccDcamBusEventInfo on
page 1159.
IEEE 1394 bus resets can occur due to a variety of reasons including adding or
removing a camera from the bus, a faulty cable or connector, a camera firmware
problem, etc.
The callback function is invoked only when the bus reset is detected on the IEEE1394
bus that this camera is connected to. Bus resets that happen on other busses will not
invoke the callback.
If this DCAM camera is disconnected from the IEEE 1394 bus, the callback function is
invoked and return a device unplugged status. Callbacks will no longer be invoked.
Notes
Unplugging a camera when CVL is running is not supported. The only way to
recover communication with a camera in this situation is to restart CVL with the
camera plugged in
38
CVL Class Reference
cc1394DCAM
cameraOrderingMode
static void cameraOrderingMode(OrderingMode mode);
static OrderingMode cameraOrderingMode();
•
static void cameraOrderingMode(OrderingMode mode);
Sets the camera ordering mode to use when enumerating cameras.
Parameters
mode
The ordering mode. Must be one of:
cc1394DCAM:eLegacy
cc1394DCAM:ePhysicalID
Cognex recommends that you use the default value of cc1394DCAM:ePhysicalID. This
ordering mode allows you to replace cameras in deployed applications without
changing the returned camera order.
cc1394DCAM:eLegacy is provided for backward compatibility only; it provides the
same behavior that was present in CVL versions before 6.6.
Notes
You must call this function before any call to ccBoard::count() or
cc1394DCAM::count().
•
static OrderingMode cameraOrderingMode();
Returns the current camera ordering mode. The returned value is one of the following:
cc1394DCAM:eLegacy
cc1394DCAM:ePhysicalID
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
CVL Class Reference
39
cc1394DCAM
Throws
ccBoard::HardwareInUse
The current process tried to access a camera that is already
owned by another running process. To avoid this error, a process
that touches the camera must exit before another process can
access the same hardware.
ccBoard::HardwareNotResponding
A camera communication error occurred.
40
CVL Class Reference
cc1Xform
#include <ch_cvl/xform.h>
class cc1Xform;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class describes a one-dimensional transformation object You can use it to scale
and offset points along one axis.
Constructors/Destructors
cc1Xform
cc1Xform();
cc1Xform(double scale, double offset);
•
cc1Xform();
Creates a new transformation object. Points are not scaled and not offset.
•
cc1Xform(double scale, double offset);
Creates a new transformation object in which points are scaled by scale and offset by
offset.
Parameters
scale
offset
CVL Class Reference
The amount by which to scale a point.
The amount by which to offset the scaled point.
41
cc1Xform
Operators
operator*
cc1Xform operator* (const cc1Xform& xform) const;
double operator* (double pt) const;
•
cc1Xform operator* (const cc1Xform& xform) const;
Return the transformation object that is the result of composing this transformation
object with xform, that is, the transformation object that gives the same result as
mapping a point first by this transformation object and then by xform.
Parameters
xform
•
The transformation object to compose with this transformation
object.
double operator* (double pt) const;
Maps the point pt according to the transformation object:
result = scale * pt + offset;
Parameters
pt
operator==
The point to be mapped.
bool operator== (const cc1Xform& that) const;
Return true if this transformation object is equal to that.
Parameters
that
operator!=
The other transformation object.
bool operator!= (const cc1Xform&) const;
Return true if this transformation object is not equal to that.
Parameters
that
42
The other transformation object.
CVL Class Reference
cc1Xform
Public Member Functions
offset
double offset();
void offset(double offset);
•
double offset();
Returns the offset component of the transformation object. The offset is the amount that
the transformation matrix adds or subtracts to a scaled point.
•
void offset(double offset);
Sets the offset of the transformation object.
Parameters
offset
scale
The amount to add or subtract to a point.
double scale();
void scale(double scale);
•
double scale();
Returns the scale component of the transformation object. The scale is the amount by
which the transformation object multiplies a point.
•
void scale(double scale);
Parameters
scale
inverse
The amount by which to multiply a point.
cc1Xform inverse() const;
Return the inverse transformation object for this transformation object.
Throws
ccMathError::Singular
The transformation is singular (scale = 0).
CVL Class Reference
43
cc1Xform
compose
cc1Xform compose(const cc1Xform& xform) const;
Return the transformation object that is the result of composing this transformation
object with xform, that is, the transformation object that gives the same result as
mapping a point first by this transformation object and then by xform.
Parameters
xform
The transformation object to compose with this transformation
object.
Notes
This is the same function as the multiplication (*) operator when the other operator
is a cc1Xform.
mapPoint
double mapPoint (double pt) const;
Map the point pt according to the transformation object:
result = scale * pt + offset;
Parameters
pt
The point to be mapped.
Notes
This is the same function as the multiplication (*) operator when the other operator
is a point.
invMapPoint
double invMapPoint (double pt) const;
Maps the point pt by the inverse of this transformation object:
result = 1/scale * (pt - offset);
Throws
ccMathError::Singular
The transformation is singular.
mapVector
double mapVector (double vect) const;
Scales the vector:
result = scale * vect;
Parameters
vect
44
The vector to scale.
CVL Class Reference
cc1Xform
invMapVector
double invMapVector (double vect) const;
Scales the vector: result = 1/scale * vect
Parameters
vect
Throws
ccMathError::Singular if the transformation object is singular.
isIdentity
bool isIdentity() const;
Return true if the transformation object is the identity transform.
isSingular
bool isSingular();
Return true if the transformation is singular; that is, all points map to the same point.
Data Members
I
static const cc1Xform I;
The identity transformation object for cc1Xform.
CVL Class Reference
45
cc1Xform
46
CVL Class Reference
cc2Matrix
#include <ch_cvl/matrix.h>
template <int D> class ccMatrix;
typedef ccMatrix<2> cc2Matrix;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class implements a four element, 2 by 2 square matrix that allows for 2D
transformations.
Note
CVL Class Reference
The template parameter, D, in the class definition specifies the
dimension of a ccMatrix. For example, ccMatrix<2> specifies a 2x2
matrix. cc2Matrix is a type definition for a ccMatrix<> object
instantiated with a template parameter of 2. Similarly, ccMatrix<3>
specifies a 3x3 matrix. cc3Matrix is a type definition for a
ccMatrix<> object instantiated with a template parameter of 3.
47
cc2Matrix
The cc2Matrix member functions let you specify the elements of the transformation
matrix in three different modalities:
1.
The explicit mode. In this modality you explicitly define the four elements of the
matrix. When you use this modality, the mapping between image coordinates (Ix, Iy)
and client coordinates (Cx, Cy) is:
Cx
Cy
=
e 11 e 12 I x
e 21 e 22 I y
where e11, e12, e21, e22 are the matrix elements that you have specified. (For the
definition of image coordinates and client coordinates as well as an overview on
image transformations see Images and Coordinates in the CVL User’s Guide).
2.
The scale-rotation mode. In this modality the matrix is specified by the rotation of
the x-axis (rx), the rotation of the y-axis (ry), the x-scale (sx) and the y-scale (sy).
When you use this modality, the mapping between image coordinates (Ix, Iy) and
client coordinates (Cx, Cy) is:
Cx
Cy
3.
=
s x cos r x – s y sin r y I x
s x sin r x s y cos r y I y
The shear-aspect mode. In this modality the matrix is specified by the scale of the
coordinate system (S), the aspect ratio of the x- and y- axes (A), the shear angle (K)
and the rotation angle of the coordinate system(R).When you use this modality, the
mapping between image coordinates (Ix, Iy) and client coordinates (Cx, Cy) is:
Cx
Cy
I
= S cos R AS ( – sin R – cos R tan K ) x
S sin R AS ( – cos R – sin R tan K ) I y
The scale-rotation and shear-aspect modalities are equivalent, so you can use the one
that best suits your application or existing algorithms. However, it is important not mix
elements from one modality with elements from the other modality. For example, if you
specified a shear angle (K) in the shear-aspect mode, then A ≠ s y ⁄ s x . In general the
scale-rotation mode is easier to work with.
Note
48
cc2Matrix is the name of the class as it is used throughout the
Cognex Vision Library. This name is actually a typedef for
ccMatrix<2>. Both forms are valid and entirely equivalent.
CVL Class Reference
cc2Matrix
Constructors/Destructors
cc2Matrix
cc2Matrix();
cc2Matrix(double e11, double e12, double e21, double e22);
cc2Matrix(const ccRadian& xRot, const ccRadian& yRot,
double xScale, double yScale);
cc2Matrix(double scale, double aspect,
const ccRadian& shear, const ccRadian& rotation);
•
cc2Matrix();
The default constructor initializes this matrix to the identity matrix ( 1 0 )
01
•
cc2Matrix(double e11, double e12, double e21, double e22);
Initializes this matrix according to the explicit mode. The constructor sets the elements
of the matrix to e11, e12, e21, e22.
Parameters
e11
•
The element of the matrix corresponding to the first row and first
column.
e12
The element of the matrix corresponding to the first row and
second column.
e21
The element of the matrix corresponding to the second row and
first column.
e22
The element of the matrix corresponding to the second row and
second column.
cc2Matrix(const ccRadian& xRot, const ccRadian& yRot,
double xScale, double yScale);
Initializes this matrix according to the scale-rotation mode.
CVL Class Reference
xRot
The x-rotation; the amount by which to rotate the x-axis in radians.
yRot
The y-rotation; the amount by which to rotate the y-axis in radians.
xScale
The x-scale; the amount by which to scale the x-axis units.
yScale
The y-scale; the amount by which to scale the y-axis units.
49
cc2Matrix
•
cc2Matrix(double scale, double aspect,
const ccRadian& shear, const ccRadian& rotation);
Initializes this matrix according to the shear-aspect mode.
scale
The scale element; the amount by which to scale all units.
aspect
The aspect ratio; the ratio of the x-axis units to the y-axis units.
shear
The shear element; the amount by which to rotate the y-axis in
radians.
rotation
The rotation element; the amount by which to rotate the entire
coordinate system in radians.
Operators
operator+
cc2Matrix operator+(const cc2Matrix& m) const;
Returns the sum of this matrix and the matrix m.
Parameters
m
operator+=
The matrix added to this matrix.
cc2Matrix& operator+=(const cc2Matrix& m);
Sets this matrix to the sum of this matrix and the matrix m.
Parameters
m
operator-
The matrix added to this matrix.
cc2Matrix operator-() const;
cc2Matrix operator-(const cc2Matrix& m) const;
•
cc2Matrix operator-() const;
Returns a matrix whose elements are the opposite (i.e. multiplied by -1) of the elements
of this matrix.
•
cc2Matrix operator-(const cc2Matrix& m) const;
Returns the difference between this matrix and the matrix m.
Parameters
m
50
The matrix subtracted from this matrix.
CVL Class Reference
cc2Matrix
operator-=
cc2Matrix& operator-=(const cc2Matrix& m);
Sets this matrix to the difference of this matrix and the matrix m.
Parameters
m
operator*
The matrix subtracted from this matrix.
cc2Matrix operator*(double s) const;
cc2Matrix operator*(const cc2Matrix& m) const;
cc2Vect operator*(const cc2Vect& v);
•
cc2Matrix operator*(double s) const;
Returns a matrix whose elements are equal to the elements of this matrix times s.
Parameters
s
•
The value each element of this matrix is multiplied by.
cc2Matrix operator*(const cc2Matrix& m) const;
Returns the matrix that is the composition of this matrix and the matrix m. Mapping a
point with the resulting matrix is equivalent to first mapping the point by the matrix m and
then by this matrix.
Parameters
m
•
The matrix composed with this matrix.
cc2Vect operator*(const cc2Vect& v) const;
Returns the vector resulting from the product of this matrix and the vector v
(representing a point). The vector returned is the point v transformed by this matrix.
Parameters
v
operator*=
The vector transformed by this matrix.
cc2Matrix& operator*=(double s);
cc2Matrix& operator*=(const cc2Matrix& m);
•
cc2Matrix& operator*=(double s);
Sets this matrix to the product of this matrix and s.
CVL Class Reference
51
cc2Matrix
Parameters
s
•
The value each element of this matrix is multiplied by.
cc2Matrix& operator*=(const cc2Matrix& m);
Sets this matrix to the composition of this matrix and m.
Parameters
m
operator/
The matrix composed with this matrix
cc2Matrix operator/(double s);
cc2Matrix operator/(const cc2Matrix& m);
•
cc2Matrix operator/(double s);
Returns a matrix whose elements are equal to the elements of this matrix divided by s.
Parameters
s
•
The value each element of this matrix is divided by.
cc2Matrix operator/(const cc2Matrix& m);
Returns the matrix composed by this matrix and the inverse of m.
Parameters
m
operator/=
The matrix whose inverse is composed with this matrix.
cc2Matrix& operator/=(double s);
cc2Matrix operator/=(const cc2Matrix& m);
•
cc2Matrix& operator/=(double s);
Sets this matrix to the quotient of this matrix and s.
Parameters
s
•
The value each element of the matrix is divided by.
cc2Matrix operator/=(const cc2Matrix& m);
Sets this matrix to the matrix composed by this matrix and the inverse of m.
Parameters
m
The matrix whose inverse is composed with this matrix.
Throws
52
CVL Class Reference
cc2Matrix
ccMathError::Singular
The matrix used as a divisor is singular.
operator==
bool operator==(const cc2Matrix& m) const;
Returns true if all the elements of this matrix are the same as the corresponding elements
of the matrix m.
m
operator!=
The matrix compared to this matrix.
bool operator!=(const cc2Matrix& m) const;
Returns true if this matrix is not the same as m.
Parameters
m
The matrix compared to this matrix.
Friends
operator *=
friend cc2Vect operator*=(const cc2Vect& v,
const cc2Matrix& m);
Returns the vector resulting from the left-product of the matrix m with the vector v. If
Vx
v =
and m =
Vy
Vx Vy
m 11 m 12
m 21 m 22
Parameters
v
m
m 11 m 12
the left-product of m with v is defined as
m 21 m 22
= ( V x m 11 + V y m 21 ) ( V x m 12 + V y m 22
The vector multiplied with m.
The matrix multiplied with v.
Public Member Functions
determinant
double determinant() const;
t t
Returns the determinant of this matrix. If this = 11 12 the value returned is
t 21 t 22
t11t22 - t12t21.
CVL Class Reference
53
cc2Matrix
inverse
cc2Matrix inverse() const;
t
– t 12
1
Returns the inverse of this matrix. The inverse of this matrix is ⎛ ------------------------⎞ 22
⎝ det [ this ]⎠ – t
where det [ this ] is the determinant of this matrix.
21 t 11
Throws
ccMathError::Singular
The transformation matrix is singular.
transpose
cc2Matrix transpose() const;
Returns the transpose of this matrix. If this =
is
t 11 t 21
t 11 t 12
the transpose of this matrix
t 21 t 22
.
t 12 t 22
isSingular
bool isSingular() const;
Returns true if this matrix is singular (i.e. if det [ this ] is exactly equal to zero).
isIdentity
bool isIdentity() const;
Returns true if this matrix is the identity matrix.
element
double element(c_Int32 row,c_Int32 column) const;
void element(c_Int32 row,c_Int32 column, double value);
•
double element(c_Int32 row,c_Int32 column) const;
Returns the element of this matrix specified by the indices row and column.
Parameters
row
The row-index.
0: Identifies the first row.
1: Identifies the second row.
column
The column-index.
0: Identifies the first column.
1: Identifies the second column.
54
CVL Class Reference
cc2Matrix
•
void element(c_Int32 row,c_Int32 column, double value);
Sets the element of this matrix specified by the indices row and column to s.
Parameters
row
The row-index.
0: identifies the first row.
1: identifies the second row.
column
The column-index.
0: identifies the first column.
1: identifies the second column.
value
xRot
The value the matrix element specified by row and column is set
to.
ccRadian xRot() const;
Returns the x-rotation element of this matrix when using the scale-rotation specification.
Throws
ccMathError::Singular
This matrix is singular.
yRot
ccRadian yRot() const;
Returns the y-rotation element of this matrix when using the scale-rotation specification.
Throws
ccMathError::Singular
This matrix is singular.
xScale
double xScale() const;
Returns the x-scale element of this matrix when using the scale-rotation specification.
Throws
ccMathError::Singular
This matrix is singular.
yScale
double yScale() const;
Returns the y-scale element of this matrix when using the scale-rotation specification.
CVL Class Reference
55
cc2Matrix
Throws
ccMathError::Singular
This matrix is singular.
scale
double scale() const;
Returns the scale element of this matrix when using the shear-aspect specification.
Throws
ccMathError::Singular
This matrix is singular.
aspect
double aspect() const;
Returns the aspect element of this matrix when using the shear-aspect specification.
Throws
ccMathError::Singular
This matrix is singular.
shear
ccRadian shear() const;
Returns the shear element of this matrix when using the shear-aspect specification.
Throws
ccMathError::Singular
This matrix is singular.
rotation
ccRadian rotation() const;
Returns the rotation element of this matrix when using the shear-aspect specification.
Throws
ccMathError::Singular
This matrix is singular.
Data Members
I
static const cc2Matrix I;
The identity transformation matrix for cc2Matrix.
56
CVL Class Reference
cc2Point
#include <ch_cvl/shapes.h>
class cc2Point : public ccShape;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class describes a point. In most cases, you can use either cc2Point or cc2Vect to
describe locations in a coordinate system. This class, however, is a full-fledged
ccShape andinherits all of the methods of that class.
Constructors/Destructors
cc2Point
cc2Point();
cc2Point(const cc2Vect& v);
cc2Point(double x, double y);
•
cc2Point();
Default constructor. Constructs a point with coordinates (0,0).
•
cc2Point(const cc2Vect& v);
Conversion constructor. Constructs a point with coordinates equal to the coordinates of
the supplied vector.
Parameters
v
•
The vector.
cc2Point(double x, double y);
Constructs a point with x and y coordinates equal to the supplied values.
Parameters
x
CVL Class Reference
The x value.
57
cc2Point
y
The y value.
Operators
operator==
bool operator==(const cc2Point &rhs) const;
Returns true if this point is equal to rhs, under strict floating point equality.
Parameters
rhs
operator!=
The other cc2Point.
bool operator!=(const cc2Point &rhs) const;
Returns true if this point is not equal to rhs, under strict floating point equality.
Parameters
rhs
The other cc2Point.
Public Member Functions
x
double x() const;
double x(double val);
•
double x() const;
Gets the x coordinate of this point.
•
double x(double val);
Sets the x coordinate of this point.
Parameters
val
y
The value to which the x coordinate is set.
double y() const;
void y(double val);
•
double y() const;
Gets the y coordinate of this point.
58
CVL Class Reference
cc2Point
•
void y(double val);
Sets the y coordinate of this point.
Parameters
val
vect
The value to which the y coordinate is set.
const cc2Vect& vect() const;
void vect(const cc2Vect &val);
•
const cc2Vect& vect() const;
Returns the vector representation of this point.
•
void vect(const cc2Vect &val);
Sets the vector representation of this point.
Parameters
val
map
The vector that represents this point.
cc2Point map(const cc2Xform& c) const;
Returns the result of mapping this point with the transformation object c.
Parameters
c
clone
The transformation object.
virtual ccShapePtrh clone() const;
Returns a pointer to a copy of this point.
isOpenContour
virtual bool isOpenContour() const;
Returns true if this shape is an open contour. For points, this function always returns true.
See ccShape::isOpenContour() for more information.
isRegion
virtual bool isRegion() const;
Returns true if this shape is a region. For points, this function always returns false. See
ccShape::isRegion() for more information.
CVL Class Reference
59
cc2Point
isFinite
virtual bool isFinite() const;
For points, this function always returns true. See ccShape::isFinite() for more
information.
isEmpty
virtual bool isEmpty() const;
Returns true if the set of points that lie on the boundary of this shape is empty. For points,
this function always returns false. See ccShape::isEmpty() for more information.
hasTangent
virtual bool hasTangent() const;
For points, this function always returns false. See ccShape::hasTangent() for more
information.
isDecomposed
virtual bool isDecomposed() const;
For points, this function always returns false. See ccShape::isDecomposed() for more
information.
isReversible
virtual bool isReversible() const;
For points, this function always returns true. See ccShape::reverse() for more
information.
boundingBox
virtual ccRect boundingBox() const;
Returns the smallest rectangle that encloses this point.
Notes
This function succeeds the deprecated encloseRect(). However, note that
boundingBox() returns a rectangle of size (0, 0), while encloseRect() returned a
rectangle of size (1, 1) for points.
See ccShape::boundingBox() for more information.
nearestPoint
virtual cc2Vect nearestPoint(const cc2Vect &p) const;
Returns this cc2Point.
Parameters
p
60
The point.
CVL Class Reference
cc2Point
perimeter
virtual double perimeter() const;
Returns 0.0 for any point.
nearestPerimPos
virtual ccPerimPos nearestPerimPos(const ccShapeInfo& info,
const cc2Vect& point) const;
Returns the nearest perimeter position on this shape to the given point. For a point, the
returned perimeter position specifies the point itself.
Parameters
info
point
Shape information for this point.
The other point.
Notes
The ccPerimPos::distAlongPrimitive() component of the returned perimeter
position is equal to 0.0.
See ccShape::nearestPerimPos() for more information.
startPoint
virtual cc2Vect startPoint() const;
Returns this cc2Point. See ccShape::startPoint() for more information.
endPoint
virtual cc2Vect endPoint() const;
Returns this cc2Point. See ccShape::endPoint() for more information.
startAngle
virtual ccRadian startAngle() const;
Throws
ccShapesError::NoTangent
hasTangent() is always false for cc2Point.
See ccShape::startAngle() for more information.
endAngle
virtual ccRadian endAngle() const;
Throws
ccShapesError::NoTangent
hasTangent() is always false for cc2Point.
See ccShape::endAngle() for more information.
CVL Class Reference
61
cc2Point
tangentRotation
virtual ccRadian tangentRotation() const;
Throws
ccShapesError::NoTangent
hasTangent() is always false for cc2Point.
See ccShape::tangentRotation() for more information.
windingAngle
virtual ccRadian windingAngle(const cc2Vect &p) const;
Returns 0.0 for a cc2Point.
Parameters
p
The start point of the vector p->t where t is this point.
See ccShape::windingAngle() for more information.
reverse
virtual ccShapePtrh reverse() const;
Returns this cc2Point. See ccShape::reverse() for more information.
sample
virtual void sample(const ccShape::ccSampleParams &params,
ccSampleResult &result) const;
Adds this cc2Point to result if params.computeTangents() is false.
Parameters
params
result
Specifies details of how the sampling should be done.
Result object to which position chains are appended.
Notes
If params.computeTangents() is true, this cc2Point does not contribute any
samples to result.
mapShape
virtual ccShapePtrh mapShape(const cc2Xform& X) const;
Returns this point mapped by X.
Parameters
X
The transformation object.
See ccShape::mapShape() for more information.
62
CVL Class Reference
cc2Point
decompose
virtual ccShapePtrh decompose() const;
Returns a zero-length line segment with both endpoints coincident with this point. See
ccShape::decompose() for more information.
subShape
virtual ccShapePtrh subShape(const ccShapeInfo &info,
const ccPerimRange &range) const;
Returns a pointer handle to this point.
Parameters
info
range
Shape information for this point.
The perimeter range. If the distance component of this
ccPerimRange is greater than 0.0, it is internally clipped to 0.0.
See ccShape::perimeter() for more information.
CVL Class Reference
63
cc2Point
64
CVL Class Reference
cc2Rigid
#include <ch_cvl/xform.h>
class cc2Rigid;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class implements a rigid transformation of coordinate data.The transformation can
be also thought of as a mapping of features from an initial coordinate frame to a second
frame. The transformation is called rigid because the data are mapped by a simple
rotation and translation, no distortions due to scaling or skews are present. The following
figure illustrates a rigid transformation that maps features from Frame A to Frame B. The
transformation is defined by a 2-element translation vector and by a rotation angle. The
elements of the translation vector specify the amount by which Frame A is translated
along the X- and Y- directions of Frame B (Tx and Ty in the following figure), while the
rotation angle specifies the angle by which the coordinate axes are rotated from Frame
B (θ in the following figure)
Translation vector Tx
XB
Frame B
Ty
XA
Rotation angle θ
Frame
A
YA
YB
X
X
P
Y
Y
CVL Class Reference
65
cc2Rigid
If your data are initially represented in Frame A, the member functions of cc2Rigid allow
you to map them to their representation in Frame B. For example, if (XA, YA) are the
coordinates of the point P in Frame A, the class provides you with ways to return the
coordinates of the point in Frame B (XB, YB). The two points are mathematically related
by the following expression:
XB
YB
=
cos θ – sin θ X A + T x
sin θ cos θ Y A
Ty
As an illustration, consider the rigid transformation characterized by the translation
vector (2,2) and the rotation angle of 90 degrees (see following figure). In this case the
point (1,1) in Frame A is mapped to the point (1, 3) in Frame B.
Fram
X
eB
X
A
ame
in Fr
B
)
e
1
,
(1
am
in Fr
)
3
,
1
(
1
1
1
3
Y
eA
Fram
Y
XB
YB
66
=
cos ( 90 ) – sin ( 90 ) 1 + 2 = 0 – 1 1 + 2 = – 1 + 2 = 1
sin ( 90 ) cos ( 90 ) 1
2
1 0 1
2
1
2
3
CVL Class Reference
cc2Rigid
Constructors/Destructors.
cc2Rigid
cc2Rigid();
cc2Rigid(const ccDegree& a, const cc2Vect& t);
•
cc2Rigid();
The default constructor initializes this rigid transformation to the identity transformation,
that is the transformation which maps features to their current location, leaving them
unchanged. The identity transformation is defined by a translation vector whose
components are both 0 (no translation) and a rotation angle of 0 degrees (no rotation).
•
cc2Rigid(const ccDegree& a, const cc2Vect& t);
Initializes the rotation angle and the translation vector of this rigid transformation.
Parameters
a
t
The rotation angle assigned to this rigid transformation.
The translation vector assigned to this rigid transformation.
Operators
operator*
cc2Rigid operator*(const cc2Rigid& xform) const;
cc2Xform operator*(const cc2Xform& xform) const;
cc2Vect operator*(const cc2Vect &pt) const;
•
cc2Rigid operator*(const cc2Rigid& xform) const;
Returns the rigid transformation that is the composition of this rigid transformation and
xform. Mapping the resulting rigid transformation is equivalent to first mapping xform
and then this rigid transformation. For example, assume that xform is defined by the
translation vector t1 and by the rotation angle a1 while this rigid transformation is defined
by the translation vector t2 and the rotation angle a2 (see following figure). The rigid
transformation returned by the operator has the same effect as the following sequence
of transformations.
4.
CVL Class Reference
xform maps data from Frame A to Frame B.
67
cc2Rigid
5.
This rigid transformation maps data from Frame B to Frame C.
X Frame C
t2
a2
t1
X
Frame B
Y
a1
Y
X
Frame A
Y
Parameters
xform
•
The rigid transformation composed with this rigid transformation.
cc2Xform operator*(const cc2Xform& xform) const;
This operator returns the cc2Xform transformation object resulting from the composition
of this rigid transformation and xform. Mapping a point with the resulting cc2Xform
transformation object is equivalent to first mapping the point by xform and then by this
rigid transformation.
Parameters
xform
68
The cc2Xform transformation object composed with this rigid
transformation.
CVL Class Reference
cc2Rigid
•
cc2Vect operator*(const cc2Vect &pt) const;
Maps the coordinates of the point pt using this rigid transformation. The point (XA, YA) in
Frame A is mapped to (XB, YB) in Frame B (see following figure). The operation
performed by this operator is equivalent to the one performed by the function mapPoint.
Frame B
XB
XA
X
Frame
A
X
YA
YB
P
Y
Y
Parameters
pt
operator ==
The point whose coordinates are mapped.
bool operator==(const cc2Rigid& xform) const;
Returns true if this rigid transformation is exactly the same as xform (that is, if the
translation and rotation of the two transformations are the same).
Parameters
xform
operator!=
The rigid transformation compared to this rigid transformation.
bool operator!=(const cc2Rigid& xform) const;
Returns true if this rigid transformation is not the same as xform.
Parameters
xform
CVL Class Reference
The transformation compared to this rigid transformation.
69
cc2Rigid
Friends
operator*
cc2Xform operator*(const cc2Xform &x,
const cc2Rigid &r);
Returns the cc2Xform resulting from the composition of the cc2Xform x and the rigid
transformation r. Mapping a point with the resulting cc2Xform transformation object is
equivalent to first mapping the point by r and then by x.
Parameters
x
r
The cc2Xform transformation object to be composed with the
rigid transformation r.
The rigid transformation to be composed with the cc2Xform
transformation object x.
Public Member Functions
angle
const ccDegree& angle()const;
void angle(const ccDegree& a);
•
const ccDegree& angle() const;
Returns the rotation angle of this rigid transformation in degrees.
•
void angle(const ccDegree& a);
Sets the rotation angle of this rigid transformation to a.
Parameters
a
cosAngle
The rotation angle assigned to this rigid transformation.
double cosAngle()const;
Returns the cosine of the rotation angle of this rigid transformation.
sinAngle
double sinAngle()const;
Returns the sine of the rotation angle of this rigid transformation.
70
CVL Class Reference
cc2Rigid
trans
const cc2Vect& trans()const;
void trans(const cc2Vect& t);
•
const cc2Vect& trans()const;
Returns the translation vector of this rigid transformation.
•
void trans(const cc2Vect& t);
Sets the translation vector of this rigid transformation to t.
Parameters
t
linear
The translation vector assigned to this rigid transformation.
cc2Xform linear() const;
Returns the equivalent cc2Xform form of this rigid transformation.
compose
cc2Rigid compose(const cc2Rigid& xform) const;
cc2Xform compose(const cc2Xform& xform) const;
•
cc2Rigid compose(const cc2Rigid& xform)const;
Returns the composition of this rigid transformation with xform. This function implements
the same operation as operator *(const cc2Rigid& xform).
Parameters
xform
•
The rigid transformation composed with this transformation.
cc2Xform compose(const cc2Xform& xform)const;
Returns the composition of this rigid transformation with the cc2Xform transformation
xform. This function implements the same operation as operator *(const cc2Xform&
xform).
Parameters
xform
CVL Class Reference
The cc2Xform transformation composed with this transformation.
71
cc2Rigid
inverse
cc2Rigid inverse() const;
Returns the inverse of this rigid transformation. The inverse of this rigid transformation is
defined as the rigid transformation that, when composed with this rigid transformation,
returns the identity transformation. If this rigid transformation maps points from Frame A
to Frame B, the inverse of this rigid transformation maps points from Frame B back to
Frame A.
mapVector
cc2Vect mapVector (const cc2Vect &vect) const;
Maps the components of vect by this rigid transformation. If (a’, b’) are the components
of vect in Frame A and (a, b) are the components of vect in Frame B, mapVector maps
(a’, b’) to (a, b).
Frame B
X
a
a’
θ’
θ
Frame
A
X
b’
b
vect
Y
Y
Parameters
vect
The vector whose components are mapped by mapVector.
Notes.
Although a vector and a point are represented by the same data type (cc2Vect) it
is important to keep in mind that they represent two distinct notions. A point
represents a specific position in the coordinate space. A vector represents a length
and direction in the same space but has no fixed location. A vector is depicted in
drawings as an arrow. Points and vectors can be represented by the same class
because a vector whose tail is placed at the origin specifies a unique point (at the
end of the arrow).
72
CVL Class Reference
cc2Rigid
invMapVector
cc2Vect invMapVector (const cc2Vect &vect) const;
Implements the inverse of the mapping operated by MapVector. If we refer to the
preceding figure, invMapVector maps (a, b) (in Frame B), to (a’, b’) in Frame A.
Parameters
vect
mapAngle
The vector mapped by invMapVector.
ccRadian mapAngle (const ccRadian& ang) const;
Maps the polar angle of some feature in coordinate Frame A (see preceding figure) to
the polar angle in coordinate Frame B. If θ’ is the polar angle of vect in Frame A,
mapAngle maps θ’ to (θ + θ’).
Parameters
ang
invMapAngle
The polar angle of a feature in coordinate Frame A.
ccRadian invMapAngle (const ccRadian& ang) const;
Implements the inverse of the mapping operated by mapAngle. If we refer to the
preceding figure, invMapAngle maps (θ + θ’) (the polar angle of vect in Frame B) to θ’
(the polar angle of vect in Frame A).
Parameters
ang
CVL Class Reference
The polar angle of a feature in coordinate Frame B
((θ + θ’) in the preceding figure).
73
cc2Rigid
mapPoint
cc2Vect mapPoint (const cc2Vect &pt) const;
Maps the point pt from its coordinates in Frame A (see following figure) to its coordinates
in Frame B. This function implements the same operation as operator *(const cc2Vect
&pt). If (xA, yA) are the coordinates of pt in Frame A and (xB, yB) are the coordinates of
pt in Frame B, mapPoint performs the following mapping: (xA, yA) -> (xB, yB).
Frame B
XB
XA
X
Frame
A
X
YA
YB
P
Y
Y
Parameters
pt
invMapPoint
The point mapped by this transformation.
cc2Vect invMapPoint (const cc2Vect &pt) const;
Implements the inverse of the mapping operated by mapPoint. In the previous figure,
invMapPoint maps (xB, yB) (the coordinates of pt in Frame B) to (xA, yA) (the
coordinates of pt in Frame A).
Parameters
pt
isIdentity
The point mapped by the inverse of this transformation.
bool isIdentity() const;
Returns true if this rigid transformation is the identity transformation.
74
CVL Class Reference
cc2Rigid
Data Members
I
static const cc2Rigid I;
The identity transformation for cc2Rigid.
CVL Class Reference
75
cc2Rigid
76
CVL Class Reference
cc2Vect
#include <ch_cvl/vector.h>
class cc2Vect;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Yes
This class describes a two-dimensional vector, a quantity that is determined by its
length (magnitude) and direction. Throughout CVL, cc2Vector is used to describe
points, so you can also think of a vector as an (x,y) coordinate pair.
Notes
cc2Vect is the name of the class as it is used throughout the Cognex Vision Library.
This name is actually a typedef for ccVector<2>. Both forms are valid and entirely
equivalent.
Do not confuse the CVL vector classes cc2Vect and cc3Vect with the C++
Standard Template Library’s vector template class. Though both have the same
mathematical underpinnings, CVL vector classes are generally used to describe
the location of points while the STL vector class is used to implement flexible
arrays.
Constructors/Destructors
cc2Vect
cc2Vect();
cc2Vect(double x, double y);
cc2Vect(double r, ccRadian t);
cc2Vect(const ccFPair& p);
cc2Vect(const ccDPair& p);
cc2Vect(const ccIPair& p);
•
cc2Vect();
The default constructor creates a vector in which both x and y components are set to
zero.
CVL Class Reference
77
cc2Vect
•
cc2Vect(double x, double y);
Creates a vector with the specified x and y components.
Parameters
x
y
•
The x-component of the vector.
The y-component of the vector.
cc2Vect(double r, ccRadian t);
Creates a vector from the specified radius and angle.
Parameters
r
t
The radius of the circle.
The angle in radians. Angles are measured from the x-axis.
Notes
If the radius is zero, the angle information is not stored. The vector is a null vector.
•
cc2Vect(const ccFPair& p);
Creates a vector from the specified pair of floats.
Parameters
p
•
The pair of floats.
cc2Vect(const ccDPair& p);
Creates a vector from the specified pair of doubles.
Parameters
p
•
The pair of doubles.
cc2Vect(const ccIPair& p);
Creates a vector from the specified pair of integers (c_Int32).
Parameters
p
78
The pair of integers.
CVL Class Reference
cc2Vect
Operators
operator[]
double& operator[](int d);
double operator[](int d) const;
•
double& operator[](int d);
Provides array-like access to the vector. Typically you use this form when your
application works with both two- and three-dimensional vectors. This form allows you to
set the value of a component.
Parameters
d
The index of the element to return.
0: The x-component.
1: The y-component.
•
double operator[](int d) const;
Provides array-like access to the vector. Typically you use this form when your
application works with both two- and three-dimensional vectors.
Parameters
d
The index of the element to return.
0: The x-component.
1: The y-component.
operator+
cc2Vect operator+(const cc2Vect& v) const;
Returns a vector that is the result of adding this vector and another vector.
Parameters
v
operator+=
The vector to add to this vector.
cc2Vect& operator+=(const cc2Vect& v);
Adds this vector to another vector and returns the result.
Parameters
v
CVL Class Reference
The vector to add to this vector.
79
cc2Vect
operator-
cc2Vect operator-() const;
cc2Vect operator-(const cc2Vect&) const;
•
cc2Vect operator-() const;
The unary minus operator.
•
cc2Vect operator-(const cc2Vect& v) const;
Returns a vector that is the result of subtracting the vector v from this vector.
Parameters
v
operator-=
The vector to subtract from this vector.
cc2Vect& operator-=(const cc2Vect& v);
Subtracts the vector v from this vector and returns the result.
Parameters
v
operator*
The vector to subtract from this vector.
cc2Vect operator*(double d) const;
friend cc2Vect operator*(double, const cc2Vect&);
double operator*(const cc2Vect& v) const;
•
cc2Vect operator*(double d) const;
Returns a vector that is the result of multiplying each element in the vector by d.
Parameters
d
•
The value by which to multiply each element of the vector.
friend cc2Vect operator*(double d, const cc2Vect& v);
Returns a vector that is the result of multiplying each element in the vector by d.
Parameters
d
v
80
The value by which to multiply each element of the vector.
The vector.
CVL Class Reference
cc2Vect
•
double operator*(const cc2Vect& v) const;
Returns the dot product of this vector and the vector v.
Parameters
v
operator*=
The other vector.
cc2Vect& operator*=(double d);
Multiplies each element in this vector by d and returns the result.
Parameters
d
operator/
The value by which to multiply each element of the vector.
cc2Vect operator/(double d) const;
Returns a vector that is the result of dividing each element in this vector by d.
Parameters
d
operator/=
The value by which to divide each element of the vector.
cc2Vect& operator/=(double d) const;
Divides each element in this vector by d and returns the result.
Parameters
d
operator==
The value by which to divide each element of the vector.
bool operator==(const cc2Vect& v) const;
Returns true if this vector is equal to another vector.
Parameters
v
operator!=
The other vector.
bool operator!=(const cc2Vect&) const;
Returns true if this vector is not equal to another vector.
Parameters
v
CVL Class Reference
The other vector.
81
cc2Vect
Public Member Functions
x
double x() const;
void x(double newX);
•
double x() const;
Returns the vector’s x-component.
•
void x(double newX);
Sets the vector’s x-component.
Parameters
newX
y
The new x-component.
double y() const;
void y(double newY);
•
double y() const;
Returns the vector’s y-component.
•
void y(double newY);
Sets the vector’s y-component.
Parameters
newY
len
The new y-component.
double len() const;
Returns the length (or magnitude) of the vector.
isNull
bool isNull() const;
Returns true if this is a null vector (both components are zero).
82
CVL Class Reference
cc2Vect
angle
ccRadian angle() const;
Returns the vector angle in the range –π < angle <= π. Angles are measured from the
x-axis.
Throws
ccMathError::NullVector
Both the x-component and the y-component are zero.
unit
cc2Vect unit() const;
Returns a unit vector parallel to this vector. A unit vector is a vector whose length is 1.
Throws
ccMathError::NullVector
Both the x-component and the y-component are zero.
project
cc2Vect project(const cc2Vect& v) const;
Returns a vector that is the result of projecting the vector v onto this vector.
Parameters
v
The vector to project onto this vector.
Throws
ccMathError::NullVector
Both the x-component and the y-component are zero.
An error is not thrown if v is null or the two vectors are
perpendicular to each other.
perpendicular
cc2Vect perpendicular() const;
Returns a vector perpendicular (rotated +90 degrees) to this vector. The new vector is
the same length as this vector.
Notes
The null vector is considered perpendicular to itself
distance
double distance(const cc2Vect& v) const;
Returns the distance to the other vector. This is the length of difference between this
vector and vector v.
Parameters
v
CVL Class Reference
The other vector.
83
cc2Vect
dot
double dot(const cc2Vect& v) const;
Returns the dot product of this vector and the vector v.
Parameters
v
cross
The other vector.
double cross(const cc2Vect& v) const;
Returns the cross product of this vector and v.
Parameters
v
floor
The other vector.
ccIPair floor() const ;
Returns a ccIPair corresponding to floor(cc2Vect::x()), floor(cc2Vect::y()).
ceil
ccIPair ceil() const ;
Returns a ccIPair corresponding to ceil(cc2Vect::x()), ceil(cc2Vect::y()).
84
CVL Class Reference
cc2Wireframe
#include <ch_cvl/wirefrm.h>
class cc2Wireframe : public ccGenPoly;
Class Properties
Copyable
Yes
Derivable
Not intended
Archiveable
Complex
The cc2Wireframe class is a general polygon (ccGenPoly) shape with an explicitly
defined polarity value plus segment length tolerance information. The weight is implicitly
defaulted to 1.0. However, the (deprecated) interface to PatMax allows you to specify
weights that are applied to a vector of cc2Wireframe objects to be trained.
PatMax does not use the tolerance information in a cc2Wireframe.
Note
cc2Wireframe
ccGenPoly
ccShape
The above figure shows the cc2Wireframe class inheritance hierarchy.
Polarity
Each wireframe has unique polarity. As you traverse the wireframe from one vertex to
another, each segment has a positive side and a negative side. By default, the positive
side of a segment with index N is that side to which the segment would move if it were
to rotate in the direction of positive angle when the center of rotation is vertex N. The
polarity is dependent on the direction of increasing indices, and the handedness of the
coordinate system. Note that when the wireframe is closed, the inside of the wireframe
will be of one polarity, and the outside will be of the opposite polarity.
CVL Class Reference
85
cc2Wireframe
The following closed wireframe diagrams show the wireframe polarity for right-handed
and left-handed coordinate systems.
1
+
-+
+ -
x
+
2
+
-
1
+ -
- +
0
y
2
+
x
+
+
+
-
+
0
3
3
y
Left-handed coordinate system.
Positive rotation is clockwise.
Positive side of each segment on the right.
Right-handed coordinate system.
Positive rotation is counterclockwise.
Positive side of each segment on the left.
2
2
-
+
+
- +
x
+ 3
1
y
1
+
- +
x
+ -
+
+
+
+
3
0
+
0
y
Left-handed coordinate system.
Positive rotation is clockwise.
Positive side of each segment on the right.
86
Right-handed coordinate system.
Positive rotation is counterclockwise.
Positive side of each segment on the left.
CVL Class Reference
cc2Wireframe
The diagrams above show the wireframe polarities for the given conditions. These
polarities are the default state. Note that you can reverse the wireframe polarity to the
reversed state by calling cc2Wireframe::polarity(). The two examples above are show
below with reversed polarity.
-
2
2
+
+
+
-
x
- +
1
y
1
x
+ -
- +
+
-
3
-
-
0
Reversed
polarity
3
+
-
0
y
Left-handed coordinate system.
Positive rotation is counter-clockwise.
Positive side of each segment on the left.
Right-handed coordinate system.
Positive rotation is clockwise.
Positive side of each segment on the right.
Each segment in the wireframe has associated tolerance information contained in a
ccDimTol object that specifies nominal, maximum, and minimum segment lengths. A
description of tolerances is presented in the ccDimTol reference page.
When tolerances are defined, the scale type associated with each segment indicates
how tolerances change when the wireframe is scaled. The effect of scaling on
tolerances is also discussed in the ccDimTol reference page.
Using PatMax with Wireframes
For new development, you should use ccGenPoly or ccGenPolyModel shapes rather
than cc2Wireframe shapes when training PatMax on synthetic shapes. If you want to
move to the new train() interface of PatMax but continue to use legacy cc2Wireframe
shapes that may already exist in your code, you will need to put the wireframes into a
shape tree prior to training. See the Training with Wireframes section of the PatMax
chapter of the CVL Vision Tools Guide for sample code that demonstrates how to do this.
CVL Class Reference
87
cc2Wireframe
Constructors/Destructors
cc2Wireframe
cc2Wireframe() {};
cc2Wireframe(const ccGenPoly& gp);
cc2Wireframe(const ccGenPoly& gp, const ccDimTol & tol);
virtual ~cc2Wireframe();
•
cc2Wireframe() {};
Default constructor. Constructs a wireframe object with no vertices or segments.
•
cc2Wireframe(const ccGenPoly& gp);
Conversion constructor. Constructs a wireframe object that is equivalent to the supplied
generalized polygon.
Parameters
gp
•
The generalized polygon used as a basis for the constructed
wireframe object.
cc2Wireframe(const ccGenPoly& gp, const ccDimTol & tol);
Constructs a wireframe object that is equivalent to the supplied generalized polygon. All
segments are set to use the specified segment length tolerance.
Parameters
gp
tol
•
The generalized polygon used as a basis for the constructed
wireframe object.
The segment length tolerance. The nominal tolerance dimension
is ignored.
virtual ~cc2Wireframe();
Destructor. Destroys this wireframe shape.
Operators
operator==
bool operator==(const cc2Wireframe&) const;
This operator allows you to compare two cc2Wireframe objects. For example,
88
CVL Class Reference
cc2Wireframe
if(frame1 == frame2) {.....}
The equality expression evaluates to true if the objects are equal. It is false if they are
not equal.
Parameters
cc2Wireframe
operator!=
The right-hand cc2Wireframe object. For example, frame2.
bool operator!=(const cc2Wireframe&) const;
This operator allows you to compare two cc2Wireframe objects. For example,
if(frame1 != frame2) {.....}
The inequality expression evaluates to true if the objects are not equal. It is false if they
are equal.
Parameters
cc2Wireframe
The right-hand cc2Wireframe object. For example, frame2.
Public Member Functions
isPolarityReversed
bool isPolarityReversed() const;
Returns true if the polarity of the wireframe is reversed from its default state (see general
polarity comments above), and false otherwise.
polarity
void polarity(bool isReversed);
If isReversed is true, the polarity of all segments in the wireframe is set to the reversed
state. (See the wireframe polarity discussion starting on page 85). If isReversed is false,
the polarity of all segments is set to the default state.
Parameters
isReversed
The reverse polarity specifier, true or false.
Throws
ccShapesError::BadGeom
isMutable() is false.
isInsidePositive
bool isInsidePositive() const;
Returns true if the polarity of the wireframe is such that the inside of the wireframe is
positive. Returns false otherwise.
CVL Class Reference
89
cc2Wireframe
Throws
ccShapesError::BadGeom
This wireframe is not closed.
insidePolarity
void insidePolarity(bool isPositive);
If isPositive is true, changes the polarity of all segments in this closed wireframe so that
the inside of the wireframe is positive. If isPositive is false, sets the polarity of all
segments so that the inside of the wireframe is negative.
Parameters
isPositive
The wireframe polarity specifier; true or false.
Throws
ccShapesError::BadGeom
isMutable() is false.
segmentLengthTol
void segmentLengthTol(c_Int32 segmentIndex,
const ccDimTol & tol);
ccDimTol segmentLengthTol(c_Int32 segmentIndex) const;
•
void segmentLengthTol(c_Int32 segmentIndex,
const ccDimTol & tol);
Sets the segment length tolerance for the segment with the specified index.
Parameters
segmentIndex
tol
The index for the target segment.
The new segment length tolerance. The nominal dimension is
ignored.
Throws
ccShapesError::BadCoeff
segmentIndex is not a valid segment index.
ccShapesError::BadGeom
isMutable() is false, or the absolute tolerances specified are not
possible.
The generalized polygon is unaffected in case of any throw.
90
CVL Class Reference
cc2Wireframe
•
ccDimTol segmentLengthTol(c_Int32 segmentIndex) const;
Returns the segment length tolerance for the segment with the specified index. The
nominal segment length will reflect the actual length of the specified segment.
Parameters
segmentIndex
The index for the target segment.
Throws
ccShapesError::BadCoeff
If segmentIndex is not a valid segment index.
The generalized polygon is unaffected in case of any throw.
clone
virtual ccShapePtrh clone() const;
Returns a pointer to a copy of this wireframe.
map
cc2Wireframe map(const cc2Rigid& c,
double scale = 1.0) const;
cc2Wireframe map(const cc2Xform& c) const;
•
cc2Wireframe map(const cc2Rigid& c,
double scale = 1.0) const;
Returns this wireframe scaled by scale, and mapped by c. The returned wireframe is
mutable. For information on scaling of wireframe segment length tolerances see the
ccDimTol class reference page.
Parameters
c
scale
The mapping transform used.
The scale factor used.
Throws
ccShapesError::BadGeom
If the scaled nominal segment length for any segment is not
within the defined fixed tolerance ranges.
CVL Class Reference
91
cc2Wireframe
•
cc2Wireframe map(const cc2Xform& c) const;
Returns this wireframe mapped by c. Wireframe tolerances are scaled according to the
scale type of each wireframe segment. Scaling is described in the ccDimTol class
reference page. The scale factor for a given segment is defined as the ratio of the old
segment length to the new segment length along a possibly elliptical arc.
The returned generalized polygon is immutable unless c.isIdentity() is true.
Parameters
c
The mapping transform used.
Throws
ccShapesError::BadGeom
If the scaled nominal segment length for any segment is not
within the defined fixed tolerance ranges.
insertVertex
void insertVertex(const cc2Vect & vertexPoint,
double roundingSize = 0.0,
const ccRadian& previousSegmentAngleSpan
= ccRadian(0.0),
const ccDimTol& previousSegmentLengthTol
= ccDimTol (-1, -1, -1));
void insertVertex(c_Int32 previousVertexIndex,
const cc2Vect& vertexPoint,
double roundingSize = 0.0,
const ccRadian& previousSegmentAngleSpan
= ccRadian(0.0),
const ccDimTol & previousSegmentLengthTol
= ccDimTol (-1, -1, -1));
•
void insertVertex(const cc2Vect & vertexPoint,
double roundingSize = 0.0,
const ccRadian & previousSegmentAngleSpan
= ccRadian(0.0),
const ccDimTol & previousSegmentLengthTol
= ccDimTol (-1, -1, -1));
Inserts the specified vertex after the last vertex in the generalized polygon. The vertex
rounding, previous segment angle span, and previous segment length tolerance are
also specified.
Parameters
vertexPoint
roundingSize
92
The x,y location of the inserted vertex.
The vertex rounding size.
CVL Class Reference
cc2Wireframe
previousSegmentAngleSpan
The previous segment angle span.
previousSegmentLengthTol
The previous segment length tolerance.
An override, see the ccGenPoly base class.
•
void insertVertex(c_Int32 previousVertexIndex,
const cc2Vect& vertexPoint,
double roundingSize = 0.0,
const ccRadian & previousSegmentAngleSpan
= ccRadian(0.0),
const ccDimTol & previousSegmentLengthTol
= ccDimTol (-1, -1, -1));
Inserts the specified vertex after the vertex with index previousVertexIndex. The vertex
rounding, previous segment angle span, and previous segment length tolerance are
also specified.
If previousVertexIndex = -1, the new vertex will become the first vertex.
In all cases, vertex indices beyond the new vertex increase by 1 as a result of adding a
new vertex.
Parameters
previousVertexIndex
The index of the vertex prior to where the new vertex is inserted.
A -1 indicates the new vertex should be the first vertex (index 0).
vertexPoint
The x,y location of the inserted vertex.
roundingSize
The vertex rounding size.
previousSegmentAngleSpan
The previous segment angle span.
previousSegmentLengthTol
The previous segment length tolerance.
An override, see the ccGenPoly base class.
CVL Class Reference
93
cc2Wireframe
close
void close(
const ccRadian & segmentAngleSpan = ccDegree(0),
const ccDimTol& segmentLengthTol = ccDimTol(-1, -1, -1));
Closes the generalized polygon. It connects the vertex with the largest index to the
vertex with the smallest index using a segment with the specified segmentAngleSpan.
segmentLengthTol sets the new segment length tolerance.
There is no effect if the generalized polygon is already closed.
An override, see the ccGenPoly base class.
Parameters
segmentAngleSpan
The segment angle span for the segment added when the
polygon is closed.
segmentLengthTol
The segment length tolerance.
Throws
ccShapesError::BadGeom
If segmentLengthTol is not valid.
See ccGenPoly base class for more throw conditions.
94
CVL Class Reference
cc2Xform
#include <ch_cvl/xform.h>
class cc2Xform;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class describes a two-dimensional transformation object. The transformation object
is made up of a four-element matrix and a two-element vector. Together, these two
components allow for transformations along six degrees of freedom.
The cc2Xform member functions let you specify coordinate transformations two
different ways. The difference between the two methods is the way you specify the
elements of the four-element matrix. Both methods use the two-element vector for
xy-translation.
The scale-rotation method for specifying transformation objects lets you set rotation of
the x-axis, rotation of the y-axis, x-scale, and y-scale. The shear-aspect method lets you
specify the scale of the coordinate system, the aspect ratio of the x to the y axis, the
shear angle, and the rotation of the coordinate system. Both methods are equivalent, so
you can use the one that suits your application or your existing algorithms. In general,
the scale-rotation method is easier to use.
Note
CVL Class Reference
cc2Xform is the name of the class as it is used throughout the
Cognex Vision Library. This name is actually a typedef for
ccXform<2>. Both forms are valid and entirely equivalent.
95
cc2Xform
Constructors/Destructors
cc2Xform
cc2Xform();
cc2Xform(const ccMatrix<2>& c, const cc2Vect& t);
cc2Xform(const cc2Vect& t, const ccRadian& xRot,
const ccRadian& yRot, double xScale, double yScale);
cc2Xform(const cc2Vect& t, double scale, double aspect,
const ccRadian& shear, const ccRadian& rotation);
•
cc2Xform();
The default constructor creates an identity transformation object.
•
cc2Xform(const ccMatrix<2>& c, const cc2Vect& t);
Creates a transformation object with a matrix component c and a translation component
t.
Parameters
c
t
•
The matrix component of the transformation object.
The translation component of the transformation object.
cc2Xform(const cc2Vect& t, const ccRadian& xRot,
const ccRadian& yRot, double xScale, double yScale);
Creates a transformation object using the scale-rotation method.
Parameters
t
•
The translation component; the amount by which to move the
origin of the mapped coordinate system.
xRot
The x-rotation; the amount by which to rotate the x-axis in radians.
yRot
The y-rotation; the amount by which to rotate the y-axis in radians.
xScale
The x-scale; the amount by which to scale the x-axis units.
yScale
The y-scale; the amount by which to scale the y-axis unit.
cc2Xform(const cc2Vect& t, double scale, double aspect,
const ccRadian& shear, const ccRadian& rotation);
Creates a transformation object using the shear-aspect method.
96
CVL Class Reference
cc2Xform
Parameters
t
The translation component; the amount by which to move the
origin of the mapped coordinate system.
scale
The scale element; the amount by which to scale all units.
aspect
The aspect ratio; the ratio of the x-axis units to the y-axis units.
shear
The shear element; the amount by which to rotate the y-axis in
radians.
rotation
The rotation element; the amount by which to rotate the entire
coordinate system in radians.
Operators
operator*
cc2Xform operator* (const cc2Xform& xform) const;
cc2Vect operator* (const cc2Vect &pt) const;
•
cc2Xform operator* (const cc2Xform& xform) const;
Returns the transformation object that is the composition of this transformation object
and the transformation object xform. Mapping a point with the resulting transformation
object has the same effect as mapping the point by the xform transformation object and
then by this transformation object.
Parameters
xform
The transformation object to compose with this one.
Notes
Using this operator is the same as using the compose() function:
xform.compose(xform2) == xform * xform2
•
cc2Vect operator* (const cc2Vect &pt) const;
Return the result of mapping the point pt with this transformation object. This is has the
same effect as:
resultPt = matrix() * pt + trans();
Parameters
pt
CVL Class Reference
The point to map.
97
cc2Xform
Notes
This operator is the same as using the mapPoint() function:
xform.mapPoint(pt) == xform * pt
operator==
bool operator== (const cc2Xform& that) const;
Return true if this transformation object is the same as that transformation object.
Parameters
that
operator!=
The other transformation object to compare.
bool operator!= (const cc2Xform&) const;
Parameters
that
The other transformation object to compare.
Public Member Functions
matrix
const ccMatrix<2>& matrix();
void matrix(const ccMatrix<2>& c);
•
const ccMatrix<2>& matrix();
Returns the 2x2 matrix component of the transformation object.
•
void matrix(const ccMatrix<2>& c);
Sets the matrix component of the transformation object to c.
Parameters
c
trans
The matrix component of the transformation object.
const cc2Vect& trans();
void trans(const cc2Vect& t);
•
const cc2Vect& trans();
Returns the 2-element translation vector of the transformation object.
•
void trans(const cc2Vect& t);
Sets the translation vector component of the transformation object to t.
98
CVL Class Reference
cc2Xform
Parameters
t
inverse
The translation component of the transformation object.
cc2Xform inverse() const;
Returns the inverse of this transformation object.
Throws
ccMathError::Singular
The transformation is singular.
compose
cc2Xform compose (const cc2Xform& xform) const;
Returns the transformation object that is the composition of this transformation object
and the transformation object xform. Mapping a point with the resulting transformation
object has the same effect as mapping the point by xform, then by this transformation
object.
Parameters
xform
The transformation object to compose with this one.
Notes
Using this function is the same as using the multiplication operator:
xform.compose(xform2) == xform * xform2
xRot
ccRadian xRot() const;
Returns the x-rotation element of the transformation object using the scale-rotation
specification.
Notes
Be careful when you mix elements from the scale-rotation specification with
elements of the shear-aspect specification. For example, if you specify a value for
shear() in the shear-aspect specification, aspect() != yScale() / xScale().
Throws
ccMathError::Singular
The transformation is singular.
yRot
ccRadian yRot() const;
Returns the y-rotation element of the transformation object using the scale-rotation
specification.
CVL Class Reference
99
cc2Xform
Notes
See note to xRot() on page 99.
Throws
ccMathError::Singular
The transformation is singular.
xScale
double xScale() const;
Returns the x-scale element of the transformation object using the scale-rotation
specification.
Notes
See note to xRot() on page 99.
Throws
ccMathError::Singular
The transformation is singular.
yScale
double yScale() const;
Returns the y-scale element of the transformation object using the scale-rotation
specification.
Notes
See note to xRot() on page 99.
Throws
ccMathError::Singular
The transformation is singular.
scale
double scale() const;
Returns the scale element of the transformation object using the shear-aspect
specification.
Notes
See note to xRot() on page 99.
Throws
ccMathError::Singular
The transformation is singular.
100
CVL Class Reference
cc2Xform
aspect
double aspect() const;
Returns the aspect element of the transformation object using the shear-aspect
specification.
Notes
See note to xRot() on page 99.
Throws
ccMathError::Singular
The transformation is singular.
shear
ccRadian shear();
Returns the shear element of the transformation object using the shear-aspect
specification.
Notes
See note to xRot() on page 99.
Throws
ccMathError::Singular
The transformation is singular.
rotation
ccRadian rotation() const;
Returns the rotation element of the transformation object using the shear-aspect
specification.
Notes
See note to xRot() on page 99.
Throws
ccMathError::Singular
The transformation is singular.
mapAngle
ccRadian mapAngle (const ccRadian& ang) const;
Return the results of mapping the angle ang with this transformation object.
Parameters
ang
invMapAngle
The angle to map in radians.
ccRadian invMapAngle (const ccRadian& ang) const;
Return the results of mapping the angle ang with the inverse of this transformation
object.
CVL Class Reference
101
cc2Xform
Parameters
ang
The angle to map in radians.
Throws
ccMathError::Singular
The transformation is singular.
mapPoint
cc2Vect mapPoint (const cc2Vect &pt) const;
Return the result of mapping the point pt with this transformation object. This is has the
same effect as:
resultPt = matrix() * pt + trans();
Parameters
pt
The point to map.
Notes
Using this function is the same as using the multiplication operator:
xform.mapPoint(pt) == xform * pt
invMapPoint
cc2Vect invMapPoint (const cc2Vect &pt) const;
Return the result of mapping the point pt with the inverse of this transformation object.
This is has the same effect as:
resultPt = matrix().inverse() * (pt - trans());
Parameters
pt
The point to map.
Throws
ccMathError::Singular
The transformation is singular.
mapVector
cc2Vect mapVector (const cc2Vect &vect) const;
Rotates and scales the vector vect by the transformation object, ignoring translation:
result = matrix() * vect;
Parameters
vect
102
The vector to be mapped.
CVL Class Reference
cc2Xform
invMapVector
cc2Vect invMapVector (const cc2Vect &vect) const;
Rotates and scales the vector vect by the inverse of the transformation object, ignoring
translation:
result = matrix().inverse() * vect;
Parameters
vect
The vector to be mapped.
Throws
ccMathError::Singular
The transformation is singular.
mapArea
double mapArea (double area) const;
Returns the area after mapping by the xform.
Parameters
area
The area to be mapped.
Notes
This function computes the mapped area by first calculating the area of a unit
square and then multiplying area by that value. You may wish to call this function
with the area 1.0 to get a conversion constant you can use without the overhead of
calling this function multiple times.
invMapArea
double invMapArea (double area) const;
Returns the area after mapping by the inverse of the xform.
Parameters
area
The area to be mapped.
Throws
ccMathError::Singular
The transformation is singular.
isIdentity
bool isIdentity() const;
Returns true if this transformation object is the identity object: all points map to
themselves.
isSingular
bool isSingular() const;
Returns true if the transformation is singular: all points map to the same line.
CVL Class Reference
103
cc2Xform
Data Members
I
static const cc2Xform I;
The identity transformation matrix for cc2Xform.
104
CVL Class Reference
cc2XformBase
#include <ch_cvl/xfbase.h>
class cc2XformBase : public ccRepBase, public ccPersistent;
Class Properties
Copyable
Yes
Derivable
Cognex-supplied classes
only
Archiveable
Complex
This is the abstract base class for 2D coordinate transforms. From this base class the
specialized classes such as cc2XformPoly and cc2XformLinear are derived.
cc2XformBase
cc2XformLinear
cc2XformPerspective
cc2XformPoly
cc2XformCalib2
cc2XformDeform
Constructors/Destructors
Use the constructors of the derived classes.
Operators
operator*
cc2Vect operator*(const cc2Vect& pt) const;
cc2XformBasePtrh operator*(const cc2XformBase& rhs) const;
•
cc2Vect operator*(const cc2Vect& pt) const;
Returns the point pt mapped by this transformation. Using this operator is equivalent to
using the mapPoint function.
Parameters
pt
CVL Class Reference
The point mapped by the operator.
105
cc2XformBase
Notes
Each derived class should make a using declaration of this operator. This assures
that additional * operator functions overload, rather than hide, the base class
operator.
•
cc2XformBasePtrh operator*(const cc2XformBase& rhs) const;
Returns the composition of this transformation with the transformation rhs. Mapping a
point with the resulting transformation is equivalent to first mapping the point by the
transformation rhs and then by this transformation. The use of this operator is equivalent
to the use of the composeBase function.
Parameters
rhs
The transformation to be composed with this transformation.
Notes
The only allowed compositions are: cc2XformLinear * cc2XformLinear,
cc2XformLinear * cc2XformPoly, cc2XformPoly * cc2XformLinear
Public Member Functions
mapPoint
virtual cc2Vect mapPoint(const cc2Vect& pt) const = 0;
Maps the point pt by using this transformation.
Parameters
pt
isLinear
The point mapped by this transformation.
virtual bool isLinear() const = 0;
Returns true if this transformation is linear.
Notes
This function is designed to efficiently identify cases where transformations are
guaranteed to be linear. The function may return false if it would take too much time
to determine otherwise.
linearXform
virtual cc2XformLinear linearXform(const cc2Vect& atThisPt)
const = 0;
Returns the linear transformation defined by the linear terms of the Taylor series
expansion about the point atThisPt.
Parameters
atThisPt
106
The point around which this transformation is linearized.
CVL Class Reference
cc2XformBase
composeBase
virtual cc2XformBasePtrh composeBase(
const cc2XformBase& rhs) const = 0;
Returns the composition of this transformation with the transformation rhs. Mapping a
point with the resulting transformation is equivalent to first mapping the point by the
transformation rhs and then by this transformation.
Parameters
rhs
The transformation to be composed with this transformation.
Notes
The run-time type of the returned result is not guaranteed to be the same across
different CVL releases, so do not write code that depends on the exact run-time
type. For example, avoid using a dynamic cast.
It is expected that, for convenience, derived classes may declare functions such as
compose() that take a particular transform type and return a particular transform
type. The return value will not be heap allocated. For example;
cc2XformLinear: cc2XformLinear compose(
const cc2XformLinear& rhs) const;
inverseBase
virtual cc2XformBasePtrh inverseBase() const = 0;
Returns a transformation that is the inverse of this transformation.
Throws
ccMathError::Singular
The transformation is singular and cannot be inverted.
Notes
In the case of nonlinear transformations, the inverse transformation may not be
exact.
clone
virtual cc2XformBasePtrh clone() const = 0;
Returns a newly allocated copy of this transformation.
Notes
This function is required for polymorphic copying.
CVL Class Reference
107
cc2XformBase
108
CVL Class Reference
cc2XformCalib2
#include <ch_cvl/ccalib.h>
class cc2XformCalib2 : public cc2XformBase;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class contains a nonlinear calibration transform. It models the effects of perspective
distortion and lens distortion. A general reference for terminology used in this
description is Multiple View Geometry in Computer Vision by Richard Hartley and
Andrew Zisserman.
A calibration transform C has the following form when mapping points from physical
space to image space:
C = L composed with Rrad composed with P
where:
P is a perspective transform and depends on the position and orientation of the object
plane with respect to the camera.
Rrad is a radial transform and depends on the camera lens used. This transform is
modeled as a cubic polynomial transform using one distortion coefficient,
L is a linear transform and depends on camera properties such as focal length (scale),
aspect, skew, and position of the optical axis relative to the image center. L does
not contain any rotation.
Thus, P depends on the properties of the image acquisition system which are external
to the camera. These are known as the extrinsic calibration parameters. Rrad and L
depend on camera properties which are internal to the camera. These are known as
intrinsic calibration parameters.
The calibration transform mapping image points to physical points is obtained by
composition of inverses of L, Rrad, and P composed in reverse order.
CVL Class Reference
109
cc2XformCalib2
There are two ways to compute this transform:
1.
Using known intrinsic and extrinsic calibration parameters.
2.
Using correspondences between physical points and client points generated from
one or more views. (Client space is usually the same as image space in the
calibration image.)
Use init() to create the transform in one of these two ways.
Correspondences
The following figure describes how we manage corresponding image points and
physical points. Each member of the ccCalib2CrspVector vector is a vector of
corresponding image point - physical point pairs. The points in each ccCrspPairVector
vector all come from one image (a view) and must contain at least 9 corresponding point
pairs.
ccCalib2CrspVector
ccCrspPairVector
ccCrspPair
ccCrspPairVector
ccCrspPair
Image point
ccCrspPair
Physical point
ccCrspPairVector
ccCrspPairVector
ccCrspPairVector
ccCrspPairVector
ccCrspPairVector
ccCrspPairVector
One per view
ccCrspPair
ccCrspPair
ccCrspPair
ccCrspPair
Must contain at least 9
corresponding pairs
Note that the cc2XformCalib2 is asymmetric between image coordinates and physical
coordinates. cc2XformCalib2 is designed to map from physical coordinates to image
coordinates. You should always initialize a cc2XformCalib2 object so that it maps from
physical coordinates to image coordinates and use either invMapPoint() or inverse()
to map from image coordinates to physical coordinates.
Since the cc2XformCalib2 is asymmetric, it is important to specify the positions in the
ccCrspPairVector in the proper order. Furthermore, the ccCrspPairVector used to
initialize a cc2XformCalib2 transform should always be paired with the image
coordinate point first, as shown in the figure above.
110
CVL Class Reference
cc2XformCalib2
Constructors/Destructors
cc2XformCalib2
cc2XformCalib2();
cc2XformCalib2(const cc2XformCalib2& calibXform);
~cc2XformCalib2();
•
cc2XformCalib2();
Constructs an identity transform. The direction of the transform is set to map points from
physical space to client space (usually the same as image space).
•
cc2XformCalib2(const cc2XformCalib2& calibXform);
Copy constructor.
Parameters
calibXform
•
The new object that is a copy of this object.
~cc2XformCalib2();
Destructor.
Operators
operator=
cc2XformCalib2& operator=(
const cc2XformCalib2& calibXform);
Assignment operator. Make this object a copy of calibXform.
Parameters
calibXform
operator*
Source of the assignment.
using cc2XformBase::operator*;
Uses the same operator* as the base class.
CVL Class Reference
111
cc2XformCalib2
Public Member Functions
init
void init(
const ccCalib2ParamsIntrinsic& intrinsicParams,
const ccCalib2ParamsExtrinsic& extrinsicParams);
void init(const ccCalib2CrspVector& correspondences);
void init(
const ccCalib2CrspVector& correspondences,
cmStd vector<double>& rmsResiduals,
cmStd vector<double>& maxResiduals);
You initialize the object with intrinsic and extrinsic parameters, or with corresponding
image points and physical points. The most recent initialization reflects the active
transform. The direction of the transform is set to map points from physical space to
client space (usually the same as image space).
•
void init(
const ccCalib2ParamsIntrinsic& intrinsicParams,
const ccCalib2ParamsExtrinsic& extrinsicParams);
Creates a calibration transform using the provided intrinsic and extrinsic parameters.
Parameters
intrinsicParams
The intrinsic parameter set.
extrinsicParams The extrinsic parameter set.
•
void init(const ccCalib2CrspVector& correspondences);
Create a calibration transform computed from a vector of corresponding image points
and physical points. The direction of the transform is from the second coordinate space
in the correspondences to the first coordinate space. If using results returned by the
feature extractor provided with CVL (cfCalib2VertexFeatureExtract()), the direction of
transformation is from physical space to client space (usually the same as image
space).
112
CVL Class Reference
cc2XformCalib2
The extrinsic parameters within this transform are set according to the first
correspondence in the ccCalib2CrspVector input vector (index 0).
The number of views equals the size of input vector, one entry per view. The
correspondences are generated from different views of a planar object. The following
conditions must be met:
1.
All intrinsic camera settings are expected to stay constant over all the views.
2.
Two views are considered different if the planes of the objects in two views are not
parallel (relative to the camera).
Parameters
correspondences
A vector of corresponding image points and physical points.
Throws
cc2XformCalibDefs::InsufficientPoints
If the number of points in any ccCrspPairVector is < 9.
cc2XformCalibDefs::NumerircalError
If computation cannot be further carried out. This may happen if
conditions above are not met.
cc2XformCalibDefs::BadParams
If size of the ccCalib2CrspVector vector is 0.
Notes
If the number of views = 1, separation of intrinsic and extrinsic parameters is not
possible.
As the number of views increases, the accuracy of computed intrinsic and extrinsic
parameters increases.
The cc2XformCalib2 is not symmetric between image coordinates and physical
coordinates. The cc2XformCalib2 transform should map from physical coordinates
to image coordinates. The first cc2Vect in each ccCrspPair should represent the
image location of the vertex expressed in image coordinates, and the second
cc2Vect should represent the corresponding location in physical coordinates.
CVL Class Reference
113
cc2XformCalib2
•
void init(
const ccCalib2CrspVector& correspondences,
cmStd vector<double>& rmsResiduals,
cmStd vector<double>& maxResiduals);
Create a calibration transform computed from a vector of correspondences. All
comments following the previous init() overload above are valid here too. Additionally,
compute the residual errors in mapping points. The vectors rmsResiduals and
maxResiduals are resized to the size of the correspondences vector.
For single view calibration, rms and maximum residual errors of mapped points from "to"
points in the single correspondence provided are computed and stored as single
elements of rmsResiduals and maxResiduals respectively.
For multiple view calibration, residual errors for the i-th correspondence are computed
as follows:
1.
A cc2XformCalib2 object T_i is constructed using intrinsic parameters of this
cc2XformCalib2 object and extrinsic parameters computed from the i-th
correspondence.
2.
"from" points in the i-th correspondence are mapped through T_i.
3.
Rms and maximum residual errors of mapped points from "to" points in the i-th
correspondence are computed and stored as the i-th element of rmsResiduals and
maxResiduals respectively.
Notes
The cc2XformCalib2 is not symmetric between image coordinates and physical
coordinates. The cc2XformCalib2 transform should map from physical coordinates
to image coordinates. The first cc2Vect in each ccCrspPair should represent the
image location of the vertex expressed in image coordinates, and the second
cc2Vect should represent the corresponding location in physical coordinates.
intrinsicParams
const ccCalib2ParamsIntrinsic& intrinsicParams() const;
Returns the intrinsic calibration parameters which are part of this calibration transform.
Throws
cc2XformCalibDefs::BadParams
If this transform was initialized with a single view.
114
CVL Class Reference
cc2XformCalib2
extrinsicParams
const ccCalib2ParamsExtrinsic& extrinsicParams() const;
void extrinsicParams(
const ccCalib2ParamsExtrinsic& extrinsicParams);
ccCalib2ParamsExtrinsic extrinsicParams (
const ccCrspPairVector& corr) const;
void extrinsicParams(const ccCrspPairVector& corr);
•
const ccCalib2ParamsExtrinsic& extrinsicParams() const;
Returns the extrinsic calibration parameters that are part of this calibration transform.
Throws
cc2XformCalibDefs::BadParams
If this transform was initialized with a single view.
•
void extrinsicParams(
const ccCalib2ParamsExtrinsic& extrinsicParams);
Sets new extrinsic calibration parameters.
Parameters
extrinsicParams The new extrinsic calibration parameters.
Throws
cc2XformCalibDefs::BadParams
If this transform was initialized with a single view.
•
ccCalib2ParamsExtrinsic extrinsicParams (
const ccCrspPairVector& corr) const;
Returns the extrinsic parameters associated with the view specified by corr.
Notes
The intrinsic camera calibration parameters used to obtain the provided
correspondence must be same parameters that are part of this transform. In other
words, the intrinsic camera settings used when init() was called must be
unchanged when this function is called.
Parameters
corr
CVL Class Reference
The corresponding image point - physical point vector for one
view.
115
cc2XformCalib2
Throws
cc2XformCalibDefs::BadParams
If this transform was initialized with a single view.
•
void extrinsicParams(const ccCrspPairVector& corr);
Sets the extrinsic parameters associated with the view specified by corr.
Notes
The intrinsic camera calibration parameters used to obtain the provided
correspondence must be same parameters that are part of this transform. In other
words, the intrinsic camera settings used when init() was called must be
unchanged when this function is called.
Calling init() with multiple views sets the extrinsic parameters in the transform to
extrinsic parameters for the first view (index 0). If you wish the change the transform
to use extrinsic parameters for a different view, you call this function.
Parameters
corr
The corresponding image point - physical point vector for one
view.
Throws
cc2XformCalibDefs::BadParams
If this transform was initialized with a single view.
extrinsicXform
cc3Xform extrinsicXform() const;
void extrinsicXform(const cc3Xform& rigidXform);
cc3Xform extrinsicXform(
const ccCrspPairVector& corr) const;
•
cc3Xform extrinsicXform() const;
Returns the rigid 3D transform between the physical 3D coordinate system and camera
3D coordinate system that is part this cc2XformCalib2 transform. The direction of
returned transform is same as direction of this cc2XformCalib2 transform.
•
void extrinsicXform(const cc3Xform& rigidXform);
Sets the rigid 3D transform between the camera coordinate system and the physical
coordinate system to provided a rigid 3D transform. If matrix Rrot in rigidXform is not
exactly a rotation matrix, it attempts to compute a rotation matrix closest to Rrot and then
sets extrinsic transform. Such a computation should succeed in practical situations.
116
CVL Class Reference
cc2XformCalib2
Parameters
rigidXform
The new 3D transform.
Throws
cc2XformCalib2Defs::BadParams
If computation of a rotation matrix (if necessary) does not
succeed.
•
cc3Xform extrinsicXform(
const ccCrspPairVector& corr) const;
Get the 3D rigid transform between the physical 3D coordinate system and camera 3D
coordinate system as specified by the correspondence coor. The direction of returned
transform is same as direction of this cc2XformCalib2 transform.
Parameters
corr
mapPoint
The correspondence vector.
virtual cc2Vect mapPoint(const cc2Vect& pt) const;
Maps a given 2-D point through this transform and returns the mapped point.
Parameters
pt
The point to be mapped.
Throws
cc2XformCalibDefs::MapsToInfity
If pt maps to infinity through this transform.
isLinear
virtual bool isLinear() const;
Returns true if this transform is an affine transform (a linear transform). For example, the
transform is linear if there is no perspective or radial distortion.
Notes
This function is designed to efficiently identify cases where transformations are
guaranteed to be linear. The function may return false if it would take too much time
to determine if it is linear.
linearXform
virtual cc2XformLinear linearXform(
const cc2Vect& atThisPt) const;
Returns a linear transform which is the best approximation to this transform at the point
atThisPt.
CVL Class Reference
117
cc2XformCalib2
Parameters
atThisPt
composeBase
The point where the transform is linearized.
virtual cc2XformBasePtrh composeBase(
const cc2XformBase& rhs) const;
Returns the transform which is the composition of this transform and the transform rhs.
Mapping a point with the resulting transformation is equivalent to first mapping the point
by the transformation rhs and then by this transformation.
Parameters
rhs
The transform to compose with this transform.
Notes
The only allowed compositions are: cc2XformLinear *cc2XformLinear,
cc2XformLinear *cc2XformPoly, cc2XformPoly *cc2XformLinear
inverseBase
virtual cc2XformBasePtrh inverseBase() const;
Returns the inverse of this transform.
Notes
In the case of nonlinear transformations, the inverse transformation may not be
exact.
clone
virtual cc2XformBasePtrh clone() const;
Returns a newly allocated copy of this object.
Notes
This function is required for polymorphic copying.
Typedefs
ccCalib2CrspVector
typedef cmStd vector<ccCrspPairVector> ccCalib2CrspVector;
ccCrspPair
typedef ccPair<cc2Vect> ccCrspPair;
ccCrspPairVector
typedef cmStd vector<ccCrspPair> ccCrspPairVector;
118
CVL Class Reference
cc2XformDeform
#include <ch_cvl/xfdeform.h>
class cc2XformDeform : public cc2XformBase
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class models a 2D coordinate deformation transform.
Constructors/Destructors
cc2XformDeform
cc2XformDeform();
cc2XformDeform(
const cmStd vector<cc2Vect>& toPoints,
const cmStd vector<cc2Vect>& fromPoints,
double smoothness = 0);
cc2XformDeform(const cc2XformDeform& rhs);
~cc2XformDeform();
•
cc2XformDeform();
Default constructor. Constructs an identity transform.
•
cc2XformDeform(
const cmStd vector<cc2Vect>& toPoints,
const cmStd vector<cc2Vect>& fromPoints,
double smoothness = 0);
Constructs a transform that maps fromPoints to toPoints using a smoothing parameter.
CVL Class Reference
119
cc2XformDeform
Notes
A smoothness of 0 yields an exact mapping at the specified point while a
smoothness of infinity yields an affine transform.
The transform is non singular whenever points in the fromPoints vector are pair-wise
distinct and not colinear.
Parameters
toPoints
A vector of from points.
fromPoints
A vector of to points.
smoothness
The smoothing parameter.
Throws
cc2XformDeformDefs::BadParams
If smoothness < 0,
or if toPoints.size() != fromPoints.size(),
or if fromPoints.size() < 3.
ccMathError::Singular
If the transform is singular.
•
cc2XformDeform(const cc2XformDeform& rhs);
Copy constructor.
•
~cc2XformDeform();
Destructor
Operators
operator=
cc2XformDeform& operator=(const cc2XformDeform& rhs);
Assignment operator.
operator*
cc2XformBasePtrh operator*(const cc2XformBase& rhs) const;
Returns the composition of this transformation with the transformation rhs. Mapping a
point with the resulting transform is equivalent to first mapping the point by the transform
rhs and then by this transform. The use of this operator is equivalent of
composeBase(rhs).
Parameters
rhs
120
The transform to be composed with this transform.
CVL Class Reference
cc2XformDeform
Public Member Functions
update
void update(
const cmStd vector<cc2Vect>& toPoints,
const cmStd vector<c_Bool>& enabled =
cmStd vector<c_Bool>());
Updates this transform using the provided set of toPoints. toPoint-fromPoint
correspondence may be enabled or disabled through the enabled vector as follows:
If the i-th element in enabled is ceTrue, then the i-th point in fromPoints (provided
through the constructor) is mapped to the i-th point in toPoints. Otherwise, the i-th points
in the fromPoints and toPoints vectors are both ignored by this transform.
Parameters
toPoints
enabled
The new to points vector.
The enable/disable vector.
Throws
cc2XformDeformDefs::BadParams
If toPoints.size() != fromPoints.size(),
or if enabled.size() != fromPoints.size(),
or if the number of ceTrue elements in enabled is < 3.
smoothness
double smoothness() const;
Returns the current smoothness value.
mapPoint
virtual cc2Vect mapPoint(const cc2Vect& pt) const;
Returns the point pt, mapped by this deformation transform.
This function is an override to the base class cc2XformBase.
Parameters
pt
isLinear
The point to map.
virtual bool isLinear() const;
Returns true if this deformation transform is linear. Returns false otherwise.
This function is an override to the base class cc2XformBase.
CVL Class Reference
121
cc2XformDeform
linearXform
virtual cc2XformLinear linearXform(
const cc2Vect& atThisPt) const;
Returns a linear transform which represents the best linearization of this transform at the
given point. This linearization will map the given point exactly but will likely be accurate
only in a small region around that point.
This function is an override to the base class cc2XformBase.
Parameters
atThisPt
inverseBase
The point where the deformation transform is to be linearized.
virtual cc2XformBasePtrh inverseBase() const;
Returns a transform which is the inverse of this transform.
This function is an override to the base class cc2XformBase.
Notes
The inverse will not be exact unless this deformation transform is linear.
This function will take time comparable to the time taken to construct the transform
to be inverted. It is not a fast operation.
Throws
ccMathError::Singular
If this transform cannot be inverted because of singularity.
clone
virtual cc2XformBasePtrh clone() const;
Returns a newly allocated copy of this object.
This function is an override to the base class cc2XformBase.
Notes
This function is required for polymorphic copying.
isIdentity
bool isIdentity() const;
Returns true if this transform is an identity transform.
This function is an override to the base class cc2XformBase.
122
CVL Class Reference
cc2XformLinear
#include <ch_cvl/xflinear.h>
class cc2XformLinear : public cc2XformBase;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class implements a linear transformation between coordinate systems. If ( C x, C y )
are the client coordinates of generic image features and ( I x, I y ) their corresponding
image coordinates, the mapping performed by the class is:
Cx
Cy
=
a 11 a 12 I x
+
a 21 a 22 I y
Tx
Ty
where:
a 11 a 12
is the matrix component of the linear transformation
a 21 a 22
Tx
is the translation vector component of the linear transformation
Ty
A generic linear transformation L will be referred to as the pair:
⎛ a a
T ⎞
L = ⎜⎜ 11 12 , x ⎟⎟
⎝ a 21 a 22 T y ⎠
CVL Class Reference
123
cc2XformLinear
Notes
If you use this class to map image features from frame A to frame B, the
components of the translation vector must be the ones of the vector that goes from
frame B to frame A expressed in Frame B (see Math Foundations of Transformations
in the CVL User’s Guide). If the translation vector is not specified in this way, the
results returned by the mapping functions will not be correct.
Constructors/Destructors
cc2XformLinear
cc2XformLinear();
cc2XformLinear(const cc2Matrix& c, const cc2Vect& t);
cc2XformLinear(const cc2Vect& t, const ccRadian& xRot,
const ccRadian& yRot, double xScale, double yScale);
cc2XformLinear(const cc2Vect& t, double scale,
double aspect, const ccRadian& shear,
const ccRadian& rotation);
cc2XformLinear(const cc2Xform&);
•
cc2XformLinear();
The default constructor initializes this transformation to the identity transformation.The
identity transformation maps a point to itself.
⎛
⎞
Identity Transformation: ⎜ 1 0 , 0 ⎟
⎝ 01 0⎠
•
cc2XformLinear(const cc2Matrix& c, const cc2Vect& t);
Initializes this transformation to the matrix c and the translation vector t.
Parameters
c
t
124
The matrix this transformation is set to
The translation vector this transformation is set to
CVL Class Reference
cc2XformLinear
•
cc2XformLinear(const cc2Vect& t, const ccRadian& xRot,
const ccRadian& yRot, double xScale, double yScale);
Initializes the matrix component of this transformation according to the scale-rotation
mode (see Math Foundations of Transformations and Images and Coordinates in the
CVL User’s Guide). The translation vector component of this transformation is set to t.
Parameters
t
•
The translation vector this transformation is set to.
xRot
The x-rotation; the amount by which to rotate the x-axis in
radiants.
yRot
The y-rotation; the amount by which to rotate the y-axis in
radiants.
xScale
The x-scale; the amount by which to scale the x-axis units.
yScale
The y-scale; the amount by which to scale the y-axis units.
cc2XformLinear(const cc2Vect& t, double scale,
double aspect, const ccRadian& shear,
const ccRadian& rotation);
Initializes the matrix component of this transformation according to the shear-aspect
mode (see Math Foundations of Transformations and Images and Coordinates in the
CVL User’s Guide). The translation vector component of this transformation is set to t.
Parameters
t
•
The translation vector this transformation is set to.
scale
The scale element; the amount by which to scale all units.
aspect
The aspect ratio; the ratio of the x-axis units to the y-axis units.
shear
The shear element; the amount by which to rotate the y-axis in
radiants.
rotation
The rotation element; the amount by which to rotate the entire
coordinate system in radiants.
cc2XformLinear(const cc2Xform& c);
Initializes this transformation to the cc2Xform transformation c.
Parameters
c
CVL Class Reference
The cc2Xform transformation this transformation is set to
125
cc2XformLinear
Notes
This constructor is primarily for convenience when using existing CVL code.
Operators
cc2Xform
operator cc2Xform() const;
Cast this transformation to its equivalent cc2Xform form.
operator==
bool operator== (const cc2XformLinear& c) const;
Returns true if all the components of this transformation are the same as the
corresponding components of m.
Parameters
c
operator!=
The transformation compared to this transformation
bool operator!= (const cc2XformLinear& c) const;
Returns true if this transformation is not the same as c.
Parameters
c
operator=
The transformation compared to this transformation
cc2XformLinear& operator=(const cc2Xform& rhs);
Assignment operator. Creates a new cc2XformLinear object equal to rhs.
Parameters
rhs
operator*
The assignment source.
cc2XformLinear operator*(
const cc2XformLinear& xform) const;
cc2XformBasePtrh operator*(const cc2XformBase& base) const;
cc2Vect operator*(const cc2Vect& pt) const;
•
cc2XformLinear operator*(
const cc2XformLinear& xform) const;
Returns the composition of this transform with the transform xform. Mapping a point with
the resulting transform is equivalent to first mapping the point by the transform xform and
then by this transform. The use of this operator is equivalent to the use of the compose()
function.
126
CVL Class Reference
cc2XformLinear
Parameters
xform
•
The transform to be composed with this transform
cc2XformBasePtrh operator*(const cc2XformBase& base) const;
Returns the composition of this transform with the base transform base. Mapping a point
with the resulting transform is equivalent to first mapping the point by the transform base
and then by this transform. The use of this operator is equivalent to the use of the
composeBase() function.
Parameters
base
•
The base transform.
cc2Vect operator*(const cc2Vect& pt) const;
Maps the point pt by using this transform. This is equivalent to calling mapPoint() (see
below).
Parameters
pt
The point to map.
Public Member Functions
mapPoint
virtual cc2Vect mapPoint(const cc2Vect& pt) const;
Maps the point pt by using this transformation (see Math Foundations of Transformations
in the CVL User’s Guide).
⎛ a a
T ⎞
pt x
If ⎜⎜ 11 12 , x ⎟⎟ is this transformation and
is the point pt,
a
a
T
pt y
y ⎠
⎝ 21 22
the point returned by the function is::
a 11 a 12 pt x
a 21 a 22 pt y
Parameters
pt
isLinear
+
Tx
Ty
The point to map.
virtual bool isLinear() const;
Always returns true since this transformation is linear.
CVL Class Reference
127
cc2XformLinear
linearXform
virtual cc2XformLinear linearXform(const cc2Vect& atThisPt)
const;
This function returns a transformation identical to this transformation regardless of
atThisPt.
Parameters
atThisPt
composeBase
The point around which this transformation is linearized.
virtual cc2XformBasePtrh composeBase
(const cc2XformBase& rhs) const;
Returns a pointer handle to the transformation that is the composition of this
transformation and rhs. This transformation can be composed with either a
cc2XformLinear or a cc2XformPoly transformation.
Parameters
rhs
inverseBase
The transformation to be composed with this transformation.
virtual cc2XformBasePtrh inverseBase() const;
Returns a pointer handle to the inverse of this transformation.
Throws
ccMathError::Singular
The transformation is singular.
clone
virtual cc2XformBasePtrh clone() const;
Returns a newly allocated copy of this transformation.
matrix
const cc2Matrix& matrix();
void matrix(const cc2Matrix& c);
•
const cc2Matrix& matrix();
Returns the matrix component of this linear transformation.
•
void matrix(const ccMatrix<2>& c);
Sets the matrix component of this linear transformation to c.
Parameters
c
128
The matrix this transformation’s matrix is set to.
CVL Class Reference
cc2XformLinear
trans
const cc2Vect& trans();
void trans(const cc2Vect& t);
•
const cc2Vect& trans();
Returns the 2-element translation vector of this transformation.
•
void trans(const cc2Vect& t);
Sets the translation vector component of this transformation to t.
Parameters
t
inverse
The vector this transformation’s vector is set to.
cc2XformLinear inverse() const;
Returns the inverse of this transformation
Throws
ccMathError::Singular
The transformation is singular.
compose
cc2XformLinear compose(const cc2XformLinear& xform) const;
Returns the transformation resulting from the composition of this transformation with
xform. Mapping a point with the resulting transformation is equivalent to first mapping
the point by the transformation xform and then by this transformation.
Parameters
xform
xRot
The linear transformation to be composed with this
transformation.
ccRadian xRot() const;
Returns the x-rotation element of this transformation when using the scale-rotation
specification.
Throws
ccMathError::Singular
The transformation is singular.
CVL Class Reference
129
cc2XformLinear
yRot
ccRadian yRot() const;
Returns the y-rotation element of this transformation when using the scale-rotation
specification.
Throws
ccMathError::Singular
The transformation is singular
xScale
double xScale() const;
Returns the x-scale element of this transformation when using the scale-rotation
specification.
Throws
ccMathError::Singular
The transformation is singular.
yScale
double yScale() const;
Returns the y-scale element of this transformation when using the scale-rotation
specification.
ccMathError::Singular
The transformation is singular
scale
double scale() const;
Returns the scale element of this transformation when using the shear-aspect
specification.
Throws
ccMathError::Singular
The transformation is singular.
aspect
double aspect() const;
Returns the aspect element of this transformation when using the shear-aspect
specification.
Notes
Be careful when you mix elements from the scale-rotation specification with
elements of the shear-aspect specification. For example, if you specify a shear
angle in the shear-aspect specification, then aspect()!= yScale() / xScale().
Throws
130
CVL Class Reference
cc2XformLinear
ccMathError::Singular
The transformation is singular.
shear
ccRadian shear();
Returns the shear element of this transformation when using the shear-aspect
specification.
Throws
ccMathError::Singular
The transformation is singular.
rotation
ccRadian rotation() const;
Returns the rotation element of this transformation when using the shear-aspect
specification.
Throws
ccMathError::Singular
The transformation is singular.
mapAngle
ccRadian mapAngle (const ccRadian& ang) const;
Return the results of mapping the angle ang with this transformation.
Parameters
ang
invMapAngle
The angle to map in radians.
ccRadian invMapAngle (const ccRadian& ang) const;
Return the results of mapping the angle ang with the inverse of this transformation.
Parameters
ang
The angle to map in radians.
Throws
ccMathError::Singular
The transformation is singular.
invMapPoint
cc2Vect invMapPoint (const cc2Vect &pt) const;
Returns the result of mapping the point pt with the inverse of this transformation
If A =
a 11 a 12
a 21 a 22
CVL Class Reference
and
Tx
are the matrix and translation vector components of this
Ty
131
cc2XformLinear
transformation and
pt x
is the point pt, the point returned by the function is:
pt y
1 - a 22 – a 12 ptx – T x
----------------det ( A ) – a
21 a 11 pt y – T y
mapVector
cc2Vect mapVector (const cc2Vect &vect) const;
Maps the vector vect by using the matrix component of this transformation. If
a 11 a 12
is the matrix component of this transformation, the vector returned by the
a 21 a 22
function is:
a 11 a 12 vect x
a 21 a 22 vect y
Parameters
vect
The vector to be mapped.
invMapVector
cc2Vect invMapVector (const cc2Vect &vect) const;
Maps the vector vect by using the inverse of the matrix component of this transformation.
If A =
a 11 a 12
is the matrix component of this transformation, the vector returned
a 21 a 22
by the function is:
1 - a 22 – a 12 vectx
----------------det ( A ) – a
21 a 11 vect y
Parameters
vect
132
The vector to be mapped.
CVL Class Reference
cc2XformLinear
Throws
ccMathError::Singular
The transformation is singular.
mapArea
double mapArea (double area) const;
Returns the area after mapping by this transformation.
Parameters
area
The area to be mapped.
Notes
This function computes the mapped area by first calculating the area of a unit
square and then multiplying area by that value. You may wish to call this function
with the area of 1.0 to get a conversion constant you can use without the overhead
of calling this function multiple times.
invMapArea
double invMapArea (double area) const;
Returns the area after mapping by the inverse of this transformation.
Parameters
area
The area to be mapped.
Throws
ccMathError::Singular
The transformation is singular.
isIdentity
bool isIdentity() const;
Returns true if this transformation is the identity transformation (in this case all points
map to themselves).
isSingular
bool isSingular() const;
Returns true if this transformation is singular (in this case all points map to the same point
or line).
Data Members
I
static const cc2XformLinear I;
The identity transformation for cc2XformLinear.
CVL Class Reference
133
cc2XformLinear
134
CVL Class Reference
cc2XformPerspective
#include <ch_cvl/xfpersp.h>
class cc2XformPerspective: public cc2XformBase
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class models a perspective transform used for viewing a planar object. In general,
this is a nonlinear transform represented by a 3x3 matrix, for example the matrix M.
The transform maps a 2D point x to the 2D point u ⁄ w
y
v⁄w
Where
u
x
v = M× y
w
1
The matrix M is a 3x3 matrix as follows:
m11 m12 m13
M = m21 m22 m23
m31 m32 m33
For more details, please see Multiple View Geometry in Computer Vision by Richard
Hartley and Andrew Zisserman.
CVL Class Reference
135
cc2XformPerspective
Constructors/Destructors
cc2XformPerspective
cc2XformPerspective();
cc2XformPerspective(
const cmStd vector<cc2Vect>& toPoints,
const cmStd vector<cc2Vect>& fromPoints);
cc2XformPerspective(
const cc2Vect& cornerPo,
const cc2Vect& cornerPx,
const cc2Vect& cornerPy,
const cc2Vect& cornerPopp);
cc2XformPerspective(const cc3Matrix& mat);
cc2XformPerspective(const cc2XformPerspective& xform);
~cc2XformPerspective();
•
cc2XformPerspective();
Constructs the identity transform.
•
cc2XformPerspective(
const cmStd vector<cc2Vect>& toPoints,
const cmStd vector<cc2Vect>& fromPoints);
Constructs a perspective transformation that achieves a least-squares best fit from
fromPoints to toPoints.
Parameters
toPoints
fromPoints
The transform to points.
The transform from points.
Throws
cc2XformPerspectiveDefs:: BadParams
If fromPoint.size() != toPoints.size(),
or if fromPoints.size() < 4.
ccMathError::Singular
If a transform cannot be determined. This can occur if the points
all lie on a single point or line.
136
CVL Class Reference
cc2XformPerspective
•
cc2XformPerspective(
const cc2Vect& cornerPo,
const cc2Vect& cornerPx,
const cc2Vect& cornerPy,
const cc2Vect& cornerPopp);
Constructs a perspective transform that maps:
(0, 0) --> cornerPo
(1, 0) --> cornerPx
(0, 1) --> cornerPy
(1, 1) --> cornerPopp
Parameters
cornerPo
Location of the Po corner.
cornerPx
Location of the Px corner.
cornerPy
Location of the Py corner.
cornerPopp
Location of the Popp corner.
Notes
If the provided corners are set to identical points, the derived transform may be
unable to map the corner of the unit square.
•
cc2XformPerspective(const cc3Matrix& mat);
Constructs a perspective transform with matrix mat. Nonzero scalar multiples of a matrix
produce the same perspective transform.
Parameters
mat
•
The supplied 3D matrix.
cc2XformPerspective(const cc2XformPerspective& xform);
Copy Constructor
•
~cc2XformPerspective();
Destructor.
CVL Class Reference
137
cc2XformPerspective
Operators
operator=
const cc2XformPerspective& operator=(
const cc2XformPerspective& that);
Assignment operator. Make this object a copy of that.
Parameters
that
operator==
The object to copy.
bool operator==(const cc2XformPerspective& that) const;
Returns true if each entry in the matrix of this is equal to each corresponding entry in the
matrix of that. Returns false otherwise.
Parameters
that
The transform to compare with this transform.
Public Member Functions
matrix
cc3Matrix matrix() const;
Returns the 3x3 matrix of this perspective transform.
mapPoint
virtual cc2Vect mapPoint(const cc2Vect& pt) const;
Returns the 2D point pt mapped through this transform.
Parameters
pt
The point to map.
Throws
ccMathError::Singular
If computation involves division by zero.
isLinear
virtual bool isLinear() const;
Returns true if this transform is exactly linear; returns false otherwise.
Using the notation in the introduction, this transform is exactly linear if m31 = m32 = 0.
138
CVL Class Reference
cc2XformPerspective
linearXform
virtual cc2XformLinear linearXform(const cc2Vect& pt)
const;
Returns a linear transform which represents the best approximation to this perspective
transform at 2D point pt.
Parameters
pt
The point where the linear approximation is made.
Throws
ccMathError::Singular
If computation involves division by zero.
composeBase
virtual cc2XformBasePtrh composeBase(
const cc2XformBase& rhs) const;
Returns a transform which is the composition of this with the given transform. For
example, (*this) * rhs.
Parameters
rhs
inverseBase
The transform to compose with this transform.
virtual cc2XformBasePtrh inverseBase() const;
Returns the inverse of this transform.
Throws
ccMathError::Singular
If this transform is singular.
clone
virtual cc2XformBasePtrh clone() const;
Returns a newly allocated copy of this object.
Notes
This function is required for polymorphic copying.
isSingular
bool isSingular() const;
Returns true if this transform is singular; returns false otherwise.
CVL Class Reference
139
cc2XformPerspective
140
CVL Class Reference
cc2XformPoly
#include <ch_cvl/xfpoly.h>
class cc2XformPoly : public cc2XformBase;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class implements a nonlinear polynomial mapping between coordinate frames to
be used in all those instances where a high level of mapping accuracy is required. The
class implements polynomial mappings of order 1, 3 and 5 (for more details, see Math
Foundations of Transformations in the CVL User’s Guide). If ( C x, C y ) are client
coordinates of generic image features and ( I x, I y ) are their corresponding image
coordinates, the mapping performed by the class is:
i+j≤n
Cx =
∑
i+j≤n
i
a ij I x I y
j
i, j ≥ 0
Cy =
∑
i
b ij I x I y
j
i, j ≥ 0
where a ij and b ij are the coefficients of the transformation and n is the degree of the
transformation.
Constructors/Destructors
cc2XformPoly
cc2XformPoly();
cc2XformPoly(const cmStd vector<cc2Vect>& toPoints,
const cmStd vector<cc2Vect>& fromPoints,
c_Int32 order = 5);
•
cc2XformPoly();
Constructs the identity transformation. The identity transformation is:
Cx = Ix
CVL Class Reference
Cy = Iy
141
cc2XformPoly
•
cc2XformPoly(const cmStd vector<cc2Vect>& toPoints,
const cmStd vector<cc2Vect>& fromPoints,
c_Int32 order = 5);
Creates a polynomial transformation of order order. The coefficients of the
transformation computed by the constructor provide the best least-square fit between
the list of points fromPoints (typically in image coordinates) and the list of points toPoints
(typically in client coordinates). Only polynomials of orders 1, 3 and 5 are allowed. The
following table lists the minimum number of points for each order
Order
Number of Points
1
3
3
10
5
21
Parameters
toPoints
The target list of points in client coordinates.
fromPoints
The starting list of points in image coordinates.
order
The order of the polynomial transformation. It must be 1, 3 or 5.
Notes
In general, the more points are used the more accurate the resulting polynomial fit
will be. It is recommended that a grid of at least 8x8 points, spanning the entire
region of interest, is used.
Throws
cc2XformPoly::BadParams
Not enough points in fromPoints and toPoints for the requested
order of the polynomial transformation.
The number of points in fromPoints is not equal to the number of
points in toPoints.
The requested order of the polynomial transformation is less than
1.
cc2XformDefs::NotImplemented
The requested order of the polynomial is positive and not 1, 3, or
5.
cc2XformPoly::IllDefined
The least-square fit cannot converge to a solution.
142
CVL Class Reference
cc2XformPoly
Public Member Functions
mapPoint
virtual cc2Vect mapPoint(const cc2Vect& fromPoint) const;
Maps the coordinates of the point fromPoint using this transformation.
Parameters
fromPoint
isLinear
The point mapped by this transformation
virtual bool isLinear() const;
Returns true if the order of this transformation is 1 or if all the coefficients of the
polynomial terms with degree greater than one are exactly zero.
linearXform
virtual cc2XformLinear linearXform(const cc2Vect& atThisPt)
const;
Returns the linear transformation defined by the linear terms of the Taylor series
expansion of this transformation about the point atThisPt (for more details see Math
Foundations of Transformations in the CVL User’s Guide).
Parameters
atThisPt
composeBase
The point where the returned cc2XformLinear transformation is
defined
virtual cc2XformBasePtrh composeBase(
const cc2XformBase& rhs)const;
Returns a transformation that is the composition of this transformation with rhs. Mapping
a point with the resulting transformation is equivalent to first mapping the point by rhs
and then by this transformation. This transformation can only be composed with a
cc2XformLinear object.
Parameters
rhs
The transformation composed with this transformation
Throws
cc2XformDefs::NotImplemented
This transformation is composed with an object other than
cc2XformLinear.
inverseBase
virtual cc2XformBasePtrh inverseBase() const;
Returns the inverse of this transformation. The inverse of this transformation maps points
in client coordinates to points in image coordinates.
CVL Class Reference
143
cc2XformPoly
Notes
This function may not provide an exact inverse mapping.
Throws
ccMathError::Singular
The transformation is singular and cannot be inverted.
clone
virtual cc2XformBasePtrh clone() const;
Returns a newly allocated copy of this object.
144
CVL Class Reference
cc3AngleVect
#include <ch_cvl/ccalib.h>
class cc3AngleVect;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class represents a rotation in 3-D space. It holds three angles which express
rotations of the axes of a 3-D coordinate system. It is used to express the orientation of
one coordinate system with respect to another. We use the convention of Givens
rotations (see Multiple View Geometry in Computer Vision, Appendix A3.1.1, by Hartley
& Zisserman).
A rotation R of 3-D coordinate axes is expressed as:
R = Rx * Ry * Rz
where
Rz = rotation of x,y-axes about a fixed z-axis,
Ry = rotation of z,x-axes about a fixed y-axis,
Rx = rotation of y,z-axes about a fixed x-axis.
The order of applying rotations is: Rz first, Ry second, and Rx third.
Constructors/Destructors
cc3AngleVect
cc3AngleVect(
const ccRadian& angleX,
const ccRadian& angleY,
const ccRadian& angleZ);
cc3AngleVect();
•
cc3AngleVect(
const ccRadian& angleX,
const ccRadian& angleY,
const ccRadian& angleZ);
Constructs an object with angles initialized to the provided values.
CVL Class Reference
145
cc3AngleVect
Parameters
angleX
•
The y,z-axes rotation angle about a fixed x-axis.
angleY
The z,x-axes rotation angle about a fixed y-axis.
angleZ
The x,y-axes rotation angle about a fixed z-axis.
cc3AngleVect();
Constructs an object with all three angles initialized to 0.
Public Member Functions
x
ccRadian x();
void x(const ccRadian& angleX);
•
ccRadian x();
Returns the y,z-axes rotation angle about a fixed x-axis.
•
void x(const ccRadian& angleX);
Sets a new y,z-axes rotation angle about a fixed x-axis.
Parameters
angleX
y
The new y,z-axes rotation angle about a fixed x-axis.
ccRadian y() const;
void y(const ccRadian& angleY);
•
ccRadian y() const;
Returns the z,x-axes rotation angle about a fixed y-axis.
•
void y(const ccRadian& angleY);
Sets a new z,x-axes rotation angle about a fixed y-axis.
Parameters
angleY
146
The new z,x-axes rotation angle about a fixed y-axis.
CVL Class Reference
cc3AngleVect
z
ccRadian z() const;
void z(const ccRadian& angleZ);
•
ccRadian z() const;
Returns the x,y-axes rotation angle about a fixed z-axis.
•
void z(const ccRadian& angleZ);
Sets a new x,y-axes rotation angle about a fixed z-axis.
Parameters
angleZ
matrix
The new x,y-axes rotation angle about a fixed z-axis.
cc3Matrix matrix() const;
void matrix(const cc3Matrix& R);
•
cc3Matrix matrix() const;
Returns the rotation matrix associated with rotation of the 3-D coordinate axes through
angles in this object. See the introduction to this reference page for the rotation order
applied.
•
void matrix(const cc3Matrix& R);
Set the angles in this object to angles computed from rotation matrix R. Theoretically, R
must satisfy determinant (R) = 1 and R * (Transpose of R) = Identity. If R is not exactly a
rotation matrix it attempts to compute a rotation matrix closest to R and then sets the
angles. Such a computation should succeed in practical situations.
Parameters
R
The new rotation matrix.
Throws
cc2XformCalib2Defs::BadParams
If computation of a rotation matrix (if necessary) does not
succeed.
CVL Class Reference
147
cc3AngleVect
148
CVL Class Reference
cc3PlanePel
#include <ch_cvl/colorpel.h>
class cc3PlanePel;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
No
The cc3PlanePel class describes a three-plane pixel that can be used to create
multi-planar pel buffers. The planes of the three-plane pixel are named plane 0, plane
1, and plane 2. The way the three planes are used depends on the application. One
typical use is RGB, although HLS and HSV can also be supported.
In addition to this three-plane pixel class, CVL also defines additional pointer, const
pointer, reference, and const reference classes that provide transparent pointer and
reference semantics:
•
cc3PlanePtr
•
cc3PlanePtr_const
•
cc3PlaneRef
•
cc3PlaneRef_const
Constructors/Destructors
cc3PlanePel
cc3PlanePel();
cc3PlanePel(c_UInt8 ch1, c_UInt8 ch2, c_UInt8 ch3);
•
cc3PlanePel();
The default constructor creates a pixel with uninitialized elements.
•
cc3PlanePel(c_UInt8 ch1, c_UInt8 ch2, c_UInt8 ch3);
Creates a pixel with the specified values for each plane.
Parameters
ch1
CVL Class Reference
Value for plane 0.
149
cc3PlanePel
ch2
Value for plane 1.
ch3
Value for plane 2.
Public Member Functions
plane0
c_UInt8& plane0();
const c_UInt8& plane0() const;
•
c_UInt8& plane0();
Returns a read-write reference to the plane 0 element of the pixel.
•
const c_UInt8& plane0() const;
Returns a read-only reference to the plane 0 element of the pixel.
plane1
c_UInt8& plane1();
const c_UInt8& plane1() const;
•
c_UInt8& plane1();
Returns a read-write reference to the plane 1 element of the pixel.
•
const c_UInt8& plane1() const;
Returns a read-only reference to the plane 1 element of the pixel.
plane2
c_UInt8& plane2();
const c_UInt8& plane2() const;
•
c_UInt8& plane2();
Returns a read-write reference to the plane 2 element of the pixel.
•
const c_UInt8& plane2() const;
Returns a read-only reference to the plane 2 element of the pixel.
150
CVL Class Reference
cc3PlanePelBuffer
#include <ch_cvl/colorbuf.h>
class cc3PlanePelBuffer : public ccPelBuffer<cc3PlanePel>;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
The cc3PlanePelBuffer class is an instance of the template class ccPelBuffer that uses
three-plane pixels (see cc3PlanePel on page 149).
Constructors/Destructors
cc3PlanePelBuffer
cc3PlanePelBuffer();
cc3PlanePelBuffer(c_Int32 width, c_Int32 height,
c_Int32 alignModulus=32);
cc3PlanePelBuffer(ccPelRoot<cc3PlanePel>* pelroot);
•
cc3PlanePelBuffer();
Creates an unbound window, that is, one that is not associated with any root image.
Height and width are set to 0 and all offsets are set to (0,0). The window’s transform is
set to identity.
•
cc3PlanePelBuffer(c_Int32 width, c_Int32 height,
c_Int32 alignModulus=32);
Allocates contiguous storage for a root image of width x height pixels of type P and a
window that encompasses the entire root image. The pixels are default-constructed.
This storage will be freed by the destructor. The byte address of the first row’s first pixel
is zero modulo the alignModulus. The allocated row width (in pixels) is increased if
necessary to make the row size (in bytes) a multiple of the specified alignModulus. Up
to (alignModulus-1) pad pixels may be allocated for each row. Pad pixels, if any, occur
to the right (greater x) of the pixels that belong to the root image. Pixel processing
routines are permitted to overwrite pad pixels.
CVL Class Reference
151
cc3PlanePelBuffer
Parameters
width
•
The width, in pixels, of the root image. (width > 0)
height
The height, in rows, of the root image. (height > 0)
alignModulus
A value that determines how memory used for the image is
aligned. A value of 1 means that memory is aligned on byte
boundaries, 2 aligns on word boundaries, 4 aligns on long word
boundaries, and so on. (alignModulus >= 1)
cc3PlanePelBuffer(ccPelRoot<cc3PlanePel>* pelroot);
Creates a window bound to the root image pelroot. Height and width are set to
encompass the entire root image. Offset is set to (0,0) and the transform is set to identity.
Parameters
pelroot
The root image the window is bound to.
Notes
If pelroot is NULL, the effect is the same as cc3PlanePelBuffer(); this window
becomes unbound.
Public Member Functions
plane0
ccPelBuffer_const<c_UInt8> plane0() const;
ccPelBuffer<c_UInt8> plane0();
•
ccPelBuffer_const<c_UInt8> plane0() const;
Returns plane 0 of this pel buffer as a read-only grey-scale pel buffer. The returned pel
buffer has the same window size, offset, root offset, and transform as this pel buffer. The
returned pel buffer exists even if this pel buffer is destroyed.
•
ccPelBuffer<c_UInt8> plane0();
Returns plane 0 of this pel buffer as a read-write grey-scale pel buffer. The returned pel
buffer has the same window size, offset, root offset, and transform as this pel buffer. The
returned pel buffer exists even if this pel buffer is destroyed.
152
CVL Class Reference
cc3PlanePelBuffer
plane1
ccPelBuffer_const<c_UInt8> plane1() const;
ccPelBuffer<c_UInt8> plane1();
•
ccPelBuffer_const<c_UInt8> plane1() const;
Returns plane 1 of this pel buffer as a read-only grey-scale pel buffer. The returned pel
buffer has the same window size, offset, root offset, and transform as this pel buffer. The
returned pel buffer exists even if this pel buffer is destroyed.
•
ccPelBuffer<c_UInt8> plane1();
Returns plane 1 of this pel buffer as a read-write grey-scale pel buffer. The returned pel
buffer has the same window size, offset, root offset, and transform as this pel buffer. The
returned pel buffer exists even if this pel buffer is destroyed.
plane2
ccPelBuffer_const<c_UInt8> plane2() const;
ccPelBuffer<c_UInt8> plane2();
•
ccPelBuffer_const<c_UInt8> plane2() const;
Returns plane 2 of this pel buffer as a read-only grey-scale pel buffer. The returned pel
buffer has the same window size, offset, root offset, and transform as this pel buffer. The
returned pel buffer exists even if this pel buffer is destroyed.
•
ccPelBuffer<c_UInt8> plane2();
Returns plane 2 of this pel buffer as a read-write grey-scale pel buffer. The returned pel
buffer has the same window size, offset, root offset, and transform as this pel buffer. The
returned pel buffer exists even if this pel buffer is destroyed.
colorSpace
ccColorSpaceDefs::ColorSpace colorSpace() const;
void colorSpace(ccColorSpaceDefs::ColorSpace colorSpace);
•
ccColorSpaceDefs::ColorSpace colorSpace() const;
Returns the color space (RGB or HSI) of the image.
CVL Class Reference
153
cc3PlanePelBuffer
•
void colorSpace(ccColorSpaceDefs::ColorSpace colorSpace);
Sets the color space (RGB or HSI) of the image.
Parameters
colorSpace
154
The color space:
ccColorSpaceDefs::eRGB or
ccColorSpaceDefs::eHSI
CVL Class Reference
cc3PlanePelBuffer_const
#include <ch_cvl/colorbuf.h>
class cc3PlanePelBuffer_const : public
ccPelBuffer_const<cc3PlanePel>
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
The cc3PlanePelBuffer class is an instance of the template class ccPelBuffer on
page 2015 that uses three-plane pixels (see cc3PlanePel on page 149). This class
allows read-only access to the planes of the pel buffer.
Constructors/Destructors
cc3PlanePelBuffer_const
cc3PlanePelBuffer_const();
cc3PlanePelBuffer_const(const ccPelRoot<cc3PlanePel>*);
•
cc3PlanePelBuffer_const();
Creates an unbound window, that is, one that is not associated with any root image.
Height and width are set to 0 and all offsets are set to (0,0). The window’s transform is
set to identity.
•
cc3PlanePelBuffer_const(
const ccPelRoot<cc3PlanePel>* pelroot);
Creates a window bound to the root image pelroot. Height and width are set to
encompass the entire root image. Offset is set to (0,0) and the transform is set to identity.
Parameters
pelroot
The root image the window is bound to.
Notes
If pelroot is NULL, the effect is the same as cc3PlanePelBuffer_const(); this
window becomes unbound.
CVL Class Reference
155
cc3PlanePelBuffer_const
Public Member Functions
plane0
ccPelBuffer_const<c_UInt8> plane0() const;
Returns plane 0 of this pel buffer as a read-only grey-scale pel buffer. The returned pel
buffer has the same window size, offset, root offset, and transform as this pel buffer. The
returned pel buffer exists even if this pel buffer is destroyed.
plane1
ccPelBuffer_const<c_UInt8> plane1() const;
Returns plane 1 of this pel buffer as a read-only grey-scale pel buffer. The returned pel
buffer has the same window size, offset, root offset, and transform as this pel buffer. The
returned pel buffer exists even if this pel buffer is destroyed.
plane2
ccPelBuffer_const<c_UInt8> plane2() const;
Returns plane 2 of this pel buffer as a read-only grey-scale pel buffer. The returned pel
buffer has the same window size, offset, root offset, and transform as this pel buffer. The
returned pel buffer exists even if this pel buffer is destroyed.
colorSpace
ccColorSpaceDefs::ColorSpace colorSpace() const;
void colorSpace(ccColorSpaceDefs::ColorSpace colorSpace);
•
ccColorSpaceDefs::ColorSpace colorSpace() const;
Returns the color space (RGB or HSI) of the image.
•
void colorSpace(ccColorSpaceDefs::ColorSpace colorSpace);
Sets the color space (RGB or HSI) of the image.
Parameters
colorSpace
156
The color space:
ccColorSpaceDefs::eRGB or
ccColorSpaceDefs::eHSI
CVL Class Reference
cc3Vect
#include <ch_cvl/vector.h>
class cc3Vect;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class describes a three-dimensional vector, a quantity that is determined by its
length (magnitude) and direction. Throughout the CVL, cc3Vector is used to describe
points in three-dimensional space, so you can also think of a vector as an (x,y,z)
coordinate.
Notes
cc3Vect is the name of the class as it is used throughout the Cognex Vision Library.
This name is actually a typedef for ccVector<3>. Both forms are valid and entirely
equivalent.
Do not confuse the CVL vectors classes cc2Vect and cc3Vect with the C++
Standard Template Library’s vector template class. Though both have the same
mathematical underpinnings, the CVL vector classes are generally used to
describe the location of points while the STL vector class is used to implement
flexible arrays.
Constructors/Destructors
cc3Vect
cc3Vect();
cc3Vect(double x, double y, double z);
•
cc3Vect();
The default constructor creates a vector in which all three components are set to zero.
•
cc3Vect(double x, double y, double z);
Creates a vector with the specified components.
CVL Class Reference
157
cc3Vect
Parameters
x
The x-component of the vector.
y
The y-component of the vector.
z
The z-component of the vector.
Operators
operator[]
double& operator[](int d);
double operator[](int d) const;
•
double& operator[](int d);
Provides array-like access to the vector. Typically you use this form when your
application works with both two- and three-dimensional vectors. This form allows you to
set the value of a component.
Parameters
d
The index of the element to return.
0: The x-component.
1: The y-component.
2: The z-component.
•
double operator[](int d) const;
Provides array-like access to the vector. Typically you use this form when your
application works with both two- and three-dimensional vectors.
Parameters
d
The index of the element to return.
0: The x-component.
1: The y-component.
2: The z-component.
operator+
cc3Vect operator+(const cc3Vect& v) const;
Returns a vector that is the result of adding this vector and another vector.
158
CVL Class Reference
cc3Vect
Parameters
v
operator+=
The vector to add to this vector.
cc3Vect& operator+=(const cc3Vect& v);
Adds this vector to another vector and returns the result.
Parameters
v
operator-
The vector to add to this vector.
cc3Vect operator-() const;
cc3Vect operator-(const cc3Vect& v) const;
•
cc3Vect operator-() const;
The unary minus operator.
•
cc3Vect operator-(const cc3Vect& v) const;
Returns a vector that is the result of subtracting the vector v from this vector.
Parameters
v
operator-=
The vector to subtract from this vector.
cc3Vect& operator-=(const cc3Vect& v);
Subtracts the vector v from this vector and returns the result.
Parameters
v
operator*
The vector to subtract from this vector.
cc3Vect operator*(double d) const;
friend cc3Vect operator*(double d, const cc3Vect& v);
double operator*(const cc3Vect& v) const;
•
cc3Vect operator*(double d) const;
Returns a vector that is the result of multiplying each element in the vector by d.
Parameters
d
CVL Class Reference
The value by which to multiply each element of the vector.
159
cc3Vect
•
friend cc3Vect operator*(double d, const cc3Vect& v);
Returns a vector that is the result of multiplying each element in the vector by d.
Parameters
d
v
•
The value by which to multiply each element of the vector.
The vector.
double operator*(const cc3Vect& v) const;
Returns the dot product of this vector and the vector v.
Parameters
v
operator*=
The other vector.
cc3Vect& operator*=(double d);
Multiplies each element in this vector by d and returns the result.
Parameters
d
operator/
The value by which to multiply each element of the vector.
cc3Vect operator/(double d) const;
Returns a vector that is the result of dividing each element in this vector by d.
Parameters
d
operator/=
The value by which to divide each element of the vector.
cc3Vect& operator/=(double d) const;
Divides each element in this vector by d and returns the result.
Parameters
d
operator==
The value by which to divide each element of the vector.
bool operator==(const cc3Vect& v) const;
Returns true if this vector is equal to another vector.
Parameters
v
160
The other vector.
CVL Class Reference
cc3Vect
operator!=
bool operator!=(const cc3Vect& v) const;
Returns true if this vector is not equal to another vector.
Parameters
v
The other vector.
Public Member Functions
x
double x() const;
void x(double newX);
•
double x() const;
Returns the vector’s x-component.
•
void x(double newX);
Sets the vector’s x-component.
Parameters
newX
y
The new x-component.
double y() const;
void y(double newY);
•
double y() const;
Returns the vector’s y-component.
•
void y(double newY);
Sets the vector’s y-component.
Parameters
newY
CVL Class Reference
The new y-component.
161
cc3Vect
z
double z() const;
void z(double newZ);
•
double z() const;
Returns the vector’s z-component.
•
void z(double newZ);
Sets the vector’s z-component.
Parameters
newZ
len
The new z-component.
double len() const;
Returns the length (or magnitude) of the vector.
isNull
bool isNull() const;
Returns true if this is a null vector (all components are zero).
unit
cc3Vect unit() const;
Returns a unit vector parallel to this vector. A unit vector is a vector whose length is 1.
Throws
ccMathError::NullVector
The x-component, the y-component, and the z-component are
zero.
project
cc3Vect project(const cc3Vect&) const;
Returns a vector that is the result of projecting the vector v onto this vector.
Parameters
v
The vector to project onto this vector.
Throws
ccMathError::NullVector
The x-component, the y-component, and the z-component are
zero.
162
CVL Class Reference
cc3Vect
An error is not thrown if v is null or the two vectors are
perpendicular to each other.
distance
double distance(const cc3Vect& v) const;
Returns the distance to the other vector. This is the length of difference between this
vector and vector v.
Parameters
v
dot
The other vector.
double dot(const cc3Vect& v) const;
Returns the dot product of this vector and the vector v.
Parameters
v
cross
The other vector.
cc3Vect cross(const cc3Vect& v) const;
Returns the cross product of this vector and v.
Parameters
v
CVL Class Reference
The other vector.
163
cc3Vect
164
CVL Class Reference
cc4200VideoMan
#include <ch_cog/vman4200.h>
class cc4200VideoMan;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class implements a video manager that emulates Cognex 4200 acquisition and
display on a Cognex 8200/CVM3 vision processor. Use this class only if you have
specific need for this functionality. The 4200 Video Manager provides the following:
•
Seamless switching of live display to any camera port.
•
Seamless image acquisition while in live display mode.
•
Seamless setting of gain and offset.
•
Default acquisition and display LUTs (lookup tables) range 0 to 255. You can
change the display LUT.
•
Minimal delay for starting live display.
In this case, “seamless” means without having to stop live display and without losing
sync with the display.
Constructors/Destructors
There is only one instance of this class created automatically. To access the single
instance of cc4200VideoMan, use the function videoMan() on page 170.
Public Member Functions
acqFifo
const ccStdGreyAcqFifoPtrh acqFifo();
Returns the 4200 Video Manager’s acquisition FIFO. Use this FIFO only to read property
values. All modifications to the FIFO are made by the member functions of
cc4200VideoMan.
CVL Class Reference
165
cc4200VideoMan
display
ccPtrHandle<ccEmbeddedDisplay> display();
Returns the 4200 Video Manager’s embedded display object. The display’s image
plane LUT is initialized to be the full 0 to 255 range. You can use imageDisplayLut() on
page 167 to change the LUT. The overlay plane LUT is set to provide the Cognex 4200
overlay colors.
startLiveDisplay
bool startLiveDisplay();
Puts the video manager in live display mode.
stopLiveDisplay
void stopLiveDisplay();
Ends live display.
image
ccPelBuffer<c_UInt8> image();
Acquires and image from the 4200 Video Manager. You can acquire images whether
live display is active or not. If the acquisition is unsuccessful, this function returns an
unbound pel buffer.
cameraPort
void cameraPort(c_UInt32 cameraPort);
c_UInt32 cameraPort();
•
void cameraPort(c_UInt32 cameraPort);
Sets the camera port of the acquisition FIFO associated with the 4200 Video Manager.
If live display is active, the change is effective immediately.
Parameters
cameraPort
The camera port.
Notes
The valid range of cameraPort depends on the frame grabber you are using. See
ccCameraPortProp on page 897 to learn how determine the number of available
camera ports.
•
c_UInt32 cameraPort();
Returns the camera port of the acquisition FIFO associated with the 4200 Video
Manager.
166
CVL Class Reference
cc4200VideoMan
gainOffset
void gainOffset(c_UInt8 gain, c_UInt8 offset);
Sets the gain and offset of the acquisition FIFO associated with the 4200 Video Manager.
If live display is active, the change is effective immediately. Gain and offset are stored
as contrast and brightness values in the FIFO’s ccContrastBrightnessProp. This
function is provided to allow you to specify brightness and contrast as gain and offset
for compatibility with the Cognex 4200.
Parameters
gain
offset
gain
The gain of the acquisition. Setting gain to a smaller value
corresponds to a larger gain in the analog section, and thus
corresponds to having a smaller range of input voltages mapped
to final pixel value. To obtain an image with more contrast the
gain should be decreased.
The offset of the acquisition. The value of offset shifts the input
voltage corresponding to the digital output of zero. Thus
increasing offset has the effect of mapping more of the input
voltages to zero, and thus decreases the brightness of the
resulting image.
c_UInt8 gain();
Returns the gain setting of the acquisition FIFO associated with the 4200 Video
Manager.
offset
c_UInt8 offset();
Returns the offset setting of the acquisition FIFO associated with the 4200 Video
Manager.
imageDisplayLut
void imageDisplayLut(const cmStd vector<c_UInt8>& lut);
const cmStd vector<c_UInt8>& imageDisplayLut() const;
•
void imageDisplayLut(const cmStd vector<c_UInt8>& lut);
Sets the image display LUT.
Parameters
lut
CVL Class Reference
The image display lookup table. This table must contain 256
elements.
167
cc4200VideoMan
•
const cmStd vector<c_UInt8>& imageDisplayLut() const;
Gets the image display LUT.
overlayDisplayLut
void overlayDisplayLut(const cmStd vector<ccRGB>& lut);
const cmStd vector<ccRGB>& overlayDisplayLut() const;
•
void overlayDisplayLut(const cmStd vector<ccRGB>& lut);
Sets the overlay display LUT.
Parameters
lut
The overlay display lookup table. This table must contain 15
elements and may contain grey-scale or color ccRGB values.
Notes
Changing the overlay display LUT may have undesired side effects, including the
following:
•
The stock colors defined in <ch_cvl/color.h> may no longer produce the
correct colors on the overlay plane (see ccColor on page 1041).
•
Blinking colors may not work properly.
•
Manipulable shapes may not be visible or may not appear in the proper color.
When changing the overlay display LUT, you should construct ccColor objects
using index values from 1 through 15, which represent an index into the overlay LUT
lut. A ccColor object with an index of zero corresponds to the pass-through value.
Example
cc4200VideoMan& display = cc4200VideoMan::videoMan();
// start live display
display.startLiveDisplay();
cmStd vector<ccRGB> new_lut(15);
#define ckNumColors 16
ccColor *color_index[ckNumColors];
for(c_Int32 i = 0; i < new_lut.size(); ++i) {
new_lut[i] = ccRGB((i+1)*10,(i+1)*10,(i+1)*10);
}
for(c_Int32 i = 0; i < ckNumColors; ++i) {
168
CVL Class Reference
cc4200VideoMan
// index 0 is the pass through color
// indexes 1..15 correspond to entries in the LUT
color_index[i] = new ccColor(i);
}
const cmStd vector<ccRGB>& org_lut =
display.overlayDisplayLut();
for(c_Int32 i = 0; i < org_lut.size(); ++i) {
cmStd cout << "Original LUT" << cmStd endl;
cmStd cout << "
index: " << i
<< " R:" << (c_Int32) org_lut[i].r()
<< " G:" << (c_Int32) org_lut[i].g()
<< " B:" << (c_Int32) org_lut[i].b() << cmStd endl;
}
display.overlayDisplayLut(new_lut);
// give the bt481 time to get setup
ccTimer::sleep(0.250);
// read back the lut again
const cmStd vector<ccRGB>& lut = display.overlayDisplayLut();
for(c_Int32 i = 0; i < lut.size(); ++i) {
cmStd cout << "New LUT" << cmStd endl;
cmStd cout << "
index: " << i
<< " R:" << (c_Int32) lut[i].r()
<< " G:" << (c_Int32) lut[i].g()
<< " B:" << (c_Int32) lut[i].b() << cmStd endl;
}
ccUITablet tablet;
tablet.draw(ccLineSeg(ccPoint(0,0),
ccPoint(640,480)),
*color_index[1],
ccUITablet::eOverlayLayer);
tablet.draw(ccLineSeg(ccPoint(640,0),
ccPoint(0,480)),
*color_index[7],
ccUITablet::eOverlayLayer);
tablet.draw(ccLineSeg(ccPoint(320,0),
ccPoint(320,480)),
*color_index[15],
ccUITablet::eOverlayLayer);
CVL Class Reference
169
cc4200VideoMan
display.display()->drawSketch(tablet.sketch(),
ccDisplay::eImageCoords);
ccTimer::sleep(5);
display.stopLiveDisplay();
for(c_Int32 i = 0; i < ckNumColors; ++i) {
delete color_index[i];
}
// restore with the original lut
display.overlayDisplayLut(org_lut);
•
const cmStd vector<ccRGB>& overlayDisplayLut() const;
Gets the overlay display LUT.
Static Functions
videoMan
static cc4200VideoMan& videoMan();
Returns a reference to the single cc4200VideoMan object. The object is constructed the
first time this function is called. This function cannot be invoked at static initialization
time.
Construction of the cc4200VideoMan object does the following:
videoFormat
•
Puts the vision processor in Cognex 4200 emulation mode. This could take up to
500 ms.
•
Creates an acquisition FIFO with a default input LUT range 0 to 255.
•
Creates an embedded display object with a default image LUT range 0 to 255.
static void videoFormat(const ccStdVideoFormat& vidFmt);
static const ccStdVideoFormat& videoFormat();
•
static void videoFormat(const ccStdVideoFormat& vidFmt);
Sets the video format of the 4200 Video Manager to vidFmt. If an acquisition FIFO and
embedded display object already exist for the single instance of the 4200 Video
Manager, they are deleted and recreated with the new video format.
170
CVL Class Reference
cc4200VideoMan
Parameters
vidFmt
•
The video format. See ccStdVideoFormat on page 2621 or the
file vidfmt.h for a list of implemented video formats. Note that not
all video formats are supported on the Cognex 8200/CVM3
platform.
static const ccStdVideoFormat& videoFormat();
Returns the 4200 Video Manager’s video format. The default is cfXc75_640x480().
shutdown
static void shutdown();
Shuts down the 4200 Video Manager. After calling this function, you may not access the
4200 Video Manager again, nor can you restart the 4200 Video Manager. You should
call this function only when your application shuts down to release memory used by the
video manager.
CVL Class Reference
171
cc4200VideoMan
172
CVL Class Reference
cc8100
#include <ch_cvl/vp8100.h>
typedef cc8100m cc8100;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
The class cc8100 has been superseded by the class cc8100m. The type cc8100 is
provided as a synonym for cc8100m to preserve compatibility with earlier versions of
CVL. See cc8100m on page 195.
CVL Class Reference
173
cc8100
174
CVL Class Reference
cc8100c
#include <ch_cvl/vp8100.h>
class cc8100c : public ccBoard,
public ccFrameGrabber,
public ccParallelIO;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes the Cognex MVS-8100C frame grabber. There is one instance of
this class for each MVS-8100C board in a system. When you write your application you
create the frame grabber object you will use with code similar to the following:
cc8100c& fg = cc8100c::get(i);
In this example, i is the MVS-8100C board number in your system, starting with 0. If you
have only one MVS-8100C in your system i will always be 0. If you have more than one
MVS-8100C board in your system you will need to know the board number you wish to
use so you can code the above line properly.
Note that generally MVS-8100C board 0 is the MVS-8100C board in the lowest
numbered slot. However, this can vary with different motherboard manufacturers and
can be BIOS dependent. You will need to consult your system hardware documentation
to verify the board numbers when you use more than one MVS-8100C in your system.
Constructors/Destructors
The single instance of this class is created automatically.
CVL Class Reference
175
cc8100c
Enumerations
movePartTimingChoice
enum movePartTimingChoice;
This enumeration, used with the movePartTiming() method, specifies whether to use
default or optimum timing for when a move-part callback function executes.
176
Value
Meaning
eDefaultTiming
Execute the move-part callback function at the end of
each image acquistion.
eOptimumTiming
Execute the move-part callback function when
integration of the each acquired image is complete.
Specifically:
•
For an interlaced, full-resolution video format with
strobeEnable(true), the move-part callback
executes at the start of active video of the first field,
about a frame earlier than the default setting.
•
For an interlaced, full-resolution video format with
strobeEnable(false), the callback function
executes at the start of the second field, about a
field earlier than the default.
•
For an interlaced single-field camera format, the
callback function executes at the start of the first
field, about a field earlier than the default.
•
For a progressive scan video format, the callback
function executes at the start of active video of the
full frame, about a frame earlier than the default.
CVL Class Reference
cc8100c
Public Member Functions
movePartTiming
void movePartTiming(movePartTimingChoice timing);
movePartTimingChoice movePartTiming() const;
•
void movePartTiming(movePartTimingChoice timing);
Specifies when a move-part callback function executes for each image acquisition.
(Specify a move-part callback function with movePartCallback(); see
ccMovePartCallbackProp on page 1889.) timing can be eDefaultTiming or
eOptimumTiming, as described in movePartTimingChoice on page 176. The default is
eDefaultTiming.
This ability to specify the function timing applies to both the MVS-8100C and
MVS-8100C/CPCI. See cc8100m on page 195 for a note on which MVS-8100M versions
are affected.
•
movePartTimingChoice movePartTiming() const;
Returns the current move-part timing specification.
inputLine
virtual ccInputLine inputLine(c_Int32 line);
Returns a ccInputLine for the specified logical input line.
Parameters
line
The number of the input line. Line numbering starts at 0. This
value must be between 0 and numInputLines() – 1.
Throws
ccParallelIO::BadParams
line is not between 0 and numInputLines() – 1.
Notes
The Cognex MVS-8100C does not support any input lines controllable with this
function.
outputLine
virtual ccOutputLine outputLine(c_Int32 line);
Returns a ccOutputLine for the specified logical output line.
CVL Class Reference
177
cc8100c
Parameters
line
The number of the output line. Line numbering starts at 0. This
value must be between 0 and numOutputLines() – 1.
Throws
ccParallelIO::BadParams
line is not between 0 and numOutputLines() – 1.
Notes
The Cognex MVS-8100C supports a single status output line.
numInputLines
virtual c_Int32 numInputLines();
Returns the number of input lines for this frame grabber.
numOutputLines
virtual c_Int32 numOutputLines();
Returns the number of output lines for this frame grabber.
getIOConfig
virtual ccIOConfig& getIOConfig() const;
Returns the parallel I/O board configuration.
setIOConfig
virtual void setIOConfig(ccIOConfig& config);
Sets the parallel I/O board configuration. See ccIOConfig and related classes in
ch_cvl/pioconfg.h.
Parameters
config
The I/O board configuration.
Example
This example sets the I/O configuration for an 8100C frame grabber.
cc8100c& fg = cc8100c::get(0);
ccParallelIO* pio = dynamic_cast<ccParallelIO*> (&fg);
pio->setIOConfig(ccIO8100());
Static Functions
count
static c_Int32 count();
Return the number of Cognex MVS-8100C frame grabbers installed.
178
CVL Class Reference
cc8100c
get
static cc8100c& get(c_Int32 i = 0);
Return the ith Cognex MVS-8100C frame grabber installed. Board numbering starts at 0.
Parameters
i
The board number.
Throws
ccBoard::BadParams
i is not in the range 0 through count() – 1.
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8100m, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
CVL Class Reference
179
cc8100c
ccBoard::FpgaLoadFailure
An error occured while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
180
CVL Class Reference
cc8100d
#include <ch_cvl/vp8100d.h>
class cc8100d : public ccBoard,
public ccFrameGrabber,
public ccCogLinkFrameGrabber,
public ccParallelIO;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes the Cognex MVS-8100D frame grabber. There is one instance of
this class for each MVS-8100D board in a system. When you write your application you
create the frame grabber object you will use with code similar to the following:
cc8100d& fg = cc8100d::get(i);
In this example, i is the MVS-8100D board number in your system, starting with 0. If you
have only one MVS-8100D in your system i will always be 0. If you have more than one
MVS-8100D board in your system you will need to know the board number you wish to
use so you can code the above line properly.
Generally, MVS-8100D board 0 is the MVS-8100D board in the lower numbered PCI slot.
However, this can vary with different motherboard manufacturers, and can be BIOS
dependent. Consult your system hardware documentation to verify the system’s PCI slot
numbering system when you use more than one MVS-8100D in your system.
Constructors/Destructors
A single instance of this class is created automatically for each MVS-8100D installed in
your system.
Public Member Functions
inputLine
virtual ccInputLine inputLine(c_Int32 line);
Returns a ccInputLine object that represents the specified logical input line.
This is an override from class ccParallelIO.
CVL Class Reference
181
cc8100d
Parameters
line
The logical line number. line must be a valid value for the
configuration set by setIOConfig().
Notes
The MVS-8100D provides eight or twelve bidirectional TTL lines, depending on
model. On other Cognex frame grabber families, the input or output direction of all
bidirectional lines are set as a group. By contrast, on the MVS-8100D, each line can
be independently enabled as an input or output line using ccOutputLine::enable()
or ccInputLine::enable().
The MVS-8100D’s parallel I/O lines have two connection options. They can be used
as TTL lines or can be connected to the Cognex external I/O module where the TTL
signals are converted to opto-isolated line pairs. The TTL and opto-isolated
connection options are described in the MVS-8100D and CDC Cameras Hardware
Manual. Consult that manual for the correspondence between the signal names
used in the tables below and the pin numbers to which you connect device wiring.
The following table shows the logical line numbers for the TTL connection option for
the MVS-8100D models, when each bidirectional line is configured as an input line.
182
inputLine
line
parameter
Signal name
on
MVS-8100D1
Signal name on
MVS-8100D2 and
MVS-8100D3
0
TTL_BI_1
TTL_BI_1
Bidirectional line,
controls any TTL input
device when this line is
enabled for input
1
TTL_BI_2
TTL_BI_2
Bidirectional, as above
2
TTL_BI_3
TTL_BI_3
Bidirectional, as above
3
TTL_BI_4
TTL_BI_4
Bidirectional, as above
4
TTL_BI_5
TTL_BI_5
Bidirectional, as above
5
TTL_BI_6
TTL_BI_6
Bidirectional, as above
6
TTL_BI_7
TTL_BI_7
Bidirectional, as above
7
TTL_BI_8
TTL_BI_8
Bidirectional, as above
8
Not available
TTL_BI_9
Bidirectional, as above
9
Not available
TTL_BI_10
Bidirectional, as above
Device Connection
CVL Class Reference
cc8100d
inputLine
line
parameter
Signal name
on
MVS-8100D1
Signal name on
MVS-8100D2 and
MVS-8100D3
Device Connection
10
Not available
TTL_BI_11
Bidirectional, as above
11
Not available
TTL_BI_12
Bidirectional, as above
The following table shows the logical line numbers for MVS-8100D input lines when
using the opto-isolated connection option and the external I/O module.
outputLine
inputLine
line parameter
Ext I/O module signal
with MVS-8100D1
Ext I/O module signal with
MVS-8100D2 and MVS-8100D3
0
IN_0±
IN_0±
1
IN_1±
IN_1±
10
Not available
IN_2±
11
Not available
IN_3±
virtual ccOutputLine outputLine(c_Int32 line);
Returns a ccOutputLine object that represents the specified logical output line.
This is an override from class ccParallelIO.
Parameters
line
CVL Class Reference
The logical line. line must be a valid value for the configuration set
by setIOConfig().
183
cc8100d
Notes
See the Notes above for inputLine(). Consult the MVS-8100D and CDC Cameras
Hardware Manual for the correspondence between the signal names used in the
tables below and the pin numbers to which you connect device wiring.
The following table shows the logical line numbers for the TTL connection option for
the MVS-8100D models, when each bidirectional line is configured as an output
line.
outputLine
line
parameter
Signal name
on
MVS-8100D1
Signal name on
MVS-8100D2 and
MVS-8100D3
0
TTL_BI_1
TTL_BI_1
Bidirectional line,
controls any TTL output
device when this line is
enabled for output
1
TTL_BI_2
TTL_BI_2
Bidirectional, as above
2
TTL_BI_3
TTL_BI_3
Bidirectional, as above
3
TTL_BI_4
TTL_BI_4
Bidirectional, as above
4
TTL_BI_5
TTL_BI_5
Bidirectional, as above
5
TTL_BI_6
TTL_BI_6
Bidirectional, as above
6
TTL_BI_7
TTL_BI_7
Bidirectional, as above
7
TTL_BI_8
TTL_BI_8
Bidirectional, as above
8
Not available
TTL_BI_9
Bidirectional, as above
9
Not available
TTL_BI_10
Bidirectional, as above
10
Not available
TTL_BI_11
Bidirectional, as above
11
Not available
TTL_BI_12
Bidirectional, as above
Device Connection
The following table shows the logical line numbers for MVS-8100D output lines
when using the opto-isolated connection option and the external I/O module.
184
outputLine
line parameter
Ext I/O module signal
with MVS-8100D1
Ext I/O module signal with
MVS-8100D2 and MVS-8100D3
0
Not used
Not used
1
Not used
Not used
CVL Class Reference
cc8100d
outputLine
line parameter
Ext I/O module signal
with MVS-8100D1
Ext I/O module signal with
MVS-8100D2 and MVS-8100D3
2
OUT_0±
OUT_0±
3
OUT_1±
OUT_1±
4
OUT_2±
OUT_2±
5
OUT_3±
OUT_3±
6
OUT_4±
OUT_4±
7
OUT_5±
OUT_5±
8
Not available
OUT_6±
9
Not available
OUT_7±
numInputLines
virtual c_Int32 numInputLines() const;
Returns the number of total input lines for this hardware. The total depends upon the
configuration set by setIOConfig().
This is an override from class ccParallelIO.
numOutputLines
virtual c_Int32 numOutputLines() const;
Returns the number of total output lines for this hardware.
This is an override from class ccParallelIO.
getIOConfig
virtual ccIOConfig& getIOConfig() const;
Returns the parallel I/O board configuration.
This is an override from class ccParallelIO.
setIOConfig
virtual void setIOConfig(ccIOConfig& config);
Sets the parallel I/O board configuration. See ccIOConfig and its derived classes, as
discussed in ccIOConfig on page 1771 and in ch_cvl/pioconfg.h.
This is an override from class ccParallelIO.
CVL Class Reference
185
cc8100d
Parameters
config
The I/O board configuration.
Example
This example sets the I/O configuration for a single channel MVS-8100D frame
grabber connected to the Cognex external I/O module.
cc8100d& fg = cc8100d::get(0);
ccParallelIO* pio = dynamic_cast<ccParallelIO*> (&fg);
pio-> setIOConfig(ccIOSingleChannelExternal8100d());
Notes
There are four classes derived from ccIOConfig that can be used as arguments to
setIOConfig() for the MVS-8100D:
ccIOSingleChannel8100d
ccIOMultiChannel8100d
ccIOSingleChannelExternal8100d
ccIOMultiChannelExternal8100d
If you are using the Cognex external I/O module, you must specify the appropriate
class for your MVS-8100D from the third and fourth classes in this list. If you are
using the 8100D’s bidirectional TTL hookup option, specify one of the first and
second classes.
deviceName
virtual ccCvlString deviceName() const;
Returns the name of this device.
This is an override from classes ccCogDevice and ccBoard.
numCogLinkChans
virtual c_Int32 numCogLinkChans() const;
Returns the number of channels this frame grabber supports.
This is an override from class ccCogLinkChanSet.
cogLinkChan
virtual const ccCogLinkDevice* cogLinkChan(
c_Int32 chanNum) const;
Returns a pointer to the device connected to the given channel (chanNum). If there is
no device connected to the given channel, or if the channel number is out of range, a
null pointer is returned.
This is an override from class ccCogLinkChanSet.
186
CVL Class Reference
cc8100d
Parameters
chanNum
The specified channel number.
Static Functions
count
static c_Int32 count();
Returns the number of Cognex MVS-8100D frame grabbers installed in the system.
get
static cc8100d& get(c_Int32 i);
Returns the cc8100d object associated with the Cognex MVS-8100D frame grabber
whose index is i. Index numbers begin with 0. See the introduction to this reference page
for additional information.
Parameters
i
The Cognex MVS-8100D board index.
Throws
ccCogLinkFrameGrabber::BadParams
If i is not a valid index.
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
CVL Class Reference
187
cc8100d
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8100m, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
ccBoard::FpgaLoadFailure
An error occured while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
188
CVL Class Reference
cc8100l
#include <ch_cvl/vp8100l.h>
class cc8100l : public ccBoard, public ccFrameGrabber,
public ccParallelIO;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes the Cognex MVS-8100L frame grabber. There is one instance of
this class for each MVS-8100L board in a system. When you write your application you
create the frame grabber object you will use with code similar to the following:
cc8100l& fg = cc8100l::get(i);
In this example, i is the MVS-8100L board number in your system, starting with 0. If you
have only one MVS-8100L in your system i will always be 0. If you have more than one
MVS-8100L board in your system you will need to know the board number you wish to
use so you can code the above line properly.
Note that generally MVS-8100L board 0 is the MVS-8100L board in the lowest numbered
slot. However, this can vary with different mother board manufacturers and can be BIOS
dependent. You will need to consult your system hardware documentation to verify the
board numbers when you use more than one MVS-8100L in your system.
Constructors/Destructors
The single instance of this class is created automatically.
CVL Class Reference
189
cc8100l
Public Member Functions
ADCReferenceVoltage
void ADCReferenceVoltage(double adcref);
double ADCReferenceVoltage() const;
This function controls the positive reference voltage (REFP) input to the BT878A A/D.
This voltage sets the top of reference ladder for the video A/Ds, affecting things beyond
just the digitized levels.
All voltage levels will not work correctly. High reference voltages have been observed
to prevent the BT878A from locking to the video signal (default reference voltage =
0.52549).
Note
CVL 5.5.3 had a number of problems that affected the quality of images acquired from
MVS-8100L frame grabbers, including the following:
•
Dark pixels in the leftmost column of images captured from RS-170 cameras
•
Dark pixels in the next to last rightmost column of images captured from some CCIR
cameras
•
For most cameras, loss of dynamic range caused by an incorrect default ADC
reference voltage setting
•
CCIR image brightness 10 grey levels higher than expected
Changes to the MVS-8100L image acquisition code introduced in CVL 6.0 fix the first
three of these problems. The changes involved adjusting the digitizer offset and pixel
aspect ratio to fix the dark pixel column problems, and changing the default ADC
reference voltage setting to fix the loss of dynamic range problem.
To fix the CCIR image brightness problem, adjust the brightness property in your CVL
application code to reduce the grey level.
The new settings will cause images captured using CVL 6.0 to be slightly different from
those captured using CVL 5.5.3. To retain exact backward compatibility with CVL 5.5.3,
use the cc8100l::ADCReferenceVoltage() function, passing
cc8100l::defaultADCReferenceVoltage, which specifies the CVL 5.5.3 default value,
as an argument. This function will always cause the MVS-8100L acquisition to revert to
CVL 5.5.3 settings, with any value argument. Always call the
cc8100l::ADCReferenceVoltage() function before creating an acquisition FIFO.
You can use the cc8100l::ADCReferenceVoltage() function either with a cc8100l
object directly (see scenario 1, below), or with generic ccBoard or ccFrameGrabber
objects (see scenario 2, below):
190
CVL Class Reference
cc8100l
Scenario 1: If your application uses a cc8100l object (for example, named fg8100l)
directly, add the following code when fg8100l is a pointer:
fg8100l->ADCReferenceVoltage(
cc8100l::defaultADCReferenceVoltage);
Add the following code when fg8100l is a reference:
fg8100l.ADCReferenceVoltage(
cc8100l::defaultADCReferenceVoltage);
Scenario 2: If your application uses a generic ccBoard or ccFrameGrabber object (for
example, named myBoard), add the following code when myBoard is a pointer:
cc8100l *fg8100l = dynamic_cast<cc8100l*>(myBoard);
if(fg8100l)
fg8100l->ADCReferenceVoltage(
cc8100l::defaultADCReferenceVoltage);
Add the following code when myBoard is a reference:
cc8100l* fg8100l = dynamic_cast<cc8100l*>(&myBoard);
if(fg8100l)
fg8100l->ADCReferenceVoltage(
cc8100l::defaultADCReferenceVoltage);
For the second scenario, you must also explicitly include the header file
<ch_cvl/vp8100l.h> to have the MVS-8100L reference voltage function and default
value definitions required for compilation.
•
void ADCReferenceVoltage(double adcref);
Sets the BT878A A/D reference voltage. A value of 0.0 sets the reference voltage to its
minimum value, and a value of 1.0 sets the reference voltage to its maximum value.
Parameters
adcref
The new reference voltage.
Throws
ccParallelIO::BadParams
If adcref is not in the range 0 - 1.0.
•
double ADCReferenceVoltage() const;
Returns the A/D reference voltage.
CVL Class Reference
191
cc8100l
inputLine
virtual ccInputLine inputLine(c_Int32 line);
Returns a ccInputLine for the specified logical input line.
This is an override. See class ccParallelIO.
Parameters
line
The number of the input line. Line numbering starts at 0. This
value must be a valid line number.
Throws
ccParallelIO::BadParams
line is not between 0 and numInputLines() – 1.
Notes
The Cognex MVS-8100L does not support any input lines controllable with this
function.
outputLine
virtual ccOutputLine outputLine(c_Int32 line);
Returns a ccOutputLine for the specified logical output line.
This is an override. See class ccParallelIO.
Parameters
line
The number of the output line. Line numbering starts at 0. This
value must be between 0 and numOutputLines() – 1.
Throws
ccParallelIO::BadParams
line is not between 0 and numOutputLines() – 1.
Notes
The Cognex MVS-8100L supports a single status output line.
numInputLines
virtual c_Int32 numInputLines();
Returns the number of input lines for this frame grabber.
This is an override. See class ccParallelIO.
numOutputLines
virtual c_Int32 numOutputLines();
Returns the number of output lines for this frame grabber.
This is an override. See class ccParallelIO.
192
CVL Class Reference
cc8100l
getIOConfig
virtual ccIOConfig& getIOConfig() const;
Returns the parallel I/O board configuration.
This is an override. See class ccParallelIO.
setIOConfig
virtual void setIOConfig(ccIOConfig& config);
Sets the parallel I/O board configuration. See ccIOConfig and related classes in
ch_cvl/pioconfg.h.
This is an override. See class ccParallelIO.
Parameters
config
The I/O board configuration.
Example
This example sets the I/O configuration for an 8100L frame grabber.
cc8100l& fg = cc8100l::get(0);
ccParallelIO* pio = dynamic_cast<ccParallelIO*> (&fg);
pio-> setIOConfig(ccIO8100());
Static Functions
count
static c_Int32 count();
Returns the number of Cognex MVS-8100L frame grabbers installed.
get
static cc8100l& get(c_Int32 i = 0);
Return the ith Cognex MVS-8100L frame grabber installed. Board numbering starts at 0.
Parameters
i
The board number.
Throws
ccBoard::BadParams
i is not in the range 0 through count() – 1.
Constants
defaultADCReferenceVoltage
static const double defaultADCReferenceVoltage;
Default = 0.52549.
CVL Class Reference
193
cc8100l
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8100m, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
ccBoard::FpgaLoadFailure
An error occured while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
194
CVL Class Reference
cc8100m
#include <ch_cvl/vp8100.h>
class cc8100m : public ccBoard,
public ccFrameGrabber,
public ccParallelIO;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes the Cognex MVS-8100M frame grabber. There is one instance of
this class for each MVS-8100M board in a system. When you write your application you
create the frame grabber object you will use with code similar to the following:
cc8100m& fg = cc8100m::get(i);
In this example, i is the MVS-8100M board number in your system, starting with 0. If you
have only one MVS-8100M in your system i will always be 0. If you have more than one
MVS-8100M board in your system you will need to know the board number you wish to
use so you can code the above line properly.
Note that generally MVS-8100M board 0 is the MVS-8100M board in the lowest
numbered slot. However, this can vary with different motherboard manufacturers and
can be BIOS dependent. You will need to consult your system hardware documentation
to verify the board numbers when you use more than one MVS-8100M in your system.
Constructors/Destructors
The single instance of this class is created automatically.
CVL Class Reference
195
cc8100m
Enumerations
shiftChoice
enum shiftChoice;
This enumeration, used with the horizontalImageShift() method, specifies whether to
shift the acquired image to the right to compensate for a side effect of the newer video
front end filter used on the MVS-8100M Style B or MVS-8100M+ frame grabber.
Value
Meaning
eNone
Do not shift the image.
eCompensateFilterShift
Shift the acquired image two pixels to the right to
compensate for the side effect of the newer video front
end filter.
movePartTimingChoice
enum movePartTimingChoice;
This enumeration, used with the movePartTiming() method, specifies whether to use
default or optimum timing for when a move-part callback function executes.
196
Value
Meaning
eDefaultTiming
Execute the move-part callback function at the end of
each image acquistion.
eOptimumTiming
Execute the move-part callback function when
integration of the each acquired image is complete.
Specifically:
•
For an interlaced, full-resolution video format with
strobeEnable(true), the move-part callback
executes at the start of active video of the first field,
about a frame earlier than the default setting.
•
For an interlaced, full-resolution video format with
strobeEnable(false), the callback function
executes at the start of the second field, about a
field earlier than the default.
•
For an interlaced single-field camera format, the
callback function executes at the start of the first
field, about a field earlier than the default.
•
For a progressive scan video format, the callback
function executes at the start of active video of the
full frame, about a frame earlier than the default.
CVL Class Reference
cc8100m
Public Member Functions
horizontalImageShift
void horizontalImageShift(shiftChoice shift);
shiftChoice horizontalImageShift() const;
•
void horizontalImageShift(shiftChoice shift);
Enable or disable a horizontal image shift two pixels to the right, to compensate for a
side effect of the video front end filter optionally used with MVS-8100M style B and
MVS-8100M+.
Parameters
shift
Specifies whether to shift the image. Must be one of the following
values:
cc8100m::eNone (default)
cc8100m::eCompensateFilterShift
Notes
Compensation is necessary only when the newer video front end filter is used (that
is, when jumpers JP16 and JP17 are in position 2-3) on MVS-8100M Style B or
MVS-8100M+ frame grabbers. The compensation is applied only to acquisition
FIFOs created after the compensation is enabled or altered.
Enabling this image shift may cause black or grey columns to appear at the extreme
left side of the image under the following circumstances:
•
•
On MVS-8100M Style B or MVS-8100M+, with JP16 and JP17 in postions 1-2
•
On the original MVS-8100 or MVS-8100M Style A at all times
shiftChoice horizontalImageShift();
Retrieves whether images are shifted two pixels to the right to compensate for a side
effect of the newer video front end filter. There is no shift compensation if the return
enumeration is cc8100m::eNone.
CVL Class Reference
197
cc8100m
movePartTiming
void movePartTiming(movePartTimingChoice timing);
movePartTimingChoice movePartTiming() const;
•
void movePartTiming(movePartTimingChoice timing);
Specifies when a move-part callback function executes for each image acquisition.
(Specify a move-part callback function with movePartCallback(); see
ccMovePartCallbackProp on page 1889.) timing can be eDefaultTiming or
eOptimumTiming, as described in movePartTimingChoice on page 196. The default is
eDefaultTiming.
This ability to specify the function timing applies to the MVS-8100M, MVS-8100C, and
MVS-8100C/CPCI, but is not applicable to the MVS-8100M+ when using a CCF-based
video format.
•
movePartTimingChoice movePartTiming() const;
Returns the current move-part timing specification.
inputLine
virtual ccInputLine inputLine(c_Int32 line);
Returns a ccInputLine for the specified logical input line.
Parameters
line
The number of the input line. Line numbering starts at 0. This
value must be between 0 and numInputLines() – 1.
Throws
ccParallelIO::BadParams
line is not between 0 and numInputLines() – 1.
Notes
The Cognex MVS-8100M does not support any input lines controllable with this
function.
outputLine
virtual ccOutputLine outputLine(c_Int32 line);
Returns a ccOutputLine for the specified logical output line.
Parameters
line
198
The number of the output line. Line numbering starts at 0. This
value must be between 0 and numOutputLines() – 1.
CVL Class Reference
cc8100m
Throws
ccParallelIO::BadParams
line is not between 0 and numOutputLines() – 1.
Notes
The Cognex MVS-8100M supports a single status output line.
numInputLines
virtual c_Int32 numInputLines();
Returns the number of input lines for this frame grabber.
numOutputLines
virtual c_Int32 numOutputLines();
Returns the number of output lines for this frame grabber.
getIOConfig
virtual ccIOConfig& getIOConfig() const;
Returns the parallel I/O board configuration.
setIOConfig
virtual void setIOConfig(ccIOConfig& config);
Sets the parallel I/O board configuration. See ccIOConfig and related classes in
ch_cvl/pioconfg.h.
Parameters
config
The I/O board configuration.
Example
This example sets the I/O configuration for an 8100 frame grabber.
cc8100m& fg = cc8100m::get(0);
ccParallelIO* pio = dynamic_cast<ccParallelIO*> (&fg);
pio-> setIOConfig(ccIO8100());
Static Functions
count
static c_Int32 count();
Returns the number of Cognex MVS-8100M frame grabbers installed.
get
static cc8100m& get(c_Int32 i = 0);
Return the ith Cognex MVS-8100M frame grabber installed. Board numbering starts at
0.
CVL Class Reference
199
cc8100m
Parameters
i
The board number.
Throws
ccBoard::BadParams
i is not in the range 0 through count() – 1.
Typedefs
cc8100
typedef cc8100m cc8100;
The type cc8100 is a synonym for cc8100m to preserve compatibility with earlier
versions of CVL.
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8100m, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
200
CVL Class Reference
cc8100m
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
ccBoard::FpgaLoadFailure
An error occured while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
CVL Class Reference
201
cc8100m
202
CVL Class Reference
cc8120
#include <ch_cvl/vp8120.h>
class cc8120 : public ccBoard,
public ccFrameGrabber,
public ccParallelIO;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes the Cognex MVS-8120 frame grabber. There is one instance of this
class for each MVS-8120 board in a system. When you write your application you create
the frame grabber object you will use with code similar to the following:
cc8120& fg = cc8120::get(i);
In this example, i is the MVS-8120 board number in your system, starting with 0. If you
have only one MVS-8120 in your system i will always be 0. If you have more than one
MVS-8120 board in your system you will need to know the board number you wish to use
so you can code the above line properly.
Note that generally MVS-8120 board 0 is the MVS-8120 board in the lowest numbered
slot. However, this can vary with different motherboard manufacturers and can be BIOS
dependent. You will need to consult your system hardware documentation to verify the
board numbers when you use more than one MVS-8120 in your system.
The MVS-8120 frame grabber provides a low latency mode that transfers images
directly from the frame grabber to system memory as the acquisition is taking place.
Under normal acquisition (with low latency mode disabled), an image is acquired into
frame grabber memory and is not transferred to system memory until the acquisition
FIFO’s complete() function is called. When low latency mode is enabled, the image is
transferred from frame grabber memory to system memory as the acquisition takes
place.
Under low latency mode, the system memory is actually a memory pool shared by all
the processes that use an MVS-8120 frame grabber. You can use sizePelPool() on
page 214 to specify the size of the memory pool, but you must do so before any other
CVL-based program runs. You can use allImagesInPool() on page 215 to specify
whether all acquired images should use the shared pool or only the ones acquired under
low latency mode. In most cases, using the shared image memory pool is more efficient
CVL Class Reference
203
cc8120
because it separates the MVS-8120’s image memory requirements from your
application’s memory requirements, and because the share image memory pool is
optimized for acquiring images.
Note that low latency mode is available only on the MVS-8210 with a CVM4 which can
acquire from only one camera at a time. Although you can enable low latency mode on
more than one camera port, there is no overlapped use of this mode on multiple
cameras.
Although low latency mode results in performance improvements for most applications,
you should not use it if you are using a region of interest (ccRoiProp), if you are using
live display, or if you need to set the makeLocal parameter to complete() to false.
Enumerations
enum {ckAllPorts = -1};
Constructors/Destructors
A single instance of this class is created automatically for each MVS-8120 installed in
your system.
Public Member Functions
lowLatency
void lowLatency(bool enabled, c_Int32 camPort);
bool lowLatency(c_Int32 camPort) const;
See the introductory comments to this reference page for a description of low latency
mode.
•
void lowLatency(bool enabled, c_Int32 camPort);
Enables or disables low latency mode for the specified camera port.
To use low latency mode with automatic triggering, you must set up low latency mode
before setting up and enabling triggers.
Parameters
enabled
camPort
204
True to enable low latency mode; false to disable it.
The camera port on which to enable or disable low latency mode.
The special value ckAllPorts sets low latency mode for all camera
ports.
CVL Class Reference
cc8120
•
bool lowLatency(c_Int32 camPort) const;
Returns true if low latency mode is enabled for the specified camera port, or false if it is
not.
Parameters
camPort
The camera port to query for low latency mode.
Notes
If you specify the special value ckAllPorts, this function returns true only if low
latency mode is enabled for all ports.
inputLine
virtual ccInputLine inputLine(c_Int32 line);
Returns a ccInputLine object for the specified logical input line.
Parameters
line
The number of the input line. Line numbering starts at 0. This
value must be a valid line number for the parallel I/O board option
that is installed. See Notes that follow.
Throws
ccParallelIO::BadParams
line is not a valid line number for your frame grabber or vision
processor.
Notes
The correspondence between logical line numbers that you supply as a parameter
to ccInputLine and the associated signal name on Cognex parallel I/O boards is
shown in the tables that follow.
For the parallel I/O boards used with the 8120 (and 8110 and 82400/PCI), all of the
bidirectional lines must be used together as input lines or as output lines. You
cannot configure some bidirectional lines as input lines and others as output lines.
Calling ccOutputLine::enable() or ccInputLine::enable() on any bidirectional line
sets the direction for all bidirectional lines.
Four input lines, TTL_IN_5 through TTL_IN_8, can be used as hardware trigger lines
without software intervention. If you are using these lines as hardware trigger lines,
do not use them at the same time as ccInputLine objects under software control.
For more information on the use of hardware trigger lines, see the hardware manual
for your frame grabber or vision processor.
CVL Class Reference
205
cc8120
inputLine line Parameter for Standard UPIO or ISA PIO Boards
The following table shows the logical line numbers for input lines when using the
universal parallel I/O (UPIO) board in its standard configuration, or when using the
ISA-based TTL or OPTO/TTL parallel I/O (PIO) boards. Use your Cognex hardware
manual to map the signal names in this table to the pin numbers of the parallel I/O
board and cable you are using.
206
inputLine line
parameter
Signal Name
Device Connection
0
TTL_IN_1
Any TTL input
1
TTL_IN_2
Any TTL input
2
TTL_IN_3
Any TTL input
3
TTL_IN_4
Any TTL input
4
TTL_IN_5
Hardware trigger 1 or any TTL input
5
TTL_IN_6
Hardware trigger 2 or any TTL input
6
TTL_IN_7
Hardware trigger 3 or any TTL input
7
TTL_IN_8
Hardware trigger 4 or any TTL input
8
TTL_BI_1
Bidirectional line, controls any TTL input
device when all bidirectional lines are
enabled for input
9
TTL_BI_2
Bidirectional, as above
10
TTL_BI_3
Bidirectional, as above
11
TTL_BI_4
Bidirectional, as above
12
TTL_BI_5
Bidirectional, as above
13
TTL_BI_6
Bidirectional, as above
14
TTL_BI_7
Bidirectional, as above
15
TTL_BI_8
Bidirectional, as above
CVL Class Reference
cc8120
inputLine line Parameter for Light Control UPIO Boards
The following table shows the logical line numbers for input lines when using the
universal parallel I/O board in its light control configuration. This board option has
a jumper, J2, that determines whether the hardware trigger lines are TTL or
opto-isolated. Use your Cognex hardware manual to map the signal names in this
table to the pin numbers of the cables to which you connect device wiring.
Note that, when using the light control option board, four bidirectional lines are
remapped for light control. The other four bidirectional lines, TTL_BI_5 through
TTL_BI_8, are no longer bidirectional, and are not controllable as input lines.
When J2 = TTL Trig
Signal
Name
Device
Connection
Signal
Name
Device Connection
0
OPTO_IN1
(from
TTL_IN_1)
Any opto-isolated
input
TTL_IN_1
Any TTL input
1
OPTO_IN2
(from
TTL_IN_2)
Any opto-isolated
input
TTL_IN_2
Any TTL input
2
OPTO_IN3
(from
TTL_IN_3)
Any opto-isolated
input
TTL_IN_3
Any TTL input
3
OPTO_IN4
(from
TTL_IN_4)
Any opto-isolated
input
TTL_IN_4
Any TTL input
4
TTL_IN_5
Hardware trigger 1
or any TTL input
OPTO_IN1
(from
TTL_IN_5)
Opto-isolated
hardware trigger 1 or
any opto-isolated input
5
TTL_IN_6
Hardware trigger 2
or any TTL input
OPTO_IN2
(from
TTL_IN_6)
Opto-isolated
hardware trigger 2 or
any opto-isolated input
6
TTL_IN_7
Hardware trigger 3
or any TTL input
OPTO_IN3
(from
TTL_IN_7)
Opto-isolated
hardware trigger 3 or
any opto-isolated input
7
TTL_IN_8
Hardware trigger 4
or any TTL input
OPTO_IN4
(from
TTL_IN_8)
Opto-isolated
hardware trigger 4 or
any opto-isolated input
line
CVL Class Reference
When J2 = OPTO Trig
207
cc8120
inputLine line Parameter for External UPIO Boards
The following table shows the logical line numbers for input lines when using the
universal parallel I/O board in its external configuration. The external option board
must be used with the Cognex external I/O module. Together, the board and
module supply opto-isolated inputs.
Note that, when using the external option board, the eight bidirectional lines
TTL_BI_1 through TTL_BI_8 are no longer bidirectional, and are not controllable as
input lines.
outputLine
inputLine
line parameter
Connection on
External I/O Module
Device Connection
0
IN_0±
Any opto-isolated input
1
IN_1±
Any opto-isolated input
2
IN_2±
Any opto-isolated input
3
IN_3±
Any opto-isolated input
4
IN_4±
Opto-isolated hardware trigger 1
or any opto-isolated input
5
IN_5±
Opto-isolated hardware trigger 2
or any opto-isolated input
6
IN_6±
Opto-isolated hardware trigger 3
or any opto-isolated input
7
IN_7±
Opto-isolated hardware trigger 4
or any opto-isolated input
virtual ccOutputLine outputLine(c_Int32 line);
Returns a ccOutputLine object for the specified logical output line.
Parameters
line
The number of the output line. Line numbering starts at 0. This
value must be a valid line number for the installed I/O board
option. See the Notes section below.
Throws
ccParallelIO::BadParams
line is not a valid line number for your frame grabber or vision
processor.
208
CVL Class Reference
cc8120
Notes
The correspondence between logical line numbers that you supply as a parameter
to ccOutputLine and the associated signal name on Cognex parallel I/O boards is
shown in the tables that follow.
For the parallel I/O boards used with the 8120 (and 8110 and 82400/PCI), all of the
bidirectional lines must be used together as input lines or as output lines. You
cannot configure some bidirectional lines as input lines and others as output lines.
Calling ccOutputLine::enable() or ccInputLine::enable() on any bidirectional line
sets the direction for all bidirectional lines.
Four opto-isolated output line pairs, OPTO_OUT1+/– through OPTO_OUT4+/–, can
be used as hardware strobe lines without software intervention. If you are using
these lines as hardware strobe lines, do not try to use them at the same time as
ccOutputLine objects under software control. For more information on the use of
hardware strobe lines, see the hardware manual for your frame grabber or vision
processor.
You can set any output line to true or false using ccOutputLine::set. For TTL
output or TTL bidirectional lines, true means TTL high (+5V). For opto-isolated lines,
true enables the no-current-flowing state (the LED inside the opto-isolator is OFF,
and thus the circuit is open). For opto-isolated lines, false sets the current-flowing
state (the LED inside the opto-isolator is ON, thus the circuit is closed). Refer to the
circuit diagram for opto-isolated parallel I/O lines in the hardware manual for your
vision processor.
outputLine line Parameter for Standard UPIO or ISA PIO Boards
The following table shows the logical line numbers for output lines when using the
universal parallel I/O (UPIO) board in its standard configuration, or when using the
ISA-based TTL or OPTO/TTL parallel I/O (PIO) boards. Use your Cognex hardware
manual to map the signal names in this table to the pin numbers of the parallel I/O
board and cable you are using.
CVL Class Reference
outputLine
line Parameter
Signal Name
Device Connection
0
TTL_OUT_1
Any TTL output
1
TTL_OUT_2
Any TTL output
2
TTL_OUT_3
Any TTL output
3
TTL_OUT_4
Any TTL output
4
TTL_OUT_5
Any TTL output
5
TTL_OUT_6
Any TTL output
209
cc8120
outputLine
line Parameter
Signal Name
Device Connection
6
TTL_OUT_7
Any TTL output
7
TTL_OUT_8
Any TTL output
8
TTL_BI_1
Bidirectional line, controls any TTL
output device when all bidirectional lines
are enabled for output
9
TTL_BI_ 2
Bidirectional, as above
10
TTL_BI_ 3
Bidirectional, as above
11
TTL_BI_ 4
Bidirectional, as above
12
TTL_BI_ 5
Bidirectional, as above
13
TTL_BI_ 6
Bidirectional, as above
14
TTL_BI_ 7
Bidirectional, as above
15
TTL_BI_ 8
Bidirectional, as above
16
OPTO_OUT1±
Any opto-isolated output device, when
not using a hardware-fired strobe on this
line
17
OPTO_OUT2±
Any opto-isolated output device, as
above
18
OPTO_OUT3±
Any opto-isolated output device, as
above
19
OPTO_OUT4±
Any opto-isolated output device, as
above
outputLine line Parameter for Light Control UPIO Boards
The following table shows the logical line numbers for output lines when using the
universal parallel I/O board in its light control configuration. Use your Cognex
hardware manual to map the signal names in this table to the pin numbers of the
cables to which you connect device wiring.
210
CVL Class Reference
cc8120
Note that, when using the light control option board, four bidirectional lines are
remapped for light control. The other four bidirectional lines, TTL_BI_5 through
TTL_BI_8, are no longer bidirectional, and are controllable only as output lines.
outputLine
line Parameter
Signal Name
Device Connection
12
TTL_BI_ 5
Bidirectional line, controls any TTL
output device when all bidirectional
lines are enabled for output
13
TTL_BI_ 6
Bidirectional, as above
14
TTL_BI_ 7
Bidirectional, as above
15
TTL_BI_ 8
Bidirectional, as above
16
OPTO_OUT1±
Any opto-isolated output device, when
not using a hardware-fired strobe on
this line
17
OPTO_OUT2±
Any opto-isolated output device, as
above
18
OPTO_OUT3±
Any opto-isolated output device, as
above
19
OPTO_OUT4±
Any opto-isolated output device, as
above
outputLine line Parameter for External UPIO Boards
The following table shows the logical line numbers for output lines when using the
universal parallel I/O board in its external configuration. The external option board
must be used with the Cognex external I/O module. Together, the board and
module supply eight opto-isolated output line pairs. In addition to the opto lines on
the external I/O module, the external option board also supplies twelve TTL lines
used as output lines, connected through a cable. Use your Cognex hardware
manual to map the signal names in this table to the pin numbers of the module
and/or cable to which you connect device wiring.
CVL Class Reference
211
cc8120
Note that, when using the external option board, the eight bidirectional lines
TTL_BI_1 through TTL_BI_8 are no longer bidirectional, and are controllable only as
output lines.
212
line
Signal Name
Connects to
Device Connection
0
TTL_OUT_1
Cable
Any TTL output
1
TTL_OUT_2
Cable
Any TTL output
2
TTL_OUT_3
Cable
Any TTL output
3
TTL_OUT_4
Cable
Any TTL output
4
TTL_OUT_5
Cable
Any TTL output
5
TTL_OUT_6
Cable
Any TTL output
6
TTL_OUT_7
Cable
Any TTL output
7
TTL_OUT_8
Cable
Any TTL output
8
TTL_BI_1
Cable
Bidirectional line, controls any
TTL output device when all
bidirectional lines are enabled
for output
9
TTL_BI_2
Cable
Bidirectional, as above
10
TTL_BI_3
Cable
Bidirectional, as above
11
TTL_BI_4
Cable
Bidirectional, as above
12
TTL_BI_5
Ext. I/O module
Bidirectional, as above
13
TTL_BI_6
Ext. I/O module
Bidirectional, as above
14
TTL_BI_7
Ext. I/O module
Bidirectional, as above
15
TTL_BI_8
Ext. I/O module
Bidirectional, as above
16
OPTO_OUT1±
Ext. I/O module
Any opto-isolated output device,
when not using a hardware-fired
strobe on this line
17
OPTO_OUT2±
Ext. I/O module
Any opto-isolated output device,
as above
CVL Class Reference
cc8120
numInputLines
line
Signal Name
Connects to
Device Connection
18
OPTO_OUT3±
Ext. I/O module
Any opto-isolated output device,
as above
19
OPTO_OUT4±
Ext. I/O module
Any opto-isolated output device,
as above
virtual c_Int32 numInputLines();
Returns the number of input lines for this frame grabber and specified I/O configuration.
numOutputLines
virtual c_Int32 numOutputLines();
Returns the number of output lines for this frame grabber and specified I/O
configuration.
getIOConfig
virtual ccIOConfig& getIOConfig() const;
Returns the parallel I/O board configuration.
setIOConfig
virtual void setIOConfig(ccIOConfig& config);
Sets the parallel I/O board configuration. See ccIOConfig and its derived classes, as
discussed in ccIOConfig on page 1771 and in ch_cvl/pioconfg.h.
Parameters
config
The I/O board configuration.
Notes
The config parameter is one of the following classes derived from ccIOConfig:
ccIOStandardOption
ccIOLightControlOption
ccIOExternalOption
CVL Class Reference
213
cc8120
Example
This example sets the I/O configuration for an MVS-8120 frame grabber with a
standard option parallel I/O board, or one or both or the ISA-based parallel I/O
boards.
cc8120& fg = cc8120::get(0);
ccParallelIO* pio = dynamic_cast<ccParallelIO*> (&fg);
pio-> setIOConfig(ccIOStandardOption());
Static Functions
count
static c_Int32 count();
Returns the number of Cognex MVS-8120 frame grabbers installed.
get
static cc8120& get(c_Int32 i = 0);
Returns the ith Cognex MVS-8120 installed. Board numbering starts at 0.
Parameters
i
The board number.
Throws
ccBoard::BadParams
i is not in the range 0 through count() - 1.
sizePelPool
static c_Int32 sizePelPool();
static c_Int32 sizePelPool(c_Int32 desiredSize);
•
static c_Int32 sizePelPool();
Returns the size of the memory pool used to store images when using low latency mode.
•
static c_Int32 sizePelPool(c_Int32 desiredSize);
Sets the size of the memory pool used to store images under low latency mode.
You must specify the size of the pool before any acquisition FIFOs have been created
and before any other CVL-based application runs.
Parameters
desiredSize
214
The desired size of the pool in bytes.
CVL Class Reference
cc8120
Notes
The function allImagesInPool() determines whether or not the low latency pool is
used for images acquired through camera ports for which low latency mode is not
enabled.
The default size of the low latency memory pool is stored in the poolsize value of the
registry key HKEY_LOCAL_MACHINE\SOFTWARE\Cognex\CVL\fg8120.
allImagesInPool
static bool allImagesInPool();
static void allImagesInPool(bool enabled);
See the introduction to this reference page for information about allImagesInPool().
•
static bool allImagesInPool();
Returns true if the low latency image pool is being used.
•
static void allImagesInPool(bool enabled);
Enables or disables use of the low latency image pool for all images. The default is true.
When this function is enabled, storage for all images is allocated from the low latency
pool whether or not low latency mode is actually enabled for a particular camera port
(see lowLatency() on page 204).
When this function is disabled, only images acquired through a camera port that has low
latency enabled will use the low latency image pool. The memory for all other acquired
images is allocated from the system heap.
Parameters
enabled
True to use the low latency image pool for all acquired images.
False to use the low latency image pool only for images acquired
in low latency mode.
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
CVL Class Reference
215
cc8120
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8100m, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
ccBoard::FpgaLoadFailure
An error occured while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
216
CVL Class Reference
cc8200
#include <ch_cvl/vp8200.h>
class cc8200 : public
public
public
public
public
ccBoard,
ccAccelerator,
ccFrameGrabber,
ccParallelIO,
ccSensor;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes the Cognex MVS-8200 and MVS-82400 vision processors. These
two vision processors use different CPUs; the I/O lines external connections are the
same for both models. Throughout this reference page, references to MVS-82400 vision
processors can be assumed to refer equally to MVS-8200 vision processors.
There is one instance of this class for each MVS-82400 board in a system. When you
write your application you create the vision processor object you will use with code
similar to the following:
cc8200& fg = cc8200::get(i);
In this example, i is the MVS-82400 board number in your system, starting with 0. If you
have only one MVS-82400 in your system i will always be 0. If you have more than one
MVS-82400 board in your system you will need to know the board number you wish to
use so you can code the above line properly.
Note that generally MVS-82400 board 0 is the MVS-82400 board in the lowest numbered
slot. However, this can vary with different motherboard manufacturers and can be BIOS
dependent. You will need to consult your system hardware documentation to verify the
board numbers when you use more than one MVS-82400 in your system.
Constructors/Destructors
A single instance of this class is created automatically for each vision processor
installed in your system.
CVL Class Reference
217
cc8200
Enumerations
movePartTimingChoice
enum movePartTimingChoice;
This enumeration specifies whether a registered move-part callback function is called
at the default or optimum timing. For the MVS-82400, this only affects the case of
interlaced full-frame video formats (such as “Sony XC75 640x480”) with non-strobed
acquisition. For this case, the enum’s values are:
Value
Move-part callback function is called ...
eDefaultTiming
After the first charge transfer interval of the first field
eOptimumTiming
After the vertical blank of the second field.(about a field later
than the default)
For completeness, the following table lists when the move-part callback function is
called for all video format types. However, only in the first case does the
movePartTimingChoice enumeration make a difference.
Video format type
Move-part callback function is called
Interlaced full frame (such as Sony
XC-75 640x480); non-strobed
acquisition
According to the setting of
movePartTimingChoice(), as per the
table above
Interlaced full frame (such as Sony
XC-75 640x480); strobed acquisition
After the first charge transfer interval of
the first field
Interlaced single frame (such as Sony
XC-75 640x240); strobed or non-strobed
After the charge transfer interval of the
first field acquired
Progressive scan (such as Sony XC-55
640x480); strobed or non-strobed
After the image is integrated
Public Member Functions
inputLine
virtual ccInputLine inputLine(c_Int32 line);
Returns a ccInputLine for the specified logical input line. The value you enter for line
depends on your hardware platform.
Parameters
line
218
The number of the input line. Line numbering starts at 0. This
value must be between 0 and numInputLines() - 1.
CVL Class Reference
cc8200
Throws
ccParallelIO::BadParams
line is not between 0 and numInputLines() - 1.
ccParallelIO::NotImplemented
This function was called from the host instead of the vision
processor.
Notes
On the all 82400 models, lines TTL_IN_5 through TTL_IN_8 can be used as
hardware trigger lines. If you are using these lines as trigger lines, do not try to use
them at the same time as ccInputLine objects under software control. For more
information on the use of hardware trigger lines, see the hardware manual for your
vision processor and the Input and Output chapter of the CVL Users Guide.
inputLine line for the MVS-82400/PCI
The MVS-82400/PCI uses the same Cognex parallel I/O boards as the MVS-8120.
See the function inputLine() in the cc8120 reference for detailed usage notes and
for tables of line parameters and their associated signal names on various parallel
I/O board configurations.
inputLine line for the MVS-82400/CPCI and MVS-82400/VME
For the CPCI and VME models of the 82400 series, parallel input lines can either be
on the Trigger/Strobe port on the vision processor’s baseboard, or on the parallel
I/O port on the I/O Option Board. There are four TTL input lines on the Trigger/Strobe
port. On the I/O Option Board, there are four TTL input lines and eight TTL
bidirectional lines that can be used as either input or output lines.
All of the bidirectional lines must be used together as input lines or as output lines.
You cannot configure some bidirectional lines as input lines and others as output
lines. Calling ccOutputLine::enable() or ccInputLine::enable() on any
bidirectional line sets the direction for all bidirectional lines.
The following table lists the correspondence between logical input line numbers
that you supply as a parameter to this function, the standardized signal names used
by Cognex parallel I/O equipment, and the pin numbers that carry those signals on
the Trigger/Strobe port or the I/O Option Board. Consult your Cognex hardware
manual and CVL Release Notes for any updates to the pin numbering scheme.
CVL Class Reference
line
Signal Name
Location
Pin
Device Connection
0
TTL_IN_1
I/O Option Board
14
Any TTL input
1
TTL_IN_2
I/O Option Board
15
Any TTL input
2
TTL_IN_3
I/O Option Board
16
Any TTL input
3
TTL_IN_4
I/O Option Board
17
Any TTL input
219
cc8200
outputLine
line
Signal Name
Location
Pin
Device Connection
4
TTL_IN_5
Trigger/Strobe port
(82400 baseboard)
1
Hardware trigger 1 or
any TTL input
5
TTL_IN_6
Trigger/Strobe port
6
Hardware trigger 1 or
any TTL input
6
TTL_IN_7
Trigger/Strobe port
11
Hardware trigger 1 or
any TTL input
7
TTL_IN_8
Trigger/Strobe port
2
Hardware trigger 1 or
any TTL input
8
TTL_BI_1
I/O Option Board
21
Bidirectional line,
controls any TTL input
device when all
bidirectional lines are
enabled for input
9
TTL_BI_2
I/O Option Board
9
Bidirectional, as above
10
TTL_BI_3
I/O Option Board
22
Bidirectional, as above
11
TTL_BI_4
I/O Option Board
8
Bidirectional, as above
12
TTL_BI_5
I/O Option Board
23
Bidirectional, as above
13
TTL_BI_6
I/O Option Board
7
Bidirectional, as above
14
TTL_BI_7
I/O Option Board
24
Bidirectional, as above
15
TTL_BI_8
I/O Option Board
6
Bidirectional, as above
virtual ccOutputLine outputLine(c_Int32 line);
Returns a ccOutputLine for the specified logical output line. The value you enter for line
depends on your hardware platform.
Parameters
line
The number of the output line. Line numbering starts at 0. This
value must be between 0 and numOutputLines() - 1.
Throws
ccParallelIO::BadParams
line is not between 0 and numOutputLines() - 1.
220
CVL Class Reference
cc8200
ccParallelIO::NotImplemented
This function was called from the host instead of the vision
processor.
Notes
You can set any output line to true or false using ccOutputLine::set. For TTL
output or TTL bidirectional lines, true means TTL high (+5V). For opto-isolated lines,
true enables the no-current-flowing state (the LED inside the opto-isolator is OFF,
and thus the circuit is open). For opto-isolated lines, false sets the current-flowing
state (the LED inside the opto-isolator is ON, thus the circuit is closed). Refer to the
circuit diagram for opto-isolated parallel I/O lines in the hardware manual for your
vision processor.
outputLine line for MVS-8200/PCI and MVS-82400/PCI
The MVS-82400/PCI uses the same Cognex parallel I/O boards as the MVS-8120.
See the function outputLine() in the cc8120 reference for detailed usage notes and
for tables of line parameters and their associated signal names on various parallel
I/O board configurations.
outputLine line for MVS-82400/CPCI and MVS-82400/VME
For the CPCI and VME models, eight output pins on the baseboard’s 15-pin
Trig/Strobe connector are configured as four pairs of opto-isolated lines, and are
normally used as strobe lines. If you are not using hardware-fired strobes, you can
control these lines with a ccOutputLine object. In addition, the I/O Option Board,
provides eight TTL output lines and eight TTL bidirectional lines.
CVL Class Reference
line
Signal Name
Location
Pin
Device Connection
0
TTL_OUT_1
I/O Option Board
26
Any TTL output
1
TTL_OUT_2
I/O Option Board
4
Any TTL output
2
TTL_OUT_3
I/O Option Board
27
Any TTL output
3
TTL_OUT_4
I/O Option Board
3
Any TTL output
4
TTL_OUT_5
I/O Option Board
28
Any TTL output
5
TTL_OUT_6
I/O Option Board
2
Any TTL output
6
TTL_OUT_7
I/O Option Board
29
Any TTL output
7
TTL_OUT_8
I/O Option Board
1
Any TTL output
221
cc8200
numInputLines
line
Signal Name
Location
Pin
Device Connection
8
TTL_BI_1
I/O Option Board
21
Bidirectional line,
controls any TTL output
device when all
bidirectional lines are
enabled for output
9
TTL_BI_2
I/O Option Board
9
Bidirectional, as above
10
TTL_BI_3
I/O Option Board
22
Bidirectional, as above
11
TTL_BI_4
I/O Option Board
8
Bidirectional, as above
12
TTL_BI_5
I/O Option Board
23
Bidirectional, as above
13
TTL_BI_6
I/O Option Board
7
Bidirectional, as above
14
TTL_BI_7
I/O Option Board
24
Bidirectional, as above
15
TTL_BI_8
I/O Option Board
6
Bidirectional, as above
16
OPTO_OUT1±
Trig/Strobe port
(82400 baseboard)
3, 14
Any opto-isolated
output device, when not
using a hardware-fired
strobe on this line
17
OPTO_OUT2±
Trig/Strobe port
(82400 baseboard)
8, 5
Any opto-isolated
output device, as above
18
OPTO_OUT3±
Trig/Strobe port
(82400 baseboard)
13, 10
Any opto-isolated
output device, as above
19
OPTO_OUT4±
Trig/Strobe port
(82400 baseboard)
4, 15
Any opto-isolated
output device, as above
virtual c_Int32 numInputLines();
Returns the number of input lines for this platform.
numOutputLines
virtual c_Int32 numOutputLines();
Returns the number of output lines for this platform.
getIOConfig
virtual ccIOConfig& getIOConfig() const;
Returns the parallel I/O board configuration.
222
CVL Class Reference
cc8200
setIOConfig
virtual void setIOConfig(ccIOConfig& config);
Sets the parallel I/O board configuration. See ccIOConfig and its derived classes, as
discussed in ccIOConfig in the CVL Class Reference and in ch_cvl/pioconfg.h.
Parameters
config
The I/O board configuration.
Notes
The config parameter is one of the following classes derived from ccIOConfig:
ccIOStandardOption
ccIOLightControlOption
ccIOExternalOption
Example
This example sets the I/O configuration for an MVS-82400 vision processor with a
standard option parallel I/O board, or with one or both of the ISA-based parallel I/O
boards.
cc8200& fg = cc8200::get(0);
ccParallelIO* pio = dynamic_cast<ccParallelIO*> (&fg);
pio-> setIOConfig(ccIOStandardOption());
movePartTiming
void movePartTiming(movePartTimingChoice choice);
Selects between default and optimum timing of the call to a registered move-part
callback function. See movePartTimingChoice on page 218 for the difference between
default and optimum behaviors.
temperatureSensorCpu
virtual ccTemperatureSensor temperatureSensorCpu();
Returns a temperature sensor object which corresponds the temperature sensor
located under the CPU of the vision processor. See ccTemperatureSensor on
page 2683.
temperatureSensorCvm
virtual ccTemperatureSensor temperatureSensorCvm();
Returns a temperature sensor object which corresponds the temperature sensor
located under the Cognex Video Module (CVM) of the vision processor. See
ccTemperatureSensor on page 2683.
CVL Class Reference
223
cc8200
init
void init(const ccCvlString& bootFileName,
double timeout = HUGE_VAL, TCHAR** argv = 0);
Boots this board with the executable image in the given file and passes the command
line arguments to the accelerator. init() blocks until the vision processor has booted and
the executable has been transferred to it, at which point the function returns. The vision
processor continues its boot sequence and queries the host to get the command line
parameters.
Once init() returns, the host can initiate communication with the vision processor.
However, communication is blocked until the vision processor is completely up and
running.
Parameters
bootFileName
The name of the file that contains the executable image.
timeout
The maximum number of seconds to wait after the executable
image is downloaded to the board until it signals to the host the
image is running. The default value, HUGE_VAL, means to wait
forever.
argv
The command line copied and passed to the embedded
application’s main() function. argv may be zero or an array of at
least two character strings. By convention, argv[0] is the name of
the program (bootFileName).
If argv is zero, it is as if it had been declared as follows:
TCHAR *argv[2] = { bootFileName.c_str(), 0 };
Throws
ccAccelerator::BadFile
bootFileName is not readable.
ccAccelerator::BootFailure
Could not boot from file.
ccBoard::Timeout
The timeout period elapsed before the board was booted.
wait
c_UInt8 wait(double timeout = HUGE_VAL);
Waits for completion of the process initiated by the init() function. Returns the value
returned when the embedded application calls exit() or return from main().
By convention, return value of zero indicates success, and a nonzero value indicates
failure. This function returns c_UInt8 (rather than c_Int32) so as to be analogous to the
POSIX wait() function.
224
CVL Class Reference
cc8200
Parameters
timeout
The number of seconds to wait for the process initiated by the
init() function to complete. A value of HUGE_VAL means to wait
forever.
Throws
ccBoard::Timeout
The timeout period has elapsed.
reset
void reset();
Resets the board and begins the power-up sequence without running diagnostics. Any
running program is halted and becomes inaccessible.
waitForAlarm
bool waitForAlarm(csFailureMessage& msg,
double timeOut = HUGE_VAL);
Waits for an alarm condition from the vision processor, such as board temperature too
high or watchdog timer expired. Returns true if the an alarm has been raised, false
otherwise.
Parameters
msg
timeOut
A structure containing an error code and error message.
The number of seconds to wait for an alarm condition. The default
value, HUGE_VAL, means to wait forever.
Static Functions
count
static c_Int32 count();
Returns the number of Cognex MVS-82400 vision processors installed.
Notes
You cannot distinguish between an MVS-8200 and an MVS-82400 in software.
get
static cc8200& get(c_Int32 i = 0);
Returns the ith Cognex MVS-8200 or MVS-82400 installed. Board numbering starts at 0.
Parameters
i
The board number.
Throws
ccBoard::BadParams
i is not in the range 0 through count() - 1.
CVL Class Reference
225
cc8200
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8100m, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
ccBoard::FpgaLoadFailure
An error occured while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
226
CVL Class Reference
cc8500l
#include <ch_cvl/vp8500l.h>
class cc8500l : public ccUnknownFG,
public ccUnknownPIO;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes the Cognex MVS-8500L frame grabber. There is one instance of
this class for each MVS-8500L board in a system. When you write your application you
create the frame grabber object you will use, with code similar to the following:
cc8500l& fg = cc8500l::get(i);
In this example, i is the MVS-8500L board number in your system, starting with 0. If you
have only one MVS-8500L in your system i will always be 0. If you have more than one
MVS-8500L board in your system you will need to know the board number you wish to
use so you can code the above line properly.
Constructors/Destructors
A single instance of this class is created automatically for each MVS-8500L installed in
your system.
Public Member Functions
inputLine
virtual ccInputLine inputLine(c_Int32 line);
Returns a ccInputLine object that represents the specified logical input line. This is an
override from class ccParallelIO.
Parameters
line
CVL Class Reference
The logical line number. line must be a valid value for the
configuration set by setIOConfig().
227
cc8500l
Notes
The MVS-8500L provides eight bidirectional TTL lines. Each line can be
independently enabled as an input or output line using ccOutputLine::enable() or
ccInputLine::enable().
The eight lines are numbered 8 through 15.
At power-on of the MVS-8500L, all lines are enabled as input lines; they must be
explicitly enabled for use as output lines. At power-on, all lines are pulled high by
an internal pull-up resistor.
The MVS-8500L’s parallel I/O lines have three connection options. They can be
used as TTL lines, can be converted to opto-isolated line pairs, or a combination of
TTL and opto-isolated lines. These connection options are described in the
MVS-8500 Hardware Manual. Consult that manual for the correspondence between
the signal names used in the table below and the pin numbers to which you connect
device wiring.
Line 8 has a dual purpose as either programmable TTL line or as a trigger line for
the currently active camera. If the acquisition FIFO’s triggerEnable() function is
invoked for line 8, then line 8 is not available for use as an input line with this
function.
Similarly, line 9 has a dual purpose as either programmable TTL line or strobe
control line for the currently active camera. If the acquisition FIFO’s strobeEnable()
function is invoked for line 9, then line 9 is not available for use as an input line with
this function.
The following table shows the logical line numbers for the eight parallel I/O lines on
the MVS-8500L, when each bidirectional line is configured as an input line.
228
inputLine
line parameter
Signal name on
MVS-8500L
8
TTL_BI_8
Trigger for the currently active camera, if
enabled. Otherwise a bidirectional line,
controls any TTL input device when this
line is enabled for input.
9
TTL_BI_9
Strobe for the currently active camera, if
enabled. Otherwise a bidirectional line,
controls any TTL input device when this
line is enabled for input.
10
TTL_BI_10
Bidirectional line, controls any TTL input
device when this line is enabled for input
11
TTL_BI_11
Bidirectional, as above
Device Connection
CVL Class Reference
cc8500l
inputLine
line parameter
Signal name on
MVS-8500L
Device Connection
12
TTL_BI_12
Bidirectional, as above
13
TTL_BI_13
Bidirectional, as above
14
TTL_BI_14
Bidirectional, as above
15
TTL_BI_15
Bidirectional, as above
The line numbers in the table above are the same whether devices are wired with
the TTL, opto-isolated, or combination connection options. Consult the MVS-8500
Hardware Manual for the pin numbers for each connection option that correspond
to the signal names in the table above.
outputLine
virtual ccOutputLine outputLine(c_Int32 line);
Returns a ccOutputLine object that represents the specified logical output line. This is
an override from class ccParallelIO.
Parameters
line
CVL Class Reference
The logical line. line must be a valid value for the configuration set
by setIOConfig().
229
cc8500l
Notes
See the Notes above for inputLine(). Remember that at power-on of the
MVS-8500L, all lines are enabled as input lines; they must be explicitly enabled for
use as output lines, using ccOutputLine::enable().
The eight lines are numbered 8 through 15.
Consult the MVS-8500 Hardware Manual for the correspondence between the
signal names used in the table below and the pin numbers to which you connect
device wiring.
The following table shows the logical line numbers for the eight parallel I/O lines on
the MVS-8500L, when each bidirectional line is configured as an output line.
outputLine
line parameter
Signal name
on MVS-8500L
8
TTL_BI_8
Trigger for the currently active camera, if
enabled. Otherwise a bidirectional line,
controls any TTL input device when this
line is enabled for input.
9
TTL_BI_9
Strobe for the currently active camera, if
enabled. Otherwise a bidirectional line,
controls any TTL input device when this
line is enabled for input.
10
TTL_BI_10
Bidirectional line, controls any TTL input
device when this line is enabled for input
11
TTL_BI_11
Bidirectional, as above
12
TTL_BI_12
Bidirectional, as above
13
TTL_BI_13
Bidirectional, as above
14
TTL_BI_14
Bidirectional, as above
15
TTL_BI_15
Bidirectional, as above
Device Connection
The line numbers in the table above are the same whether devices are wired with
the TTL, opto-isolated, or combination connection options. Consult the MVS-8500
Hardware Manual for the pin numbers for each connection option that correspond
to the signal names in the table above.
230
CVL Class Reference
cc8500l
numInputLines
virtual c_Int32 numInputLines() const;
Returns the number of total input lines for this hardware. The total depends upon the
configuration set by setIOConfig().
This is an override from class ccParallelIO.
numOutputLines
virtual c_Int32 numOutputLines() const;
Returns the number of total output lines for this hardware.
This is an override from class ccParallelIO.
getIOConfig
virtual ccIOConfig& getIOConfig() const;
Returns the parallel I/O board configuration.
This is an override from class ccParallelIO.
setIOConfig
virtual void setIOConfig(ccIOConfig& config);
Sets the parallel I/O board configuration. See ccIOConfig and its derived classes, as
discussed in ccIOConfig on page 1771 and in ch_cvl/pioconfg.h.
This is an override from class ccParallelIO.
Parameters
config
The I/O board configuration.
Notes
The config parameter is one of the following classes derived from ccIOConfig:
ccIO8500l (for use with cable 300-0390)
ccIOExternal8500l (for use with cable 300-0389)
ccIOSplit8500l (for use with cable 300-0399)
CVL Class Reference
231
cc8500l
Example
This example sets the I/O configuration for an MVS-8500L frame grabber using
cable 300-0390 and the pass-through TTL connection module.
cc8500l& fg = cc8500l::get(0);
ccParallelIO* pio = dynamic_cast<ccParallelIO*> (&fg);
pio->setIOConfig(ccIO8500l());
Static Functions
count
static c_Int32 count();
Returns the number of Cognex MVS-8500L frame grabbers installed in the system.
get
static cc8500l& get(c_Int32 i = 0);
Returns the cc8500l object associated with the Cognex MVS-8500L frame grabber
whose index is i. Index numbers begin with 0. See the introduction to this reference page
for additional information.
Parameters
i
The Cognex MVS-8500L board index.
Throws
ccBoard::BadParams
If i is not a valid index.
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
232
CVL Class Reference
cc8500l
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8100m, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
ccBoard::FpgaLoadFailure
An error occured while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
CVL Class Reference
233
cc8500l
234
CVL Class Reference
cc8501
#include <ch_cvl/vp8501.h>
class cc8501 : public ccBoard,
public ccFrameGrabber,
public ccParallelIO;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes the Cognex MVS-8501 frame grabber. There is one instance of this
class for each MVS-8501 board in a system. When you write your application you create
the frame grabber object you will use, with code similar to the following:
cc8501& fg = cc8501::get(i);
In this example, i is the MVS-8501 board number in your system, starting with 0. If you
have only one MVS-8501 in your system i will always be 0. If you have more than one
MVS-8501 board in your system you will need to know the board number you wish to use
so you can code the above line properly.
Generally, MVS-8501 board 0 is the MVS-8501 board in the lower numbered PCI slot.
However, this can vary with different motherboard manufacturers, and can be BIOS
dependent. Consult your system hardware documentation to verify the system’s PCI slot
numbering system when you use more than one MVS-8501 in your system.
Constructors/Destructors
A single instance of this class is created automatically for each MVS-8501 installed in
your system.
Public Member Functions
inputLine
virtual ccInputLine inputLine(c_Int32 line);
Returns a ccInputLine object that represents the specified logical input line. This is an
override from class ccParallelIO.
CVL Class Reference
235
cc8501
Parameters
line
The logical line number. line must be a valid value for the
configuration set by setIOConfig().
Notes
The MVS-8501 provides sixteen bidirectional TTL lines. On some Cognex frame
grabber families, the input or output direction of all bidirectional lines is set as a
group. By contrast, on the MVS-8500 series, each line can be independently
enabled as an input or output line using ccOutputLine::enable() or
ccInputLine::enable().
At power-on of the MVS-8501, all sixteen lines are enabled as input lines; they must
be explicitly enabled for use as output lines. At power-on, all lines are pulled high
by an internal pull-up resistor. By contrast, on other Cognex frame grabbers,
parallel I/O lines are pulled low or allowed to float.
The MVS-8501’s parallel I/O lines have three connection options. They can be used
as TTL lines, can be converted to opto-isolated line pairs, or a combination of TTL
and opto-isolated lines. These connection options are described in the MVS-8500
Hardware Manual. Consult that manual for the correspondence between the signal
names used in the table below and the pin numbers to which you connect device
wiring.
Line 8 has a dual purpose as either programmable TTL line or as a trigger line for
the currently active camera. If the acquisition FIFO’s triggerEnable() function is
invoked for line 8, then line 8 is not available for use as an input line with this
function.
Similarly, line 9 has a dual purpose as either programmable TTL line or strobe
control line for the currently active camera. If the acquisition FIFO’s strobeEnable()
function is invoked for line 9, then line 9 is not available for use as an input line with
this function.
The following table shows the logical line numbers for the sixteen parallel I/O lines
on the MVS-8501, when each bidirectional line is configured as an input line.
236
inputLine
line parameter
Signal name on
MVS-8501
0
TTL_BI_0
Bidirectional line, controls any TTL input
device when this line is enabled for input
1
TTL_BI_1
Bidirectional, as above
2
TTL_BI_2
Bidirectional, as above
3
TTL_BI_3
Bidirectional, as above
Device Connection
CVL Class Reference
cc8501
inputLine
line parameter
Signal name on
MVS-8501
Device Connection
4
TTL_BI_4
Bidirectional, as above
5
TTL_BI_5
Bidirectional, as above
6
TTL_BI_6
Bidirectional, as above
7
TTL_BI_7
Bidirectional, as above
8
TTL_BI_8
Trigger for the currently active camera, if
enabled, or bidirectional, as above
9
TTL_BI_9
Strobe for the currently active camera, if
enabled, or bidirectional, as above
10
TTL_BI_10
Bidirectional line, controls any TTL input
device when this line is enabled for input
11
TTL_BI_11
Bidirectional, as above
12
TTL_BI_12
Bidirectional, as above
13
TTL_BI_13
Bidirectional, as above
14
TTL_BI_14
Bidirectional, as above
15
TTL_BI_15
Bidirectional, as above
The line numbers in the table above are the same whether devices are wired with
the TTL, opto-isolated, or combination connection options. Consult the MVS-8500
Hardware Manual for the pin numbers for each connection option that correspond
to the signal names in the table above.
outputLine
virtual ccOutputLine outputLine(c_Int32 line);
Returns a ccOutputLine object that represents the specified logical output line. This is
an override from class ccParallelIO.
Parameters
line
CVL Class Reference
The logical line. line must be a valid value for the configuration set
by setIOConfig().
237
cc8501
Notes
See the Notes above for inputLine(). Remember that at power-on of the MVS-8501,
all sixteen lines are enabled as input lines; they must be explicitly enabled for use
as output lines, using ccOutputLine::enable().
Consult the MVS-8500 Hardware Manual for the correspondence between the
signal names used in the table below and the pin numbers to which you connect
device wiring.
The following table shows the logical line numbers for the sixteen parallel I/O lines
on the MVS-8501, when each bidirectional line is configured as an output line.
238
outputLine
line parameter
Signal name
on MVS-8501
0
TTL_BI_0
Bidirectional line, controls any TTL output
device when this line is enabled for output
1
TTL_BI_1
Bidirectional, as above
2
TTL_BI_2
Bidirectional, as above
3
TTL_BI_3
Bidirectional, as above
4
TTL_BI_4
Bidirectional, as above
5
TTL_BI_5
Bidirectional, as above
6
TTL_BI_6
Bidirectional, as above
7
TTL_BI_7
Bidirectional, as above
8
TTL_BI_8
Trigger for the currently active camera if
enabled, or bidirectional, as above
9
TTL_BI_9
Strobe for the currently active camera if
enabled, or bidirectional, as above
10
TTL_BI_10
Bidirectional line, controls any TTL output
device when this line is enabled for output
11
TTL_BI_11
Bidirectional, as above
12
TTL_BI_12
Bidirectional, as above
13
TTL_BI_13
Bidirectional, as above
14
TTL_BI_14
Bidirectional, as above
15
TTL_BI_15
Bidirectional, as above
Device Connection
CVL Class Reference
cc8501
The line numbers in the table above are the same whether devices are wired with
the TTL, opto-isolated, or combination connection options. Consult the MVS-8500
Hardware Manual for the pin numbers for each connection option that correspond
to the signal names in the table above.
numInputLines
virtual c_Int32 numInputLines() const;
Returns the number of total input lines for this hardware. The total depends upon the
configuration set by setIOConfig().
This is an override from class ccParallelIO.
numOutputLines
virtual c_Int32 numOutputLines() const;
Returns the number of total output lines for this hardware.
This is an override from class ccParallelIO.
getIOConfig
virtual ccIOConfig& getIOConfig() const;
Returns the parallel I/O board configuration.
This is an override from class ccParallelIO.
setIOConfig
virtual void setIOConfig(ccIOConfig& config);
Sets the parallel I/O board configuration. See ccIOConfig and its derived classes, as
discussed in ccIOConfig on page 1771 and in ch_cvl/pioconfg.h.
This is an override from class ccParallelIO.
Parameters
config
The I/O board configuration.
Notes
The config parameter is one of the following classes derived from ccIOConfig:
ccIO8501 (for use with cable 300-0390)
ccIOExternal8501 (for use with cable 300-0389)
ccIOSplit8501 (for use with cable 300-0399)
CVL Class Reference
239
cc8501
Example
This example sets the I/O configuration for an MVS-8501 frame grabber using cable
300-0390 and the pass-through TTL connection module.
cc8501& fg = cc8501::get(0);
ccParallelIO* pio = dynamic_cast<ccParallelIO*> (&fg);
pio->setIOConfig(ccIO8501());
Static Functions
count
static c_Int32 count();
Returns the number of Cognex MVS-8501 frame grabbers installed in the system.
get
static cc8501& get(c_Int32 i = 0);
Returns the cc8501 object associated with the Cognex MVS-8501 frame grabber whose
index is i. Index numbers begin with 0. See the introduction to this reference page for
additional information.
Parameters
i
The Cognex MVS-8501 board index.
Throws
ccBoard::BadParams
If i is not a valid index.
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
240
CVL Class Reference
cc8501
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8100m, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
ccBoard::FpgaLoadFailure
An error occured while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
CVL Class Reference
241
cc8501
242
CVL Class Reference
cc8504
#include <ch_cvl/vp8504.h>
class cc8504 : public ccBoard,
public ccFrameGrabber,
public ccParallelIO;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes the Cognex MVS-8504 frame grabber. There is one instance of this
class for each MVS-8504 board in a system. When you write your application you create
the frame grabber object you will use, with code similar to the following:
cc8504& fg = cc8504::get(i);
In this example, i is the MVS-8504 board number in your system, starting with 0. If you
have only one MVS-8504 in your system i will always be 0. If you have more than one
MVS-8504 board in your system you will need to know the board number you wish to use
so you can code the above line properly.
Generally, MVS-8504 board 0 is the MVS-8504 board in the lower numbered PCI slot.
However, this can vary with different motherboard manufacturers, and can be BIOS
dependent. Consult your system hardware documentation to verify the system’s PCI slot
numbering system when you use more than one MVS-8504 in your system.
Constructors/Destructors
A single instance of this class is created automatically for each MVS-8504 installed in
your system.
Public Member Functions
inputLine
virtual ccInputLine inputLine(c_Int32 line);
Returns a ccInputLine object that represents the specified logical input line. This is an
override from class ccParallelIO.
CVL Class Reference
243
cc8504
Parameters
line
The logical line number. line must be a valid value for the
configuration set by setIOConfig().
Notes
The MVS-8504 provides sixteen bidirectional TTL lines. On some Cognex frame
grabber families, the input or output direction of all bidirectional lines is set as a
group. By contrast, on the MVS-8500 series, each line can be independently
enabled as an input or output line using ccOutputLine::enable() or
ccInputLine::enable().
At power-on of the MVS-8504, all sixteen lines are enabled as input lines; they must
be explicitly enabled for use as output lines. At power-on, all lines are pulled high
by an internal pull-up resistor. By contrast, on other Cognex frame grabbers,
parallel I/O lines are pulled low or allowed to float.
The MVS-8504’s parallel I/O lines have three connection options. They can be used
as TTL lines, can be converted to opto-isolated line pairs, or a combination of TTL
and opto-isolated lines. These connection options are described in the MVS-8500
Hardware Manual. Consult that manual for the correspondence between the signal
names used in the table below and the pin numbers to which you connect device
wiring.
Lines 8, 10, 12, and 14 have a dual purpose as either programmable TTL lines or
dedicated trigger lines. If the acquisition FIFO’s triggerEnable() function is invoked
for a given camera channel, the dedicated trigger line for that channel is not
available for use as an input line with this function.
Similarly, lines 9, 11, 13, and 15 have a dual purpose as either programmable TTL
lines or dedicated strobe control lines. If the acquisition FIFO’s strobeEnable()
function is invoked for a given camera channel, the dedicated strobe line for that
channel is not available for use as an input line with this function.
The following table shows the logical line numbers for the sixteen parallel I/O lines
on the MVS-8504, when each bidirectional line is configured as an input line.
244
inputLine
line parameter
Signal name
on MVS-8504
0
TTL_BI_0
Bidirectional line, controls any TTL input
device when this line is enabled for input
1
TTL_BI_1
Bidirectional, as above
2
TTL_BI_2
Bidirectional, as above
3
TTL_BI_3
Bidirectional, as above
Device Connection
CVL Class Reference
cc8504
inputLine
line parameter
Signal name
on MVS-8504
Device Connection
4
TTL_BI_4
Bidirectional, as above
5
TTL_BI_5
Bidirectional, as above
6
TTL_BI_6
Bidirectional, as above
7
TTL_BI_7
Bidirectional, as above
8
TTL_BI_8
Trigger for camera channel 1 if enabled,
or bidirectional, as above
9
TTL_BI_9
Strobe for camera channel 1 if enabled,
or bidirectional, as above
10
TTL_BI_10
Trigger for camera channel 2 if enabled,
or bidirectional, as above
11
TTL_BI_11
Strobe for camera channel 2 if enabled,
or bidirectional, as above
12
TTL_BI_12
Trigger for camera channel 3 if enabled,
or bidirectional, as above
13
TTL_BI_13
Strobe for camera channel 3 if enabled,
or bidirectional, as above
14
TTL_BI_14
Trigger for camera channel 4 if enabled,
or bidirectional, as above
15
TTL_BI_15
Strobe for camera channel 4 if enabled,
or bidirectional, as above
The line numbers in the table above are the same whether devices are wired with
the TTL, opto-isolated, or combination connection options. Consult the MVS-8500
Hardware Manual for the pin numbers for each connection option that correspond
to the signal names in the table above.
outputLine
virtual ccOutputLine outputLine(c_Int32 line);
Returns a ccOutputLine object that represents the specified logical output line. This is
an override from class ccParallelIO.
Parameters
line
CVL Class Reference
The logical line. line must be a valid value for the configuration set
by setIOConfig().
245
cc8504
Notes
See the Notes above for inputLine(). Remember that at power-on of the MVS-8504,
all sixteen lines are enabled as input lines; they must be explicitly enabled for use
as output lines, using ccOutputLine::enable().
Consult the MVS-8500 Hardware Manual for the correspondence between the
signal names used in the table below and the pin numbers to which you connect
device wiring.
The following table shows the logical line numbers for the sixteen parallel I/O lines
on the MVS-8504, when each bidirectional line is configured as an output line.
246
outputLine
line parameter
Signal name
on MVS-8504
0
TTL_BI_0
Bidirectional line, controls any TTL output
device when this line is enabled for output
1
TTL_BI_1
Bidirectional, as above
2
TTL_BI_2
Bidirectional, as above
3
TTL_BI_3
Bidirectional, as above
4
TTL_BI_4
Bidirectional, as above
5
TTL_BI_5
Bidirectional, as above
6
TTL_BI_6
Bidirectional, as above
7
TTL_BI_7
Bidirectional, as above
8
TTL_BI_8
Trigger for camera channel 1 if enabled, or
bidirectional, as above
9
TTL_BI_9
Strobe for camera channel 1 if enabled, or
bidirectional, as above
10
TTL_BI_10
Trigger for camera channel 2 if enabled, or
bidirectional, as above
11
TTL_BI_11
Strobe for camera channel 2 if enabled, or
bidirectional, as above
12
TTL_BI_12
Trigger for camera channel 3 if enabled, or
bidirectional, as above
13
TTL_BI_13
Strobe for camera channel 3 if enabled, or
bidirectional, as above
Device Connection
CVL Class Reference
cc8504
outputLine
line parameter
Signal name
on MVS-8504
14
TTL_BI_14
Trigger for camera channel 4 if enabled, or
bidirectional, as above
15
TTL_BI_15
Strobe for camera channel 4 if enabled, or
bidirectional, as above
Device Connection
The line numbers in the table above are the same whether devices are wired with
the TTL or opto-isolated connection options. Consult the MVS-8500 Hardware
Manual for the pin numbers for each connection option that correspond to the
signal names in the table above.
numInputLines
virtual c_Int32 numInputLines() const;
Returns the number of total input lines for this hardware. The total depends upon the
configuration set by setIOConfig().
This is an override from class ccParallelIO.
numOutputLines
virtual c_Int32 numOutputLines() const;
Returns the number of total output lines for this hardware.
This is an override from class ccParallelIO.
getIOConfig
virtual ccIOConfig& getIOConfig() const;
Returns the parallel I/O board configuration.
This is an override from class ccParallelIO.
setIOConfig
virtual void setIOConfig(ccIOConfig& config);
Sets the parallel I/O board configuration. See ccIOConfig and its derived classes, as
discussed in ccIOConfig on page 1771 and in ch_cvl/pioconfg.h.
This is an override from class ccParallelIO.
Parameters
config
CVL Class Reference
The I/O cable and connection box configuration, in the form of a
class derived from ccIOConfig.
247
cc8504
Notes
The config parameter is one of the following classes derived from ccIOConfig:
ccIO8504 (for use with cable 300-0390)
ccIOExternal8504 (for use with cable 300-0389)
ccIOSplit8504 (for use with cable 300-0399)
Example
This example sets the I/O configuration for an MVS-8504 frame grabber using cable
300-0390 and the pass-through TTL connection module.
cc8504& fg = cc8504::get(0);
ccParallelIO* pio = dynamic_cast<ccParallelIO*> (&fg);
pio->setIOConfig(ccIO8504());
Static Functions
count
static c_Int32 count();
Returns the number of Cognex MVS-8504 frame grabbers installed in the system.
get
static cc8504& get(c_Int32 i = 0);
Returns the cc8504 object associated with the Cognex MVS-8504 frame grabber whose
index is i. Index numbers begin with 0. See the introduction to this reference page for
additional information.
Parameters
i
The Cognex MVS-8504 board index.
Throws
ccBoard::BadParams
If i is not a valid index.
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
248
CVL Class Reference
cc8504
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8100m, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
ccBoard::FpgaLoadFailure
An error occured while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
CVL Class Reference
249
cc8504
250
CVL Class Reference
cc8600
#include <ch_cvl/vp8600.h>
class cc8600 : public ccBoard,
public ccFrameGrabber,
public ccParallelIO;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class describes the Cognex MVS-8600 and MVS-8600e frame grabbers. There is
one instance of this class for each frame grabber board in a system.
The MVS-8600 and MVS-8600e series frame grabbers consist of three frame grabber
boards that plug into your PC. The MVS-8601 and MVS-8602 plug into the PCI bus and
the MVS-8602e plugs into the PCI Express bus. The MVS-8601 has one camera port and
can support one camera. The MVS-8602 and MVS-8602e have two camera ports and
can support one or two cameras each. In this class reference we use the term
MVS-8600, or just 8600, to refer to all three of the MVS-8600 and MVS-8600e frame
grabber boards.
When you write your application, you create the frame grabber object you will use with
code like this example:
cc8600& fg = cc8600::get(i);
In this example, i is the MVS-8600 or MVS-8600e board number in your system, starting
with 0. If you have only one MVS-8600 or MVS-8600e in your system i will always be 0.
If you have more than one, you will need to know the board number you wish to address
so you can code the above line properly.
Generally, board 0 is the MVS-8600 or MVS-8600e board in the lower numbered PCI
slot. However, this can vary with different motherboard manufacturers, and can be BIOS
dependent. Consult your system hardware documentation to verify the system’s PCI slot
numbering system when you use more than one MVS-8600 or MVS-8600e in your
system.
Constructors/Destructors
A single instance of this class is created automatically for each MVS-8600 installed in
your system.
CVL Class Reference
251
cc8600
Public Member Functions
inputLine
virtual ccInputLine inputLine(c_Int32 line);
Returns a ccInputLine object that represents the specified logical input line. This is an
override from class ccParallelIO.
Parameters
line
The logical line number. line must be a valid value for the
configuration set by setIOConfig().
Notes
The MVS-8600 provides six or eight pairs of opto-isolated input lines, depending on
the I/O configuration you specify with setIOConfig().
I/O Configuration
Number of programmable input lines
ccIO8600LVDS
8
ccIO8600TTL
8
ccIO8600DualLVDS
6
The following table shows the logical line numbers for the eight opto-isolated input
line pairs. Match the signal names to connection pin numbers by using the
MVS-8600 Hardware Manual.
252
inputLine
line parameter
Signal name
on MVS-8600
0
OPTO_IN_0±
1
OPTO_IN_1±
2
OPTO_IN_2±
3
OPTO_IN_3±
4
OPTO_IN_4±
5
OPTO_IN_5±
6
OPTO_IN_6±
7
OPTO_IN_7±
Notes
Not available when connecting two line
scan cameras with two LVDS encoders (that
is, when using ccIO8600DualLVDS).
CVL Class Reference
cc8600
outputLine
virtual ccOutputLine outputLine(c_Int32 line);
Returns a ccOutputLine object that represents the specified logical output line. This is
an override from class ccParallelIO.
Parameters
line
The logical line. line must be a valid value for the configuration set
by setIOConfig().
Notes
The MVS-8600 provides six or eight pairs of opto-isolated output lines, depending
on the I/O configuration you specify with setIOConfig().
I/O Configuration
Number of programmable output lines
ccIO8600LVDS
8
ccIO8600TTL
8
ccIO8600DualLVDS
6
The following table shows the logical line numbers for the eight opto-isolated output
line pairs. Match the signal names to connection pin numbers by using the
MVS-8600 Hardware Manual.
CVL Class Reference
outputLine
line parameter
Signal name
on MVS-8600
0
OPTO_OUT_0±
1
OPTO_OUT_1±
2
OPTO_OUT_2±
3
OPTO_OUT_3±
4
OPTO_OUT_4±
5
OPTO_OUT_5±
6
OPTO_OUT_6±
7
OPTO_OUT_7±
Notes
Not available when connecting two line
scan cameras with two LVDS encoders
(that is, when using ccIO8600DualLVDS).
253
cc8600
numInputLines
virtual c_Int32 numInputLines() const;
Returns the number of total input lines for this hardware. The total depends upon the
configuration set by setIOConfig().
This is an override from class ccParallelIO.
numOutputLines
virtual c_Int32 numOutputLines() const;
Returns the number of total output lines for this hardware.
This is an override from class ccParallelIO.
getIOConfig
virtual ccIOConfig& getIOConfig() const;
Returns the parallel I/O board configuration.
This is an override from class ccParallelIO.
setIOConfig
virtual void setIOConfig(ccIOConfig& config);
Sets the parallel I/O board configuration. See ccIOConfig and its derived classes, as
discussed in ccIOConfig on page 1771 and in ch_cvl/pioconfg.h.
This is an override from class ccParallelIO.
Parameters
config
The I/O cable and connection box configuration, in the form of a
class derived from ccIOConfig.
Notes
The config parameter is one of the following classes derived from ccIOConfig:
ccIO8600LVDS (for use with cable 300-0539)
ccIO8600TTL (for use with cable 300-0540)
ccIO8600DualLVDS (for use with cable 300-0538)
In all cases, the same I/O connection module is used, Cognex part number
800-5885-1.
254
CVL Class Reference
cc8600
Example
This example sets the I/O configuration for an MVS-8600 frame grabber using cable
300-0539 and the MVS-8600 I/O connection module.
cc8600& fg = cc8600::get(0);
ccParallelIO* pio = dynamic_cast<ccParallelIO*> (&fg);
pio->setIOConfig(ccIO8600LVDS());
sizePelPool
c_Int32 sizePelPool();
void sizePelPool(c_Int32 desiredSize);
The pel pool is a special pool used to store images acquired using the MVS-8600 and
MVS-8600e frame grabbers. Each frame grabber has its own pel pool. The default size
is 32 MB each.
•
c_Int32 sizePelPool();
Returns the current pel pool size, in bytes.
•
void sizePelPool(c_Int32 desiredSize);
Sets a new pel pool size, in bytes.
Parameters
desiredSize
The new pel pool size.
Notes
When you set a new pel pool size, you set the size for all MVS-8600 and MVS-8600e
frame grabbers.
Static Functions
count
static c_Int32 count();
Returns the number of Cognex MVS-8600 frame grabbers installed in the system.
get
static cc8600& get(c_Int32 i = 0);
Returns the cc8600 object associated with the Cognex MVS-8600 frame grabber whose
index is i. Index numbers begin with 0. See the introduction to this reference page for
additional information.
Parameters
i
CVL Class Reference
The Cognex MVS-8600 board index.
255
cc8600
Throws
ccBoard::BadParams
If i is not a valid index.
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8600, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
ccBoard::FpgaLoadFailure
An error occurred while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
256
CVL Class Reference
cc8600
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
CVL Class Reference
257
cc8600
258
CVL Class Reference
cc8BitInputLutProp
#include <ch_cvl/prop.h>
class cc8BitInputLutProp;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class describes the 8-bit lookup table, a 256-element array. The digitizer converts
each pixel into an 8-bit value. This value is used as an index into the input lookup table.
The resulting value is stored in the root image. For dual-tap cameras, which use one
digitizer for the even field and another for the odd field, two lookup tables are used.
Since this class is one of the base classes of ccAcqProps, you do not need to create
an instance of this class. All classes derived from ccAcqFifo can use
ccAcqFifo::properties() to return a properties object that includes this property.
A table showing the acquisition hardware platforms that support this property is
included in the Acquiring Images chapter of the CVL User’s Guide.
Constructors/Destructors
cc8BitInputLutProp
cc8BitInputLutProp();
explicit cc8BitInputLutProp(const c_UInt8* ilut);
explicit cc8BitInputLutProp(const c_UInt8* ilut0,
const c_UInt8* ilut1);
•
cc8BitInputLutProp();
Creates a new input lookup table property not associated with any FIFO. Uses
cc8BitInputLutProp::default8BitInputLut as the lookup table.
•
explicit cc8BitInputLutProp(const c_UInt8* ilut);
Creates a new input lookup table property not associated with any FIFO. This function
uses a copy of ilut as the lookup table.
CVL Class Reference
259
cc8BitInputLutProp
Parameters
ilut
•
An array of 256 8-bit values (c_UInt8) to use as the lookup table.
explicit cc8BitInputLutProp(const c_UInt8* ilut0,
const c_UInt8* ilut1);
Creates a new input lookup table property not associated with any FIFO. This function
uses a copy of ilut0 as the lookup table for the fist (even) digitizer and ilut1 as the lookup
table for the second (odd) digitizer.
Parameters
ilut0
ilut1
An array of 256 8-bit values (c_UInt8) to use as the lookup table
for the first (even) digitizer.
An array of 256 8-bit values (c_UInt8) to use as the lookup table
for the second (odd) digitizer.
Enumerations
LutChannel
enum LutChannel;
This enumeration lets you specify the digitizer that an input lookup table refers to.
Value
Meaning
eOnly
The input lookup table is the only lookup table and applies to all
digitizers.
eEven
The input lookup table applies to the digitizer for the even field. For
single-tap cameras, eEven is the same as eOnly.
eOdd
The input lookup table applies to the digitizer for the odd field.
Public Member Functions
inputLut
void inputLut(const c_UInt8* ilut);
void inputLut(const c_UInt8* ilut, LutChannel lutCh);
const c_UInt8* inputLut(LutChannel lut=eOnly) const;
•
void inputLut(const c_UInt8* ilut);
Sets the 8-bit input lookup table to a copy of ilut.
260
CVL Class Reference
cc8BitInputLutProp
Parameters
ilut
•
An array of 256 8-bit values (c_UInt8) to use as the lookup table.
void inputLut(const c_UInt8* ilut, LutChannel lutCh);
Sets the 8-bit lookup table for the specified digitizer to a copy of ilut.
Parameters
ilut
lutCh
An array of 256 8-bit values (c_UInt8) to use as the lookup table.
The digitizer to which ilut applies. Must be one of:
cc8BitInputLutProp::eOnly
cc8BitInputLutProp::eEven
cc8BitInputLutProp::eOdd
•
const c_UInt8* inputLut(LutChannel lut=eOnly) const;
Returns the 8-bit input lookup table for the specified digitizer.
Constants
default8BitInputLut
static const c_UInt8 default8BitInputLut[256];
The default input lookup table is a positive linear mapping in the range 15 to 240. Values
below 15 are mapped to 15; values above 240 are mapped to 240.
positive8BitLut
static const c_UInt8 positive8BitLut[256];
This table is a positive linear mapping from 0 to 255.
shifted8BitLut
static const c_UInt8 shifted8BitLut[256];
This table is a positive linear mapping with values in the range 0 to 225 shifted to 15 to
240. Values in the range 226 to 255 are clamped to 240. Use this LUT instead of the
default8BitInputLut when you are using an 8-bit desktop for display and you want to
preserve as much information as possible in the low end of the pixel values.
CVL Class Reference
261
cc8BitInputLutProp
262
CVL Class Reference
ccAccelerator
#include <ch_cvl/comm.h>
class ccAccelerator : public ccCommunicator;
Class Properties
Copyable
No
Derivable
Cognex-supplied classes
only
Archiveable
No
This abstract class is used to describe Cognex vision processors. Your application will
typically use a class derived from this class to specify a Cognex vision processor.
Constructors/Destructors
Construction and destruction of derived classes is done automatically.
Public Member Functions
init
virtual void init(const ccCvlString& bootFileName,
double timeout = HUGE_VAL, TCHAR** argv = 0) = 0;
Boots this board with the executable image in the given file and passes the command
line arguments to the accelerator.
Parameters
bootFileName
The name of the file that contains the executable image.
timeout
The maximum number of seconds to wait after the executable
image is downloaded to the board until it signals to the host the
image is running. The default value, HUGE_VAL, means to wait
forever.
argv
The command line copied and passed to the embedded
application’s main() function. argv may be zero or an array of at
least two character strings. By convention, argv[0] is the name of
the program (bootFileName).
If argv is zero, it is as if it had been declared as follows:
TCHAR *argv[2] = {bootFileName.c_str(), 0};
CVL Class Reference
263
ccAccelerator
Throws
ccAccelerator::BadFile
bootFileName is not readable.
ccAccelerator::BootFailure
Could not boot from file.
ccBoard::Timeout
The timeout period elapsed before the board was booted.
wait
virtual c_UInt8 wait(double timeout = HUGE_VAL);
Waits for completion of the process initiated by the init() function. Returns the value
returned when the embedded application calls exit() or return from cfMain().
By convention, a return value of zero indicates success, and a nonzero value indicates
failure. This function returns c_UInt8 (rather than c_Int32) so as to be analogous to the
POSIX wait() function.
Parameters
timeout
The number of seconds to wait for the process initiated by the
init() function to complete. A value of HUGE_VAL means to wait
forever.
Throws
ccBoard::Timeout
The timeout period has elapsed.
reset
virtual void reset() = 0;
Resets the board and begins the power-up sequence without running diagnostics. Any
running program is halted and becomes inaccessible.
debuggerBreak
virtual void debuggerBreak() = 0;
Causes an asynchronous event that readies a board to accept attachment from a
debugger.
waitForAlarm
virtual bool waitForAlarm(csFailureMessage& msg,
double timeOut = HUGE_VAL) = 0;
Waits for an alarm condition from the vision processor, such as board temperature too
high or watchdog timer expired. Returns true if the an alarm has been raised, false
otherwise.
264
CVL Class Reference
ccAccelerator
Parameters
msg
timeOut
A structure containing an error code and error message.
The number of seconds to wait for an alarm condition. The default
value, HUGE_VAL, means to wait forever. Use a value of zero to
poll for alarm conditions.
Static Functions
count
static c_Int32 count();
Returns number of accelerators installed in the system.
Notes
This function is not available at static initialization time.
get
static ccAccelerator& get(c_Int32 i = 0);
Return the ith accelerator installed. Accelerator numbering starts at 0.
Parameters
i
The board number.
Throws
ccBoard::BadParams
i is not in the range 0 through count() - 1, or no accelerators are
installed (count() returns 0).
Notes
This function is not available at static initialization time.
debuggerSerialBreak
static void debuggerSerialBreak(c_Int32 serialPort = 1);
Sends an asynchronous break over the specified serial line.
Throws
ccBoard::BadParams
If serialPort is less than 1 or the serial port cannot be opened.
ccBoard::HardwareNotResponding
If a break cannot be sent.
CVL Class Reference
265
ccAccelerator
266
CVL Class Reference
ccAcqFailure
#include <ch_cvl/acqfail.h>
class ccAcqFailure;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class returns information about why an acquisition failed.
Constructors/Destructors
ccAcqFailure
ccAcqFailure();
~ccAcqFailure();
•
ccAcqFailure();
Creates an instance of this class. The initial state of this class is successful (no failures).
•
~ccAcqFailure();
Destructor.
Operators
bool
operator bool();
Casting this class to bool returns true if the acquisition failed or false otherwise.
CVL Class Reference
267
ccAcqFailure
Public Member Functions
isMissed
bool isMissed();
void isMissed(bool missedState);
•
bool isMissed() const;
Returns true if the acquisition failed because of a missed trigger. Otherwise returns
false. A missed trigger is a hardware trigger which failed to cause an acquisition to
occur.
In general, this failure is an indication that triggers are occurring faster than the
acquisition system can process them.
If you try to start an acquisition on a ccAcqFifo object that already has the maximum
number of outstanding acquisitions, (ccAcqFifo::kMaxOutstanding) the acquisition will
fail. When you eventually try to complete the acquisition, the resulting ccAcqFailure will
be isMissed().
In semi-trigger mode, you must call ccAcqFifo::start() for each acquire. If a trigger
occurs and start was not called, the trigger will cause an isMissed() error.
Notes
On a CVM4 (Cognex CVC-1000 camera), ccAcqFailure may report either
isOverrun() or isMissed().
If a master FIFO fails because of isMissed(), its slaves never receive notification of
the missed trigger. To the slave FIFOs, it is as if the triggers never occurred.
•
void isMissed(bool missedState);
Sets the missed state of the acquisition.
Parameters
missedState
268
The new missed state.
CVL Class Reference
ccAcqFailure
isOverrun
bool isOverrun() const;
void isOverrun(bool overrun);
•
bool isOverrun() const;
Returns true if the acquisition failed because a trigger was received, but an image could
not be acquired. Otherwise returns false.
This error occurs when a trigger caused image integration by the camera, but the image
could not be acquired from the camera. Generally, isOverrun() errors occur when
triggers are arriving too frequently.
If a master FIFO fails because of an isOverrun() condition, the slave FIFOs may
successfully complete their acquisitions.
Notes
This function always returns false on a Cognex MVS-8120 with CVM1 or CVM6.
On a CVM4 (Cognex CVC-1000 camera), ccAcqFailure may report either
isOverrun() or isMissed().
•
void isOverrun(bool overrun);
Sets the overrun property of the acquisition.
Parameters
overrun
isAbnormal
The overrun state.
bool isAbnormal();
void isAbnormal(bool abnormalState);
•
bool isAbnormal();]
Returns true if the acquisition failed because a trigger was received, but an image could
not be acquired. Otherwise returns false.
This error occurs when a trigger caused image integration by the camera, but the image
could not be acquired from the camera. Generally, isAbnormal() errors are caused by
factors unrelated to trigger rate, such as PCI bus saturation, blown camera fuse,
overheating, and so on. If you are experiencing isAbnormal() errors, consult the release
notes and hardware-specific documentation to determine the possible causes of the
errors.
For the 8100L, isAbnormal() can return true if the camera is not connected, or if the
hardware is dropping pixel data because of excessive PCI bus latencies.
CVL Class Reference
269
ccAcqFailure
Notes
This failure should never happen in a properly functioning system. Some examples
of abnormal failures are a blown camera fuse or a temperature alert that indicates
that the frame grabber is overheating.
•
void isAbnormal(bool abnormalState);
Sets the abnormal state of the acquisition.
Parameters
abnormalState
isIncomplete
The new abnormal state.
bool isIncomplete() const;
void isIncomplete(bool incompleteState);
•
bool isIncomplete() const;
Returns true if the acquisition failed because the ccAcqFifo::baseComplete() maxWait
interval expired before the acquisition entered the complete state
(ccAcqFifo::isComplete() returns true).
Notes
Although using maxWait as a timeout timer is one possible design choice, the preferred
approach is to leave maxWait set to the default (HUGE_VAL) and the use
ccAcqFifo::isComplete() to determine when an acquisition is completed. This will
avoid isIncomplete() errors entirely.
•
void isIncomplete(bool incompleteState);
Sets the incomplete state of the acquisition.
Parameters
incompleteState The new incomplete state.
270
CVL Class Reference
ccAcqFailure
isTooFastEncoder
bool isTooFastEncoder() const;
void isTooFastEncoder(bool tooFastState);
•
bool isTooFastEncoder() const;
Returns true if the acquisition failed because of a line overrun situation. This situation is
the result of one or more of the following conditions:
•
The line rate being dictated by the position counter is exceeding the output line
rate of the camera.
•
The value given to ccEncoderProp::stepsPerLine() is too small given the rate
at which the position counter increments or decrements/.
•
The value given to ccExposureProp::exposure() maps to a line exposure
interval that exceeds the length of a line as specified by the position counter
and ccEncoderProp::stepsPerLine(). This condition applies only when using
cameras that support a variable line exposure interval.
Notes
This error occurs only with line scan cameras.
•
void isTooFastEncoder(bool tooFastState);
Sets the “too fast” state of the acquisition.
Parameters
tooFastState
isInvalidRoi
The new “too fast” state.
bool isInvalidRoi() const;
void isInvalidRoi(bool invalid);
bool isInvalidRoi() const;
Returns true if an acquisition could not be performed because the region of interest
property was invalid (see ccRoiProp on page 2367). Typically, a region of interest that
is too large will generate this error.
CVL Class Reference
271
ccAcqFailure
Notes
Some cameras, such as line scan cameras, are implemented with a direct relationship
between the ROI property and the image acquired. In these cases, it is possible to
specify a ROI outside of the physical bounds of the camera and frame grabber
combination.
void isInvalidRoi(bool invalid);
Sets the invalid region of interest property of the acquisition.
Parameters
invalid
The invalid state.
abnormalErrorCode
c_Int32 abnormalErrorCode() const;
void abnormalErrorCode(c_Int32);
For Cognex use only. In some circumstances, technical support may ask you to use this
function to gather more data to help them locate the problem.
•
c_Int32 abnormalErrorCode() const;
Returns error information specific to a particular hardware platform thrown by
acquisition hardware because of some unusual condition.
•
void abnormalErrorCode(c_Int32);
Sets an abnormal error code.
Parameters
c_Int32
isTimingError
The error code.
bool isTimingError() const;
void isTimingError(bool flag);
•
bool isTimingError() const;
Returns true if there is a grievous video timing error that prevented the acquisition from
occurring. This is commonly caused by attempting to acquire when the camera is not
plugged in, or when the video format is not appropriate for the camera.
272
CVL Class Reference
ccAcqFailure
Notes
This error will occur only for mismatches that prevent the acquire hardware from working
at all. Other mismatches may cause corrupted images but not this error.
•
void isTimingError(bool);
Sets the timing error flag.
Parameters
flag
The timing error flag.
Deprecated Members
isOtherFifoError
bool isOtherFifoError() const;
void isOtherFifoError(bool error);
This function has been deprecated and is maintained for backward compatibility only.
It should not be used in new applications.
•
bool isOtherFifoError() const;
Returns true if the acquisition failed because of a failure on a master or slave acquisition
FIFO.
•
void isOtherFifoError(bool error);
Sets the other error property of the acquisition.
Parameters
error
isTimeout
The error state.
bool isTimeout();
void isTimeout(bool timeoutState);
This function has been deprecated and is maintained for backward compatibility only.
It should not be used in new applications.
CVL Class Reference
273
ccAcqFailure
•
bool isTimeout();
Returns true if the acquisition failed because the timeout period elapsed before the
acquisition system was able to obtain the required resources. Returns false otherwise.
Timeout errors can occur when the required hardware is being used by another FIFO.
Notes
This error is never returned in combination with isMissed() or isOverrun().
•
void isTimeout(bool timeoutState);
Sets the timeout state of the acquisition.
Parameters
timeoutState
274
The new timeout state.
CVL Class Reference
ccAcqFifo
#include <ch_cvl/acqbase.h>
class ccAcqFifo : public virtual ccRepBase;
Class Properties
Copyable
No
Derivable
Cognex-supplied classes
only
Archiveable
No
You create ccAcqFifo objects by calling ccStdVideoFormat::newAcqFifoEx() which
returns various instantiations derived from this class. You use ccAcqFifo methods to
acquire images for all concrete fifo types.
Notes
Using ccAcqFifo::complete() in derived classes to handle acquired images is now
replaced by ccAcqFifo::completeAcq(). The older method is retained for
backward compatibility, but you should use ccAcqFifo::completeAcq() for all new
code.
Constructors/Destructors
ccAcqFifo
virtual ~ccAcqFifo();
ccAcqFifo(ccAcqFifo&);
•
virtual ~ccAcqFifo();
Destroys the FIFO and cancels all outstanding acquisitions on it.
•
ccAcqFifo(ccAcqFifo&);
Copy constructor.
CVL Class Reference
275
ccAcqFifo
Enumerations
ceStartReqStatus
enum ceStartReqStatus;
These constants provide additional information about the state of an acquisition request
after a call to baseComplete() or complete() in the derived classes.
Value
Meaning
ckStartReqWasServiced
•
A new call to start() is needed to get the next
image.
•
The returned appTag is valid.
•
The complete() call is in sync with the other
FIFOs of the master-slave sequence.
•
A new call to start() is not needed to get the
next image.
•
The returned appTag is not valid.
•
The complete() call is out of sync with the other
FIFOs of the master-slave sequence.
ckStartReqNotServiced
enum
enum {kMaxOutstanding = 32};
The maximum number of outstanding acquisitions supported per FIFO. Attempting to
have more than this number of acquisitions outstanding at one time causes either start()
to return false (if the trigger model specifies ckRequestAcquireOrFail as its
startAction()) or a ccAcqFailure::isMissed failure otherwise.
276
CVL Class Reference
ccAcqFifo
Public Member Functions
start
bool start(c_UInt32 appTag = 0);
Requests that an acquisition be started as soon as possible. The request is added to
the FIFO of outstanding acquisitions. A copy of the current property values is stored with
the request, so that subsequent changes to this FIFO’s properties have no effect on the
outstanding acquisitions.
Returns true to indicate the start request was successful. A return of false means the
resources were not available and the requested acquisition will not take place.
appTag is an arbitrary value supplied by the application for identifying this acquisition
request. The value is returned by the matching complete() or baseComplete()
invocation. The value is not interpreted by ccAcqFifo. Typically, the appTag is used to
facilitate FIFO order integrity verification.
Parameters
appTag
An application defined value that identifies this acquisition
request.
Notes
The exact behavior of start() is controlled by ccTriggerModel::startAction(). See
ceStartAction on page 2718.
See prepare() for a description of what it means to start an acquisition “as soon as
possible.”
triggerEnabled() must be true for acquisitions to proceed.
Throws
ccAcqFifo::StartNotAllowed
The selected trigger model does not allow start() to be invoked.
See ceStartAction on page 2718.
CVL Class Reference
277
ccAcqFifo
baseComplete
cc_PelBuffer* baseComplete (
const ccAcqFifo::CompleteArgs& args);
cc_PelBuffer* baseComplete (
ccAcqFailure* failure=0,
c_UInt32* appTag = 0,
bool makeLocal = true,
double maxWait = HUGE_VAL,
bool autoStart = false,
ceStartReqStatus* startReqStatus = 0);
Notes
Using baseComplete() or complete() in derived classes to handle acquired
images is now replaced by ccAcqFifo::completeAcq(). The older method is
retained for backward compatibility, but you should use
ccAcqFifo::completeAcq() for all new code.
Classes derived from this class override this function to return a more specific
ccPelBuffer<P> type. Derived classes typically also supply a function, complete(),
which is similar to baseComplete() but which returns a ccPelBuffer object rather
than a pointer to one.
The returned pel buffer is a window onto the valid pixels of a pelroot. The underlying
pelroot may be larger than this window. For example, the width of the underlying
pelroot is often larger to accommodate DMA transfer alignment restrictions
imposed by each frame grabber. In this case, the returned pel buffer is a window
onto the valid pixels, and the underlying pelroot is larger and contains invalid pixel
data. Avoid resizing or repositioning the pel buffer to include the invalid pixel data,
since there is no guarantee on the contents of this memory.
278
CVL Class Reference
ccAcqFifo
The first baseComplete() overload takes a ccAcqFifo::CompleteArgs object to specify
its parameters. Using CompleteArgs allows you to specify any parameter in any order
without having to specify the preceding parameters. For more information on the
baseComplete() parameters see CompleteArgs on page 3425.
Using the second baseComplete() overload you specify individual parameters as call
arguments. This syntax has the following limitations, compared to the first overload:
1.
Arguments must be specified in the given order, even when not making use of a
particular argument. For example, if you wish only to change the maxWait timeout
value, you must also specify the three preceding parameters.
2.
You cannot specify the use of a ccAcquireInfo object to contain the results of the
image acquisition. The ccAcquireInfo::triggerNum() feature does not have an
analogous argument in the old form, and thus cannot be used with the old form.
The recommended way to examine or test the results of an image acquisition is to
specify a ccAcquireInfo object to contain the results. This object is specified as a
CompleteArgs parameter, as shown in the second example on page 280. For more
information on ccAcquireInfo objects, see ccAcquireInfo on page 315.
•
cc_PelBuffer* baseComplete (
const ccAcqFifo::CompleteArgs& args);
Specify parameters in a CompleteArgs object. See CompleteArgs on page 3425.
Returns the image of the oldest completed outstanding image acquisition in the FIFO,
and removes it from the FIFO. If there are no completed acquisitions in the FIFO, this
function waits for one.
Returns null if the acquisition failed or if the ccAcqFifo::CompleteArgs().maxWait()
period has elapsed. In this case, the ccAcquireInfo object you specified with
ccAcqFifo::CompleteArgs contains the reason the acquisition failed.
Parameters
args
A completion arguments object.
Throws
ccPel::BadWindow
You specified a region of interest, but the intersection of the ROI
and the entire window was a null rectangle. See ccRoiProp on
page 2367.
CVL Class Reference
279
ccAcqFifo
Example
This code fragment gets an image from an outstanding acquisition:
auto_ptr<cc_PelBuffer> pb(fifo->baseComplete());
if (pb.get())
processImage(*pb);
This code fragment determines how the acquisition failed:
ccAcquireInfo info;
ccPtrHandle<cc_PelBuffer> pb = fifo->baseComplete
(ccAcqFifo::CompleteArgs().acquireInfo(&info));
if (pb)
processImage(*pb);
else if (info.failure().isTimeout())
// Clean up after the timeout
else
// Report or log an unexpected acquisition failure
•
cc_PelBuffer* baseComplete (
ccAcqFailure* failure=0,
c_UInt32* appTag = 0,
bool makeLocal = true,
double maxWait = HUGE_VAL,
bool autoStart = false,
ceStartReqStatus* startReqStatus = 0);
Specify the parameters as arguments.
Parameters
failure
280
See the description of ccAcquireInfo::failure() on page 316.
appTag
See the description of ccAcquireInfo::appTag() on page 316.
makeLocal
See the description of
ccAcqFifo::CompleteArgs().makeLocal() on page 3427.
maxWait
See the description of ccAcqFifo::CompleteArgs().maxWait()
on page 3428.
autoStart
Deprecated parameter. See the description of
ccAcqFifo::CompleteArgs().autoStart() on page 3429.
startReqStatus
See the description of
ccAcqFifo::CompleteArgs().startReqStatus() on page 3428.
CVL Class Reference
ccAcqFifo
completeAcq
virtual ccAcqImagePtrh completeAcq(
const CompleteArgs& args = CompleteArgs()) = 0;
Gets the image of the oldest outstanding acquisition. This call blocks if there is no
outstanding completed acquisition.
The function returns the acquired image. If the acquisition failed or the maxWait period
elapsed the image will be unbound.
Parameters
args
isValid
A completion arguments object.
bool isValid(ccAcqProblem* problem = 0) const;
Returns true if the FIFO is configured properly and is able to perform an image
acquisition.
Parameters
problem
If this function returns false, this optional argument contains the
reason that the FIFO was not configured properly.
Notes
isValid() performs a more comprehensive check of a FIFO’s master/slave
configuration than the ccTriggerProp::triggerMaster() and
ccTriggerProp::couldSlaveTo() methods. If a master/slave configuration does not
perform as expected, use isValid() to check whether the FIFOs are configured
properly. If isValid() returns false, use ccAcqProblem::hasInvalidMaster() or
ccAcqProblem::hasInvalidSlave() to diagnose the problem.
isIdle
bool isIdle() const;
Returns true if there are no outstanding acquisitions on the FIFO.
isWaiting
bool isWaiting() const;
Becomes true when the FIFO begins waiting for start(), and returns to false when
hardware resources are allocated and all setup delays are finished.
isAcquiring
bool isAcquiring() const;
Returns true if the oldest outstanding acquisition is waiting for a trigger signal or is
acquiring an image. For master/slave acquisitions, it becomes true only after the master
and all slaves are ready for acquisition.
CVL Class Reference
281
ccAcqFifo
isMovable
bool isMovable() const;
Returns true if the oldest outstanding acquisition has progressed to the point where the
camera’s field of view can be changed without affecting the acquired image. For
example, for strobed and shuttered acquisitions, this means that the strobe or the
shutter has been fired.
When an acquisition enters this state, the acquisition software invokes the move-part
callback function that you can specify with the move-part callback property. See
ccMovePartCallbackProp on page 1889.
isComplete
bool isComplete() const;
Returns true if the oldest outstanding acquisition has completed, perhaps
unsuccessfully. The next invocation of baseComplete() returns the image if the
acquisition was successful or a null pointer if it was not.
When an acquisition enters this state, the acquisition software invokes the acquisition
complete callback function that you can specify with the acquisition complete callback
property. See ccCompleteCallbackProp on page 1069.
pendingAcqs
c_Int32 pendingAcqs() const;
Returns the number of acquisitions in the pending state. This is the number of
acquisitions requested by start() for which acquisition has not started. To achieve high
frame rate acquisition in manual trigger mode, the FIFO must always have one or more
pending acquisitions.
completedAcqs
c_Int32 completedAcqs() const;
Returns the number of acquisitions in the completed state. This is the number of
completed acquisitions for which the user has not called complete(). This is similar to
isComplete(), except it indicates if more than one completed acquisition is available. If
images are being acquired faster than they are being consumed, the number returned
by completedAcqs() will begin increasing. If left unchecked, this will eventually result
in isMissed or other errors. completedAcqs() can be used to control production line
speed to maximize the inspection rate without generating errors.
availableAcqs
c_Int32 availableAcqs() const;
Returns the number of acquisitions in the available state. This method returns an upper
bound on the number of additional acquisitions that may be added to the FIFO before
errors occur. In manual or semi-automatic trigger mode, calling start() decreases the
282
CVL Class Reference
ccAcqFifo
number of available acquisitions. In auto trigger mode, each trigger decreases the
number of available acquisitions. In all trigger modes, calling complete() and releasing
pel buffers increases available acquisitions.
Notes
The number returned by availableAcqs() is an upper bound and not a guaranteed
minimum. It is intended to be used to detect resource leaks during debugging.
The sum of (pending + completed + available) is not a constant. Acquisitions in
progress are neither pending nor completed.
Calling start() does not always decrease availableAcqs() by one.
Actions of other FIFOs may affect availableAcqs().
pendingAcqs() and completedAcqs() function the same on all platforms and CVL
revisions. availableAcqs() may behave differently between platforms and CVL
revisions. For example, the way available image memory affects availableAcqs()
can vary.
prepare
bool prepare(double maxWait = HUGE_VAL);
This function prepares the video subsystem as needed for this FIFO, waiting up to
maxWait seconds before returning. It returns true if successful and false if not
successful. If prepare() returns false, do not attempt an acquisition with this FIFO, as it
will fail and likely hang.
Calling prepare() does not eliminate or reduce the setup time, but allows the same setup
time to occur prior to calling start(). This is useful if an acquisition cannot be started
immediately, but you want to get the hardware ready now. If an acquisition can start
immediately, there is no performance benefit to calling prepare() before start(). In this
case, the primary use of prepare() is to detect hardware setup problems, such as a
missing camera.
For an acquisition to take place, the FIFO requires that a certain subset of the video
subsystem be in the proper state. For example, a FIFO created to acquire images in
RS-170 640x480 format, requires that the video subsystem switch to RS-170 640x480
timing. If the video subsystem section selected by this FIFO is already in this state, the
FIFO is considered prepared, and acquisitions can begin immediately.
If the FIFO is not prepared when an acquisition starts, the acquisition software starts
preparing the video subsystem automatically and blocks all subsequent acquisitions for
that FIFO until the FIFO is prepared or until the timeout limit is reached. Be aware that
certain state transitions of the video subsystem take a significant amount of time (up to
hundreds of milliseconds) to complete.
The prepare() and isPrepared() functions let you make sure that an acquisition can start
immediately.
CVL Class Reference
283
ccAcqFifo
Notes
isPrepared() is deprecated..
In a typical application, the acquisition FIFOs are always prepared and all acquisitions
start immediately, so most applications do not need to use the prepare() function.
Parameters
maxWait
The number of seconds to wait until the video subsystem is
prepared before returning. The value HUGE_VAL (defined in
<math.h>) indicates that the system should wait indefinitely.
The FIFO should be idle before calling prepare(). If it is not idle
(starts are queued, or you are in auto trigger mode with triggers
enabled), prepare() will assume the hardware is already
prepared and will return true immediately. When the FIFO is idle
there should be no wait, so Cognex recommends you always set
maxWait to 0.
Notes
On most platforms, maxWait has a granularity between 1 millisecond and 1
microsecond.
If ccTriggerProp::triggerEnable() is false and start() calls are queued, prepare()
will return immediately without preparing the FIFO. If you use prepare() you should
call prepare() and then start(), not the reverse.
Calling prepare() on a master or slave FIFO prepares all the associated master and
slave FIFOs. You could prepare each master and slave FIFO individually, but that
would be redundant.
You do not need to call prepare() when using automatic triggering. The acquisition
software performs hardware preparation for you when triggerEnable() is true.
flush
void flush();
Discards all outstanding acquisitions, leaving this FIFO in the idle state. If an acquisition
is in progress, it is cancelled and discarded. If ccTriggerProp::triggerEnable() is true,
this function disables triggers before discarding all acquisitions, then re-enables
triggers.
properties
virtual ccAcqProps& properties()= 0;
Returns a reference to the FIFO’s properties object.
284
CVL Class Reference
ccAcqFifo
Notes
The reference that this function returns is not const so that you can invoke
appropriate ccAcqProps member functions to set individual properties. Derived
classes typically override this function to return a more specific type derived from
ccAcqProps.
propertyQuery
ccAcqPropertyQuery& propertyQuery();
Returns a property query object that you can use to test whether the FIFO supports a
particular property. If the property is supported, this function returns a valid property
object. The returned object may be used to set property values. Both pointer and
reference semantics are supported.
Example
To set the timeout property only if this FIFO supports it, you would write:
ccTimeoutProp* timeoutProp = fifo->propertyQuery();
if (timeoutProp)
timeoutProp->timeout(10.0);
Or, using reference semantics, you would write:
try
{
ccTimeoutProp& timeoutProp = fifo->propertyQuery();
timeoutProp.strobeEnable(true);
}
catch (cmStd bad_cast&)
{
// The timeout property is not supported.
}
triggerModel
void triggerModel(const ccTriggerModel& model);
void triggerModel(ccTriggerModelPtrh model);
const ccTriggerModel& triggerModel() const;
•
void triggerModel(const ccTriggerModel& model);
Sets the trigger model for the current FIFO. The default model is cfManualTrigger(). See
ccTriggerModel on page 2715.
CVL Class Reference
285
ccAcqFifo
Parameters
model
•
A trigger model object, usually created with one of the global
functions cfManualTrigger(), cfAutoTrigger(), cfSemiTrigger(),
or cfSlaveTrigger().
void triggerModel(ccTriggerModelPtrh model);
Sets the trigger model for the current FIFO. Cognex recommends that custom trigger
models be set using the ccTriggerModelPtrh overload. Built-in trigger models (such as
cfManualTrigger) can only be set using the ccTriggerModel& overload.
Parameters
model
•
The name of your custom trigger model object.
const ccTriggerModel& triggerModel() const;
Returns the currently set trigger model for this FIFO.
See also cfManualTrigger() on page 3289, cfAutoTrigger() on page 3103,
cfSemiTrigger() on page 3397, and cfSlaveTrigger() on page 3405.
triggerEnable
void triggerEnable(bool enable);
bool triggerEnable() const;
•
void triggerEnable(bool enable);
Enables or disables triggers. The default is true.
Invoking triggerEnable() for a master camera channel or any of its slaves has the effect
of invoking triggerEnable() for all. That is, masters and slaves have the same
triggerEnable() setting.
Parameters
enable
•
In general, true allows acquisitions to happen and false prevents
acquisitions from happening, depending on the current trigger
model and its state. For more information on each trigger model,
see cfManualTrigger() on page 3289, cfAutoTrigger() on
page 3103, cfSemiTrigger() on page 3397, and
cfSlaveTrigger() on page 3405.
bool triggerEnable() const;
Returns true if triggers are enabled, false otherwise.
286
CVL Class Reference
ccAcqFifo
movePartInfoCallback
void movePartInfoCallback(const ccCallbackAcqInfoPtrh&);
const ccCallbackAcqInfoPtrh& movePartInfoCallback() const;
•
void movePartInfoCallback(const ccCallbackAcqInfoPtrh&);
This function is one of two ways to register a callback class for the movable state:
Method
Features
See
ccAcqFifo::
movePartInfoCallback()
Calls your callback
function, passing a
ccAcquireInfo class.
this section
ccMovePartCallbackProp
Calls your callback
function.
ccMovePartCallbackProp
on page 1889
This function effectively registers a callback function that you want the acquisition
engine to call when the acquisition enters the movable state (that is, when
ccAcqFifo::isMovable() returns true). The movable state is when the camera’s field of
view can be changed without affecting the acquired image.
An unbound handle means no callback will occur.
This function actually registers, not a function, but a callback class you define. Your
callback class contains your callback function, defined as an override of operator()() of
that class.
A ccCallbackAcqInfo class is a special case of a ccCallback1 class in which an
instance of ccAcquireInfo is passed as an argument. This allows your callback function
to use the information about the current state of the acquisition stored in the
ccAcquireInfo object.
The callback function you write should set flags or semaphores in your application that
allow your program to proceed to another state the next time it executes. Your callback
function is executed internally by the acquisition engine, which cannot proceed until
your callback function returns. Callback functions should be short and quick, and must
not block. Callback functions should not call CVL routines such as start() and
complete(). The time taken to execute your callback function blocks the acquisition
engine.
In general, an acquisition enters the movable state during the acquisition’s next-to-last
vertical blank interval. With an RS-170 camera, for example, an acquisition would enter
the movable state 17 ms (one field time) before it enters the complete state.
CVL Class Reference
287
ccAcqFifo
Not all frame grabbers can detect the next-to-last vertical blank interval. When using one
of these frame grabbers, the acquisition enters the movable and complete states at the
same time. In such cases, the move-part callback is always invoked first, followed
immediately by the completion callback.
On the MVS-8100M, MVS-8100C, and MVS-8100C/CPCI (but not the MVS-8100M+
when using CCF-based video formats), you can select between default and optimum
timing of the move-part callback function’s execution. See
cc8100m::movePartTimingChoice on page 196.
For a further discussion, see Using Callback Functions in the Acquiring Images chapter
of the CVL User’s Guide.
Parameters
ccCallbackAcqInfoPtrh
Pointer handle referencing an instance of a callback class you’ve
defined, that contains the callback function you have defined as
an override of operator()() for that class.
•
const ccCallbackAcqInfoPtrh& movePartInfoCallback() const;
Returns a pointer handle to the registered callback class instance for this acquisition.
288
CVL Class Reference
ccAcqFifo
completeInfoCallback
void completeInfoCallback(const ccCallbackAcqInfoPtrh&);
const ccCallbackAcqInfoPtrh& completeInfoCallback() const;
•
void completeInfoCallback(const ccCallbackAcqInfoPtrh&);
This function is one of two ways to register a callback class for the complete state:
Method
Features
See
ccAcqFifo::
completeInfoCallback()
Calls your callback
function, passing a
ccAcquireInfo class.
this section
ccCompleteCallbackProp
Calls your callback
function.
ccCompleteCallbackProp
on page 1069
This function effectively registers a callback function that you want the acquisition
engine to call when the image acquisition is complete. An acquisition enters the
complete state (ccAcqFifo::isComplete() returns true) when the next invocation of
ccAcqFifo::baseComplete() would return the acquired image (if the acquisition was
successful) or null (if the acquisition was not successful).
An unbound handle means no callback will occur.
This function actually registers, not a function, but a callback class you define. Your
callback class contains your callback function, defined as an override of operator()() of
that class.
A ccCallbackAcqInfo class is a special case of a ccCallback1 class in which an
instance of ccAcquireInfo is passed as an argument. This allows your callback function
to use the information about the current state of the acquisition stored in the
ccAcquireInfo object.
The callback function you write should set flags or semaphores in your application that
allow your program to proceed to another state the next time it executes. Your callback
function is executed internally by the acquisition engine, which cannot proceed until
your callback function returns. Callback functions should be short and quick, and must
not block. Callback functions should not call CVL routines such as start() and
complete(). The time taken to execute your callback function blocks the acquisition
engine.
For a further discussion, see Using Callback Functions in the Acquiring Images chapter
of the CVL User’s Guide.
CVL Class Reference
289
ccAcqFifo
Parameters
ccCallbackAcqInfoPtrh
Pointer handle referencing an instance of a callback class you’ve
defined, that contains the callback function you have defined as
an override of operator()() for that class.
•
const ccCallbackAcqInfoPtrh& completeInfoCallback() const;
Returns a pointer handle to the registered callback class instance for this acquisition.
290
CVL Class Reference
ccAcqFifo
overrunInfoCallback
void overrunInfoCallback(const ccCallbackAcqInfoPtrh&);
const ccCallbackAcqInfoPtrh& overrunInfoCallback() const;
•
void overrunInfoCallback(const ccCallbackAcqInfoPtrh&);
This function is one of two ways to register a callback class for the overrun state:
Method
Features
See
ccAcqFifo::
overrunInfoCallback()
Calls your callback
function, passing a
ccAcquireInfo class.
this section
ccOverrunCallbackProp
Calls your callback
function.
ccOverrunCallbackProp
on page 1989
This function effectively registers a callback function that you want the acquisition
engine to call if an overrun occurs. Generally, overrun errors and isMissed() errors
occur when triggers occur too fast. See ccAcqFailure::isOverrun() and
ccAcqFailure::isMissed() for more information about the overrun state.
An unbound handle means no callback will occur.
This function actually registers, not a function, but a callback class you define. Your
callback class contains your callback function, defined as an override of operator()() of
that class.
A ccCallbackAcqInfo class is a special case of a ccCallback1 class in which an
instance of ccAcquireInfo is passed as an argument. This allows your callback function
to use the information about the current state of the acquisition stored in the
ccAcquireInfo object.
The callback function you write should set flags or semaphores in your application that
allow your program to handle the overrun condition the next time it executes. Your
callback function is executed internally by the acquisition engine, which cannot proceed
until your callback function returns. Callback functions should be short and quick, and
must not block. Callback functions should not call CVL routines such as start() and
complete(). The time taken to execute your callback function blocks the acquisition
engine.
For a further discussion, see Using Callback Functions in the Acquiring Images chapter
of the CVL User’s Guide.
CVL Class Reference
291
ccAcqFifo
Parameters
ccCallbackAcqInfoPtrh
Pointer handle referencing an instance of a callback class you’ve
defined, that contains the callback function you have defined as
an override of operator()() for that class.
•
const ccCallbackAcqInfoPtrh& overrunInfoCallback() const;
Returns a pointer handle to the registered callback class instance for this acquisition.
videoFormat
virtual const ccVideoFormat& videoFormat() const = 0;
Returns the video format for which this FIFO was constructed.
frameGrabber
virtual ccFrameGrabber& frameGrabber() const = 0;
Returns the frame grabber for which this FIFO was constructed.
hardwareImagePoolSize
c_Int32 hardwareImagePoolSize() const;
void hardwareImagePoolSize(c_Int32 numberOfImages);
•
c_Int32 hardwareImagePoolSize() const;
Returns the size of the MVS-8600 hardware image pool in number of images.
•
void hardwareImagePoolSize(c_Int32 numberOfImages);
Sets the size, in number of images, of the MVS-8600 hardware image pool used the by
the acquisition FIFO. A larger image pool size reduces the likelihood of acquisition
errors due to system latency or high CPU load. A smaller pool size conserves memory.
For area scan cameras the amount of memory, in bytes, used for the image pool is:
videoFormatWidth * videoFormatHeight * bytesPerPixel * numberOfImages.
For line scan cameras the amount of memory in bytes is:
videoFormatWidth * imageROIHeight * bytesPerPixel * numberOfImages.
In most cases, a minimum pool size of 4 images is recommended. In the case of images
larger than 32MB, a pool size of 2 or 3 images may be used to conserve memory if the
acquisition rate allows..
292
CVL Class Reference
ccAcqFifo
Parameters
numberOfImages
The number of images to allocate in the hardware pool. The
lowest number allowed is 2 images. Specifying zero sets the
number of images to defaultHardwareImagePoolSize().
Notes
This function applies only to the MVS-8600 and MVS-8600e frame grabbers.
If there isn’t enough memory available to create an image pool of the given size,
prepare() returns False, completeAcq() fails, and isAbnormal() is True with error
code 2. In this case, try reducing the pool size. If the pool is exhausted at runtime,
completeAcq() fails, and isAbnormal() is True with error code 7. In this case, try
increasing the pool size.
Throws
ccAcqFifo::BadParams
numberOfImages is 1 or less than zero,.
defaultHardwareImagePoolSize
c_Int32 defaultHardwareImagePoolSize() const;
Returns the default number of images available in the MVS-8600 image pool. For line
scan acquisition default the number of images depends on the image height which you
can adjust with the region of interest (ROI) setting.
Notes
This function applies only to the MVS-8600 and MVS-8600e frame grabbers.
Deprecated Members
isPrepared
bool isPrepared() const;
Returns true if the resources that the FIFO needs to perform an acquisition are ready. If
isPrepared() returns true, an acquisition request begins immediately.
This function is deprecated in CVL 6.2 cr10.
CVL Class Reference
293
ccAcqFifo
Friends
ccDirectDrawSurfacePool
friend class ccDirectDrawSurfacePool;
cc_FGDisplay
friend class cc_FGDisplay;
Typedefs
ccAcqFifoPtrh
typedef ccPtrHandle<ccAcqFifo> ccAcqFifoPtrh;
ccAcqFifoPtrh_const
typedef ccPtrHandle_const<ccAcqFifo> ccAcqFifoPtrh_const;
294
CVL Class Reference
ccAcqImage
#include <acqimage.h>
class ccAcqImage : public virtual ccRepBase
Class Properties
Copyable
No
Derivable
Not Intended
Archiveable
Yes
ccAcqImage holds the information for an acquired image. A ccAcqImage object
containing the acquired image is returned when you call ccAcqFifo::completeAcq().
This class contains the public member functions you can call to convert the acquired
image into various formats. If the requested format is different from the acquired image
format, the acquired image is converted to the requested format and the new image is
returned. The acquired image is unchanged.
If the requested format is the same as the acquired format, the acquired image is
returned directly without copying. Be aware that in this case you are working with the
acquired image, not a copy.
When there is an acquisition error, the returned ccAcqImage object will be unbound. In
this case, calling any of the conversion routines will also result in unbound images.
Check whether an image is bound before making conversion calls.
Image format conversions are done completely in software and can
have a significant impact on system performance. For a one
megapixel image, the conversion can take over 100 milliseconds on
a 1 GHz processor.
Note
The ceImageFormat enum on page 296 lists the possible acquired image formats. All
acquired image formats with the exception of ceImageFormat_Bayer16 can be
converted into formats acceptable to CVL by calling conversion routines in this class.
CVL Class Reference
295
ccAcqImage
Constructors/Destructors
ccAcqImage
ccAcqImage() {}
ccAcqImage(
const ccPelBuffer<c_UInt8>& buf,
ceImageFormat formatAcquired);
ccAcqImage(const ccPelBuffer<ccPackedRGB16Pel>& buf);
ccAcqImage(const ccPelBuffer<ccPackedRGB32Pel>& buf);
ccAcqImage(const cc3PlanePelBuffer& buf);
~ccAcqImage() {}
Notes
Since ccAcqImage objects are returned to you when you call
ccAcqFifo::completeAcq() there is no need for you to create ccAcqImage objects
in your program.
Enumerations
ceImageFormat
enum ceImageFormat;
These values specify all of the possible acquired image formats.
296
Value
Format
Bit Depth
ceImageFormat_Grey8
Monochrome
8 bits/pixel
ceImageFormat_Grey10
Monochrome
10 bits/pixel
ceImageFormat_Grey12
Monochrome
12 bits/pixel
ceImageFormat_Grey16
Monochrome
16 bits/pixel
ceImageFormat_PackedRGB16
[R,G,B]=[5,6,5]
16 bits/pixel
ceImageFormat_PackedRGB32
[a,R,G,B]=[8,8,8,8]
32 bits/pixel
ceImageFormat_Bayer8
Bayer8
8 bits/pixel
ceImageFormat_Bayer16
Bayer16
16 bits/pixel
ceImageFormat_UYYVYY
YUV 4:1:1
12 bits/pixel (average)
ceImageFormat_UYVY
YUV 4:2:2
16 bits/pixel (average)
CVL Class Reference
ccAcqImage
Value
Format
Bit Depth
ceImageFormat_UYV
YUV 4:4:4
24 bits/pixel
ceImageFormat_PackedRGB24
[R,G,B]=[8,8,8]
24 bits/pixel
ceImageFormat_PackedRGB48
[R,G,B]=[16,16,16]
48 bits/pixel
ceImageFormat_PlanarRGB8
R=G=B=8 bits
8 bits/pixel * 3
ceImageFormat_PackedBGR24
[B,G,R]=[8,8,8]
24 bits/pixel
ceImageFormat_Grey16BigEndian
Monochrome
16 bits/pixel
ceImageFormat_Unknown
Unknown video format
Public Member Functions
getGrey8PelBuffer
ccPelBuffer<c_UInt8> getGrey8PelBuffer();
Return the acquired image in ceImageFormat_Grey8 format. If the acquired image
format is not ceImageFormat_Grey8 the acquired image is converted to
ceImageFormat_Grey8 and the new image is returned. The acquired image is
unchanged.
If the acquired image format is ceImageFormat_Grey8, the acquired image is returned
directly without copying. Be aware that in this case you are working with the acquired
image, not a copy.
Throws
ccAcqImage::NotSupported
The conversion of the acquired image format to
ceImageFormat_Grey8 is not supported.
getGrey16PelBuffer
ccPelBuffer<c_UInt16> getGrey16PelBuffer();
Return the acquired image in ceImageFormat_Grey16 format. If the acquired image
format is not ceImageFormat_Grey16 the acquired image is converted to
ceImageFormat_Grey16 and the new image is returned. The acquired image is
unchanged.
If the acquired image format is ceImageFormat_Grey16, the acquired image is returned
directly without copying. Be aware that in this case you are working with the acquired
image, not a copy.
CVL Class Reference
297
ccAcqImage
Throws
ccAcqImage::NotSupported
The conversion of the acquired image format to
ceImageFormat_Grey16 is not supported.
getPackedRGB16PelBuffer
ccPelBuffer<ccPackedRGB16Pel> getPackedRGB16PelBuffer();
Return the acquired image in ceImageFormat_PackedRGB16 format. If the acquired
image format is not ceImageFormat_PackedRGB16 the acquired image is converted to
ceImageFormat_PackedRGB16 and the new image is returned. The acquired image is
unchanged.
If the acquired image format is ceImageFormat_PackedRGB16, the acquired image is
returned directly without copying. Be aware that in this case you are working with the
acquired image, not a copy.
Throws
ccAcqImage::NotSupported
The conversion of the acquired image format to
ceImageFormat_PackedRGB16 is not supported.
getPackedRGB32PelBuffer
ccPelBuffer<ccPackedRGB32Pel> getPackedRGB32PelBuffer();
Return the acquired image in ceImageFormat_PackedRGB32 format. If the acquired
image format is not ceImageFormat_PackedRGB32 the acquired image is converted to
ceImageFormat_PackedRGB32 and the new image is returned. The acquired image is
unchanged.
If the acquired image format is ceImageFormat_PackedRGB32, the acquired image is
returned directly without copying. Be aware that in this case you are working with the
acquired image, not a copy.
Throws
ccAcqImage::NotSupported
The conversion of the acquired image format to
ceImageFormat_PackedRGB32 is not supported.
get3PlanePelBuffer
cc3PlanePelBuffer get3PlanePelBuffer();
Return the acquired image in ceImageFormat_PlanarRGB8 format. If the acquired
image format is not ceImageFormat_PlanarRGB8 the acquired image is converted to
ceImageFormat_PlanarRGB8 and the new image is returned. The acquired image is
unchanged.
298
CVL Class Reference
ccAcqImage
If the acquired image format is ceImageFormat_PlanarRGB8, the acquired image is
returned directly without copying. Be aware that in this case you are working with the
acquired image, not a copy.
Throws
ccAcqImage::NotSupported
The conversion of the acquired image format to
ceImageFormat_PlanarRGB8 is not supported.
isBound
bool isBound() const;
Return true if the image is bound to a root image. Return false otherwise.
isConversionSupported
bool isConversionSupported(
ceImageFormat formatConverted) const;
Return true if the formatConverted conversion is supported. Return false otherwise.
Parameters
formatConverted
The format to test.
isColor
bool isColor() const;
Returns true if the image was acquired using a color video format. Returns false
otherwise.
width
c_Int32 width() const;
Return the width of the acquired image in pixels (if the image is bound).
height
c_Int32 height() const;
Return the height of the acquired image in rows (if the image is bound).
alignModulus
c_Int32 alignModulus() const;
Return the row alignment of the acquired image in bytes (if the image is bound).
rowUpdate
c_Int32 rowUpdate() const;
Return the row update of the acquired image in bytes (if the image is bound).
CVL Class Reference
299
ccAcqImage
formatAcquired
ceImageFormat formatAcquired() const;
Return the format of the acquired image (if the image is bound).
Typedefs
ccAcqImagePtrh
300
typedef ccPtrHandle<ccAcqImage> ccAcqImagePtrh;
CVL Class Reference
ccAcqProblem
#include <ch_cvl/acqprob.h>
class ccAcqProblem;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class contains member functions that help you identify why a FIFO is improperly
configured. You should use these functions when ccAcqFifo::isValid() returns false.
For more information about valid FIFOs and using ccAcqProblem, see the CVL User’s
Guide and the acqprob.cpp sample program.
Attempting to acquire from an invalid FIFO is not recommended, and can result in image
corruption and may hang your program. However, this is a recommendation and is not
strictly enforced.
Note that member functions in this class attempt to identify a set of common problems
and may not identify every possible problem. You may encounter problems in your
application that ccAcqProblem does not specifically identify.
Constructors/Destructors
ccAcqProblem
ccAcqProblem();
ccAcqProblem(const ccAcqProblem&);
virtual ccAcqProblem::~ccAcqProblem();
•
ccAcqProblem();
Default constructor.
•
ccAcqProblem(const ccAcqProblem&);
Copy constructor.
CVL Class Reference
301
ccAcqProblem
•
virtual ccAcqProblem::~ccAcqProblem();
Destructor.
Operators
bool
operator bool() cons;
Casting this class to bool returns true if the acquisition is configured improperly. It
returns false otherwise.
operator=
ccAcqProblem& operator=(const ccAcqProblem& prob);
Assignment operator. Assigns the value of prob to this object.
Parameters
prob
The value to assign.
Public Member Functions
slavePortInvalid
bool slavePortInvalid() const;
Returns true if the camera port settings are invalid. While the individual camera port
settings for each FIFO may be valid, two FIFOs may be erroneously assigned to the
same camera. Another possibility is that the master/slave arrangement may violate a
platform-specific requirement. For example, a platform may require the slave FIFO to be
on the next higher port from the master.
slaveNotSlaveTrigger
bool slaveNotSlaveTrigger() const;
Returns true if a FIFO has been assigned a trigger master but not assigned a slave
trigger model.
slaveTriggerNoMaster
bool slaveTriggerNoMaster() const;
Returns true if the FIFO has a slave trigger model but has not been assigned a trigger
master.
302
CVL Class Reference
ccAcqProblem
masterIsSlaveTrigger
bool masterIsSlaveTrigger() const;
Returns true if trigger master is assigned the slave trigger model. A trigger master
cannot be slaved to another FIFO.
mismatchedExposures
bool mismatchedExposures() const;
Returns true if the master and slaves are using different exposure settings. The
exposures for all master/slaved FIFOs must be set to identical values to ensure the
cameras stay synchronized for shared strobe applications.
This problem can be ignored when using the CVC-1000 and non-strobed acquisitions.
mismatchedFormats
bool mismatchedFormats() const;
Returns true if master and slave FIFOs are using different camera formats. In most cases
you application will hang when you attempt to acquire images with this condition.
It may be possible to master/slave compatible cameras, for example two different
RS-170 type cameras that have identical CTIs. This can occur when individual cameras
are replaced with a later model or different brand. However any differences in video
timing will cause problems in master/slave applications.
invalidCameraPort
bool invalidCameraPort() const;
Returns true if the camera port setting is outside the range of 0 - numCameraPort()-1
invalidAuxLightPort
bool invalidAuxLightPort() const;
Returns true if lighting is enabled and the aux light port setting is outside the range of
0 - 4, or if it is in conflict with the camera port setting. If an acquire is attempted the aux
light will not work.
tooFewPorts
bool tooFewPorts() const;
Returns true if, in a master/slave configuration, there are not enough camera ports to
support the number of taps needed for all the cameras.
CVL Class Reference
303
ccAcqProblem
badSyncModel
bool badSyncModel() const;
Returns true if, in a master/slave configuration, a slave is set to an improper sync model.
Deprecated Members
The following functions are deprecated and are maintained for backward compatibility
only. These functions should not be used in new applications.
hasInvalidSlave
bool hasInvalidSlave() const;
Returns true when the FIFO is invalid due to some master/slave problem. Other methods
in this class provide information regarding why the master/slave setup is invalid.
This problem can occur due to limitations or constraints of the frame grabber associated
with selecting master and slave ccAcqFifos. Check your frame grabber-specific
documentation for constraints regarding ccAcqFifos. For example, check the camera
port intended for master/slave acquisitions.
hasInvalidMaster
bool hasInvalidMaster() const;
Returns true when the FIFO is invalid due to some master/slave problem. Other methods
in this class provide information regarding why the master/slave setup is invalid.
This problem can occur due to limitations or constraints of the frame grabber associated
with selecting master and slave ccAcqFifos. Check your frame grabber-specific
documentation for constraints regarding ccAcqFifos. For example, check the camera
port intended for master/slave acquisitions.
304
CVL Class Reference
ccAcqPropertyQuery
#include <ch_cvl/prop.h>
class ccAcqPropertyQuery;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
No
This class is used with ccAcqFifo::propertyQuery() to determine whether a FIFO
supports a particular property. When cast implicitly or explicitly to any of the property
classes, the resulting cast returns a pointer or a reference to the property class. If the
property is not supported, it returns a null pointer, or, in the case of reference semantics,
throws std::bad_cast.
For example, to set the timeout property only if a FIFO supports it, you would write:
ccContrastBrightnessProp* contrastBrightnessProp =
fifo->propertyQuery();
if (contrastBrightnessProp)
contrastBrightnessProp->contrastBrightness(0.5, 0.5);
Or, using reference semantics, you would write:
try
{
ccContrastBrightnessProp& contrastBrightnessProp =
fifo->propertyQuery();
contrastBrightnessProp.contrastBrightness(0.5, 0.5);
}
catch (cmStd bad_cast&)
{
// The contrast/brightness property is not supported.
}
The constructor and destructor for this class are protected.
CVL Class Reference
305
ccAcqPropertyQuery
Operators
All of the cast operators for the ccAcqPropertyQuery class are public.
The cast-to-pointer operators all return a pointer to a property object, if the FIFO
supports that property. If not, they return a null pointer.
The cast-to-reference operators all return a reference to a property object, if the FIFO
supports that property. If not, they throw an std::bad_cast exception. Table 1 lists the
type-safe property cast operators and their signatures.
Cast Operator
Signature
operator ccTriggerProp* ()
virtual operator ccTriggerProp* () const;
operator ccTriggerProp& ()
virtual operator ccTriggerProp& () const;
operator ccTriggerFilterProp* ()
virtual operator ccTriggerFilterProp* () const;
operator ccTriggerFilterProp& ()
virtual operator ccTriggerFilterProp& () const;
operator ccStrobeProp* ()
virtual operator ccStrobeProp* () const;
operator ccStrobeProp& ()
virtual operator ccStrobeProp& () const;
operator ccStrobeDelayProp* ()
virtual operator ccStrobeDelayProp* () const;
operator ccStrobeDelayProp& ()
virtual operator ccStrobeDelayProp& () const;
operator ccExposureProp* ()
virtual operator ccExposureProp* () const;
operator ccExposureProp& ()
virtual operator ccExposureProp& () const;
operator ccSettlingTimeProp* ()
virtual operator ccSettlingTimeProp* () const;
operator ccSettlingTimeProp& ()
virtual operator ccSettlingTimeProp& () const;
operator ccTimeoutProp* ()
virtual operator ccTimeoutProp* () const;
operator ccTimeoutProp& ()
virtual operator ccTimeoutProp& () const;
operator ccCameraPortProp* ()
virtual operator ccCameraPortProp* () const;
operator ccCameraPortProp& ()
virtual operator ccCameraPortProp& () const;
operator ccCameraLocationProp* ()
virtual operator ccCameraLocationProp* () const;
operator ccCameraLocationProp& ()
virtual operator ccCameraLocationProp& () const;
operator ccMovePartCallbackProp* ()
virtual operator ccMovePartCallbackProp* () const;
operator ccMovePartCallbackProp& ()
virtual operator ccMovePartCallbackProp& () const;
Table 1.
306
Cast operators used for property queries with ccAcqPropertyQuery class
CVL Class Reference
ccAcqPropertyQuery
Cast Operator
Signature
operator ccOverrunCallbackProp* ()
virtual operator ccOverrunCallbackProp* () const;
operator ccOverrunCallbackProp& ()
virtual operator ccOverrunCallbackProp& () const;
operator ccCompleteCallbackProp* ()
virtual operator ccCompleteCallbackProp* () const;
operator ccCompleteCallbackProp& ()
virtual operator ccCompleteCallbackProp& () const;
operator ccPelRootPoolProp* ()
virtual operator ccPelRootPoolProp* () const;
operator ccPelRootPoolProp& ()
virtual operator ccPelRootPoolProp& () const;
operator ccCtiProp* ()
virtual operator ccCtiProp* () const;
operator ccCtiProp& ()
virtual operator ccCtiProp& () const;
operator ccHorizAdjustProp* ()
virtual operator ccHorizAdjustProp* () const;
operator ccHorizAdjustProp& ()
virtual operator ccHorizAdjustProp& () const;
operator ccRoiProp* ()
virtual operator ccRoiProp* () const;
operator ccRoiProp& ()
virtual operator ccRoiProp& () const;
operator ccSyncProp* ()
virtual operator ccSyncProp* () const;
operator ccSyncProp& ()
virtual operator ccSyncProp& () const;
operator ccLightProp* ()
virtual operator ccLightProp* () const;
operator ccLightProp& ()
virtual operator ccLightProp& () const;
operator cc8BitInputLutProp* ()
virtual operator cc8BitInputLutProp* () const;
operator cc8BitInputLutProp& ()
virtual operator cc8BitInputLutProp& () const;
operator ccContrastBrightnessProp* ()
virtual operator ccContrastBrightnessProp* () const;
operator ccContrastBrightnessProp& ()
virtual operator ccContrastBrightnessProp& () const;
operator ccFirstPelOffsetProp* ()
virtual operator ccFirstPelOffsetProp* () const;
operator ccFirstPelOffsetProp& ()
virtual operator ccFirstPelOffsetProp& () const;
operator ccEncoderControlProp* ()
virtual operator ccEncoderControlProp* () const;
operator ccEncoderControlProp& ()
virtual operator ccEncoderControlProp& () const;
operator ccEncoderProp* ()
virtual operator ccEncoderProp* () const;
operator ccEncoderProp& ()
virtual operator ccEncoderProp& () const;
Table 1.
Cast operators used for property queries with ccAcqPropertyQuery class
CVL Class Reference
307
ccAcqPropertyQuery
Cast Operator
Signature
operator ccClippingProp* ()
virtual operator ccClippingProp* () const;
operator ccClippingProp& ()
virtual operator ccClippingProp& () const;
operator ccOffsetClampProp* ()
virtual operator ccOffsetClampProp* () const;
operator ccOffsetClampProp& ()
virtual operator ccOffsetClampProp& () const;
operator ccAlphaColorProp* ()
virtual operator ccAlphaColorProp* () const;
operator ccAlphaColorProp& ()
virtual operator ccAlphaColorProp& () const;
operator ccDigitalCameraControlProp* ()
virtual operator ccDigitalCameraControlProp* () const;
operator ccDigitalCameraControlProp& ()
virtual operator ccDigitalCameraControlProp& () const;
operator ccSampleProp* ()
virtual operator ccSampleProp* () const;
operator ccSampleProp& ()
virtual operator ccSampleProp& () const;
operator ccReadoutDirectionProp* ()
virtual operator ccReadoutDirectionProp* () const;
operator ccReadoutDirectionProp& ()
virtual operator ccReadoutDirectionProp& () const;
operator ccCameraTestProp* ()
virtual operator ccCameraTestProp* () const;
operator ccCameraTestProp& ()
virtual operator ccCameraTestProp& () const;
operator ccCdcCameraCalibrationProp* ()
virtual operator ccCdcCameraCalibrationProp* () const;
operator ccCdcCameraCalibrationProp& ()
virtual operator ccCdcCameraCalibrationProp& () const;
Table 1.
308
Cast operators used for property queries with ccAcqPropertyQuery class
CVL Class Reference
ccAcqProps
#include <ch_cvl/prop.h>
class ccAcqProps :
public ccTriggerProp,
public ccTriggerFilterProp,
public ccStrobeProp,
public ccStrobeDelayProp,
public ccExposureProp,
public ccSettlingTimeProp,
public ccTimeoutProp,
public ccCameraPortProp,
public ccCameraLocationProp,
public ccMovePartCallbackProp,
public ccOverrunCallbackProp,
public ccCompleteCallbackProp,
public ccPelRootPoolProp,
public ccCtiProp,
public ccHorizAdjustProp,
public ccRoiProp,
public ccSyncProp,
public ccLightProp,
public cc8BitInputLutProp,
public ccContrastBrightnessProp,
public ccFirstPelOffsetProp,
public ccEncoderControlProp,
public ccEncoderProp,
public ccClippingProp,
public ccOffsetClampProp,
public ccAlphaColorProp,
public ccDigitalCameraControlProp,
public ccCameraTestProp,
public ccSampleProp,
public ccReadoutDirectionProp,
public ccCdcCameraCalibrationProp;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This is the base class for all properties that are common to all ccAcqFifo types.
CVL Class Reference
309
ccAcqProps
ccAnalogAcqProps
ccRoiProp
ccAcqProps
ccSampleProp
ccTriggerProp
ccExposureProp
ccStrobeProp
ccTimeoutProp
ccCtiProp
ccEncoderProp
ccSyncProp
cc8BitInputLutProp
ccClippingProp
ccLightProp
ccHorizAdjustProp
ccAlphaColorProp
ccCameraPortProp
ccPelRootPoolProp
ccOffsetClampProp
ccCameraTestProp
ccSettlingTimeProp
ccStrobeDelayProp
ccEncoderControlProp
ccFirstPelOffsetProp
ccMovePartCallbackProp
ccCameraLocationProp
ccTriggerFilterProp
ccContrastBrightnessProp
ccReadoutDirectionProp
ccOverrunCallbackProp
ccCdcCameraCalibrationProp
ccCompleteCallbackProp
ccDigitalCameraControlProp
The above figure shows the ccAcqProps class inheritance hierarchy.
Constructors/Destructors
ccAcqProps
ccAcqProps();
Creates a properties object not associated with any FIFO. All values are default values.
310
CVL Class Reference
ccAcuBarCodeCalibrationResult
#include <ch_cvl/acubar.h>
class ccAcuBarCodeCalibrationResult;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class contains the results of applying the calibrate operation to the Barcode tool.
ccAcuBarCodeCalibrationResult
1
decodeResult_:ccAcuBarCodeResult
ccAcuBarCodeRunParams
ccAcuBarCodeTuneParams
ccPersistent
Constructors/Destructors
Uses the compiler-generated default constructor, copy constructor, destructor, and
assignment operator.
CVL Class Reference
311
ccAcuBarCodeCalibrationResult
Public Member Functions
isCalibrated
bool isCalibrated() const;
Returns true if calibration is successful, false otherwise. Calibration is considered
successful if the associated decode operation, using the calibrated barcode properties,
is successful, that is if the score of the decode operation is greater than or equal to the
accept threshold.
symbolType
ccAcuBarCodeDefs::Symbology symbolType() const;
Returns the type of 1D symbology found. The symbology must have been computed as
a result of calibration.
resultWindow
ccPelRect resultWindow(bool includeQuietZone) const;
Returns an image-coordinate-aligned rectangle that best fits the limits of the barcode.
Parameters
includeQuietZone
If includeQuietZone is true, the rectangle returned includes the
leading and trailing quiet zones. If includeQuietZone is false, the
rectangle returned encloses just the barcode and does not
include the leading and trailing quiet zones.
Notes
The position of the barcode is the center of this best-fit rectangle.
pitch
double pitch() const;
Returns the pitch of the barcode in pixels. The pitch of the barcode is the average
spacing between consecutive bars.
stringLength
c_Int32 stringLength() const;
Returns the length of the encoded string. This includes the check character, if any. For
Code128, the check character is not present in the returned string.
scanDirection
ccAcuBarCodeDefs::ScanDirection scanDirection() const;
Returns eLeftToRight or eRightToLeft to indicate the orientation of the barcode. The
orientation must have been computed as a result of calibration.
312
CVL Class Reference
ccAcuBarCodeCalibrationResult
clientFromImageXform
const cc2Xform &clientFromImageXform() const;
Returns the client-from-image transform required to translate image coordinates to client
coordinates.
time
double time() const;
Returns the time in seconds required to compute this result.
decodeResult
const ccAcuBarCodeResult &decodeResult() const;
Returns the result of decoding the barcode using the calibrated barcode properties. The
result object must have been computed as a result of calibration.
operator==
bool operator== (const ccAcuBarCodeCalibrationResult& that)
const;
Returns true if *this equals that, false otherwise. Two ccAcuBarCodeCalibrationResult
objects are considered equal if all of their corresponding data members are equal
except the time. Doubles are compared using cfRealEq() (see ch_cvl/math.h) with 1.e-8
as the tolerance.
Parameters
that
CVL Class Reference
ccAcuBarCodeCalibrationResult object being compared to the
current one.
313
ccAcuBarCodeCalibrationResult
314
CVL Class Reference
ccAcquireInfo
#include <ch_cvl/acqbase.h>
class ccAcquireInfo;
Class Properties
Copyable
No
Derivable
No
Archiveable
No
This class stores information about an image acquisition, which can be retrieved when
calling completeAcq() for that acquisition, or when calling a callback function.
You can examine or test the results of an image acquisition by declaring a
ccAcquireInfo object to contain the results. You pass this object as a
ccAcqFifo::CompleteArgs parameter to completeAcq() as shown in this code
fragment:
ccAcquireInfo info;
ccAcqImagePtrh img = fifo->completeAcq
(ccAcqFifo::CompleteArgs().acquireInfo(&info));
To pass a ccAcquireInfo object to a callback function, use the ccAcqFifo member
function completeInfoCallback(), movePartInfoCallback(), or overrunInfoCallback(),
as appropriate. These functions register a callback function that the acquisition engine
calls at certain times. These callback functions can use member functions of the
ccAcquireInfo instance passed to them by the acquisition engine.
Constructors/Destructors
ccAcquireInfo
ccAcquireInfo();
Default constructor, used when creating an object to supply to completeAcq().
CVL Class Reference
315
ccAcquireInfo
Public Member Functions
appTag
c_UInt32 appTag() const;
Returns the apptag for this acquisition, if one was specified by ccAcqFifo::start().
An apptag is an arbitrary integer optionally applied to each image acquisition initiated
with ccAcqFifo::start(). An application can assign a tag to each acquisition, and match
it to the tag returned by appTag() on completion of the acquisition, or on invocation of a
callback function.
triggerNum
c_UInt32 triggerNum() const;
Returns the FIFO’s current trigger number count.
A trigger number is a monotonically increasing integer value (excepting integer
wraparound) that counts the number of triggers processed by the acquisition FIFO. The
trigger number count is maintained automatically by the image acquisition engine, to the
best of its ability. You do not need to initialize or start the count of trigger numbers. The
trigger number count starts over when the acquisition FIFO object is instantiated.
For some applications, using the trigger number provides an easier method of tracking
missed triggers than using failure().IsMissed() errors. Tracking the trigger number is
particularly useful if the trigger model is semi-automatic or custom, where
failure().IsMissed() errors require extra calls to complete() relative to the number of
calls to start().
failure
ccAcqFailure failure() const;
Returns the ccAcqFailure object associated with this image acquisition.
Member functions of ccAcqFailure allow you to query the reason an image acquisition
failed. See ccAcqFailure on page 267. The ccAcqFailure object is passed as part of
the ccAcquireInfo object you associate with each image acquisition.
You can test the success of an acquisition as shown in this code fragment:
ccAcquireInfo info;
ccAcqImagePtrh img = fifo->completeAcq
(ccAcqFifo::CompleteArgs().acquireInfo(&info));
...
if (info.failure())
// Acquisition failed, find out why
if (info.failure().isIncomplete())
...
316
CVL Class Reference
ccAcquireInfo
Typedefs
ccCallbackAcqInfo
typedef ccCallback1<const ccAcquireInfo&>
ccCallbackAcqInfo;
ccCallbackAcqInfoPtrh
typedef ccPtrHandle<ccAcquireInfoCB>
ccCallbackAcqInfoPtrh;
CVL Class Reference
317
ccAcquireInfo
318
CVL Class Reference
ccAcuBarCodeDefs
#include <ch_cvl/acubar.h>
class ccAcuBarCodeDefs;
A name space that holds enumerations used with the Barcode tool classes.
Enumerations
FieldType
enum FieldType;
Field string specifiers.
CVL Class Reference
Value
Meaning
eLastField
Termination of field map
eAlpha
Character A-Z
eNumeric
Character 0-9
eAlphanumeric
Any alphanumeric
eDash
'-' character
ePeriod
'.' character
eSpace
' ' character
eSemiAlpha
Semichecksum character (0 through 7,
and A through H)
eAll
All characters supported by a particular
symbology
eOther
All characters specified by eAll, but not by
any of the other field types
319
ccAcuBarCodeDefs
Symbology
enum Symbology;
Supported symbologies.
ScanDirection
Value
Meaning
eCode39
Code 39 or Code 3-of-9; supports all 36
alphanumeric characters, seven additional
characters, a variable symbol length, and an
optional checksum.
eBC412
Supports alphanumeric characters, A through Z, 0
through 9, dash (-), and the semichecksum
characters 0 through 7 and A through H.
eIBM412
Supports alphanumeric characters, A through Z, 0
through 9, dash (-), and the semichecksum
characters 0 through 7 and A through H.
eCode128
Supports the entire ASCII character set, plus a
packed decimal representation (2 digits per byte).
enum ScanDirection;
The scan direction for the symbol. This enumeration can be used to set the intended
scan direction and it is used to report the actual scan direction.
Value
Meaning
eLeftToRight
Left-to-right scan.
eRightToLeft
Right-to-left scan.
eBoth
Scan in either direction.
Constants
The following constants specify the maximum number of fields represented by a
barcode. This includes the NULL character.
320
Value
Meaning
kMaxNFieldsCode39 = 21
Maximum number of fields for Code39
kMaxNFieldsIBM412 = 19
Maximum number of fields for IBM412
CVL Class Reference
ccAcuBarCodeDefs
CVL Class Reference
Value
Meaning
kMaxNFieldsBC412 = 19
Maximum number of fields for BC412
kMaxNFieldsCode128 = 45
Maximum number of fields for Code 128
kMaxNFieldChars = 45
Maximum number of acceptable characters in
any field
321
ccAcuBarCodeDefs
322
CVL Class Reference
ccAcuBarCodeResult
#include <ch_cvl/acubar.h>
class ccAcuBarCodeResult : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class contains results obtained from a single decoding operation executed by a
ccAcuBarCodeTool object. An instance of this class is contained within a
ccAcuBarCodeCalibrationResult object.
ccAcuBarCodeCalibrationResult
1
decodeResult_:ccAcuBarCodeResult
ccAcuBarCodeRunParams
ccAcuBarCodeTuneParams
ccPersistent
CVL Class Reference
323
ccAcuBarCodeResult
Constructors/Destructors
ccAcuBarCodeResult
ccAcuBarCodeResult();
virtual ~ccAcuBarCodeResult();
•
ccAcuBarCodeResult();
Constructs a ccAcuBarCodeResult object with the data members initialized to the
following values:
•
Parameter
Initial Value
isFound
false
score
0
decoded string
'‘
symbol type
eBC412
time
0.0
checksumValid
false
scanDirection
eLeftToRight
decodedData
Empty vector
virtual ~ccAcuBarCodeResult();
Destroys an instance of this class.
Operators
operator==
bool operator==(const ccAcuBarCodeResult& that) const;
Returns true if all of the data members except time of this ccAcuBarCodeResult object
are equal to the data members of a second ccAcuBarCodeResult object.
Parameters
that
324
The other parameter set
CVL Class Reference
ccAcuBarCodeResult
Public Member Functions
isFound
bool isFound() const;
Returns true if the string was decoded correctly and the score exceeded the
acceptance threshold, false otherwise.
score
double score() const;
Returns the score that measures the decoding level in the range 0.0 through 1.0. A score
of 1.0 indicates perfect decoding, while a score of 0 indicates decoding that was totally
unsuccessful.
Notes
For any barcode with a checksum, failure to read the checksum sets the score to 0
(always fails).
decodedString
ccCvlString decodedString() const;
Returns the decoded string.
decodedData
cmStd vector<c_UInt8> decodedData() const;
Returns the raw bytes which make up the barcode. For Code 128 symbols, the bytes
returned by this function include all of the characters plus the shift and control codes
defined in the Code 128 symbology.
symbolType
ccAcuBarCodeDefs::Symbology symbolType()
const;
Returns the type of 1D Symbology that was decoded to produce this result.
time
double time() const;
Returns the time required in seconds to compute this result.
checksumValid
bool checksumValid() const;
Returns true if checksum is valid. As defined under “Some Useful Definitions” in the
Barcode Tool chapter of the CVL Vision Tools Guide, a checksum is a “character used
in calculating a check for correct decoding.”
CVL Class Reference
325
ccAcuBarCodeResult
Notes
For any barcode with a checksum, failure to read the checksum sets the score to 0,
which causes the decode() operation to fail. checksumValid() returns true only if a
checksum was present, and the tool was successful in reading the checksum
irrespective of whether the tool passed the acceptance threshold.
scanDirection
ccAcuBarCodeDefs::ScanDirection scanDirection() const;
Returns the direction in which the symbol was scanned. This function returns one of the
following values:
ccAcuBarCodeDefs::eRightToLeft
ccAcuBarCodeDefs::eLeftToRight
326
CVL Class Reference
ccAcuBarCodeRunParams
#include <ch_cvl/acusymbl.h>
class ccAcuBarCodeRunParams: public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
The ccAcuBarCodeRunParams class contains a set of common parameters required
to support the Barcode tool. After you have set up a ccAcuBarCodeRunParams object,
you pass it to ccAcuBarCodeTool::decode(), which performs the decoding operation.
You can set up the lighting parameters yourself, or you can use
ccAcuBarCodeTool::tune() to iterate over several possibilities to create a set of lighting
parameters for you.
Constructors/Destructors
ccAcuBarCodeRunParams
ccAcuBarCodeRunParams(
ccAcuBarCodeDefs::Symbology symbolType =
ccAcuBarCodeDefs::eBC412,
ccAcuBarCodeDefs::FieldType defaultType =
ccAcuBarCodeDefs::eAlphanumeric,
double accept = 0.5,
ccAcuBarCodeDefs::ScanDirection scanDirection =
ccAcuBarCodeDefs::eLeftToRight);
Constructs a ccAcuBarCodeRunParams object, and initializes the symbology type to
that specified by symbolType and the field strings at all positions to those specified by
defaultType. Requires that defaultType be a valid field type for the specified
symbology.
The other parameters are initialized to the following values:
•
checksum is false for Code39 and true for Code128, BC412, and IBM412, which
have built-in error-correcting checksums.
•
lightPower = 0.0.
•
brightFieldPowerRatio = 0.0.
CVL Class Reference
327
ccAcuBarCodeRunParams
Parameters
symbolType
The format for encoding and decoding a specific type of
barcode.
defaultType
The type of character that each field may contain.
accept
The acceptance threshold. Valid range: 0.0 through 1.0. The
acceptance threshold is the percentage of scan lines crossing
the barcode that must correctly decode for the read to pass.
scanDirection
The direction in which to scan the barcode. If you specify
ccAcuBarCodeDefs::eBoth, then the tool attempts to decode the
barcode in both left-to-right and right-to-left directions; it returns
the best score. scanDirection must be one of the following
values:
ccAcuBarCodeDefs::eRightToLeft
ccAcuBarCodeDefs::eLeftToRight
ccAcuBarCodeDefs::eBoth
Notes
BC412 and IBM412 symbologies support the ccAcuBarCodeDefs::eLastField,
ccAcuBarCodeDefs::eAlpha, ccAcuBarCodeDefs::eNumeric,
ccAcuBarCodeDefs::eAlphanumeric, ccAcuBarCodeDefs::eDash,
ccAcuBarCodeDefs::eSemiAlpha, and ccAcuBarCodeDefs::eAll field types.
Code39 and Code128 support all of the aforementioned plus
ccAcuBarCodeDefs::ePeriod, ccAcuBarCodeDefs::eSpace, and
ccAcuBarCodeDefs::eOther.
Throws
ccAcuBarCodeDefs::BadParams
An invalid field type is specified for the symbology type, or
accept is out of range 0.0 through 1.0.
Public Member Functions
accept
double accept() const;
void accept(double acceptVal);
•
double accept() const;
Gets the accept threshold, which is the percentage of scan lines crossing the barcode
that must correctly decode for the read to pass.
328
CVL Class Reference
ccAcuBarCodeRunParams
•
void accept(double acceptVal);
Sets the accept threshold.
Parameters
acceptVal
The accept threshold; requires that acceptVal be between 0.0
and 1.0 inclusive.
Throws
ccAcuBarCodeDefs::BadParams
The value being set is outside the valid range.
changeSymbolAndFieldType
void changeSymbolAndFieldType (
ccAcuBarCodeDefs::Symbology symbolType,
ccAcuBarCodeDefs::FieldType type);
Changes the type of 1D Symbology to be decoded and sets the field strings at all
positions to the type specified by type.
Parameters
symbolType
type
The format for encoding and decoding a specific type of
barcode.
The type of character that each field may contain.
Throws
ccAcuBarCodeDefs::BadParams
An invalid field type is specified for the symbology type.
Notes
BC412 and IBM412 symbologies support the ccAcuBarCodeDefs::eLastField,
ccAcuBarCodeDefs::eAlpha, ccAcuBarCodeDefs::eNumeric,
ccAcuBarCodeDefs::eAlphanumeric, ccAcuBarCodeDefs::eDash,
ccAcuBarCodeDefs::eSemiAlpha, and ccAcuBarCodeDefs::eAll field types.
Code39 and Code128 support all of the aforementioned plus
ccAcuBarCodeDefs::ePeriod, ccAcuBarCodeDefs::eSpace, and
ccAcuBarCodeDefs::eOther.
ccAcuBarCodeRunParams::changeSymbolAndFieldType() invalidates all
previously set field string specifications for the object.
Whenever the symbology of a ccAcuBarCodeRunParams object is changed to
ccAcuBarCodeDefs::eBC412, ccAcuBarCodeDefs::eIBM412,
ccAcuBarCodeDefs::eCode39, or ccAcuBarCodeDefs::eCode128, the checksum
is enabled.
CVL Class Reference
329
ccAcuBarCodeRunParams
checksum
bool checksum() const;
void checksum(bool val);
•
bool checksum() const;
Gets the checksum enable state.
•
void checksum(bool val);
Sets the checksum enable state. (For BC412, IBM412, and Code128 symbologies, val
is always true.)
Parameters
val
True or false depending on whether the tool should perform a
checksum operation.
Notes
For any symbology that has an optional checksum, you can set this parameter to
true or false. For other symbologies, such as BC412 and IBM412 which have built-in
error-correcting checksums, it is always set to true. You cannot toggle this value.
Throws
ccAcuBarCodeDefs::BadParams
The given symbology is ccAcuBarCodeDefs::eBC412,
ccAcuBarCodeDefs::eIBM412, or
ccAcuBarCodeDefs::eCode128, and the setter is passed false.
brightFieldPowerRatio
double brightFieldPowerRatio() const;
void brightFieldPowerRatio(double val);
•
double brightFieldPowerRatio() const;
Returns the bright field power ratio for this object. The bright field power ratio is the
portion (in the range 0.0 through 1.0) of the total light energy allocated to the bright field
lights.
•
void brightFieldPowerRatio(double val);
Sets the bright field power ratio for this object. The bright field power ratio is the portion
(in the range 0.0 through 1.0) of the total light energy allocated to the bright field lights.
330
CVL Class Reference
ccAcuBarCodeRunParams
Parameters
val
The power ratio. Must be in the range 0.0 (full darkfield) through
1.0 (full brightfield).
Throws
ccAcuBarCodeDefs::BadParams
val was out of range.
fieldString
cmStd string fieldString (c_UInt32 position) const;
void fieldString(c_UInt32 position,
const cmStd string &str);
void fieldString(c_UInt32 position,
ccAcuBarCodeDefs::FieldType type);
•
cmStd string fieldString (c_UInt32 position) const;
Returns the acceptable characters in the given field position.
Parameters
position
The character position. Character positions must be between the
following values:
0 and kMaxNFieldsCode39 - 1 inclusive for symbology
ccAcuBarCodeDefs::eCode39
0 and kMaxNFieldsBC412 - 1 inclusive for symbology
ccAcuBarCodeDefs::eBC412
0 and kMaxNFieldsIBM412 - 1 inclusive for symbology
ccAcuBarCodeDefs::eIBM412
0 and kMaxNFieldsCode128 - 1 inclusive for symbology
ccAcuBarCodeDefs::eCode128
Throws
ccAcuBarCodeDefs::BadParams
The position specified is invalid for the symbology type of this
ccAcuBarCodeRunParams object.
•
void fieldString(c_UInt32 position,
const cmStd string &str);
Sets the field string at certain positions.
Parameters
position
CVL Class Reference
The character position. Character positions must be between the
following values:
331
ccAcuBarCodeRunParams
0 and kMaxNFieldsCode39 - 1 inclusive for symbology
ccAcuBarCodeDefs::eCode39
0 and kMaxNFieldsBC412 - 1 inclusive for symbology
ccAcuBarCodeDefs::eBC412
0 and kMaxNFieldsIBM412 - 1 inclusive for symbology
ccAcuBarCodeDefs::eIBM412
0 and kMaxNFieldsCode128 - 1 inclusive for symbology
ccAcuBarCodeDefs::eCode128
str
Valid characters for the symbology type.
Throws
ccAcuBarCodeDefs::BadParams
Position is not in the valid range, or the string contains invalid
characters.
•
void fieldString(c_UInt32 position,
ccAcuBarCodeDefs::FieldType type);
Sets the field string at a particular position to a predefined fieldType value.
Parameters
position
The character position. Character positions must be between the
following values:
0 and kMaxNFieldsCode39 - 1 inclusive for symbology
ccAcuBarCodeDefs::eCode39
0 and kMaxNFieldsBC412 - 1 inclusive for symbology
ccAcuBarCodeDefs::eBC412
0 and kMaxNFieldsIBM412 - 1 inclusive for symbology
ccAcuBarCodeDefs::eIBM412
0 and kMaxNFieldsCode128 - 1 inclusive for symbology
ccAcuBarCodeDefs::eCode128
type
Valid field type for the symbology type of this
ccAcuBarCodeRunParams object.
Notes
BC412 and IBM412 symbologies support the ccAcuBarCodeDefs::eLastField,
ccAcuBarCodeDefs::eAlpha, ccAcuBarCodeDefs::eNumeric,
ccAcuBarCodeDefs::eAlphanumeric, ccAcuBarCodeDefs::eDash,
ccAcuBarCodeDefs::eSemiAlpha, and ccAcuBarCodeDefs::eAll field types.
Code39 and Code128 support all of the aforementioned plus
ccAcuBarCodeDefs::ePeriod, ccAcuBarCodeDefs::eSpace, and
ccAcuBarCodeDefs::eOther.
332
CVL Class Reference
ccAcuBarCodeRunParams
Throws
ccAcuBarCodeDefs::BadParams
Position is not in the valid range, or the field type does not agree
with the symbology type of this ccAcuBarCodeRunParams
object.
lightPower
double lightPower() const;
void lightPower(double val);
•
double lightPower() const;
Gets the light power to be used.
•
void lightPower(double val);
Sets the light power to be used.
Parameters
val
The light power. Must be in the range 0.0 through 1.0.
Throws
ccAcuBarCodeDefs::BadParams
val lies outside the valid range.
symbolType
ccAcuBarCodeDefs::Symbology symbolType() const;
Gets the type of 1D Symbology to be decoded using the parameters contained in the
ccAcuBarCodeRunParams object.
scanDirection
ccAcuBarCodeDefs::ScanDirection scanDirection() const;
void scanDirection(ccAcuBarCodeDefs::ScanDirection
scanDirection);
•
ccAcuBarCodeDefs::ScanDirection scanDirection() const;
Returns the scan direction of this ccAcuBarCodeRunParams object. The function
returns one of the following values:
ccAcuBarCodeDefs::eRightToLeft
ccAcuBarCodeDefs::eLeftToRight
ccAcuBarCodeDefs::eBoth
CVL Class Reference
333
ccAcuBarCodeRunParams
•
void scanDirection(ccAcuBarCodeDefs::ScanDirection
scanDirection);
Sets the scan direction of this ccAcuBarCodeRunParams object.
Parameters
scanDirection
The direction in which to scan the barcode. If you specify
ccAcuBarCodeDefs::eBoth, then the tool attempts to decode the
barcode in both left-to-right and right-to-left directions; it returns
the best score. scanDirection must be one of the following
values:
ccAcuBarCodeDefs::eRightToLeft
ccAcuBarCodeDefs::eLeftToRight
ccAcuBarCodeDefs::eBoth
Operators
operator==
bool operator==(const ccAcuBarCodeRunParams& that) const;
Returns true if these ccAcuBarCodeRunParams are the same as another set of
ccAcuBarCodeRunParams. Two parameter sets are considered equal if all of their
attributes are the same.
Parameters
that
334
The other parameter set
CVL Class Reference
ccAcuBarCodeTool
#include <ch_cvl/acubar.h>
class ccAcuBarCodeTool;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
No
This class represents the base class for the 1D symbology tools. Tools for decoding
specific 1D symbologies are derived from the base class.
The class ccAcuBarCodeTool and the related classes ccAcuBarCodeRunParams,
ccAcuBarCodeTuneParams, and ccAcuBarCodeResult support the following two
types of 1D barcode decoders:
•
Decoders used for BC412 and IBM412 symbologies, which may require an
intermediate tuning step based on light settings to estimate optimal parameters.
•
Decoders used for the Code39 and Code 128 symbologies, which do not normally
require any tuning prior to decoding except in some special cases (for example,
when reading wafers).
To create the Barcode tool, you create a ccAcuBarCodeTool object and then perform
the following steps:
1.
Create a ccAcuBarCodeResult object.
ccAcuBarCodeResult result;
2.
Create a ccAcuBarCodeRunParams object.
ccAcuBarCodeRunParams bestParams(ccAcuBarCodeDefs::eIBM412);
bestParams.lightPower(0.5);
bestParams.fieldString(7, ccAcuBarCodeDefs::eLastField);
3.
Create a ccAcuBarCodeTuneParams object.
ccAcuBarCodeTuneParams stTuneParams;
4.
CVL Class Reference
Extract the region of interest to be used for tuning.
335
ccAcuBarCodeTool
cc8120& fg = cc8120::get(0);
const ccStdVideoFormat& fmt =
ccStdVideoFormat::getFormat(cmT("Sony XC75 640x480"))
ccStdGreyAcqFifo *fifo = fmt.newAcqFifo(fg);
fifo->properties().triggerEnable( true);
cc2Xform xform(cc2Matrix(1, 0, 0, 1), cc2Vect(0, 0));
ccAffineRectangle affrect(cc2Vect(110, 180),
cc2Vect(210, 190), cc2Vect(110, 290));
ccAffineSamplingParams affparams(affrect, 100, 100);
5.
Call tune() to perform the tuning step.
ccAcuBarCodeTool mbct;
mbct.tune (*fifo, xform, affparams, stTuneParams,
bestParams, result);
To perform a barcode decoding operation, perform the following steps:
1.
Acquire the image.
ccPelBuffer_const<c_UInt8> img = fifo->complete();
Make sure that the acquired image includes the entire barcode,
including the quiet zone. For more information on quiet zones, see
the chapter The Barcode Tool in the CVL Vision Tools Manual.
Note
2.
Create a ccAcuBarCodeResult object.
ccAcuBarCodeResult result;
3.
Create a ccAcuBarCodeRunParams object.
ccAcuBarCodeRunParams params;
4.
If necessary, change symbol and field type.
params.changeSymbolAndFieldType(ccAcuBarCodeDefs::eIBM412,
ccAcuBarCodeDefs::eAlpha);
params.fieldString(0, ccAcuBarCodeDefs::eAlphanumeric);
params.fieldString(7, ccAcuBarCodeDefs::eLastField);
params.accept(0.1);
5.
Decode the barcode.
mbct.decode (img, params, result);
For more detailed information about decoding barcodes, see the chapter The Barcode
Tool in the CVL Vision Tools Manual.
336
CVL Class Reference
ccAcuBarCodeTool
In addition to the tune and decode functions, the Barcode tool supports a calibrate
function, which automatically determines the properties and location of a barcode in an
image. After a successful calibration, the ccAcuBarCodeCalibrationResult class
holds the result.
To calibrate the Barcode tool, perform the following steps:
1.
Acquire the image.
ccPelBuffer_const<c_UInt8> img = fifo->complete();
Make sure that the acquired image includes the entire barcode,
including the quiet zone. For more information on quiet zones, see
the chapter The Barcode Tool in the CVL Vision Tools Manual
Note
2.
Create a ccAcuBarCodeRunParams object to specify the runtime parameters for
each symbology to be included in the calibration process. For example, to calibrate
the Barcode tool for Code39 and BC412 symbologies, create two
ccAcuBarCodeRunParams objects, one for eCode39 and one for eBC412. By
creating only these two objects, you can exclude the other supported symbologies
(for example, IBM412 and Code128) from the calibration process.
ccAcuBarCodeRunParams code39Params;
ccAcuBarCodeRunParams bc412Params;
3.
Set the runtime parameters for each symbology, if desired. Runtime parameters
can include accept threshold, character set for each field, length of encoded string,
scan direction, and presence of checksum character.
Set the length of the encoded string using the eLastField character to mark the end
of the string. Not specifying an eLastField character in the field map implies that the
encoded string length is to be determined.
Setting the scan direction to eBoth implies that the barcode scan direction is to be
determined.
See the chapter on the ccAcuBarCodeRunParams class for details.
4.
Create a vector of the ccAcuBarCodeRunParams objects created in the last step.
cmStd vector<ccAcuBarCodeRunParams> runParamsSet[2];
runParamsSet[0] = code39Params;
runParamsSet[1] = bc412Params;
5.
Create a ccAcuBarCodeCalibrationResult object.
ccAcuBarCodeCalibrationResult calResult;
6.
Calibrate the Barcode tool.
ccAcuBarCodeTool mbct;
mbct.calibrate(img, runParamsSet, calResult);
CVL Class Reference
337
ccAcuBarCodeTool
Constructors/Destructors
ccAcuBarCodeTool
ccAcuBarCodeTool();
virtual ~ccAcuBarCodeTool();
•
ccAcuBarCodeTool();
Default constructor.
•
virtual ~ccAcuBarCodeTool();
Destroys instances of this class.
Public Member Functions
decode
virtual void decode (ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccAffineSamplingParams &affParams,
const ccAcuBarCodeRunParams &runParams,
ccAcuBarCodeResult &result, bool autoRetry = true) const;
virtual void decode (
const ccPelBuffer_const<c_UInt8> &image,
const ccAcuBarCodeRunParams &runParams,
ccAcuBarCodeResult &result, bool autoRetry = true) const;
•
virtual void decode (ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccAffineSamplingParams &affParams,
const ccAcuBarCodeRunParams &runParams,
ccAcuBarCodeResult &result, bool autoRetry = true) const;
Decodes the barcode located within the region of interest (ROI) specified by affParams
and returns the results of the decode operation in the object specified by result.
The fifo object acquires an image containing the barcode symbol. The light properties
of the FIFO are based on the light power and dark level parameters contained in the
runParams object. You set these parameters prior to acquiring the image. The xform
object specifies the clientFromImage transform of the acquired image. The affine
sampling parameters are used to extract the region of interest containing the target
338
CVL Class Reference
ccAcuBarCodeTool
barcode symbol. The tool then uses this region of interest for decoding the string. When
the decoding operation finishes, the properties of the FIFO are left in the state specified
by runParams.
If the decode operation returns a score for the barcode below the accept threshold you
specify in runParams, the tool will automatically attempt to decode the barcode using an
advanced decoding strategy. If the tool invokes the advanced decoding strategy, the
decode will take about 10 times longer to perform, but the advanced strategy may be
able to handle barcodes that could not otherwise be decoded.
If you need to ensure that calls to decode take a consistent amount of time, you can
prevent the tool from automatically invoking the advanced decode strategy by
specifying a value of false for the autoRetry argument to this function.
Requires that xform be nonsingular and the region of interest be nonnull.
The decode operation supports timeouts via the use of ccTimeout.
Parameters
fifo
An acquisition FIFO.
xform
A coordinate transformation to convert pixel coordinates to client
coordinates.
affParams
Affine sampling parameters used to extract the region of interest
containing the target barcode symbol.
runParams
A set of parameters used to support the decoding operation
including symbol type, field type, and accept threshold.
result
Results obtained from a single decoding operation including
score, the decoded string, and the result of the checksum
operation.
autoRetry
Specify false to prevent the tool from automatically retrying failed
decodes using the advanced decoding strategy. Specify true to
allow the tool to automatically retry failed decodes.
Notes
To extract the ROI, the tool performs a windowing operation based on the affine
rectangle if you specify the following affine sampling parameters:
•
No subsampling
•
Image alignment of image coordinates
Otherwise, the tool samples the acquired image as specified.
CVL Class Reference
339
ccAcuBarCodeTool
Throws
ccAcuBarCodeDefs::BadParams
The xform is singular or the region of interest specified by
affParams is null or the field string in runParams does not contain
a ccAcuBarCodeDefs::eLastField character marking the end of
the string.
ccAcuBarCodeDefs::NotImplemented
The symbolType of runParams is not eBC412, eIBM412,
eCode39, or eCode128.
•
virtual void decode (
const ccPelBuffer_const<c_UInt8> &image,
const ccAcuBarCodeRunParams &runParams,
ccAcuBarCodeResult &result, bool autoRetry = true) const;
Decodes the string from the source image, and returns the result in the specified result
object. Requires that the image be bound, and its window be adjusted to fit the region
of interest containing the target barcode symbol and the quiet zone.
If the decode operation returns a score for the barcode below the accept threshold you
specify in runParams, the tool will automatically attempt to decode the barcode using an
advanced decoding strategy. If the tool invokes the advanced decoding strategy, the
decode will take about 10 times longer to perform, but the advanced strategy may be
able to handle barcodes that could not otherwise be decoded.
If you need to ensure that calls to decode() take a consistent amount of time, you can
prevent the tool from automatically invoking the advanced decode strategy by
specifying a value of false for the autoRetry argument to this function.
The decode operation supports timeouts via the use of ccTimeout.
Parameters
image
340
The pel buffer that contains the image being read.
runParams
A set of parameters used to support the decoding operation
including symbol type, field type, and accept threshold.
result
Results obtained from a single decoding operation including
score, the decoded string, and the result of the checksum
operation.
autoRetry
Specify false to prevent the tool from automatically retrying failed
decodes using the advanced decoding strategy. Specify true to
allow the tool to automatically retry failed decodes.
CVL Class Reference
ccAcuBarCodeTool
Throws
ccAcuBarCodeDefs::BadParams
The image is not bound or the field string in runParams does not
contain an ccAcuBarCodeDefs::eLastField character marking
the end of the string.
ccAcuBarCodeDefs::NotImplemented
The symbolType of runParams is not eBC412, eIBM412,
eCode39, or eCode128.
calibrate
virtual void calibrate (
const ccPelBuffer_const<c_UInt8> &image,
ccAcuBarCodeCalibrationResult &result,
const cmStd vector<ccAcuBarCodeDefs::Symbology>
&symbolTypes =
cmStd vector<ccAcuBarCodeDefs::Symbology>());
virtual void calibrate (
const ccPelBuffer_const<c_UInt8> &image,
const cmStd vector<ccAcuBarCodeRunParams> &runParamsSet,
ccAcuBarCodeCalibrationResult &result);
•
virtual void calibrate (
const ccPelBuffer_const<c_UInt8> &image,
ccAcuBarCodeCalibrationResult &result,
const cmStd vector<ccAcuBarCodeDefs::Symbology>
&symbolTypes =
cmStd vector<ccAcuBarCodeDefs::Symbology>());
Given an image containing a barcode, this calibrate method determines all of the
barcode properties using an accept threshold of 0.5 and disabling the checksum for
eCode39, for which the checksum is optional. Calibration determines the barcode
symbology (Code39, BC412, IBM412, or Code128), encoded string length, orientation
(left-to-right or right-to-left), pitch, and location (ROI in the image that encloses the
barcode).
Parameters
image
CVL Class Reference
Pelbuffer containing the barcode to be used for calibration.
result
Result object containing information on the result of the
calibration.
symbolTypes
Specifies a vector of the symbologies to be included in the
calibration. For example, to exclude eCode128 from calibration,
specify a vector of the other three supported symbol types
(eCode39, eBC412, and eIBM412). Specifying an empty vector
for symbolTypes causes the calibrate method to take all
supported symbologies into consideration.
341
ccAcuBarCodeTool
Throws
ccAcuBarCodeDefs::NotImplemented
The symbology specified by the vector of symbol types is not one
of eCode39, eBC412, eIBM412, or eCode128.
ccAcuBarCodeDefs::BadParams
Two or more elements in the symbolTypes vector correspond to
the same symbology.
ccAcuBarCodeDefs::BadImage
The image is not bound or does not satisfy the minimum window
size requirement of 32x10 pixels.
•
virtual void calibrate (
const ccPelBuffer_const<c_UInt8> &image,
const cmStd vector<ccAcuBarCodeRunParams> &runParamsSet,
ccAcuBarCodeCalibrationResult &result);
Given an image containing a barcode, the calibrate method determines the barcode
symbology (Code39, BC412, IBM412, or Code128), encoded string length, orientation
(left-to-right or right-to-left), pitch, and location (that is, the ROI in the image that
encloses the barcode).
Parameters
image
342
Pelbuffer containing the barcode to be used for calibration.
runParamsSet
Specifies a vector of runtime parameters for each symbology to
be included in the calibration process. For example, to exclude
eIBM412 and eCode128 from calibration, specify a vector of two
runparams objects, one for eCode39 and one for eBC412, each
containing a set of parameters to control the calibration of the
corresponding symbology. For each symbology, you can control
any or all of the following runtime parameters:
- accept threshold
- character set for each field
- length of the encoded string (by using the eLastField character
to mark the end of the string; not specifying an eLastField
character in the field map implies that the encoded string length
is to be determined)
- scan direction (eBoth implies that the barcode orientation is to
be determined)
- presence or absence of checksum character
result
Result object containing information on the result of the
calibration.
CVL Class Reference
ccAcuBarCodeTool
Throws
ccAcuBarCodeDefs::NotImplemented
The symbology specified by the runParamsSet vector is not one
of eCode39, eBC412, eIBM412, or eCode128.
ccAcuBarCodeDefs::BadParams
The runParamsSet vector is empty, or two or more elements in the
vector correspond to the same symbology.
ccAcuBarCodeDefs::BadImage
The image is not bound or does not satisfy the minimum window
size requirement of 32x10 pixels.
tune
virtual void tune (
ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccAffineSamplingParams &affParams,
const ccAcuBarCodeTuneParams &startTuneParams,
ccAcuBarCodeRunParams &bestParams,
ccAcuBarCodeResult &result);
virtual void tune(
const ccAcuBarCodeTuneParams &startTuneParams,
ccAcuBarCodeRunParams &bestParams,
ccAcuBarCodeResult &result);
•
virtual void tune (
ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccAffineSamplingParams &affParams,
const ccAcuBarCodeTuneParams &startTuneParams,
ccAcuBarCodeRunParams &bestParams,
ccAcuBarCodeResult &result);
Estimates optimal decoding parameters for the Barcode tool based on various light
settings, which you specify in startTuneParams.
Images are acquired using the FIFO object specified by fifo. The xform object specifies
the clientFromImage transform for the acquired image. The affine sampling parameters
are used to extract the region of interest to be used for tuning. The optimal light
parameters are returned via the bestParams object. The result of decoding using
optimal parameters is returned via the result object. Upon completion of the tune
operation, the tool sets the light properties of the FIFO object to the optimal values
returned via bestParams.
Requires that xform be nonsingular and the region of interest be nonnull.
The tune operation supports timeouts via the use of ccTimeout.
CVL Class Reference
343
ccAcuBarCodeTool
Parameters
fifo
An acquisition FIFO.
xform
A coordinate transformation to convert pixel coordinates to client
coordinates.
affParams
Affine sampling parameters used to extract the region of interest
containing the target barcode symbol.
startTuneParams Tuning parameters including dark field and bright field
properties.
bestParams
A set of parameters used to support the decoding operation
including symbol type, field type, and accept threshold.
result
Results obtained from a single decoding operation including the
score, the decoded string, and the result of the checksum
operation.
Notes
To extract the ROI, the tool performs a windowing operation based on the affine
rectangle if you specify the following affine sampling parameters:
•
No subsampling
•
Image alignment of image coordinates
Otherwise, the tool samples the acquired image as specified.
Use this function only if you need to tune light parameters in applications such as
Wafer ID where the symbology type is either BC412 or IBM412.
Throws
ccAcuBarCodeDefs::BadParams
The xform is singular, the region of interest specified by
affparams is null, or the field string in bestParams does not
contain an ccAcuBarCodeDefs::eLastField character marking
the end of the string.
ccAcuBarCodeDefs::NotImplemented
The symbolType of bestParams is not eBC412, eIBM412,
eCode39, or eCode128.
344
CVL Class Reference
ccAcuBarCodeTool
•
virtual void tune(
const ccAcuBarCodeTuneParams &startTuneParams,
ccAcuBarCodeRunParams &bestParams,
ccAcuBarCodeResult &result);
Estimates optimal decoding parameters for the Barcode tool based on various light
settings, which you specify in startTuneParams.
You supply the images used for tuning by overriding the
ccAcuBarCodeTool::acquireImage() function.
The optimal light parameters are returned via the bestParams object. The result of
decoding using optimal parameters is returned via the result object. Upon completion
of the tuning operation, the tool sets the light properties of the FIFO object to the optimal
values returned via bestParams.
Requires that xform be nonsingular and the region of interest be nonnull.
The tune operation supports timeouts via the use of ccTimeout.
Parameters
startTuneParams Tuning parameters including dark field and bright field
properties.
bestParams
A set of parameters used to support the decoding operation
including symbol type, field type, and accept threshold.
result
Results obtained from a single decoding operation including the
score, the decoded string, and the result of the checksum
operation.
Notes
Use this function only if you need to tune light parameters in applications such as
Wafer ID where the symbology type is either BC412 or IBM412.
Throws
ccAcuBarCodeDefs::NotImplemented
The symbolType of bestParams is not eBC412, eIBM412,
eCode39, or eCode128.
ccAcuBarCodeDefs::BadParams
The field string in bestParams does not contain an
ccAcuBarCodeDefs::eLastField character marking the end of the
string.
CVL Class Reference
345
ccAcuBarCodeTool
acquireImage
virtual ccPelBuffer<c_UInt8> acquireImage(
const ccAcuBarCodeRunParams& currentParams);
You should not call this function directly. To use this function, override it in a class that
you derive from ccAcuBarCodeTool.
This function lets you tune lighting parameters without using an acquisition FIFO to
acquire images. When you use the second overload of ccAcuBarCodeTool::tune(),
this function is called to obtain images. Your overload of this function should return the
image to use for tuning.
Parameters
currentParams
update
The current acquisition parameters.
virtual bool update () const;
virtual
const
const
const
const
•
bool update(
ccAcuBarCodeRunParams &currentParams,
ccAcuBarCodeRunParams &bestParams,
ccAcuBarCodeResult &currentResult,
ccAcuBarCodeResult &bestResult)
virtual bool update () const;
Returns bool, indicating whether the tuning process should continue or not.
•
virtual
const
const
const
const
bool update(
ccAcuBarCodeRunParams &currentParams,
ccAcuBarCodeRunParams &bestParams,
ccAcuBarCodeResult &currentResult,
ccAcuBarCodeResult &bestResult)
You should not call this function directly. To use this function, override it in a class that
you derive from ccAcuBarCodeTool.
Provides a hook that lets you update intermediate tune() results. The tuning process
continues as long as this function returns true. The default update() function always
returns true.
Notes
A user-overloaded update() function may abort tuning by returning false.
Parameters
currentParams
346
The current acquisition parameters.
bestParams
The best acquisition parameters.
currentResult
The results of decoding using currentParams.
CVL Class Reference
ccAcuBarCodeTool
bestResult
CVL Class Reference
The results of decoding using bestParams.
347
ccAcuBarCodeTool
348
CVL Class Reference
ccAcuBarCodeTuneParams
#include <ch_cvl/acubar.h>
class ccAcuBarCodeTuneParams : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class provides tuning parameters for the tuning process of the Barcode tool. You
pass the ccAcuBarCodeTuneParams object to ccAcuBarCodeTool::tune(). That
function uses the information in the tuning parameters to generate a
ccAcuBarCodeRunParams object that contains the optimal light parameters for the
decoding operation.
Constructors/Destructors
ccAcuBarCodeTuneParams
ccAcuBarCodeTuneParams (
bool enableDark = true,
double darkLow = 0.062745,
double darkHigh = 1.0,
double darkStep = 0.12157,
bool enableBright = true,
double brightLow = 0.062745,
double brightHigh = 1.0,
double brightStep = 0.12157);
Creates a tune-parameters object with the specified values.
Parameters
enableDark
CVL Class Reference
True to enable darkfield tuning.
darkLow
The minimum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
darkHigh
The maximum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
darkStep
The darkfield step value. Must be in the range 0.0 through 1.0.
enableBright
True to enable brightfield tuning.
349
ccAcuBarCodeTuneParams
brightLow
The minimum light power for brightfield tuning. Must be in the
range 0.0 through 1.0.
brightHigh
The maximum light power for brightfield tuning. Must be in the
range 0.0 through 1.0.
brightStep
The brightfield step value. Must be in the range 0.0 through 1.0.
Throws
ccAcuBarCodeDefs::BadParams
darkLow, darkHigh, darkStep, brightLow, brightHigh, brightStep
are set to be outside the valid range 0.0 through 1.0.
Notes
The default dark field and light field values are set as specified.
Operators
operator==
bool operator==(const ccAcuBarCodeTuneParams& that) const;
Returns true if these ccAcuBarCodeTuneParams are the same as another set of
ccAcuBarCodeTuneParams. Two parameter sets are considered equal if all of their
attributes are the same.
Parameters
that
The other parameter set
Public Member Functions
brightLow
double brightLow() const;
void brightLow(double val);
•
double brightLow() const;
Returns the minimum light power for brightfield tuning.
•
void brightLow(double val);
Sets the minimum light power for brightfield tuning.
Parameters
val
350
The minimum light power for brightfield tuning. Must be in the
range 0.0 through 1.0 where the light power increases
monotonically.
CVL Class Reference
ccAcuBarCodeTuneParams
Throws
ccAcuBarCodeDefs::BadParams
val is out of range.
brightHigh
double brightHigh() const;
void brightHigh(double val);
•
double brightHigh() const;
Returns the maximum light power for brightfield tuning.
•
void brightHigh(double val);
Sets the maximum light power for brightfield tuning.
Parameters
val
The maximum light power for brightfield tuning. Must be in the
range 0.0 through 1.0 where the light power increases
monotonically.
Throws
ccAcuBarCodeDefs::BadParams
val is out of range.
brightStep
double brightStep() const;
void brightStep(double val);
•
double brightStep() const;
Returns the brightfield step for tuning.
•
void brightStep(double val);
Sets the brightfield step for tuning.
Parameters
val
The brightfield step value. Must be in the range 0.0 through 1.0
where the light power increases monotonically.
Throws
ccAcuBarCodeDefs::BadParams
val is out of range.
CVL Class Reference
351
ccAcuBarCodeTuneParams
darkLow
double darkLow() const;
void darkLow(double val);
•
double darkLow() const;
Returns the minimum light power for darkfield tuning.
•
void darkLow(double val);
Sets the minimum light power for darkfield tuning.
Parameters
val
The minimum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuBarCodeDefs::BadParams
val is out of range.
darkHigh
double darkHigh() const;
void darkHigh(double val);
•
double darkHigh() const;
Returns the maximum light power for darkfield tuning.
•
void darkHigh(double val);
Sets the maximum light power for darkfield tuning.
Parameters
val
The maximum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuBarCodeDefs::BadParams
val is out of range.
352
CVL Class Reference
ccAcuBarCodeTuneParams
darkStep
double darkStep() const;
void darkStep(double val);
•
double darkStep() const;
Returns the darkfield step for tuning.
•
void darkStep(double val);
Sets the darkfield step for tuning.
Parameters
val
The darkfield step value. Must be in the range 0.0 through 1.0.
Throws
ccAcuBarCodeDefs::BadParams
val is out of range.
enableBright
bool enableBright() const;
void enableBright(bool val);
•
bool enableBright() const;
Returns true if brightfield tuning is enabled.
•
void enableBright(bool val);
Enables or disables brightfield tuning.
Parameters
val
enableDark
True if brightfield tuning is enabled. False otherwise.
bool enableDark() const;
void enableDark(bool val);
•
bool enableDark() const;
Returns true if darkfield tuning is enabled.
•
void enableDark(bool val);
Enables or disables darkfield tuning.
CVL Class Reference
353
ccAcuBarCodeTuneParams
Parameters
val
354
True if darkfield tuning is enabled. False otherwise.
CVL Class Reference
ccAcuRead
#include <ch_cvl/acuread.h>
class ccAcuRead;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
No
This class provides access to basic OCR reading and tuning functions. In your
application, you would create an instance of this class and use the read() function to
read a string. You can use the tune() function to obtain the optimum reading parameters
for your application. The mechanism for enabling Non-Linear OCR is to pass a
ccAcuReadFont that has been initialized with a nonlinear font to the read() or tune()
function.
You can control some aspects of the tuning function by creating a class derived from
this class and overriding the functions update() and userPreprocessAcquiredImage().
For more detailed information about OCR, reading, and tuning, see the chapter
acuRead in the CVL Vision Tools Guide.
Constructors/Destructors
You can use the default constructor and destructor to create and destroy instances of
this class.
Public Member Functions
tune
void tune(const ccPelBuffer_const<c_UInt8> &image,
const cc_AcuReadFont &font,
const cc_AcuReadFont &fontNL,
const ccAcuReadTuneParams &tuneParams,
const ccAcuReadRunParams &initial,
ccAcuReadRunParams &best,
ccAcuReadResultSet &resultSet);
void tune(ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccPelRect &rect,
const cc_AcuReadFont &font,
const cc_AcuReadFont &fontNL,
CVL Class Reference
355
ccAcuRead
const ccAcuReadTuneParams &tuneParams,
const ccAcuReadRunParams &initial,
ccAcuReadRunParams &best,
ccAcuReadResultSet &resultSet);
•
void tune(const ccPelBuffer_const<c_UInt8> &image,
const cc_AcuReadFont &font,
const cc_AcuReadFont &fontNL,
const ccAcuReadTuneParams &tuneParams,
const ccAcuReadRunParams &initial,
ccAcuReadRunParams &best,
ccAcuReadResultSet &resultSet);
Cycles through the preprocessing and size parameters, using the image in image and
invoking read() for each setting. Outputs the best read results and, if resultSet.found()
is true, the run parameters used to generate them.
Parameters
image
The pel buffer that contains the image being read.
font
The font of the characters being read.
fontNL
To enable non-linear OCR, specify a ccAcuReadFont object
initialized with a non-linear font. To disable non-linear OCR, set
this parameter to a default-constructed ccAcuReadFont object.
If font is a user-defined font, use a default-constructed
ccAcuReadFont object for fontNL.
tuneParams
The tuning parameters.
initial
The initial run parameters.
best
The run parameters that generated the best read result.
resultSet
The best read result.
Throws
ccAcuReadDefs::BadParams
font is uninitialized,
the checksum specified in initial is not eNone and
isVariableLength is set to true, or
fontNL is initialized and font is initialized to be a user-defined font.
ccAcuReadDefs::BadImage
image is unbound.
356
CVL Class Reference
ccAcuRead
•
void tune(ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccPelRect &rect,
const cc_AcuReadFont &font,
const cc_AcuReadFont &fontNL,
const ccAcuReadTuneParams &tuneParams,
const ccAcuReadRunParams &initial,
ccAcuReadRunParams &best,
ccAcuReadResultSet &resultSet);
Cycles through the preprocessing, size, and lighting parameters, using the specified
region of interest of an acquired image and invoking read() for each setting. Outputs the
best read results and, if resultSet.found() is true, the run parameters used to generate
them.
Parameters
fifo
An acquisition FIFO.
xform
A coordinate transformation to convert pixel coordinates to client
coordinates.
rect
The region of interest.
font
The font of the characters being read.
fontNL
To enable Non-Linear OCR, specify a ccAcuReadFont object
initialized with a nonlinear font. To disable Non-Linear OCR, set
this parameter to a default-constructed ccAcuReadFont object.
tuneParams
The tuning parameters.
initial
The initial run parameters.
best
The run parameters that generated the best read result.
resultSet
The best read result.
Throws
ccAcuReadDefs::BadParams
font is uninitialized,
the checksum specified in initial is not eNone and
isVariableLength is set to true, or
fontNL is initialized and font is initialized to be a user-defined font.
read
void read(ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccPelRect &rect,
const cc_AcuReadFont &font,
CVL Class Reference
357
ccAcuRead
const cc_AcuReadFont &fontNL,
const ccAcuReadRunParams &params,
ccAcuReadResultSet &resultSet);
void read(const ccPelBuffer_const<c_UInt8> &image,
const cc_AcuReadFont &font,
const cc_AcuReadFont &fontNL,
const ccAcuReadRunParams &params,
ccAcuReadResultSet &resultSet);
•
void read(ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccPelRect &rect,
const cc_AcuReadFont &font,
const cc_AcuReadFont &fontNL,
const ccAcuReadRunParams &params,
ccAcuReadResultSet &resultSet);
Performs a single read operation on the specified region of interest of an acquired image
using the specified parameters. Employs the following sub-functions, in the following
order:
1.
Acquisition
2.
Preprocessing
3.
Character segmentation
4.
Character identification
5.
Checksum computation.
Parameters
fifo
358
An acquisition FIFO.
xform
A coordinate transformation to convert pixel coordinates to client
coordinates.
rect
The region of interest.
font
The font of the characters being read. See ccAcuReadFont on
page 367.
fontNL
To enable Non-Linear OCR, specify a ccAcuReadFont object
initialized with a non-linear font. To disable non-linear OCR, set
this parameter to a default-constructed ccAcuReadFont object.
params
The run parameters.
resultSet
The read result.
CVL Class Reference
ccAcuRead
Throws
ccAcuReadDefs::BadParams
font is uninitialized,
the checksum specified in initial is not eNone and
isVariableLength is set to true, or
fontNL is initialized and font is initialized to be a user-defined font.
•
void read(const ccPelBuffer_const<c_UInt8> &image,
const cc_AcuReadFont &font,
const cc_AcuReadFont &fontNL,
const ccAcuReadRunParams &params,
ccAcuReadResultSet &resultSet);
Performs a single read operation on the specified image using the specified
parameters. Employs the following sub-functions, in the following order:
1.
Preprocessing, using the passed-in image
2.
Character segmentation
3.
Character identification
4.
Checksum computation.
Parameters
image
The pel buffer that contains the image being read.
font
The font of the characters being read. See ccAcuReadFont on
page 367.
fontNL
To enable non-linear OCR, specify a ccAcuReadFont object
initialized with a non-linear font. To disable non-linear OCR, set
this parameter to a default-constructed ccAcuReadFont object.
params
The run parameters.
resultSet
The read result.
Throws
ccAcuReadDefs::BadParams
font is uninitialized,
the checksum specified in params is not eNone and
isVariableLength is set to true, or
fontNL is initialized and font is initialized to be a user-defined font.
ccAcuReadDefs::BadImage
If image is unbound.
CVL Class Reference
359
ccAcuRead
update
virtual
const
const
const
bool update(const
ccAcuReadRunParams
ccAcuReadResultSet
ccAcuReadResultSet
ccAcuReadRunParams &current,
&best,
&currentRes,
&bestRes);
Provides a hook that lets you update intermediate tune() results. The tuning process
continues as long as this function returns true. The default update() function always
returns true.
Parameters
current
The current acquisition parameters.
best
The best acquisition parameters.
currentRes
The result of the current read operation.
bestRes
The results of the best read operation so far.
userPreprocessAcquiredImage
virtual bool userPreprocessAcquiredImage(
ccPelBuffer<c_UInt8>& src, const ccPelRect& rect,
ccPelBuffer<c_UInt8>& dst);
Allows preprocessing of the acquired image in a custom-defined manner during tune()
and read(). The tune or read process continues as long as this function returns true.
The default implementation assigns the source pel buffer to the destination pel buffer,
and sets the window of the destination pel buffer to rect. The OCR tool uses the window
and client coordinate transform of the destination pel buffer for subsequent processing.
You can override the default behavior in a derived class of your own to define other
custom preprocessing transformations.
Unless a throw occurs, the default implementation is always to return true. You can
override this behavior in a derived class of your own to return false, and abort the tune()
or read() operation in progress, if your custom image preprocessing is unsuccessful.
This has nothing to do with the image preprocessing that the OCR tool applies internally,
which happens only after this function returns true.
Parameters
src
The acquired image. This pel buffer must be bound.
rect
The region of interest within src.
dst
The destination pel buffer. The OCR tool uses the window and
client coordinate transform returned in this pel buffer for
subsequent processing.
Throws
360
CVL Class Reference
ccAcuRead
ccPel::BadWindow
src is not bound, either the width() or height() of rect is not
positive, or rect is not entirely contained within the window of src.
Notes
The default implementation throws under the conditions listed above. You can
override this behavior in a derived class of your own.
CVL Class Reference
361
ccAcuRead
362
CVL Class Reference
ccAcuReadDefs
#include <ch_cvl/acuread.h>
class ccAcuReadDefs;
A name space that holds enumerations and constants used with the acuRead classes.
Enumerations
Checksum
enum Checksum;
Values for the checksum parameter.
Fields
Value
Meaning
eNone
No checksum.
eSemi
SEMI checksum.
eBC412
BC412 checksum.
eIBM412
IBM412 checksum.
eVirtual
Virtual checksum.
enum Fields;
Convenience enumerations for identifying potential characters in a field.
CVL Class Reference
Value
Meaning
eLastField
Termination of field map.
eAlpha
Uppercase alphabetic character (A through Z).
eNumeric
Numeric character (0 through 9).
eAlphanumeric
Uppercase alphabetic or numeric character.
eDash
A dash or minus (–).
ePeriod
A period or decimal point (.).
eSpace
A space ( ).
eSemiAlpha
A SEMI checksum character (0 through 7 and A
through H).
363
ccAcuReadDefs
Color
enum Color;
Flags describing character and background colors.
OcrfFlags
Value
Meaning
eBlack
Black characters on white background.
eWhite
White characters on black background.
eLightInverse
Character color is the inverse of the light mode. This
option is for use during light tuning. It allows the
character color to change when tuning changes the
light mode. It should not be used when the image is
stored in a pel buffer.
enum OcrfFlags;
Flags enabling tuning of the filtering modes. These values can be ORed together.
Value
Meaning
eLoPass
Low-pass filter.
eHiPass
High-pass filter.
eTopHat
Top-hat filter.
eClip
Clipping filter.
eAll
All filters combined.
Notes
Use these flags with ccAcuReadTuneParams objects only. Do not use them as
preprocessing options with ccAcuReadRunParams objects.
ExitCode
enum ExitCode;
Codes that indicate how the ccAcuRead::read() and ccAcuRead::tune() methods
terminated.
364
CVL Class Reference
ccAcuReadDefs
Notes
ccAcuread::read() only terminates with eNormal. ccAcuRead::tune() may
terminate with any of the values.
Value
Meaning
eNormal = 0
Normal termination.
eValidLimit
The required number of successful reads occurred.
eTimeToValid
The maximum allowed time limit expired.
eScoreLimit
The minimum time limit expired and the score did not
exceed the score threshold.
Constants
The following constants are used with the optical character recognition classes:
CVL Class Reference
Value
Meaning
kMaxStringLength = 30
The maximum number of actual characters in a string
being read not including the end of field map
position.
kMaxFieldStringLength = 39
The maximum length of a field string. (A field string
lists the character(s) expected at a specific position.)
With field strings that contain multiple special
characters, the maximum length is 39 not including
the terminating NULL character.
365
ccAcuReadDefs
366
CVL Class Reference
ccAcuReadFont
#include <ch_cvl/acurdfnt.h>
class ccAcuReadFont: public cc_AcuReadFont;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
No
ccAcuReadFont encapsulates a font used by the acuRead tool. You populate the
object by calling ccAcuReadFont::access() and passing it a predefined font name or
an ccOCAlphabetPtrh object that contains a font set definition.
Constructors/Destructors
ccAcuReadFont
ccAcuReadFont();
virtual ~ccAcuReadFont();
•
ccAcuReadFont();
Default constructor. Initializes the object, but does not provide access to any font.
•
virtual ~ccAcuReadFont();
Operators
operator==
bool operator==(const ccAcuReadFont& rhs) const;
Returns true if the font in this object is identical to the font in rhs. Returns false otherwise.
CVL Class Reference
367
ccAcuReadFont
Public Member Functions
access
virtual bool access(
const ccCvlString & fontName);
virtual bool access(
const ccCvlString & fontBaseName,
bool enableNonLinear);
bool access(
const ccOCAlphabetPtrh_const & alphabet);
•
virtual bool access(
const ccCvlString & fontName);
Searches the list of predefined fonts and provides access to the first such font whose
name matches fontName. The predefined fonts currently supported are semi_nrm,
semi_nln, ocra_nrm, ocra_nln, trip_nrm, trip_nln, cano_nrm and cano_nln.
Returns true if successful and returns false if unable to find the specified name.
Parameters
fontName
The font name.
Notes
fontName should contain the suffix nrm or nln specifying whether the nonlinear
mode or normal mode is selected. For example semi_nrm and semi_nln.
•
virtual bool access(
const ccCvlString & fontBaseName,
bool enableNonLinear);
You specify the font name to access and the nonlinear or normal mode. The function
then searches the list of predefined fonts and provides access to the first such font
whose name matches fontBaseName with the specified mode enabled.
Returns true if successful and false if unable to find the specified font name.
Parameters
fontBaseName
The name of the font you wish to access.
enableNonLinear
True for nonlinear mode, and false for normal mode.
Notes
fontBaseName should not contain the extension nrm or nln. It should be one of semi,
ocra, trip or cano.
368
CVL Class Reference
ccAcuReadFont
•
bool access(
const ccOCAlphabetPtrh_const & alphabet);
Creates a user-defined OCR font from an ccOCAlphabet object.
Returns true if successful. If alphabet is invalid, an exception is thrown.
Parameters
alphabet
An OC alphabet.
Notes
Fonts can be either fixed width or proportional width.
Nonlinear mode is not supported for user-defined fonts. A user-defined font cannot
be used as a nonlinear font in a read or tune operation.
Requirements:
alphabet must contain no more than 39 characters. Only the characters with the
following ASCII codes are allowed: 32 (space), 45 (dash), 46 (period), 48 through
57 (digits), 65 through 90 (uppercase letters).
The key used must be the ASCII code of the character.
The character bitmap must be binary. That is, the bitmap must contain only two
distinct values. The two values can be anything in the range of 0 through 255. The
lower of the two values specifies the background and the higher value specifies the
foreground.
All character bitmaps in the alphabet must have the same height.
A blank character must be specified with type eBlank only. If the alphabet contains
a space character, it must be specified with type eBlank and have the value 32 as
its key.
Masking is not allowed.
The area of each character must be less than or equal to 1024 pixels.
There must be no more than one representation of any character.
The client transform of all character pel buffers must be the identity transform.
The string returned by alphabet->name() must be less than or equal to 31
characters (not including the NULL terminator).
Throws
ccAcuReadDefs::BadParams
Any of the above requirements are not met.
CVL Class Reference
369
ccAcuReadFont
fontName
virtual ccCvlString fontName() const;
Returns an ANSI string containing the name of the font being accessed. If no font is
accessed, a null string is returned,
isAccessed
bool isAccessed() const;
Returns true if the most recent call to the access() method successfully populated the
object with font information. Returns false if the call failed, or if access() has not yet been
called.
isUserDefined
bool isUserDefined() const;
Returns true if the this font was created from an ccOCAlphabet and returns false
otherwise.
370
CVL Class Reference
ccAcuReadResult
#include <ch_cvl/acuread.h>
class ccAcuReadResult;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
No
This class holds the results from reading an individual character. You access instances
of this class as part of a result set returned by ccAcuRead::tune() or
ccAcuRead::read(). See ccAcuReadResultSet on page 375 of the CVL Class
Reference.
You should not construct a ccAcuReadResult object directly.
Note
Constructors/Destructors
ccAcuReadResult
ccAcuReadResult();
Creates a character result. Instances of this class are created automatically as part of a
result set.
Operators
operator==
bool operator== (const ccAcuReadResult& that) const;
Returns true if this object equals that. Returns false otherwise.
Two ccAcuReadResult objects are considered equal if their character(), location(),
score(), and found() values are equal. Doubles are compared using cfRealEq() with
1.e-8 as the tolerance.
Parameters
that
CVL Class Reference
The other ccAcuReadResult object.
371
ccAcuReadResult
Public Member Functions
found
bool found() const;
Returns true if the character’s score was above the character acceptance threshold.
Returns false otherwise. See the following description.
character
c_Int32 character() const;
Character score
Returns the ASCII code of the found character. If the character was not found but the
character score was above the minimum character acceptance threshold, it returns an
asterisk ‘*’. If the character score was below the minimum character acceptance
threshold it returns a question mark ‘?’. See the following diagram:
Character acceptance
threshold
Successful ID
Return the character found
Not found. Return a ‘*’.
Minimum character
acceptance threshold
Not found. Return a ‘?’.
You specify an acceptance threshold for the entire string by calling
ccAcuReadRunParams::accept(). acuRead derives the character acceptance
threshold and the minimum character acceptance threshold from this value.
location
cc2Vect location() const;
Returns the coordinates of identified character in the client coordinate system.
Notes
The returned coordinates are invalid for prefix characters.
score
double score() const;
Returns the score of the identified character in the range 0.0 through 1.0. A value of 0.0
is always returned for force fitted fields. The value returned for characters that the OCR
actually reads, as opposed to those that are force fitted, is a measure of how closely the
actual character image data match the identified character. Scores returned for the
special characters “ “ (space), “-” (dash), and “.” (period) do not contribute to the overall
string score.
372
CVL Class Reference
ccAcuReadResult
CVL Class Reference
373
ccAcuReadResult
374
CVL Class Reference
ccAcuReadResultSet
#include <ch_cvl/acuread.h>
class ccAcuReadResultSet : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class holds the results of reading a string. In addition to the results for the string as
a whole, the result set also includes a vector of results for the individual characters. The
functions ccAcuRead::tune() and ccAcuRead::read() take parameters of type
ccAcuReadResultSet and fill them with the appropriate results.
Constructors/Destructors
ccAcuReadResultSet
ccAcuReadResultSet();
Creates a result set. Default-constructed instances of this class can be passed to
ccAcuRead::tune() and to ccAcuRead::read().
Operators
operator==
bool operator== (const ccAcuReadResultSet& that) const;
Returns true if this result set is the same as another result set. Two result sets are
considered equal if the following attributes are the same: string, angle, checksum,
score, acquisition count, and individual character results.
Parameters
that
The other result set.
Public Member Functions
found
bool found() const;
Returns true if the character string is found. This function returns false if the score for this
result is less than the accept threshold or if no checksum was valid (and you had
enabled at least one checksum).
CVL Class Reference
375
ccAcuReadResultSet
Notes
Always use found() to determine whether or not a read or tune was successful. Do
not compare the value of score() with an accept threshold to determine success or
failure.
readString
ccCvlString readString() const;
Returns the identified string.
The characters '*' or '?' are placed in positions in the string where incorrect matches
were determined during the read or tune operation. See the
acuReadResult::character() reference material for an explanation of the “*” and “?”
characters.
angle
ccDegree angle() const;
Returns the angle of the identified string in the client coordinate system of the run-time
image.
score
double score() const;
Returns the string score, in the range 0.0 through 1.0.
checksum1Valid
bool checksum1Valid() const;
Returns true if only one checksum was enabled (either a standard checksum or the
Virtual Checksum) and that checksum passed successfully; or if two checksums were
enabled (a standard checksum and Virtual Checksum), but only one of them passed.
checksum2Valid
bool checksum2Valid() const;
Returns true if a standard checksum (SEMI, BC412, or IBM412) was specified with
Non-Linear OCR enabled (thereby enabling both the standard checksum and the Virtual
Checksum), and both checksums passed.
acquireCount
c_Int32 acquireCount() const;
Returns the number of acquisitions completed.
result
const cmStd vector<ccAcuReadResult> &result() const;
Returns a vector of ccAcuReadResult objects that represent the results for each
individual character. See ccAcuReadResult on page 371.
376
CVL Class Reference
ccAcuReadResultSet
Notes
When running with a fixed string length the size of this vector is set by where you
place the ccAcuReadDefs::eLastField in the ccAcuReadRunParams object. See
ccAcuReadRunParams::fieldString().
You set fixed string length mode by setting isVariableLength() = false in the
ccAcuReadRunParams object passed to ccAcuRead::tune() or
ccAcuRead::read(),
time
double time() const;
Returns the number of seconds the read operation took.
exitCode
ccAcuReadDefs::ExitCode exitCode() const;
When reading, this function always returns ccAcuReadDefs::eNormal.
When tuning it returns one of the following codes indicating how the tuning operation
terminated.
ccAcuReadDefs::eNormal
ccAcuReadDefs::eValidLimit
ccAcuReadDefs::eTimeToValid
ccAcuReadDefs::eScoreLimit
runParams
const ccAcuReadRunParams &runParams() const;
Returns the ccAcuReadRunParams used to obtain this result.
nonlinearMode
bool nonlinearMode() const;
Returns true if nonlinear OCR was used to obtain this result, false otherwise.
CVL Class Reference
377
ccAcuReadResultSet
378
CVL Class Reference
ccAcuReadRunParams
#include <ch_cvl/acuread.h>
class ccAcuReadRunParams : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class lets you specify parameters used to perform optical character recognition.
After you have set up a ccAcuReadRunParams object, you pass it to
ccAcuRead::read(), which performs the reading operation. See ccAcuRead on
page 355 of the CVL Class Reference.
You can set up the reading parameters yourself, or you can use ccAcuRead::tune(),
which iterates over several possibilities to create a set of parameters for you.
For more detailed information about OCR, reading, and tuning, see the chapter
acuRead in the CVL Vision Tools Manual.
Constructors/Destructors
ccAcuReadRunParams
ccAcuReadRunParams();
ccAcuReadRunParams(double accept,
double acceptNL,
c_Int32 lineError,
c_Int32 spaceError,
c_Int32 charHeight,
c_Int32 charWidth,
c_Int32 checksum,
c_Int32 color,
c_Int32 preprocessing,
double lightPower,
double brightFieldPowerRatio,
CVL Class Reference
379
ccAcuReadRunParams
const ccCvlString & prefix,
bool isVariableLength = false,
c_Int32 refine = 3);
ccAcuReadRunParams(const ccAcuReadRunParams &src);
~ccAcuReadRunParams();
•
ccAcuReadRunParams();
Creates a default parameters object with the following initial values:
Parameter
Initial Value
accept
0.40
acceptNL
0.7
lineError
2
spaceError
4
charHeight
28
charWidth
14
checksum
ccAcuReadDefs::eNone
color
ccAcuReadDefs::eLightInverse
preprocessing
0
lightPower
0
brightFieldPowerRatio
0
prefix
““
isVariableLength
false
refine
3
The field map contains the string “0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ”
for positions 0 through kMaxStringLength - 1, and eLastField for position
kMaxStringLength.
•
380
ccAcuReadRunParams(
double accept,
double acceptNL,
CVL Class Reference
ccAcuReadRunParams
c_Int32 lineError,
c_Int32 spaceError,
c_Int32 charHeight,
c_Int32 charWidth,
c_Int32 checksum,
c_Int32 color,
c_Int32 preprocessing,
double lightPower,
double brightFieldPowerRatio,
const ccCvlString & prefix,
bool isVariableLength = false,
c_Int32 refine = 3);
Creates a parameters object with the specified values.
Parameters
accept
The acceptance threshold for standard OCR. Valid range, 0.0
through 1.0.
acceptNL
The acceptance threshold in nonlinear mode. Valid range, 0.0
through 1.0.
lineError
The line error tolerance in pixels. Valid range, 0 through 20.
spaceError
The space error tolerance in pixels. Valid range, 0 through 20.
charHeight
The initial character height in pixels. Valid range, 8 through 128.
charWidth
The initial character width in pixels. Valid range, 8 through 64.
checksum
The checksum method. Must be one of the following values:
ccAcuReadDefs::eNone
ccAcuReadDefs::eSemi
ccAcuReadDefs::eVirtual
For details, see checksum on page 390.
color
The character color. Must be one of:
ccAcuReadDefs::eBlack
ccAcuReadDefs::eWhite
ccAcuReadDefs::eLightInverse
For details, see Color on page 364.
preprocessing
CVL Class Reference
The preprocessing filters to apply. Must be one of the following
values:
381
ccAcuReadRunParams
0: 1D TopHat
1: 1D TopHat + Low Pass
2: 1D High Pass
3: 1D High Pass + Low Pass
4: 2D Top Hat
5: 2D Top Hat + Low Pass
6: 2D High Pass
7: 2D High Pass + Low Pass
8: Clip + 1D TopHat
9: Clip + 1D TopHat + Low Pass
10: Clip + 1D High Pass
11: Clip + 1D High Pass + Low Pass
12: Clip + 2D Top Hat
13: Clip + 2D Top Hat + Low Pass
14: Clip + 2D High Pass
15: Clip + 2D High Pass + Low Pass
lightPower
The light power level to be used. Valid range is 0.0 through 1.0.
brightFieldPowerRatio
The bright field power ratio specifies the fraction of the total light
power allocated to the bright field.
Also see the description under brightFieldPowerRatio on
page 392.
prefix
The prefix string prepended to each read string before
calculating the checksum.
isVariableLength
Set to true if the length of the string(s) to be read is not known. Set
to false otherwise.
Also see description under isVariableLength on page 393.
refine
The refinement strategy. Must be one of the following values:
0: no refinement
1: scale refinement
2: field string compliance
3: scale refinement and field string compliance (the default)
Also see notes under refine on page 393.
ccAcuReadDefs::BadParams
A parameter value was out of range.
382
CVL Class Reference
ccAcuReadRunParams
•
ccAcuReadRunParams(const ccAcuReadRunParams &src);
Copy constructor.
Parameters
src
•
The source ccAcuReadRunParams object.
~ccAcuReadRunParams();
Destroys a ccAcuReadRunParams object.
Operators
operator==
bool operator== (const ccAcuReadRunParams& that) const;
Returns true if the attribute values in the current run parameters object are equal to those
in the other.
Parameters
that
The other ccAcuReadRunParams object.
Public Member Functions
accept
double accept() const;
void accept(double val);
•
double accept() const;
Returns the acceptance threshold value. This is the string acceptance threshold used
by the normal mode OCR. A string must achieve at least this score to be reported as
found.
The acceptance threshold is the minimum score that a character needs to achieve to be
considered a valid character.
•
void accept(double val);
Sets the acceptance threshold value.
Parameters
val
CVL Class Reference
The acceptance threshold. Must be a value in the range 0.0
through 1.0.
383
ccAcuReadRunParams
Throws
ccAcuReadDefs::BadParams
val was out of range.
acceptNL
double acceptNL() const;
void acceptNL(double val);
•
double acceptNL() const;
Returns the acceptance threshold for nonlinear mode.
•
void acceptNL(double val);
Sets the acceptance threshold for nonlinear mode.
Parameters
val
The acceptance threshold. Must be a value in the range 0.0
through 1.0.
Throws
ccAcuReadDefs::BadParams
val was out of range.
lineError
c_Int32 lineError() const;
void lineError(c_Int32 val);
•
c_Int32 lineError() const;
Returns the line error tolerance. The line error tolerance is the number of pixels that a
character can be from an ideal baseline and still be considered a match.
•
void lineError(c_Int32 val);
Sets the line error tolerance.
Parameters
val
The line error tolerance in pixels. Must be a value in the range 0
through 20.
Throws
ccAcuReadDefs::BadParams
val was out of range.
384
CVL Class Reference
ccAcuReadRunParams
spaceError
c_Int32 spaceError() const;
void spaceError(c_Int32 val);
•
c_Int32 spaceError() const;
Returns the space error tolerance. The space error tolerance is the number of pixels that
a character can deviate left or right from an ideal center line that spaces all of the
characters equally.
•
void spaceError(c_Int32 val);
Sets the space error tolerance.
Parameters
val
The space error tolerance in pixels. Must be a value in the range
0 through 20.
Throws
ccAcuReadDefs::BadParams
val was out of range.
fieldString
ccCvlString fieldString(c_Int32 position) const;
void fieldString(c_Int32 position,
const ccCvlString &str);
void fieldString(c_Int32 position,
ccAcuReadDefs::FieldType type);
•
ccCvlString fieldString(c_Int32 position) const;
Returns the string that lists the characters that are valid at the specified position in the
string to be read.
Parameters
position
The character position. Must be in the range 0 through
kMaxStringLength.
Throws
ccAcuReadDefs::BadParams
position was out of range.
CVL Class Reference
385
ccAcuReadRunParams
•
void fieldString(c_Int32 position,
const ccCvlString &str);
Specifies the characters that are valid at the specified position in the string to be read.
"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ" is the default field string for
character positions 0 through KMaxStringLength - 1.
Parameters
position
str
The character position. Must be in the range 0 through
kMaxStringLength.
String containing the acceptable characters at the specified field
position. For positions 0 through kMaxStringLength - 1, the string
can either be empty (if this field is intended to be the end of the
string to be read) or contain any combination of alphanumeric
characters ‘A’ through ‘Z’, ‘0’ through ‘9’, or special characters ‘–’
(dash), ‘ ’ (space), or ‘.’ (period), without repetition. For position
kMaxStringLength, the string must be empty.
Example
The following code sets the field string at field position 3 to accept numerics and
special characters:
{...
ccAcuReadRunParams rp;
rp.fieldString(3, “0123456 -.”);
...
}
Throws
ccAcuReadDefs::BadParams
position was out of range, str included an invalid or duplicate
character, a non-empty str is specified for position
kMaxStringLength, or the length of str was greater than
ccAcuReadDefs::kMaxFieldStringLength–1.
•
void fieldString(c_Int32 position,
ccAcuReadDefs::FieldType type);
Sets the field string at the specified position to a predefined fieldType value.
Parameters
position
type
386
The character position to be set. Must be in the range 0 through
kMaxStringLength.
The type of field that is valid at the specified position.
CVL Class Reference
ccAcuReadRunParams
For positions 0 through kMaxStringLength - 1, the following are
valid field types:
ccAcuReadDefs::eAlpha (‘A’ through ‘Z’)
ccAcuReadDefs::eNumeric, (‘0’ through ‘9’)
ccAcuReadDefs::eAlphanumeric, (any alphanumeric)
ccAcuReadDefs::eDash, ('-' character)
ccAcuReadDefs::ePeriod, ('.' character)
ccAcuReadDefs::eSpace, (' ' character)
ccAcuReadDefs::eSemiAlpha (Semi checksum character ‘0’
through ‘7’ or ‘A’ through ‘H’)
For position kMaxStringLength, the only valid field type is
ccAcuReadDefs::eLastField.
See Fields on page 363.
Throws
ccAcuReadDefs::BadParams
position was out of range, type was an unknown or invalid type,
or a type other than ccAcuReadDefs::eLastField was specified
for position kMaxStringLength.
charHeight
c_Int32 charHeight() const;
void charHeight(c_Int32 val);
•
c_Int32 charHeight() const;
Returns the height of the characters to be read.
•
void charHeight(c_Int32 val);
Sets the height of the characters to be read. Values larger than the height of the region
of interest cause failed reads.
Parameters
val
The expected height, in pixels, of the characters to be read.
Values must be in the range 8 through 128.
Notes
If this object is being used to pass the initial parameters to ccAcuRead::tune(), it
is recommended that val be equal to the heightNominal value of the
ccAcuReadTuneParams object being used to pass the tuning parameters.
CVL Class Reference
387
ccAcuReadRunParams
Throws
ccAcuReadDefs::BadParams
val was out of range.
charWidth
c_Int32 charWidth() const;
void charWidth(c_Int32 val);
•
c_Int32 charWidth() const;
Returns the width of the characters to be read.
•
void charWidth(c_Int32 val);
Sets the width of the characters to be read. Values larger than the width of the region of
interest cause failed reads.
Parameters
val
The expected width, in pixels, of the characters to be read.
Values must be in the range 8 through 64.
Notes
If this object is being used to pass the initial parameters to ccAcuRead::tune(), it
is recommended that val be equal to the widthNominal value of the
ccAcuReadTuneParms object being used to pass the tuning parameters.
Throws
ccAcuReadDefs::BadParams
val was out of range.
color
ccAcuReadDefs::Color color() const;
void color(ccAcuReadDefs::Color val);
•
ccAcuReadDefs::Color color() const;
Returns the character color.
•
void color(ccAcuReadDefs::Color val);
Sets the character color.
388
CVL Class Reference
ccAcuReadRunParams
Notes
The default color, ccAcuReadDefs::eLightInverse, should not be used with the
overloads of ccAcuRead::read() and ccAcuRead::tune() that examine images
stored in pel buffers.
Parameters
val
The character color. Must be one of:
ccAcuReadDefs::eBlack
ccAcuReadDefs::eWhite
ccAcuReadDefs::eLightInverse
For details, see Color on page 364.
Throws
ccAcuReadDefs::BadParams
val was an unsupported value.
preprocessing
c_UInt32 preprocessing() const;
void preprocessing(c_UInt32 val);
•
c_UInt32 preprocessing() const;
Returns the preprocessing options.
•
void preprocessing(c_UInt32 val);
Sets the preprocessing options to use when reading a string.
Parameters
val
The preprocessing options. Must be one of the following values:
0: 1D TopHat
1: 1D TopHat + Low Pass
2: 1D High Pass
3: 1D High Pass + Low Pass
4: 2D Top Hat
5: 2D Top Hat + Low Pass
6: 2D High Pass
7: 2D High Pass + Low Pass
8: Clip + 1D TopHat
9: Clip + 1D TopHat + Low Pass
10: Clip + 1D High Pass
11: Clip + 1D High Pass + Low Pass
12: Clip + 2D Top Hat
CVL Class Reference
389
ccAcuReadRunParams
13: Clip + 2D Top Hat + Low Pass
14: Clip + 2D High Pass
15: Clip + 2D High Pass + Low Pass
The 1D and 2D versions of the top-hat and high-pass filters
enable you to choose between one-dimensional and
two-dimensional operations on pixel values. The 2D options are
more accurate, but slower than the 1D options.
Notes
If this runparams object was initialized by ccAcuRead::tune(), changing the
preprocessing options is not recommended.
Throws
ccAcuReadDefs::BadParams
val was an unsupported value.
checksum
ccAcuReadDefs::Checksum checksum() const;
void checksum(ccAcuReadDefs::Checksum val);
•
ccAcuReadDefs::Checksum checksum() const;
Returns the checksum method.
•
void checksum(ccAcuReadDefs::Checksum val);
Sets the checksum method or methods.
Parameters
val
The checksum method. Must be one of the following values:
Checksum selected
Interpretation
ccAcuReadDefs::eNone
ccAcuReadDefs::eSemi
ccAcuReadDefs::eBC412
ccAcuReadDefs::eIBM412
ccAcuReadDefs::eVirtual
eNone
eSemi + eVirtual
eBC412 + eVirtual
eIBM412 + eVirtual
eVirtual
Throws
ccAcuReadDefs::BadParams
val was an unsupported value.
390
CVL Class Reference
ccAcuReadRunParams
Notes
ccAcuReadDefs::eNone disables all checksums.
ccAcuReadDefs::eVirtual enables Virtual Checksum if Non-Linear OCR is enabled,
and is ignored if Non-Linear OCR is not enabled.
ccAcuReadDefs::eSemi enables the SEMI checksum if Non-Linear OCR is
disabled, and enables both the SEMI checksum and the Virtual Checksum when
Non-Linear OCR is enabled.
eVirtual is ignored when using user-defined fonts.
Checksum is not supported for variable length strings. If the checksum method is
set, the ccAcuRead::tune() and ccAcuRead::run() member functions will throw an
exception. Refer to the ccAcuRead::tune() and ccAcuRead::read() methods for
information on enabling Non-Linear OCR.
lightPower
double lightPower() const;
void lightPower(double val);
•
double lightPower() const;
Returns the light power value.
•
void lightPower(double val);
Sets the light power.
Parameters
val
The light power. Must be in the range 0.0 through 1.0.
Throws
ccAcuReadDefs::BadParams
val was out of range.
CVL Class Reference
391
ccAcuReadRunParams
brightFieldPowerRatio
double brightFieldPowerRatio() const;
void brightFieldPowerRatio(double val);
The bright field power ratio specifies the fraction of the total light power allocated to the
bright field. The setting must be in the range 0.0 through 1.0. A value of 0.0 indicates
bright field is completely off, and a value of 1.0 indicates bright field is fully on.
This is a tunable parameter.
•
double brightFieldPowerRatio() const;
Returns the current bright field power ratio setting.
•
void brightFieldPowerRatio(double val);
Sets a new bright field power ratio setting.
Parameters
val
The new bright field power ratio setting.
Throws
ccAcuReadDefs::BadParams
If val is outside the valid range.
prefix
ccCvlString prefix() const;
void prefix(const ccCvlString & str);
•
ccCvlString prefix() const;
Returns the prefix string prepended to each read string before calculating the
checksum.
•
void prefix(const ccCvlString & str);
Sets the prefix string prepended to each read string before calculating the checksum.
Parameters
str
392
The prefix string.
CVL Class Reference
ccAcuReadRunParams
refine
c_Int32 refine() const;
void refine(c_Int32 val);
The result refinement strategy. Controls the scale refinement and field string compliance
as described below:
•
Value
Scale refinement
Field string compliance
0
1
2
3 (default)
Disabled
Enabled
Disabled
Enabled
Disabled
Disabled
Enabled
Enabled
c_Int32 refine() const;
Returns the refinement strategy.
•
void refine(c_Int32 val);
Sets a new refinement strategy.
Parameters
val
The new refinement strategy.
Throws
ccAcuReadDefs::BadParams
If val is outside the valid range.
Notes
Turning off string compliance causes acuRead to ignore any specified field strings
and to use the default field string (‘0’ through ‘9’, ‘A’ through ‘Z’) to read all
characters.
This function is included for backward compatibility; its use is not recommended.
isVariableLength
bool isVariableLength() const;
void isVariableLength(bool isVarLen);
Set isVariableLength to true if the length of the string(s) to be read is not known. When
set to true, the tool considers the length of the field map as the maximum possible value.
Consequently, the read operation can result in a string that is smaller than the field map.
If set to false, the resulting string length will always be equal to that of the field map.
CVL Class Reference
393
ccAcuReadRunParams
•
bool isVariableLength() const;
Returns the isVariableLength flag; true or false.
•
void isVariableLength(bool isVarLen);
Sets the isVariableLength flag.
Parameters
isVarLen
The new flag value, true of false.
Notes
Characters at the rightmost and leftmost positions of a string are termed end
characters. The tool will not report any end characters whose score is below the
accept threshold. These will not affect the overall score of the string. However,
non-end (middle) characters with a “?” or a “*” will be reported and will affect the
overall score. For information about characters reported as “?” or “*” see the
ccAcuReadResult::character() reference material.
It may not be possible to provide certain types of information using the field string
API for variable length strings. For example, if a single “-” is expected in a string but
its position varies from one string to another, and you do not want the “-” to be a
choice for other positions in the field string, there is no way to specify this case with
the API.
Checksum is not supported for variable length strings. If the checksum method is
set, the ccAcuRead::tune() and ccAcuRead::run() member functions will throw an
exception. Refer to the ccAcuRead::tune() and ccAcuRead::read() methods for
information.
Deprecated Members
The following function is deprecated and is now maintained for backward compatibility
only. For new code development use brightFieldPowerRatio().
darkLevel
double darkLevel() const;
void darkLevel(double val);
•
double darkLevel() const;
Returns the dark level to be used. The range must be between 0.0 and 1.0.
394
CVL Class Reference
ccAcuReadRunParams
•
void darkLevel(double val);
Sets the darkLevel to be used. The range must be between 0.0 and 1.0.
Parameters
val
Dark level in the range 0.0 through 1.0.
Throws
ccAcuReadDefs::BadParams
val was out of range.
CVL Class Reference
395
ccAcuReadRunParams
396
CVL Class Reference
ccAcuReadTuneParams
#include <ch_cvl/acuread.h>
class ccAcuReadTuneParams : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class lets you specify the parameters used to tune the lighting, filtering, and
character-scaling parameters that affect optical character recognition.
In addition to passing ccAcuRead::tune() a ccAcuReadRunParams object with initial
reading parameters, you pass a ccAcuReadTuneParams object to specify how the
tuning function should alter the initial parameters as it attempts to find the run
parameters that yield the best string score. See ccAcuRead on page 355.
For more detailed information about OCR, reading, and tuning, see the chapter
acuRead in the CVL Vision Tools Manual.
Constructors/Destructors
ccAcuReadTuneParams
ccAcuReadTuneParams();
ccAcuReadTuneParams(bool enableDark,
double darkLow,
double darkHigh,
double darkStep,
bool enableBright,
double brightLow,
double brightHigh,
double brightStep,
bool enableHeight,
c_Int32 heightNominal,
c_Int32 heightRange,
bool enableWidth,
c_Int32 widthNominal,
c_Int32 widthRange,
c_UInt32 enableOcrf,
c_Int32 validLimit,
double timeToValid,
CVL Class Reference
397
ccAcuReadTuneParams
double scoreLimit,
bool scoreLimitChecksum,
double timeToScore);
~ccAcuReadTuneParams();
•
ccAcuReadTuneParams();
Creates a default tune-parameters object. The initial parameters are set as follows:
398
Parameter
Value
enableDark
true
darkLow
0.062745
darkHigh
1.0
darkStep
0.12157
enableBright
true
brightLow
0.062745
brightHigh
1.0
brightStep
0.12157
enableHeight
true
heightNominal
28
heightRange
4
enableWidth
true
widthNominal
14
widthRange
2
enableOcrf
ccAcuReadDefs::eAll
validLimit
255
timeToValid
30000
scoreLimit
0.10
scoreLimitChecksum
false
timeToScore
30000
CVL Class Reference
ccAcuReadTuneParams
•
ccAcuReadTuneParams(bool enableDark,
double darkLow,
double darkHigh,
double darkStep,
bool enableBright,
double brightLow,
double brightHigh,
double brightStep,
bool enableHeight,
c_Int32 heightNominal,
c_Int32 heightRange,
bool enableWidth,
c_Int32 widthNominal,
c_Int32 widthRange,
c_UInt32 enableOcrf,
c_Int32 validLimit,
double timeToValid,
double scoreLimit,
bool scoreLimitChecksum,
double timeToScore);
Parameters
enableDark
CVL Class Reference
True to enable darkfield tuning.
darkLow
The minimum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
darkHigh
The maximum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
darkStep
The darkfield step value. Must be in the range 0.0 through 1.0.
enableBright
True to enable brightfield tuning.
brightLow
The minimum light power for brightfield tuning. Must be in the
range 0.0 through 1.0.
brightHigh
The maximum light power for brightfield tuning. Must be in the
range 0.0 through 1.0.
brightStep
The brightfield step value. Must be in the range 0.0 through 1.0.
enableHeight
True to enable tuning for character height.
heightNominal
The nominal character height, in pixels. Must be in the range 8
through 128.
heightRange
The character height range, in pixels. Must be in the range 0
through 16.
enableWidth
True to enable tuning of character width.
399
ccAcuReadTuneParams
widthNominal
The nominal character width, in pixels. Must be in the range 8
through 64.
widthRange
The character width range, in pixels. Must be in the range 0
through 16.
enableOcrf
One of the following values that specify which filters to tune (or
zero to disable filter tuning):
ccAcuReadDefs::eLoPass
ccAcuReadDefs::eHiPass
ccAcuReadDefs::eTopHat
ccAcuReadDefs::eClip
ccAcuReadDefs::eAll
validLimit
The maximum number of successful reads that can occur without
producing a new best score.
timeToValid
The maximum number of seconds to spend tuning.
scoreLimit
The score threshold for early termination of tuning. Must be in the
range 0.0 through 1.0.
scoreLimitChecksum
True terminates tuning if the checksum passes.
timeToScore
The maximum time, in seconds, that can elapse before tuning
reaches scoreLimit.
Throws
ccAcuReadDefs::BadParams
A parameter value was out of range.
•
~ccAcuReadTuneParams();
Destroys a tune-parameters object.
Operators
operator==
bool operator== (const ccAcuReadTuneParams& that) const;
Returns true if these tuning parameters are the same as another set. Two tuning
parameter sets are considered equal if all of their attributes are the same.
Parameters
that
400
The other tuning parameter set.
CVL Class Reference
ccAcuReadTuneParams
Public Member Functions
enableDark
bool enableDark() const;
void enableDark(bool val);
•
bool enableDark() const;
Returns true if darkfield tuning is enabled.
•
void enableDark(bool val);
Enables or disables darkfield tuning.
Parameters
val
darkLow
True to enable darkfield tuning, false to disable.
double darkLow() const;
void darkLow(double val);
•
double darkLow() const;
Returns the minimum light power for darkfield tuning.
•
void darkLow(double val);
Sets the minimum light power for darkfield tuning.
Parameters
val
The minimum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuReadDefs::BadParams
val was out of range.
darkHigh
double darkHigh() const;
void darkHigh(double val);
•
double darkHigh() const;
Returns the maximum light power for darkfield tuning.
CVL Class Reference
401
ccAcuReadTuneParams
•
void darkHigh(double val);
Sets the maximum light power for darkfield tuning.
Parameters
val
The maximum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuReadDefs::BadParams
val was out of range.
darkStep
double darkStep() const;
void darkStep(double val);
•
double darkStep() const;
Returns the darkfield step for tuning.
•
void darkStep(double val);
Sets the darkfield step for tuning.
Parameters
val
The darkfield step value. Must be in the range 0.0 through 1.0.
Throws
ccAcuReadDefs::BadParams
val was out of range.
enableBright
bool enableBright() const;
void enableBright(bool val);
•
bool enableBright() const;
Returns true if brightfield tuning is enabled.
•
void enableBright(bool val);
Enables or disables brightfield tuning.
Parameters
val
402
True to enable brightfield tuning, false to disable.
CVL Class Reference
ccAcuReadTuneParams
brightLow
double brightLow() const;
void brightLow(double val);
•
double brightLow() const;
Returns the minimum light power for brightfield tuning.
•
void brightLow(double val);
Sets the minimum light power for brightfield tuning.
Parameters
val
The minimum light power for brightfield tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuReadDefs::BadParams
val was out of range.
brightHigh
double brightHigh() const;
void brightHigh(double val);
•
double brightHigh() const;
Returns the maximum light power for brightfield tuning.
•
void brightHigh(double val);
Returns the maximum light power for brightfield tuning.
Parameters
val
The maximum light power for brightfield tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuReadDefs::BadParams
val was out of range.
CVL Class Reference
403
ccAcuReadTuneParams
brightStep
double brightStep() const;
void brightStep(double val);
•
double brightStep() const;
Returns the brightfield step for tuning.
•
void brightStep(double val);
Sets the brightfield step for tuning.
Parameters
val
The brightfield step value. Must be in the range 0.0 through 1.0.
Throws
ccAcuReadDefs::BadParams
val was out of range.
enableHeight
bool enableHeight() const;
void enableHeight(bool val);
•
bool enableHeight() const;
Returns true if character height tuning is enabled.
•
void enableHeight(bool val);
Enables or disables character height tuning.
Parameters
val
heightNominal
True to enable character height tuning, false to disable.
c_Int32 heightNominal() const;
void heightNominal(c_Int32 val);
•
c_Int32 heightNominal() const;
Returns the nominal (initial) character height.
404
CVL Class Reference
ccAcuReadTuneParams
•
void heightNominal(c_Int32 val);
Sets the nominal (initial) character height.
Parameters
val
The nominal character height, in pixels. Must be in the range 8
through 128. It is recommended that val be equal to the
charHeight value of the ccAcuReadRunParams object being
used to pass the initial parameters to ccAcuRead::tune().
Throws
ccAcuReadDefs::BadParams
val was out of range.
heightRange
c_Int32 heightRange() const;
void heightRange(c_Int32 val);
•
c_Int32 heightRange() const;
Returns the tolerance that controls the range of character heights tested during tuning.
The range is twice this value, which is a plus-and-minus tolerance applied to the nominal
height.
•
void heightRange(c_Int32 val);
Sets the tolerance that controls the range of character heights tested during tuning. The
range is twice this value, which is a plus-and-minus tolerance applied to the nominal
height.
Parameters
val
The character height tolerance, in pixels. Must be in the range 0
through 16.
Throws
ccAcuReadDefs::BadParams
val was out of range.
Notes
During tuning, acuRead sometimes tests values outside the range you specify, with
the result that the character height returned after tuning may fall outside the range
(heightNominal – heightRange, heightNominal + heightRange).
CVL Class Reference
405
ccAcuReadTuneParams
enableWidth
bool enableWidth() const;
void enableWidth(bool val);
•
bool enableWidth() const;
Returns true if character width tuning is enabled.
•
void enableWidth(bool val);
Enables or disables character width tuning.
Parameters
val
widthNominal
True to enable character width tuning, false to disable.
c_Int32 widthNominal() const;
void widthNominal(c_Int32 val);
•
c_Int32 widthNominal() const;
Returns the nominal (initial) character width.
•
void widthNominal(c_Int32 val);
Sets the nominal (initial) character width.
Parameters
val
The nominal character width, in pixels. Must be in the range 8
through 64. It is recommended that val be equal to the charWidth
value of the ccAcuReadRunParams object being used to pass
the initial parameters to ccAcuRead::tune().
Throws
ccAcuReadDefs::BadParams
val was out of range.
406
CVL Class Reference
ccAcuReadTuneParams
widthRange
c_Int32 widthRange() const;
void widthRange(c_Int32 val);
•
c_Int32 widthRange() const;
Returns the tolerance that controls the range of character widths tested during tuning.
The range is twice this value, which is a plus-and-minus tolerance applied to the nominal
width.
•
void widthRange(c_Int32 val);
Sets the tolerance that controls the range of character widths tested during tuning. The
range is twice this value, which is a plus-and-minus tolerance applied to the nominal
width.
Parameters
val
The character width tolerance, in pixels. Must be in the range 0
through 16.
Throws
ccAcuReadDefs::BadParams
val was out of range.
Notes
During tuning, acuRead sometimes tests values outside the range you specify, with
the result that the character width returned after tuning may fall outside the range
(widthNominal – widthRange, widthNominal + widthRange).
enableOcrf
c_UInt32 enableOcrf() const;
void enableOcrf(c_UInt32 code);
•
c_UInt32 enableOcrf() const;
Returns zero if filter tuning is disabled or, when filter tuning is enabled, a value formed
by ORing together one or more of the following values:
ccAcuReadDefs::eLoPass
ccAcuReadDefs::eHiPass
ccAcuReadDefs::eTopHat
ccAcuReadDefs::eClip
ccAcuReadDefs::eAll
The returned value indicates which filters will be considered during filter tuning.
CVL Class Reference
407
ccAcuReadTuneParams
•
void enableOcrf(c_UInt32 code);
Specifies which filters will be considered during filter tuning.
Parameters
code
The preprocessing options. Use zero to disable filter tuning. Use
any of the following values, which can be ORed together, to
enable filter tuning:
ccAcuReadDefs::eLoPass
ccAcuReadDefs::eHiPass
ccAcuReadDefs::eTopHat
ccAcuReadDefs::eClip
ccAcuReadDefs::eAll
For details, see OcrfFlags on page 364.
Throws
ccAcuReadDefs::BadParams
If code is an invalid value.
Notes
Either ccAcuReadDefs::eTopHat or ccAcuReadDefs::eHiPass must be selected for
tuning to take place. If one of these filters is not chosen, filter tuning is not
performed.
validLimit
c_Int32 validLimit() const;
void validLimit(c_Int32 val);
•
c_Int32 validLimit() const;
Returns the maximum number of successful reads that can be performed during tuning
without producing a new best score.
•
void validLimit(c_Int32 val);
Sets the maximum number of successful reads that can occur during tuning without
producing a new best score.
Parameters
val
The maximum number of successful reads. Must be in the range
0 through 255.
Throws
ccAcuReadDefs::BadParams
val was out of range.
408
CVL Class Reference
ccAcuReadTuneParams
timeToValid
double timeToValid() const;
void timeToValid(double val);
•
double timeToValid() const;
Returns the maximum number of seconds to spend tuning.
•
void timeToValid(double val);
Sets the maximum number of seconds to spend tuning.
Parameters
val
The maximum number of seconds to spend tuning. Must be
nonnegative
Throws
ccAcuReadDefs::BadParams
val was out of range.
scoreLimit
double scoreLimit() const;
void scoreLimit(double val);
•
double scoreLimit() const;
Returns the string score that tuning must reach within timeToScore() seconds in order
for tuning to continue.
•
void scoreLimit(double val);
Sets the string score that tuning must reach within timeToScore() seconds to continue.
If scoreLimitChecksum() is true, the string being read will also need to pass its
checksum for tuning to continue beyond timeToScore() seconds.
Parameters
val
The score threshold for early termination of tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuReadDefs::BadParams
val was out of range.
CVL Class Reference
409
ccAcuReadTuneParams
scoreLimitChecksum
bool scoreLimitChecksum() const;
void scoreLimitChecksum(bool val);
•
bool scoreLimitChecksum() const;
Returns true if the tuning operation considers the checksum in addition to the string
score to determine whether tuning should continue beyond timeToScore() seconds.
•
void scoreLimitChecksum(bool val);
Specifies whether or not the string must pass its checksum within timeToScore()
seconds for tuning to continue.
Parameters
val
True to use the checksum, false to exclude the checksum.
Notes
If no checksum is enabled by the initial run parameters you pass to
ccAcuRead::tune(), setting scoreLimitChecksum() true has no effect.
timeToScore
double timeToScore() const;
void timeToScore(double val);
•
double timeToScore() const;
Returns the maximum number of seconds that tuning can continue before the string
reaches scoreLimit() and, if scoreLimitChecksum() is true, passes its checksum.
•
void timeToScore(double val);
Sets the maximum number of seconds that tuning can continue before the string
reaches scoreLimit() and, if scoreLimitChecksum() is true, passes its checksum.
Parameters
val
The maximum number of seconds to tune without reaching the
desired string score and, if required, passing the checksum.
Must be nonnegative.
Throws
ccAcuReadDefs::BadParams
val was out of range.
410
CVL Class Reference
ccAcuSymbolDataMatrixDefs
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolDataMatrixDefs: public ccAcuSymbolDefs;
A name space that holds enumerations and constants used with the Symbol tool
classes.
Enumerations
ECCType
enum ECCType;
Values for the ECCType parameter:
LearnFlags
Value
Meaning
eECC0
ECC level 0
eECC050
ECC level 50
eECC080
ECC level 80
eECC100
ECC level 100
eECC140
ECC level 140
eECC200
ECC level 200
kDefaultECC
eECC200
enum LearnFlags;
Setting the following LearnFlags determines which parameters the tool learns:
CVL Class Reference
Value
Meaning
eNone = 0
Tool learns no parameters.
eECC = 1
Tool learns ECC level.
eGrid = 2
Tool learns Grid size.
eNominalGrid = 4
Tool learns nominal grid.
ePolarity = 8
Tool learns polarity.
eModel = 16
Turns optimization on.
411
ccAcuSymbolDataMatrixDefs
Value
Meaning
eAll = 31
Tool learns all learning parameters.
kDefaultLearn = eAll
Default is for the tool to learn all learning
parameters.
kMaxDataMatrixModelSize
enum kMaxDataMatrixModelSize;
Maximum size for a Data Matrix symbol:
Polarity
Value
Meaning
kMaxDataMatrixModelSize =
48
The maximum supported symbol size is
48.
enum Polarity;
Values for the Polarity parameter:
412
Value
Meaning
eDarkOnLight
Dark symbol on a light background
eLightOnDark
Light symbol on a dark background
CVL Class Reference
ccAcuSymbolDataMatrixLearnParams
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolDataMatrixLearnParams:
public ccAcuSymbolLearnParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
The class ccAcuSymbolDataMatrixLearnParams supplies the parameters that the
Symbol tool uses to create a Data Matrix symbol model. The tool can acquire values for
the parameters in this class in the following ways:
•
You can set the Learn parameters to their default values by using the default
constructor.
•
You can specify values for specific Learn parameters using the overload
constructor.
•
You can set values for the Learn parameters using the setters of the class.
•
You can have the tool learn the parameters specified by learnFlags. For those
parameters not learned by the tool, you use this class to specify the values.
Constructors/Destructors
ccAcuSymbolDataMatrixLearnParams
ccAcuSymbolDataMatrixLearnParams();
virtual ~ccAcuSymbolDataMatrixLearnParams();
ccAcuSymbolDataMatrixLearnParams(
const ccAffineRectangle& nominalGrid,
c_UInt8 nrows,
c_UInt8 ncols,
ccAcuSymbolDataMatrixDefs::ECCType ecc =
ccAcuSymbolDataMatrixDefs::kDefaultECC,
ccAcuSymbolDataMatrixDefs::Polarity symbolPolarity =
ccAcuSymbolDataMatrixDefs::eDarkOnLight,
ccRadian angle = ccRadian(0.0),
CVL Class Reference
413
ccAcuSymbolDataMatrixLearnParams
double scale = 1.0,
bool aimFlag = true,
bool mirror = false);
•
ccAcuSymbolDataMatrixLearnParams();
Default constructor. The members are initialized to their default values, which are:
Parameter
Value
nRows
10
nCols
10
nominalGrid
Points at (0, 10), (10, 10), (0, 0)
eccType
ccAcuSymbolDataMatrixDefs::kDefaultECC
symbolPolarity
ccAcuSymbolDataMatrixDefs::eDarkOnLight
aimFlag
True
Notes
The nominal grid as well as the number of rows and columns are set to match the
smallest symbol size (10 x 10) allowed for an AIM-compliant Data Matrix symbol
(version ECC 200). The transform of the nominal grid is set to identity.
•
virtual ~ccAcuSymbolDataMatrixLearnParams();
Destroys instances of this class.
•
ccAcuSymbolDataMatrixLearnParams(
const ccAffineRectangle& nominalGrid,
c_UInt8 nrows,
c_UInt8 ncols,
ccAcuSymbolDataMatrixDefs::ECCType ecc =
ccAcuSymbolDataMatrixDefs::kDefaultECC,
ccAcuSymbolDataMatrixDefs::Polarity symbolPolarity =
ccAcuSymbolDataMatrixDefs::eDarkOnLight,
ccRadian angle = ccRadian(0.0),
double scale = 1.0,
bool aimFlag = true,
bool mirror = false);
Constructor overload with specified values.
414
CVL Class Reference
ccAcuSymbolDataMatrixLearnParams
Parameters
nominalGrid
nrows
The affine rectangle that encloses the symbol.
The number of rows in the symbol. For AIM-compliant symbols,
the number of rows must be the same as the number of columns
for the symbol grid for all versions except eECC200.
For AIM-compliant square symbols, nrows should be:
Odd and in the range 9 through kMaxDataMatrixModelSize if the
ECC type specified is eECC0-eECC140.
Even and in the range 10 through kMaxDataMatrixModelSize if
the version specified is eECC200.
For AIM-compliant rectangular symbols (version ECC 200 only),
nrows must be one of the following combinations:
ncols
nrows
ncols
8
18
8
32
12
26
12
36
16
36
16
48
The number of columns in the symbol. For AIM-compliant
symbols, the number of rows must be the same as the number of
columns for the symbol grid for all versions except eECC200.
For AIM-compliant square symbols, ncols should be:
Odd and in the range 9 through kMaxDataMatrixModelSize if the
ECC type specified is eECC0-eECC140.
Even and in the range 10 through kMaxDataMatrixModelSize if
the version specified is eECC200.
CVL Class Reference
415
ccAcuSymbolDataMatrixLearnParams
For AIM-compliant rectangular symbols (version ECC 200 only),
ncols must be one of the following combinations:
nrows
ncols
8
18
8
32
12
26
12
36
16
36
16
48
ecc
The ECC level.
symbolPolarity
The polarity of the symbol, either dark-on-light or light-on-dark.
angle
The angle of the symbol relative to the model. Should be
specified in radians.
scale
The scale of the symbol relative to the model. scale should be
greater than 0.
aimFlag
If true, then the symbol is AIM-compliant.
mirror
If true, then the tool reverses the image of the symbol after
acquisition.
Throws
ccAcuSymbolDefs::BadParams
The conditions described above are not met.
Operators
operator==
bool operator== (
const ccAcuSymbolDataMatrixLearnParams &that) const;
Compares this object with another. Two ccAcuSymbolDataMatrixLearnParams
objects are considered equal if all their corresponding data members are identical.
416
CVL Class Reference
ccAcuSymbolDataMatrixLearnParams
Public Member Functions
aimFlag
bool aimFlag() const;
Gets the AIM-compliance flag.
cols
c_UInt8 cols() const;
Gets the number of columns in the symbol grid.
ecc
ccAcuSymbolDataMatrixDefs::ECCType ecc()
const;
Gets the Data Matrix version specified by ECC level.
modelTypeAndSize
void modelTypeAndSize (
ccAcuSymbolDataMatrixDefs::ECCType ecc,
c_UInt8 rows,
c_UInt8 cols
bool aimFlag);
Sets the version, number of rows, and number of columns in the symbol grid; it also
specifies AIM compliance.
Parameters
ecc
nrows
The Data Matrix version specified by ECC level.
The number of rows in the symbol. For AIM-compliant symbols,
the number of rows must be the same as the number of columns
for the symbol grid for all versions except eECC200.
For AIM-compliant square symbols, nrows should be:
Odd and in the range 9 through kMaxDataMatrixModelSize if the
ECC type specified is eECC0-eECC140.
Even and in the range 10 through kMaxDataMatrixModelSize if
the version specified is eECC200.
CVL Class Reference
417
ccAcuSymbolDataMatrixLearnParams
For AIM-compliant rectangular symbols (version ECC 200 only),
nrows must be one of the following combinations:
nrows
ncols
8
18
8
32
12
26
12
36
16
36
16
48
rows and cols should be in the range 9 through
kMaxDataMatrixModelSize, but need not be equal or have a
pre-determined size.
ncols
The number of columns in the symbol. For AIM-compliant
symbols, the number of rows must be the same as the number of
columns for the symbol grid for all versions except eECC200.
For AIM-compliant square symbols, ncols should be:
Odd and in the range 9 through kMaxDataMatrixModelSize if the
ECC type specified is eECC0-eECC140.
Even and in the range 10 through kMaxDataMatrixModelSize if
the version specified is eECC200.
For AIM-compliant rectangular symbols (version ECC 200 only),
ncols must be one of the following combinations:
418
nrows
ncols
8
18
8
32
12
26
12
36
16
36
16
48
CVL Class Reference
ccAcuSymbolDataMatrixLearnParams
rows and cols should be in the range 9 through
kMaxDataMatrixModelSize, but need not be equal or have a
pre-determined size.
aimFlag
The AIM-compliance flag. It is learned only when the tool
operates in high-contrast mode. Otherwise, you must supply a
flag value. For AIM-compliant square symbols, aimFlag must be
set true. For non-AIM-compliant symbols, aimFlag must be set
false.
Throws
ccAcuSymbolDefs::BadParams
The conditions described above are not met.
Notes
For all versions except ECC 200, the number of rows must be the same as the
number of columns for the symbol grid.
The row and column specification does not include the quiet zone.
rows
c_UInt8 rows() const;
Gets the number of rows in the symbol grid.
symbolPolarity
ccAcuSymbolDataMatrixDefs::Polarity symbolPolarity()
const;
void symbolPolarity (
ccAcuSymbolDataMatrixDefs::Polarity pol);
•
ccAcuSymbolDataMatrixDefs::Polarity symbolPolarity()
const;
Gets the symbol polarity.
•
void symbolPolarity (
ccAcuSymbolDataMatrixDefs::Polarity pol);
Sets the symbol polarity.
Parameters
pol
CVL Class Reference
The polarity of the symbol, either dark on light or light on dark.
419
ccAcuSymbolDataMatrixLearnParams
420
CVL Class Reference
ccAcuSymbolDataMatrixTool
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolDataMatrixTool: public ccAcuSymbolTool;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
You use this class to create the central object for the Data Matrix tool, which contains
the trained representation of a Data Matrix symbol, and the functions for the learn and
decode phases of the tool’s operation.
CVL Class Reference
421
ccAcuSymbolDataMatrixTool
Constructors/Destructors
ccAcuSymbolDataMatrixTool
ccAcuSymbolDataMatrixTool(
ccAcuSymbolDefs::OperatingMode opMode =
ccAcuSymbolDefs::eAutoDetect);
virtual ~ccAcuSymbolDataMatrixTool();
ccAcuSymbolDataMatrixTool(
const ccAcuSymbolDataMatrixLearnParams& learnParams,
c_UInt32 learnFlags,
ccAcuSymbolDefs::OperatingMode opMode =
ccAcuSymbolDefs::eAutoDetect );
•
ccAcuSymbolDataMatrixTool(
ccAcuSymbolDefs::OperatingMode opMode =
ccAcuSymbolDefs::eAutoDetect);
Constructs a Symbol tool for decoding Data Matrix symbols. The tool is in an unlearned
state, the operating mode defaults to eAutoDetect, and all members are initialized to the
following defaults:
•
Parameter
Value
initialLearnParams
default constructed ccAcuSymbolDataMatrixLearnParams
bestLearnedParams
default constructed ccAcuSymbolDataMatrixLearnParams
learnFlags
ccAcuSymbolDataMatrixDefs::eAll
isLearned
false
virtual ~ccAcuSymbolDataMatrixTool();
Destroys instances of this class.
422
CVL Class Reference
ccAcuSymbolDataMatrixTool
•
ccAcuSymbolDataMatrixTool(
const ccAcuSymbolDataMatrixLearnParams& learnParams,
c_UInt32 learnFlags,
ccAcuSymbolDefs::OperatingMode opMode =
ccAcuSymbolDefs::eAutoDetect);
Creates a Symbol tool that learns those parameters in the
ccAcuSymbolDataMatrixLearnParams object specified by learnFlags and sets the
remaining parameters to their defaults or to those values supplied by the setters of the
ccAcuSymbolDataMatrixLearnParams class. (Constructor overload)
Requires that learnFlags be a bitwise combination of any of the
ccAcuSymbolDataMatrixDefs::LearnFlags values. learnFlags must be in the range
[0, 31].
Parameters
learnParams
Parameters that the tool can learn or that you can set. Examples
include ECC level, grid size, nominal grid, and polarity. You must
set the Learn parameter mirrorFlag or use the default.
learnFlags
Flags that when set direct the tool to learn a specific Learn
parameter.
opMode
Determines the operating mode for the tool, which can be one of:
ccAcuSymbolDefs::eStandard
ccAcuSymbolDefs::eHighContrast
ccAcuSymbolDefs::eAutoDetect
Throws
ccAcuSymbolDefs::BadParams
learnFlags is not in the range 0 through 31.
Public Member Functions
bestLearnedParams
const ccAcuSymbolDataMatrixLearnParams&
bestLearnedParams() const;
Returns the final learned parameters after the tool, which is in Learn and Decode mode,
has performed the following actions:
1.
Found a symbol in the image
2.
Learned the parameters specified by learnFlags
3.
Created a model from the parameters specified by learnFlags and those specified
by the ccAcuSymbolDataMatrixLearnParams object
CVL Class Reference
423
ccAcuSymbolDataMatrixTool
4.
Decoded the symbol
Notes
This function should be used to get the learned parameters after the tool has
undergone learning successfully as indicated by isLearned() returning true.
Throws
ccAcuSymbolDefs::NotLearned
This function is invoked when the tool has not undergone the
learning phase successfully and isLearned() returns false.
decode
bool decode (
const ccPelBuffer_const<c_UInt8>& image,
const ccAcuSymbolFinderParams& findParams,
ccAcuSymbolResult& result) const;
Finds the symbol in the given image and decodes it using the specified Find parameters
and internally stored Learn parameters. The result of decoding is returned via the result
object. Returns true if successful, false if the operation failed. Requires that the image
be bound.
This function places the tool in Standard Decode mode for Data Matrix symbology.
Parameters
image
The acquired image. The pel buffer must be bound.
findParams
The Find parameters, which the tool uses to locate and orient
each runtime symbol. Examples include angle, scale, confusion
threshold, and acceptance threshold.
result
The result object that contains data derived from the decoding
operation including angle, score, and scale.
Notes
In high-contrast mode, the tool ignores the findParams value, and instead uses 5%
as a scale range and 180 degrees (or ckPI/2) as an angle range.
This function supports the use of a ccTimeout-based timeout.
Throws
ccAcuSymbolDefs::BadImage
The image is not bound.
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
424
CVL Class Reference
ccAcuSymbolDataMatrixTool
initialLearnParams
const ccAcuSymbolDataMatrixLearnParams&
initialLearnParams() const;
void initialLearnParams(
const ccAcuSymbolDataMatrixLearnParams& learnParams);
•
const ccAcuSymbolDataMatrixLearnParams&
initialLearnParams() const;
Gets the initial parameters used for learning prior to estimation by the learn and decode
phase.
•
void initialLearnParams(
const ccAcuSymbolDataMatrixLearnParams& learnParams);
Sets the initial parameters used for learning, prior to estimation by the learn and decode
phase.
Parameters
learnParams
Parameters that the tool can learn or that you can set. Examples
include ECC level, grid size, nominal grid, and polarity. You must
set the Learn parameter mirrorFlag or use the default.
Notes
The setter function should be used to initialize the learn parameters in preparation
for the learning phase.
When operating in high-contrast mode, the tool ignores all initial learn parameters
except the cell size range.
learn
void learn (
const ccPelBuffer_const<c_UInt8>& image,
const ccAcuSymbolFinderParams& findParams,
ccAcuSymbolResult& result);
Estimates the optimal configuration of selected symbol learning parameters as specified
by initialLearnParams and learnFlags. If learning is successful, the tool updates
bestLearnedParams and decodes the symbol using the internally learned parameters
and the findParams object. Finally, the tool returns decoding results via the result object.
Requires that the image be bound.
This function places the tool in Learn and Decode mode for Data Matrix symbology.
Parameters
image
CVL Class Reference
The acquired image. The pel buffer must be bound.
425
ccAcuSymbolDataMatrixTool
findParams
The Find parameters, which the tool uses to locate and orient
each runtime symbol. Examples include angle, scale, confusion
threshold, and acceptance threshold.
result
The result object that contains data derived from the decoding
operation including angle, score, and scale.
Notes
In high-contrast mode, the tool ignores the findParams value, and instead uses 5%
as a scale range and 180 degrees (or ckPI/2) as an angle range.
This function supports the use of a ccTimeout-based timeout.
Throws
ccAcuSymbolDefs::BadImage
The image is not bound.
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
learnFlags
c_UInt32 learnFlags() const;
void learnFlags(c_UInt32 flags);
•
c_UInt32 learnFlags() const;
Gets the learnable parameter flags. The parameter flags must be a bitwise combination
of any of the ccAcuSymbolDataMatrixDefs::LearnFlags values. flags must be in the
range 0 through 31.
426
CVL Class Reference
ccAcuSymbolDataMatrixTool
•
void learnFlags(c_UInt32 flags);
Sets the learnable parameter flags, which are:
Value
Meaning
eNone = 0
Tool learns no parameters.
eECC = 1
Tool learns ECC level.
eGrid = 2
Tool learns Grid size.
eNominalGrid = 4
Tool learns nominal grid.
ePolarity = 8
Tool learns polarity.
eModel = 16
Turns optimization on.
eAll = 31
Tool learns all learning parameters.
kDefaultLearn = eAll
Default is for the tool to learn all learning
parameters.
The parameter flags must be a bitwise combination of any of the
ccAcuSymbolQRCodeDefs::LearnFlags values. flags must be in the range 0 through 31.
Parameters
flags
The learnFlags that if set, direct the tool to learn a specific Learn
parameter.
Notes
In high-contrast mode, the tool ignores the flags value, unless it is
ccAcuSymbolDataMatrixDefs::eNone, and uses
ccAcuSymbolDataMatrixDefs::eAll.
Throws
ccAcuSymbolDefs::BadParams
flags is not in the range 0 through 31.
tune
virtual void tune (ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccAffineSamplingParams &affParams,
CVL Class Reference
427
ccAcuSymbolDataMatrixTool
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &tuneParams,
ccAcuSymbolTuneResult &tuneResult);
virtual void tune (
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &startTuneParams,
ccAcuSymbolTuneResult &tuneResult);
•
virtual void tune (ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccAffineSamplingParams &affParams,
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &tuneParams,
ccAcuSymbolTuneResult &tuneResult);
This function automatically determines the optimal lighting properties using the supplied
ccGreyAcqFifo to acquire images. The supplied cc2Xform and
ccAffineSamplingParams are used to extract the region of interest from each acquired
image. The supplied ccAcuSymbolTuneParams object is used to set the tuning
parameters and the supplied ccAcuSymbolFinderParams object is used to locate the
symbols.
If the tool is currently in the learned state (isLearned() returns true), this function uses
the best learned parameters and calls decode(); otherwise, this function invokes the
learn() function.
The tuned parameters (and the decode results produced using those parameters) are
returned through the supplied ccAcuSymbolTuneResult object. If tuning is successful,
the lighting properties of the supplied ccGreyAcqFifo are set to the tuned values. If
tuning fails, the original values are restored.
Parameters
fifo
428
The fifo to acquire images with.
xform
A cc2xform that describes the region of interest.
affParams
The sampling parameters to use to construct the region of
interest image.
findParams
The search parameters to use to find the symbol.
tuneParams
The tuning parameters to use for tuning.
tuneResult
A reference to a ccAcuSymbolTuneResult object into which the
results of tuning are placed.
CVL Class Reference
ccAcuSymbolDataMatrixTool
Notes
You can override the update() function to control the tuning process.
This function supports the use of a ccTimeout-based timeout.
Throws
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
•
virtual void tune (
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &startTuneParams,
ccAcuSymbolTuneResult &tuneResult);
This function automatically determines the optimal lighting properties using images
acquired by calling your override of the ccAcuSymbolTool::acquireImage() function.
The supplied ccAcuSymbolTuneParams object is used to set the tuning parameters
and the supplied ccAcuSymbolFinderParams object is used to locate the symbols.
The tuned parameters (and the decode results produced using those parameters) are
returned through the supplied ccAcuSymbolTuneResult object.
Parameters
findParams
The search parameters to use to find the symbol.
tuneParams
The initial tuning parameters to use for tuning (supplied to your
callback function).
tuneResult
A reference to a ccAcuSymbolTuneResult object into which the
results of tuning are placed.
Notes
This function supports the use of a ccTimeout-based timeout.
Throws
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
CVL Class Reference
429
ccAcuSymbolDataMatrixTool
430
CVL Class Reference
ccAcuSymbolDefs
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolDefs;
A name space that holds enumerations and constants used with the Symbol tool
classes.
Enumerations
TuneMethod
enum TuneMethod;
An enumeration that describes which method (learn or decode) was used during tuning.
TuneExitCode
Value
Meaning
eLearn
The learn method was used during
tuning.
eDecode
The decode method was used during
tuning.
enum TuneExitCode;
An enumeration that indicates why tuning was stopped.
CVL Class Reference
Value
Meaning
eNormal
Tuning completed normally.
eTime
Tuning timed out.
eNumSuccess
Tuning was stopped because the
specified number of successful decodes
without score improvement was
reached.
431
ccAcuSymbolDefs
OperatingMode
enum OperatingMode;
An enumeration that describes operating modes for the Symbol tool.
Value
Meaning
eHighContrast
An operating mode suitable for label, PCB, and
high-contrast, direct-mark applications where there is
high-contrast within the symbol region and possibly
high clutter/confusion outside the symbol region.
eStandard
An operating mode intended for wafer and degraded
direct-mark applications where there is the possibility of
low contrast or degradation within the symbol region
and low clutter/confusion outside the symbol region.
eAutoDetect
The Symbol tool automatically selects and runs in an
appropriate operating mode based on your system’s
security. Use eAutoDetect for general, direct-mark
applications.
System behavior is dependent on the level of hardware security present in your
machine. Two security levels are available: Standard security uses the 2DSymbol
security bit, and High Contrast security uses the 2DSymbolHighContrast security bit. If
you wish to run in eStandard mode, you require Standard security in your machine. If
you wish to run in eHighContrast mode, you require High Contrast security in your
machine. eAutoDetect mode checks your system security and runs in the appropriate
mode.
The following table summarizes the operating modes, hardware security, and system
behavior.
Run Mode
Security
System behavior
eStandard
Standard
Runs in eStandard mode
High Contrast
Throws an exception
Standard and High Contrast
Runs in eStandard mode
Standard
Throws an exception
High Contrast
Runs in eHighContrast mode
Standard and High Contrast
Runs in eHighContrast mode
eHighContrast
432
CVL Class Reference
ccAcuSymbolDefs
CVL Class Reference
Run Mode
Security
System behavior
eAutoDetect
Standard
Runs in eStandard mode
High Contrast
Runs in eHighContrast mode
Standard and High Contrast
Runs in combined mode
433
ccAcuSymbolDefs
434
CVL Class Reference
ccAcuSymbolFinderParams
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolFinderParams : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class holds a set of parameters used to locate and decode both Data Matrix and
QR Code symbols. The parameters are defaulted at construction, and may be read
using getters and written using setters.
Constructors/Destructors
ccAcuSymbolFinderParams
ccAcuSymbolFinderParams();
Creates a ccAcuSymbolFinderParams object and sets all parameters to the following
default values:.
CVL Class Reference
Parameter
Value
accept
0.5
confusion
0.7
contrast
0.5
angleRange
ckPI/90.0
scaleRange
0.0
aspectDistortion
1.0
angleRef
cc2Vect(1.0, 0.0)
435
ccAcuSymbolFinderParams
Operators
operator==
bool operator== (const ccAcuSymbolFinderParams &that)
const;
Returns true if these finder parameters are the same as another set. Two parameter sets
are considered equal if all of their attributes are the same.
Public Member Functions
accept
double accept() const;
Returns the acceptance threshold.
acceptAndConfusion
void acceptAndConfusion(double accept, double confusion);
Sets the acceptance and confusion thresholds during the search phase, the period
when the tool searches for a symbol. Both accept and confusion must be between 0.0
and 1.0 inclusive, and accept must be less than or equal to confusion.
Parameters
accept
confusion
The acceptance threshold, a score below which the tool rejects
a candidate symbol as a symbol.
The confusion threshold, a score above which the tool accepts
the candidate symbol as a symbol.
Notes
Features which return a score below the accept threshold are not considered
during the search phase.
The confusion parameter specifies the maximum score that an erroneous feature
can have and not be considered a symbol. Features that return scores greater than
or equal to the confusion threshold are considered to be valid instances of the
symbol.
Features that return scores below the confusion threshold but greater than or equal
to the accept threshold may or may not be valid instances of the symbol.
Throws
ccAcuSymbolDefs::BadParams
The above conditions are not met.
436
CVL Class Reference
ccAcuSymbolFinderParams
angleRange
ccRadian angleRange() const;
void angleRange(ccRadian range);
•
ccRadian angleRange() const;
Gets the angle range specified in radians. The angle range is a range of angles through
which the Symbol tool rotates the symbol model during the search phase. If the angle of
the runtime symbol matches the angle of the symbol model after being rotated, the
Symbol tool considers the runtime symbol to be an instance of the symbol if all other Find
parameters have acceptable values. Requires that the range must be greater than or
equal to 0.0.
•
void angleRange(ccRadian range);
Sets the angle range, specified in radians. Requires that the range must be greater than
or equal to 0.0.
Parameters
range
The allowed deviation in radians of the angle parameter from its
expected value
Throws
ccAcuSymbolDefs::BadParams
The range is not greater than or equal to 0.0.
Notes
This parameter sets the range of angles to be considered while locating the symbol.
The range of angles considered is:
angleRef
•
nominal angle - range
•
nominal angle + range
cc2Vect angleRef () const;
void angleRef (const cc2Vect &ref);
•
cc2Vect angleRef () const;
Gets the angle that specifies the reference coordinate system of the symbol. This
coordinate system is relative to the x-axis of the current coordinate system of the tool.
Requires both angleRef.x() and angleRef.y() must be in the range -1.0 through 1.0.
CVL Class Reference
437
ccAcuSymbolFinderParams
•
void angleRef (const cc2Vect &ref);
Sets the angle that specifies the reference coordinate system of the symbol. This
coordinate system is relative to the x-axis of the current coordinate system of the tool.
Requires both angleRef.x() and angleRef.y() must be in the range -1.0 through1.0.
Parameters
ref
A vector that specifies the reference angle with respect to the
x-axis of the current coordinate system.
Notes
You use the angleRef parameter when a symbology is aligned with a specific
reference orientation. For such cases, you can specify the x and y components of
the angleRef vector in the reference direction with respect to the x-axis of the
current coordinate system. All angles are then be measured with respect to the
specified reference orientation.
Using the angleRef parameter assumes that the current coordinate system is
orthogonal.
Throws
ccAcuSymbolDefs::BadParams
The above condition is not met.
aspectDistortion
double aspectDistortion() const;
void aspectDistortion(double aspectDistortion);
•
double aspectDistortion() const;
Gets the expected aspect distortion while determining the location of the symbol, with
respect to the client coordinate space of the image presented for learn/decode.
Requires that the aspectDistortion be greater than 0.0.
•
void aspectDistortion(double aspectDistortion);
Sets the expected aspect distortion while determining the location of the symbol, with
respect to the client coordinate space of the image presented for learn/decode.
Requires that the aspectDistortion be greater than 0.0.
Parameters
aspectDistortion The expected ratio of pixel width to pixel height.
438
CVL Class Reference
ccAcuSymbolFinderParams
Notes
You should use the default value except with unusual cameras or single-field
acquires.
Throws
ccAcuSymbolDefs::BadParams
The above condition is not met.
confusion
double confusion() const;
Returns the confusion threshold.
contrast
double contrast() const;
void contrast(double contrast);
•
double contrast() const;
Gets minimum acceptable model contrast expressed as a fraction of the trained
symbol’s contrast.
•
void contrast(double contrast);
Sets minimum acceptable model contrast expressed as a fraction of the trained
symbol’s contrast. Requires the specified value must be between 0.0 and 1.0 inclusive.
Parameters
contrast
The minimum acceptable image contrast where contrast is the
difference in pixel value between the symbol and the background
Throws
ccAcuSymbolDefs::BadParams
The above condition is not met.
scaleRange
double scaleRange() const;
void scaleRange(double range);
•
double scaleRange() const;
Gets the scale range, which is a range of percentages by which the Symbol tool
multiplies the size of the model during the search phase. If size of the runtime symbol
matches the size of the symbol model after being multiplied by any of these
CVL Class Reference
439
ccAcuSymbolFinderParams
percentages, the Symbol tool considers the runtime symbol to be an instance of the
symbol if all other Find parameters have acceptable values. Requires that the scale
must be greater than or equal to 0.0.
•
void scaleRange(double range);
Sets the scale range. Requires that the scale must be greater than or equal to 0.0.
Parameters
range
The range of variation in the scale parameter while locating the
symbol expressed as a percentage. To specify a value of 5%,
supply a value of 0.05.
Throws
ccAcuSymbolDefs::BadParams
The above condition is not met.
440
CVL Class Reference
ccAcuSymbolLearnParams
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolLearnParams : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
Cognex-supplied classes
only
Archiveable
Complex
The ccAcuSymbolLearnParams class is an abstract base class from which the tool
specific classes, ccAcuSymbolDataMatrixLearnParams and
ccAcuSymbolQRCodeLearnParams, are derived. These classes provide symbology
specific parameters for learning.
Constructors/Destructors
The constructors and destructors are used by the derived classes. You should not need
to use them in your own applications.
Public Member Functions
angle
ccRadian angle() const;
void angle(ccRadian ang);
•
ccRadian angle() const;
Gets the expected orientation of the symbol to be located.
•
void angle(ccRadian ang);
Sets the expected orientation of the symbol to be located. (The expected angle is
relative to the client coordinate system of the image.)
Parameters
ang
CVL Class Reference
The expected angle of the symbol to be located.
441
ccAcuSymbolLearnParams
cellSizeRange
const ccRange &cellSizeRange() const;
void cellSizeRange(const ccRange &range);
•
const ccRange &cellSizeRange() const;
Returns the range of the cell size for the 2-D symbol. The range is measured in the client
units of the learn-time image.
•
void cellSizeRange(const ccRange &range);
Sets the range of the cell size for the 2-D symbol. The range is measured in the client
units of the learn-time image.
Parameters
range
The cell size range.
Throws
ccAcuSymbolDefs::BadParams
The start or end of the cell size range is less than 0.
Notes
The cell size range is not learned. It applies to high-contrast and standard operating
modes.
If you supply an empty range (ccRange::EmptyRange(), the default value) the tool
determines an optimal cell size range. The optimal cell size range varies with
operating mode and symbology. The following table shows these default ranges for
standard and high-contrast operating modes.
Mode
Symbol type
Range (min)
Range (max)
eStandard
QR Code symbols
7 pixels
14 pixels
Data Matrix symbols
4.5 pixels
9 pixels
Continuous symbols
7 pixels
21 pixels
Dot-matrix symbols
7 pixels
14 pixels
eHighContrast
Setting a cell size range larger than these default ranges can substantially increase
the tool execution time during learning operations.
When loading from older archives, the cell size range is set to its default value.
442
CVL Class Reference
ccAcuSymbolLearnParams
mirrorFlag
bool mirrorFlag() const;
void mirrorFlag(bool mirror);
•
bool mirrorFlag() const;
Gets the mirror flag.
•
void mirrorFlag(bool mirror);
Sets the mirror flag. If mirror is true, then mirroring is present, and the tool automatically
reverses the image after acquisition.
Parameters
mirror
Indicates whether the images containing the symbols to be
decoded are mirrored or not.
Notes
The mirror parameter is learned only when the tool operates in high-contrast mode.
Otherwise, a user input is required.
nominalGrid
const ccAffineRectangle& nominalGrid () const;
void nominalGrid (const ccAffineRectangle& affRect);
•
const ccAffineRectangle& nominalGrid () const;
Gets the affine rectangle which defines the 2D symbol grid.
•
void nominalGrid (const ccAffineRectangle& affRect);
Sets the affine rectangle which defines the 2D symbol grid.
Parameters
affRect
The affine rectangle that defines the 2D symbol grid.
Notes
The affine rectangle specified should be defined to enable the tool to determine the
dimensions and orientation of the finder pattern and the 2D symbol grid of the
symbol to be located. The specification of an affine rectangle allows variations in
the scale, orientation, and aspect from the symbol model used to locate the symbol
CVL Class Reference
443
ccAcuSymbolLearnParams
in the runtime image. These variations typically arise from two sources: (1) From the
characteristics of the camera used to acquire the image of the printed symbol, and
(2) during printing of the symbol.
The nominal grid of a Data Matrix symbol is defined by the 3 corners of its L-shaped
finder pattern. The nominal grid of a Model 1 or Model 2 QR Code symbol is defined
by the centers of the 3 finder patterns, whereas the nominal grid of a Micro QR Code
symbol is defined by the corners formed by the single finder pattern and the 2
timing patterns running along the top row and left column of the symbol.
scale
double scale() const;
void scale(double scale);
•
double scale() const;
Gets the ratio of the expected scale of the symbol to be located in relation to the scale
of the model. Requires scale must be greater than 0.0.
•
void scale(double scale);
Sets the ratio of the expected scale of the symbol to be located in relation to the scale
of the model. Requires scale must be greater than 0.0. (The scale of the symbol used in
the learning phase becomes the scale of the model.)
Parameters
scale
The expected scale of the symbol to be located in relation to the
scale of the model.
Throws
ccAcuSymbolDefs::BadParams
The scale is not greater than 0.0.
Notes
This parameter is relative to the client coordinate space of the image presented for
learn/decode. For example, specifying scale to be 1.2 implies that the expected
scale of the symbol (in client coordinate space) is 1.2 times the scale of the model
(in client coordinate space).
444
CVL Class Reference
ccAcuSymbolLearnParams
Operators
operator==
bool operator== (const ccAcuSymbolLearnParams &that) const;
Returns true if these learn parameters are the same as another set. Two parameter sets
are considered equal if all of their attributes are the same.
CVL Class Reference
445
ccAcuSymbolLearnParams
446
CVL Class Reference
ccAcuSymbolQRCodeDefs
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolQRCodeDefs: public ccAcuSymbolDefs;
A name space that holds enumerations and constants used with the Symbol tool
classes.
Enumerations
Polarity
enum Polarity;
Values for the Polarity parameter:
QRModelType
Value
Meaning
eDarkOnLight
Dark symbol on a light background
eLightOnDark
Light symbol on a dark background
enum QRModelType;
Values for the QRModelType parameter:
LearnFlags
Value
Meaning
eQRModelUnknown = 0
Unknown model
eQRModel1 = 1
Model 1
eQRModel2 = 2
Model 2
eMicroQR = 4
Micro QR code
kDefaultQRModel =
eQRModel2
Model 2
enum LearnFlags;
Setting the following LearnFlags determines which parameters the tool learns:
CVL Class Reference
Value
Meaning
eNone = 0
Tool learns no parameters.
eQRModel = 1
Tool learns QR model.
447
ccAcuSymbolQRCodeDefs
Value
Meaning
eGrid = 2
Tool learns grid size.
eNominalGrid = 4
Tool learns nominal grid.
ePolarity = 8
Tool learns polarity.
eModel = 16
Turns optimization on.
eAll = 31
Tool learns all learning parameters.
kDefaultLearn = eAll
Default is for the tool to learn all
parameters.
kMaxQRModelSize
enum kMaxQRModelSize;
Maximum size for a QR Code symbol:
448
Value
Meaning
kMaxQRModelSize = 45
The maximum supported symbol size is
45.
CVL Class Reference
ccAcuSymbolQRCodeLearnParams
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolQRCodeLearnParams:
public ccAcuSymbolLearnParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
The class ccAcuSymbolQRCodeLearnParams supplies the parameters that the
Symbol tool uses to create a QR Code symbol model. The tool can acquire values for
the parameters in this class in the following ways:
•
You can set the Learn parameters to their default values by using the default
constructor.
•
You can specify values for specific Learn parameters using the overload
constructor.
•
You can set values for the Learn parameters using the setters of the class.
•
You can have the tool learn the parameters specified by learnFlags. For those
parameters not learned by the tool, you use this class to specify the values.
Constructors/Destructors
ccAcuSymbolQRCodeLearnParams
ccAcuSymbolQRCodeLearnParams();
virtual ~ccAcuSymbolQRCodeLearnParams();
ccAcuSymbolQRCodeLearnParams(
const ccAffineRectangle& nominalGrid,
c_Int32 size,
ccAcuSymbolQRCodeDefs::QRModelType model =
ccAcuSymbolQRCodeDefs::kDefaultQRModel,
ccAcuSymbolQRCodeDefs::Polarity symbolPolarity =
ccAcuSymbolQRCodeDefs::eDarkOnLight,
CVL Class Reference
449
ccAcuSymbolQRCodeLearnParams
ccRadian angle = ccRadian(0.0),
double scale = 1.0,
bool mirror = false);
•
ccAcuSymbolQRCodeLearnParams();
Default constructor. The members are initialized to their default values, which are:
Parameter
Value
size
21
nominalGrid
points at (0, 21), (21, 21), (0, 0)
qrModelType
ccAcuSymbolQRCodeDefs::kDefaultQRModel
symbolPolarity
ccAcuSymbolQRCodeDefs::eDarkOnLight
Notes
The nominal grid as well as the number of rows and columns are set to match the
smallest symbol size (21 x 21) allowed for a QR Code model 2 symbol. The
transform of the nominal grid is set to identity. qrModelsToLearn is set to
eQRModel2 | eMicroQR by default.
•
virtual ~ccAcuSymbolQRCodeLearnParams();
Destroys instances of this class.
•
450
ccAcuSymbolQRCodeLearnParams(
const ccAffineRectangle& nominalGrid,
c_Int32 size,
ccAcuSymbolQRCodeDefs::QRModelType model =
ccAcuSymbolQRCodeDefs::kDefaultQRModel,
ccAcuSymbolQRCodeDefs::Polarity symbolPolarity =
ccAcuSymbolQRCodeDefs::eDarkOnLight,
CVL Class Reference
ccAcuSymbolQRCodeLearnParams
ccRadian angle = ccRadian(0.0),
double scale = 1.0,
bool mirror = false);
Constructor overload with specified values. qrModelsToLearn is set to its default value
of eQRModel2 | eMicroQR.
The function has the following requirements:
•
model should be one of the predefined types: unknown, model1, model 2. or
microQR
•
size should be:
•
in the range 21 through kMaxQRModelSize for eQRModel1
•
in the range 21 through kMaxQRModelSize for eQRModel2
•
in the range 11 through 17 for eMicroQR
Parameters
nominalGrid
The affine rectangle that encloses the symbol.
size
The grid size where the length and width of the symbol are equal.
model
unknown, model1, model 2. or microQR.
symbolPolarity
The polarity of the symbol, either dark on light or light on dark.
angle
The angle of the symbol relative to the model.
scale
The scale of the symbol relative to the model.
mirror
If true, then the tool reverses the image of the symbol after
acquisition.
Throws
ccAcuSymbolDefs::BadParams
The conditions described above are not met.
Operators
operator==
bool operator== (
const ccAcuSymbolQRCodeLearnParams &that) const;
Compares this object with another. Two ccAcuSymbolQRCodeLearnParams objects
are considered equal if all their corresponding data members are identical.
CVL Class Reference
451
ccAcuSymbolQRCodeLearnParams
Public Member Functions
modelTypeAndSize
void modelTypeAndSize (
ccAcuSymbolQRCodeDefs::QRModelType modelType,
c_Int32 size);
Sets the QR Code model type and grid size. The function has the following
requirements:
•
modelType should be one of the predefined types: unknown, model1, model 2. or
microQR
•
size should be:
•
in the range 21 through kMaxQRModelSize for eQRModel1
•
in the range 21 through kMaxQRModelSize for eQRModel2
•
in the range 11 through 17 for eMicroQR
Parameters
modelType
size
unknown, model1, model 2. or microQR.
The grid size where the length and width of the symbol are equal.
Notes
The number of rows is always equal to the number of columns.
Throws
ccAcuSymbolDefs::BadParams
The conditions described above are not met.
qrModel
ccAcuSymbolQRCodeDefs::QRModelType qrModel()
const;
Gets the QR Code model type.
size
c_Int32 size() const;
Gets the grid size.
Notes
The number of rows is always equal to the number of columns.
452
CVL Class Reference
ccAcuSymbolQRCodeLearnParams
symbolPolarity
ccAcuSymbolQRCodeDefs::Polarity symbolPolarity()
const;
void symbolPolarity (
ccAcuSymbolQRCodeDefs::Polarity pol);
•
ccAcuSymbolQRCodeDefs::Polarity symbolPolarity()
const;
Gets the symbol polarity, which is either dark-on-light or light-on-dark.
•
void symbolPolarity (
ccAcuSymbolQRCodeDefs::Polarity pol);
Sets the symbol polarity.
Parameters
pol
The polarity of the symbol, either dark-on-light or light-on-dark.
qrModelsToLearn
c_UInt32 qrModelsToLearn() const;
void qrModelsToLearn(c_UInt32 modelsToLearn);
Get/Set the QR Code model types to look for at learn time when the model type of the
symbol is to be determined by the tool. When the model type need not be learned, this
parameter is ignored and qrModelType is used instead.
The model types are specified as a bitwise-OR of the appropriate entries from
ccAcuSymbolQRCodeDefs::QRModelType.
•
c_UInt32 qrModelsToLearn() const;
Returns the QR Code model types.
•
void qrModelsToLearn(c_UInt32 modelsToLearn);
Sets the QR Code model types.
Parameters
modelsToLearn
CVL Class Reference
The model types.
453
ccAcuSymbolQRCodeLearnParams
Throws
ccAcuSymbolDefs::BadParams
If modelsToLearn = 0,
or if modelsToLearn is a value not created by the bitwise-OR of
values from ccAcuSymbolQRCodeDefs::QRModelType.
Notes
This parameter is not learned.
At decode time the tool can only decode a symbol with a model type that it has
learned, as specified by the internally stored learned params.
454
CVL Class Reference
ccAcuSymbolQRCodeTool
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolQRCodeTool : public ccAcuSymbolTool;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
You use this class to create the central object for the QR Code tool, which contains the
trained representation of a QR Code symbol, and the functions for the learn and decode
phases of the tool’s operation.
CVL Class Reference
455
ccAcuSymbolQRCodeTool
Constructors/Destructors
ccAcuSymbolQRCodeTool
ccAcuSymbolQRCodeTool (
ccAcuSymbolDefs::OperatingMode opMode =
ccAcuSymbolDefs::eAutoDetect);
virtual ~ccAcuSymbolQRCodeTool();
ccAcuSymbolQRCodeTool (
const ccAcuSymbolQRCodeLearnParams& learnParams,
c_UInt32 learnFlags,
ccAcuSymbolDefs::OperatingMode opMode =
ccAcuSymbolDefs::eAutoDetect );
•
ccAcuSymbolQRCodeTool (
ccAcuSymbolDefs::OperatingMode opMode =
ccAcuSymbolDefs::eAutoDetect);
Constructs a Symbol tool for decoding QR Code symbols. The tool is in an unlearned
state, the operating mode defaults to eAutoDetect, and all members are initialized to the
following defaults:
•
Parameter
Value
initialLearnParams
default constructed ccAcuSymbolQRCodeLearnParams
bestLearnedParams
default constructed ccAcuSymbolQRCodeLearnParams
learnFlags
ccAcuSymbolQRCodeDefs::eAll
isLearned
false
virtual ~ccAcuSymbolQRCodeTool();
Destroys instances of this class.
456
CVL Class Reference
ccAcuSymbolQRCodeTool
•
ccAcuSymbolQRCodeTool (
const ccAcuSymbolQRCodeLearnParams& learnParams,
c_UInt32 learnFlags,
ccAcuSymbolDefs::OperatingMode opMode =
ccAcuSymbolDefs::eAutoDetect);
Creates a Symbol tool that learns those parameters in the
ccAcuSymbolQRCodeLearnParams object specified by learnFlags and sets the
remaining parameters to their defaults or to those values supplied by the setters of the
ccAcuSymbolQRCodeLearnParams class. (Constructor overload)
Requires that learnFlags be a bitwise combination of any of the
ccAcuSymbolQRCodeDefs::LearnFlags values. learnFlags must be in the range 0
through 31.
Parameters
learnParams
Parameters that the tool can learn or you can set. Examples
include QRModel type, grid size, nominal grid, and polarity. You
must set the Learn parameter mirrorFlag or use the default.
learnFlags
Flags that when set direct the tool to learn a specific Learn
parameter. Values set in the
ccAcuSymbolQRCodeLearnParams object are ignored by the
learn() function unless the appropriated learnFlags value is set.
opMode
Determines the operating mode for the tool, which can be one of:
ccAcuSymbolDefs::eStandard
ccAcuSymbolDefs::eHighContrast
ccAcuSymbolDefs::eAutoDetect
Throws
ccAcuSymbolDefs::BadParams
learnFlags is not in the range 0 through 31.
Public Member Functions
bestLearnedParams
const ccAcuSymbolQRCodeLearnParams&
bestLearnedParams() const;
Returns the final learned parameters after the tool, which is in Learn and Decode mode,
has performed the following actions:
1.
Found a symbol in the image.
2.
Learned the parameters specified by learnFlags.
CVL Class Reference
457
ccAcuSymbolQRCodeTool
3.
Created a model from the parameters specified by learnFlags and those specified
by the ccAcuSymbolQRCodeLearnParams object.
4.
Decoded the symbol.
Notes
This function should be used to get the learned parameters after the tool has
undergone learning successfully as indicated by isLearned() returning true.
Throws
ccAcuSymbolDefs::NotLearned
This function is invoked when the tool has not undergone the
learning phase successfully and isLearned() returns false.
decode
bool decode (
const ccPelBuffer_const<c_UInt8>& image,
const ccAcuSymbolFinderParams& findParams,
ccAcuSymbolResult& result) const;
Finds the symbol in the given image and decodes it using the specified Find parameters
and internally stored Learn parameters. The result of decoding is returned via the result
object. Returns true if successful; false if the operation failed. Requires that the image
be bound.
This function places the tool in Standard Decode mode for QR Code symbology.
Parameters
image
The acquired image. The pel buffer must be bound.
findParams
The Find parameters, which the tool uses to locate and orient
each runtime symbol. Examples include angle, scale, confusion
threshold, and acceptance threshold.
result
The result object that contains data derived from the decoding
operation including angle, score, and scale.
Notes
In high-contrast mode, the tool ignores the findParams value, and instead uses 5%
as a scale range and 180 degrees (or ckPI/2) as an angle range.
This function supports the use of a ccTimeout-based timeout.
Throws
ccAcuSymbolDefs::BadImage
The image is not bound.
458
CVL Class Reference
ccAcuSymbolQRCodeTool
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
initialLearnParams
const ccAcuSymbolQRCodeLearnParams& initialLearnParams()
const;
void initialLearnParams(
const ccAcuSymbolQRCodeLearnParams& learnParams);
•
const ccAcuSymbolQRCodeLearnParams& initialLearnParams()
const;
Gets the initial parameters used for learning prior to estimation by the learn and decode
phase.
•
void initialLearnParams(
const ccAcuSymbolQRCodeLearnParams& learnParams);
Sets the initial parameters used for learning prior to estimation by the learn and decode
phase.
Parameters
learnParams
Parameters that the tool can learn or that you can set. Examples
include QRModel type, grid size, nominal grid, and polarity. You
must set the Learn parameter mirrorFlag or use the default.
Notes
The setter function should be used to initialize the learn parameters in preparation
for the learning phase.
When operating in high-contrast mode, the tool ignores all initial learn parameters
except for the cell size range and qrModelsToLearn.
CVL Class Reference
459
ccAcuSymbolQRCodeTool
learn
void learn (const ccPelBuffer_const<c_UInt8>& image,
const ccAcuSymbolFinderParams& findParams,
ccAcuSymbolResult& result);
Estimates the optimal configuration of selected symbol learning parameters as specified
by initialLearnParams and learnFlags. If learning is successful, the tool updates
bestLearnedParams and decodes the symbol using the internally learned parameters
and the findParams object. Finally, the tool returns decoding results via the result object.
Requires that the image be bound.
This function places the tool in Learn and Decode mode for QR Code symbology.
Parameters
image
The acquired image. The pel buffer must be bound.
findParams
The Find parameters, which the tool uses to locate and orient
each runtime symbol. Examples include angle, scale, confusion
threshold, and acceptance threshold.
result
The result object that contains data derived from the decoding
operation including angle, score, and scale.
Notes
In high-contrast mode, the tool ignores the findParams value, and instead uses 5%
as a scale range and 180 degrees (or ckPI/2) as an angle range.
This function supports the use of a ccTimeout-based timeout.
Throws
ccAcuSymbolDefs::BadImage
The image is not bound.
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
ccAcuSymbolDefs::BadParams
If there are any inconsistencies between the learnable parameter
flags and the appropriate learn parameters. For example, the
eQRModel bit of the learn flags is set to 0 (meaning the model
type of the symbol should not be learned) but the model type
provided by the initial learn parameters is eQRModelUnknown.
460
CVL Class Reference
ccAcuSymbolQRCodeTool
learnFlags
c_UInt32 learnFlags() const;
void learnFlags(c_UInt32 flags);
•
c_UInt32 learnFlags() const;
Gets the learnable parameter flags, a bitwise combination of any of the
ccAcuSymbolQRCodeDefs::LearnFlags values. learnFlags_ must be in the range 0
through 31.
•
void learnFlags(c_UInt32 flags);
Sets the learnable parameter flags, which are:
Value
Meaning
eNone = 0
Tool learns no parameters.
eQRModel = 1
Tool learns QR model.
eGrid = 2
Tool learns grid size.
eNominalGrid = 4
Tool learns nominal grid.
ePolarity = 8
Tool learns polarity.
eModel = 16
Turns optimization on.
eAll = 31
Tool learns all parameters.
kDefaultLearn = eAll
Default is for the tool to learn all
parameters.
The parameter flags must be a bitwise combination of any of the
ccAcuSymbolQRCodeDefs::LearnFlags values. flags must be in the range 0 through 31.
Parameters
flags
The learnFlags that when set direct the tool to learn a specific
Learn parameter.
Notes
In high-contrast mode, the tool ignores the flags value, unless it is
ccAcuSymbolQRCodeDefs::eNone, and uses ccAcuSymbolQRCodeDefs::eAll.
Throws
ccAcuSymbolDefs::BadParams
flags is not in the range 0 through 31.
CVL Class Reference
461
ccAcuSymbolQRCodeTool
tune
virtual void tune (ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccAffineSamplingParams &affParams,
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &tuneParams,
ccAcuSymbolTuneResult &tuneResult);
virtual void tune (
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &startTuneParams,
ccAcuSymbolTuneResult &tuneResult);
•
virtual void tune (ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccAffineSamplingParams &affParams,
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &tuneParams,
ccAcuSymbolTuneResult &tuneResult;
This function automatically determines the optimal lighting properties using the supplied
ccGreyAcqFifo to acquire images. The supplied cc2Xform and
ccAffineSamplingParams are used to extract the region of interest from each acquired
image. The supplied ccAcuSymbolTuneParams object is used to set the tuning
parameters and the supplied ccAcuSymbolFinderParams object is used to locate the
symbols.
If the tool is currently in the learned state (isLearned() returns true), this function uses
the best learned parameters and calls decode(); otherwise, this function invokes the
learn() function.
The tuned parameters (and the decode results produced using those parameters) are
returned through the supplied ccAcuSymbolTuneResult object. If tuning is successful,
the lighting properties of the supplied ccGreyAcqFifo are set to the tuned values. If
tuning fails, the original values are restored.
Parameters
fifo
462
The fifo to acquire images with.
xform
A cc2xform that describes the region of interest.
affParams
The sampling parameters to use to construct the region of
interest image.
findParams
The search parameters to use to find the symbol.
tuneParams
The tuning parameters to use for tuning.
tuneResult
A reference to a ccAcuSymbolTuneResult object into which the
results of tuning are placed.
CVL Class Reference
ccAcuSymbolQRCodeTool
Notes
You can override the update() function to control the tuning process.
This function supports the use of a ccTimeout-based timeout.
Throws
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
ccAcuSymbolDefs::BadParams
if, when learn() is invoked, there are any inconsistencies between
the learnable parameter flags and the appropriate learn
parameters. For example, the eQRModel bit of the learn flags is
set to 0 (meaning the model type of the symbol should not be
learned) but the model type provided by the initial learn
parameters is eQRModelUnknown.
•
virtual void tune (
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &startTuneParams,
ccAcuSymbolTuneResult &tuneResult);
This function automatically determines the optimal lighting properties using images
acquired by calling your override of the ccAcuSymbolTool::acquireImage() function.
The supplied ccAcuSymbolTuneParams object is used to set the tuning parameters
and the supplied ccAcuSymbolFinderParams object is used to locate the symbols.
The tuned parameters (and the decode results produced using those parameters) are
returned through the supplied ccAcuSymbolTuneResult object.
Parameters
findParams
The search parameters to use to find the symbol.
tuneParams
The initial tuning parameters to use for tuning (supplied to your
callback function).
tuneResult
A reference to a ccAcuSymbolTuneResult object into which the
results of tuning are placed.
Notes
This function supports the use of a ccTimeout-based timeout.
Throws
CVL Class Reference
463
ccAcuSymbolQRCodeTool
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
ccAcuSymbolDefs::BadParams
if, when learn() is invoked, there are any inconsistencies between
the learnable parameter flags and the appropriate learn
parameters. For example, the eQRModel bit of the learn flags is
set to 0 (meaning the model type of the symbol should not be
learned) but the model type provided by the initial learn
parameters is eQRModelUnknown.
464
CVL Class Reference
ccAcuSymbolResult
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolResult : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class contains the results for either Data Matrix and QR Code symbols.
Constructors/Destructors
ccAcuSymbolResult
ccAcuSymbolResult();
Constructs a ccAcuSymbolResult object with all members initialized to the following
default values:
CVL Class Reference
Parameter
Value
isFound
False
decodedFlag
False
decodedMBCSString
empty vector
decodedString
""
decodedData
0
location
cc2Vect(0.0, 0.0)
score
0.0
scale
1.0
angle
0.0
aspect
1.0
time
0.0
465
ccAcuSymbolResult
Parameter
Value
imgFromClient
Identity transform
resultGrid
Default constructed affine rectangle
numErrors
0
numErrorBits
0
learnParams
Default constructed
ccAcuSymbolLearnParams
Operators
operator==
bool operator==(const ccAcuSymbolResult&) const;
Returns true if all result parameters except for time are the same as another set. Two
parameter sets are considered equal if all of their attributes are the same.
Public Member Functions
angle
ccRadian angle() const;
Returns the angle with respect to the reference angle if any.
aspect
double aspect() const;
Returns the aspect ratio of the 2D symbol that was found with respect to the client
coordinate space. The aspect ratio is the expected ratio of pixel height to pixel width.
decodedData
cmStd vector<c_UInt8> decodedData() const;
Returns the raw bit-stream to be decoded as a sequence of bytes. You can use this
function to return a sequence of uninterpreted bytes, from which the original string
encoded in the symbol can be reconstructed using an alternate custom string decoder.
Throws
ccAcuSymbolDefs::BadString
This function is invoked when isFound() returns false.
Notes
The raw decoded data corresponds to the encoded bit-stream. It typically contains
sub-streams, which begin with a ECI header that contains information about the
mode used for encoding and the number of characters in the sub-stream. The
466
CVL Class Reference
ccAcuSymbolResult
header is followed by the data bit-stream. A raw bit-stream corresponding to a
QR Code symbol may be composed of two sub-streams, the first encoded in
AlphaNumeric mode, and the second in Kanji (2 bytes per character).
Conceptually, the raw bit-stream could be represented as follows:
|AlphaNumeric mode indicator|char count| -- Data bit-stream
--| |Kanji Mode indicator |char count| -- Data bit-stream --|
The sequence of bytes in the raw bit-stream should not be altered prior to decoding
as this may corrupt any multi-byte encoded data.
decodedString
ccCvlString decodedString() const;
Returns the decoded string of the symbol just found.
Throws
ccAcuSymbolDefs::BadString
This function is invoked when isDecoded() returns false.
Notes
This function processes the raw uninterpreted bit-stream and generates an ANSI
string. Use this function only for symbols that you know do not contain multibyte
characters.
decodedMBCSString
cmStd vector<c_UInt8> decodedMBCSString() const;
Returns the decoded data as a null-terminated, multi-byte string. The size of the vector
includes the null terminator.
For symbologies that encode 8-bit characters, this function returns a string of
single-byte characters. For example, for the Data Matrix symbology, this function returns
a single-byte stream of ASCII and extended ASCII characters.
For symbologies that encode single-byte and double-byte characters, this function
returns a stream of multi-byte characters. For example, for the QR Code symbology, this
function returns a stream of JIS8 characters (8-bit character set) and Shift JIS characters
(double-byte character set that encodes Kanji characters).
You can convert multi-byte characters to unicode using the mbtowc() and mbstowcs()
C library routines.
Throws
ccAcuSymbolDefs::BadString
If this function is invoked when isDecoded() returns false.
CVL Class Reference
467
ccAcuSymbolResult
imageFromClientXform
const cc2Xform& imageFromClientXform () const;
Returns the transform required to translate client coordinates to image coordinates.
isDecoded
bool isDecoded() const;
Returns true if this symbol is decoded, false otherwise.
isFound
bool isFound() const;
Returns true if this runtime symbol is found, false otherwise. A symbol is found if its score
equals or exceeds the accept threshold, implying that the symbol location was
determined with sufficient confidence.
location
cc2Vect location() const;
Returns the location of center of the found symbol in the client coordinate system of the
runtime image.
resultGrid
const ccAffineRectangle& resultGrid () const;
Returns the affine rectangle applied to compute this result. The affine rectangle returned
by this function reflects the “natural” orientation and handedness of the symbol being
decoded, as shown in the following figure:
Po
Px
Py
Py
Po
Px
Data Matrix (right-handed)
scale
QR Code (left handed)
double scale() const;
Returns the scale of the 2D symbol that was found, as a fraction of the scale of the model
size.
468
CVL Class Reference
ccAcuSymbolResult
score
double score() const;
Returns the result score in the range 0.0 through 1.0, which is the correlation between
the runtime symbol and the model.
Notes
If the score is 0.0 after the Symbol tool attempts to locate the symbol, the tool does
not perform the decoding step. In this case, the angle, scale and aspect are set to
their nominal values.
time
double time() const;
Returns the time (in seconds) required to decode the symbol.
numErrors
c_Int32 numErrors () const;
Returns the number of erroneous data words encountered while decoding the symbol.
The function returns -1 if this information is not available.
numErrorBits
c_Int32 numErrorBits () const;
Returns the number of erroneous bits encountered while decoding the symbol. This
function returns -1 if this information is not available
learnParams
const ccAcuSymbolLearnParams& learnParams () const;
Returns the ccAcuSymbolLearnParams used to compute this result.
Throws
ccAcuSymbolDefs::BadParams
The symbol is neither decoded nor found: both isFound() and
isDecoded() return false.
CVL Class Reference
469
ccAcuSymbolResult
470
CVL Class Reference
ccAcuSymbolTool
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolTool : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
Cognex-supplied classes
only
Archiveable
Complex
ccAcuSymbolTool is an abstract the base class from which the following tool classes
representing specific 2D matrix symbologies are derived:
•
ccAcuSymbolDataMatrixTool
•
ccAcuSymbolQRCodeTool
The Symbol tool operates in two modes:
•
Standard Decode mode where the tool uses a set of externally specified
parameters to locate and decode the target symbol
•
Learn and Decode mode, which consists of a learning phase and a decode phase
During the learning phase, the application acquires a source image with the target
symbol. The tool then locates a candidate symbol in the image and analyzes it, and
learns optimal parameters based on learning flags provided. The objective of the
learning phase is to estimate a set of parameters when incomplete information
regarding best parameters is available.The learned parameters are stored inside
the tool along with parameters that you specify as part of a model of the symbol.
During the decode phase, the tool decodes the symbol using the internally stored
parameters. Results of decoding are returned via a ccAcuSymbolResult object.
For more detailed information about the Symbol tool, see the chapter Symbol Tool in the
CVL Vision Tools Guide.
Constructors/Destructors
The constructors and destructors are used by the derived classes. You should not need
to use them in your own applications.
CVL Class Reference
471
ccAcuSymbolTool
Public Member Functions
decode
virtual bool decode (
const ccPelBuffer_const<c_UInt8>& image,
const ccAcuSymbolFinderParams& findParams,
ccAcuSymbolResult& result) const = 0;
Finds the symbol in the given image and decodes it using the specified findParams and
internally stored learned parameters. The result of decoding is returned via result.
Returns true if the decoding operation was successful; false if not. Requires that the
image be bound.
Notes
The function decode() should be over-ridden in the derived tool class. Because this
function is pure virtual, you need to define this function in all the classes derived
from this class corresponding to the standard decode phase of this tool.
After a symbol is found within a defined area, Decode() begins symbol recognition.
If the size in found symbols differs significantly (greater than ± 5 percent), the
function can fail. To prevent this failure, avoid using eHighContrast operating mode
and adjust the ScaleRange, which is one of the findParams, in proportion to the
difference in size.
Parameters
image
The pel buffer that contains the image being read.
findParams
The finder parameters, which the tool uses to locate and orient
each runtime symbol. Examples include angle, scale, confusion
threshold, and acceptance threshold.
result
The result object that contains data derived from the decoding
operation including angle, score, and scale.
Throws
ccAcuSymbolDefs::BadImage
The image is not bound.
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
isLearned
bool isLearned() const;
Gets the learned state of this tool. True indicates that the tool has undergone the learning
phase successfully, while false indicates an unsuccessful learning phase.
472
CVL Class Reference
ccAcuSymbolTool
learn
virtual void learn (
const ccPelBuffer_const<c_UInt8>& image,
const ccAcuSymbolFinderParams& findParams,
ccAcuSymbolResult& result) = 0;
Estimates the optimal configuration of selected symbol learning parameters as specified
by the initialLearnParams and learnFlags. The result of decoding is returned via the
result object. Requires that the image be bound.
Notes
The function learn() should be over-ridden in the derived tool class. Because this
function is pure virtual, you need to define this function in all the classes derived
from this class corresponding to the standard decode phase of this tool.
Parameters
image
The pel buffer that contains the image being read.
findParams
The finder parameters, which the tool uses to locate and orient
each runtime symbol. Examples include angle, scale, confusion
threshold, and acceptance threshold.
result
The result object that contains data derived from the decoding
operation including angle, score, and scale.
Throws
ccAcuSymbolDefs::BadImage
The image is not bound.
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
operatingMode
ccAcuSymbolDefs::OperatingMode operatingMode() const;
Returns the current operating mode for the tool, which can be one of the following
values:
ccAcuSymbolDefs::eStandard
ccAcuSymbolDefs::eHighContrast
ccAcuSymbolDefs::eAutoDetect
tune
virtual void tune (ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccAffineSamplingParams &affParams,
CVL Class Reference
473
ccAcuSymbolTool
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &tuneParams,
ccAcuSymbolTuneResult &tuneResult) = 0;
virtual void tune (
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &startTuneParams,
ccAcuSymbolTuneResult &tuneResult) = 0;
•
virtual void tune (ccGreyAcqFifo &fifo,
const cc2Xform &xform,
const ccAffineSamplingParams &affParams,
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &tuneParams,
ccAcuSymbolTuneResult &tuneResult) = 0;
This function automatically determines the optimal lighting properties using the supplied
ccGreyAcqFifo to acquire images. The supplied cc2Xform and
ccAffineSamplingParams are used to extract the region of interest from each acquired
image. The supplied ccAcuSymbolTuneParams object is used to set the tuning
parameters and the supplied ccAcuSymbolFinderParams object is used to locate the
symbols.
If the tool is currently in the learned state (isLearned() returns true), this function uses
the best learned parameters and calls decode(); otherwise, this function invokes the
learn() function.
The tuned parameters (and the decode results produced using those parameters) are
returned through the supplied ccAcuSymbolTuneResult object. If tuning is successful,
the lighting properties of the supplied ccGreyAcqFifo are set to the tuned values. If
tuning fails, the original values are restored.
Parameters
fifo
The fifo to acquire images with.
xform
A cc2xform that describes the region of interest.
affParams
The sampling parameters to use to construct the region of
interest image.
findParams
The search parameters to use to find the symbol.
tuneParams
The tuning parameters to use for tuning.
tuneResult
A reference to a ccAcuSymbolTuneResult object into which the
results of tuning are placed.
Notes
You can override the update() function to control the tuning process.
474
CVL Class Reference
ccAcuSymbolTool
Throws
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
•
virtual void tune (
const ccAcuSymbolFinderParams &findParams,
const ccAcuSymbolTuneParams &startTuneParams,
ccAcuSymbolTuneResult &tuneResult) = 0;
This function automatically determines the optimal lighting properties using images
acquired by calling your override of the acquireImage() function. The supplied
ccAcuSymbolTuneParams object is used to set the tuning parameters and the
supplied ccAcuSymbolFinderParams object is used to locate the symbols.
The tuned parameters (and the decode results produced using those parameters) are
returned through the supplied ccAcuSymbolTuneResult object.
Parameters
findParams
The search parameters to use to find the symbol.
tuneParams
The initial tuning parameters to use for tuning (supplied to your
callback function).
tuneResult
A reference to a ccAcuSymbolTuneResult object into which the
results of tuning are placed.
Throws
ccSecurityViolation
Hardware security is not enabled for the specified operating
mode; or hardware security is not enabled for any operating
mode.
update
virtual bool update (
const ccAcuSymbolTuneResult& currentTuneResult,
const ccAcuSymbolTuneResult& bestTuneResult);
Provides a hook that lets you update intermediate tune() results. The tuning process
continues as long as this function returns true. The default update() function always
returns true.
Parameters
currentTuneResult
The result of the current tune cycle.
CVL Class Reference
475
ccAcuSymbolTool
bestTuneResult
The result of the tune cycle that has produced the best (highest
scoring) result so far.
userPreProcessAcquiredImage
virtual bool userPreprocessAcquiredImage(
ccPelBuffer<c_UInt8>& src,
const ccPelRect& rect, ccPelBuffer<c_UInt8>& dst);
Provides a hook that lets perform your own preprocessing on images acquired by the
tool for reading or tuning. If your override returns false, tuning is stopped.
The default userPreprocessAcquiredImage() function copies the pixels in src that lie
within rect to dst and returns true.
Parameters
src
acquireImage
The acquired image. This pel buffer must be bound.
rect
The region of interest within src.
dst
The destination pel buffer. This pel buffer must be unbound.
virtual ccPelBuffer<c_UInt8> acquireImage(
const ccAcuSymbolTuneParams& tuneParams);
You must provide an override of this function if you use the second overload of the tune()
function. Your implementation should acquire and return an image. The function is
supplied with a ccAcuSymbolTuneParams you can use to control your acquisition.
Parameters
tuneParams
The tuning parameters computed by the tune() function.
Throws
ccAcuSymbolDefs::BadImage
You did not provide an override of this function.
476
CVL Class Reference
ccAcuSymbolTuneParams
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolTuneParams : public ccPersistent;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class lets you specify the parameters used to tune the lighting, parameters for
decoding symbols etched or scribed on reflective surfaces.
Constructors/Destructors
ccAcuSymbolTuneParams
ccAcuSymbolTuneParams (bool enableDark = true,
double darkLow = 0.062745,
double darkHigh = 1.0, double darkStep = 0.12157,
bool enableBright = true, double brightLow = 0.062745,
double brightHigh = 1.0, double brightStep = 0.12157,
double nominalLightPower = 0.062745,
double nominalBrightFieldPowerRatio = 1.0,
double maxTime = 3000., c_Int32 validLimit = 255);
Constructs a ccAcuSymbolTuneParams.
Parameters
enableDark
CVL Class Reference
True to enable darkfield tuning.
darkLow
The minimum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
darkHigh
The maximum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
darkStep
The darkfield step value. Must be in the range 0.0 through 1.0.
enableBright
True to enable brightfield tuning.
brightLow
The minimum light power for brightfield tuning. Must be in the
range 0.0 through 1.0.
477
ccAcuSymbolTuneParams
brightHigh
The maximum light power for brightfield tuning. Must be in the
range 0.0 through 1.0.
brightStep
The brightfield step value. Must be in the range 0.0 through 1.0.
nominalLightPower
The nominal light power value (used by the tune callback
function).
nominalBrightFieldPowerRatio
The nominal brightfield power ratio (the portion of the light power
allocated to brightfield lighting). Must be in the range 0.0 through
1.0. This value is used by the tune callback function.
maxTime
The maximum number of seconds to allow for tuning.
validLimit
The maximum number of successful decodes that can occur
without producing a new best score.
Throws
ccAcuSymbolToolDefs::BadParams
A parameter value was out of range.
Operators
operator==
bool operator== (const ccAcuSymbolTuneParams& that) const;
Two ccAcuSymbolTuneParams objects are considered equal if all of their data
members are equal to a numerical precision of 1.e-8.
Parameters
that
The ccAcuSymbolTuneParams to compare to this one.
Public Member Functions
enableBright
bool enableBright() const;
void enableBright(bool val);
•
bool enableBright() const;
Returns true if brightfield tuning is enabled.
•
void enableBright(bool val);
Enables or disables brightfield tuning.
478
CVL Class Reference
ccAcuSymbolTuneParams
Parameters
val
enableDark
True to enable brightfield tuning, false to disable.
bool enableDark() const;
void enableDark(bool val);
•
bool enableDark() const;
Returns true if darkfield tuning is enabled.
•
void enableDark(bool val);
Enables or disables darkfield tuning.
Parameters
val
brightLow
True to enable darkfield tuning, false to disable.
double brightLow() const;
void brightLow(double val);
•
double brightLow() const;
Returns the minimum light power for brightfield tuning.
•
void brightLow(double val);
Sets the minimum light power for brightfield tuning.
Parameters
val
The minimum light power for brightfield tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuSymbolToolDefs::BadParams
val was out of range.
CVL Class Reference
479
ccAcuSymbolTuneParams
brightHigh
double brightHigh() const;
void brightHigh(double val);
•
double brightHigh() const;
Returns the maximum light power for brightfield tuning.
•
void brightHigh(double val);
Sets the maximum light power for brightfield tuning.
Parameters
val
The maximum light power for brightfield tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuSymbolToolDefs::BadParams
val was out of range.
brightStep
double brightStep() const;
void brightStep(double val);
•
double brightStep() const;
Returns the brightfield step for tuning.
•
void brightStep(double val);
Sets the brightfield step for tuning.
Parameters
val
The brightfield step value. Must be in the range 0.0 through 1.0.
Throws
ccAcuSymbolToolDefs::BadParams
val was out of range.
480
CVL Class Reference
ccAcuSymbolTuneParams
darkLow
double darkLow() const;
void darkLow(double val);
•
double darkLow() const;
Returns the minimum light power for darkfield tuning.
•
void darkLow(double val);
Sets the minimum light power for darkfield tuning.
Parameters
val
The minimum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuSymbolToolDefs::BadParams
val was out of range.
darkHigh
double darkHigh() const;
void darkHigh(double val);
•
double darkHigh() const;
Returns the maximum light power for darkfield tuning.
•
void darkHigh(double val);
Sets the maximum light power for darkfield tuning.
Parameters
val
The maximum light power for darkfield tuning. Must be in the
range 0.0 through 1.0.
Throws
ccAcuSymbolToolDefs::BadParams
val was out of range.
CVL Class Reference
481
ccAcuSymbolTuneParams
darkStep
double darkStep() const;
void darkStep(double val);
•
double darkStep() const;
Returns the darkfield step for tuning.t
•
void darkStep(double val);
Sets the darkfield step for tuning.
Parameters
val
The darkfield step value. Must be in the range 0.0 through 1.0.
Throws
ccAcuSymbolToolDefs::BadParams
val was out of range.
nominalLightPower
double nominalLightPower() const;
void nominalLightPower(double val);
•
double nominalLightPower() const;
Returns the nominal light power value.
•
void nominalLightPower(double val);
Sets the nominal light power value. This value is used in conjunction with the
ccAcuSymbolTool::tune() function. It specifies the light power setting for a remote fifo
object used to acquire an image during tuning.
Parameters
val
The light power value in the range 0.0 through 1.0.
Throws
ccAcuSymbolToolDefs::BadParams
val was out of range.
482
CVL Class Reference
ccAcuSymbolTuneParams
nominalBrightFieldPowerRatio
double nominalBrightFieldPowerRatio() const;
void nominalBrightFieldPowerRatio(double val);
•
double nominalBrightFieldPowerRatio() const;
Returns the nominal brightfield power ratio (the portion, in the range 0.0 through 1.0, of
light power allocated to brightfield illumination).
•
void nominalBrightFieldPowerRatio(double val);
Sets the nominal brightfield power ratio (the portion, in the range 0.0 through 1.0, of light
power allocated to brightfield illumination). This value is used in conjunction with the
ccAcuSymbolTool::tune() function. It specifies the brightfield power ratio for a remote
fifo object used to acquire an image during tuning.
Parameters
val
The brightfield power ratio in the range 0.0 through 1.0.
Throws
ccAcuSymbolToolDefs::BadParams
val was out of range.
maxTime
double maxTime() const;
void maxTime(double maxTime);
•
double maxTime() const;
Returns the tuning timeout value (in seconds).
•
void maxTime(double maxTime);
Sets the tuning timeout value (in seconds). Tuning will be stopped after the specified
number of seconds.
Parameters
maxTime
The timeout value in seconds.
Throws
ccAcuSymbolDefs::BadParams if maxTime is less than 0.
CVL Class Reference
483
ccAcuSymbolTuneParams
validLimit
c_Int32 validLimit() const;
void validLimit(c_Int32 val);
•
c_Int32 validLimit() const;
Returns the maximum successful decode count. Tuning is stopped after the indicated
number of decodes are performed with no score improvement.
•
void validLimit(c_Int32 val);
Sets the maximum successful decode count. Tuning is stopped after the indicated
number of decodes are performed with no score improvement.
Parameters
val
The maximum number of successful decodes in the range 0
through 255.
Throws
ccAcuSymbolDefs::BadParams
val is out of range.
Notes
If you specify both a timeout and a valid limit, tuning stops when the first condition
is met.
484
CVL Class Reference
ccAcuSymbolTuneResult
#include <ch_cvl/acusymbl.h>
class ccAcuSymbolTuneResult : public ccPersistent;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class contains the results of a tune operation performed by the Symbol tool.
Constructors/Destructors
ccAcuSymbolTuneResult
ccAcuSymbolTuneResult ();
Constructs a ccAcuSymbolTuneResult with the following values::
CVL Class Reference
Parameter
Value
isTuned
false
tuneMethod
ccAcuSymbolDefs::eLearn
lightPower
0.0
brightFieldPowerRatio
0.12157
result
Default-constructed
ccAcuSymbolResult
numSuccess
0
time
0
tuneExitCode
ccAcuSymbolDefs::eNormal
485
ccAcuSymbolTuneResult
Operators
operator==
bool operator== (const ccAcuSymbolTuneResult& that) const;
Two ccAcuSymbolTuneResult objects are considered equal if all of their attributes are
the same to a numerical precision of 1.e-8.
Parameters
that
The ccAcuSymbolTuneResult to compare to this one.
Public Member Functions
isTuned
bool isTuned() const;
Returns true if this ccAcuSymbolTuneResult contains the results of a successful tune
operation.
tuneMethod
ccAcuSymbolDefs::TuneMethod tuneMethod() const;
Returns the tuning method used during tuning (learn or decode). This function returns
one of the following values:
ccAcuSymbolToolDefs::eLearn
ccAcuSymbolToolDefs::eDecode
lightPower
double lightPower() const;
Returns the tuned light power level value (in the range 0.0 through 1.0).
brightFieldPowerRatio
double brightFieldPowerRatio() const;
Returns the tuned bright field power ratio value (in the range 0.0 through 1.0).
result
const ccAcuSymbolResult& result() const;
Returns the ccAcuSymbolResult object containing the decode results produced using
the tuned lighting values
numSuccesses
c_UInt32 numSuccesses() const;
Returns the number of successful learn or decode operations that were performed
during tuning without improving the decode score.
486
CVL Class Reference
ccAcuSymbolTuneResult
time
double time() const;
Returns the amount of time (in seconds) required for tuning.
exitCode
ccAcuSymbolDefs::TuneExitCode exitCode() const;
Returns the reason that tuning terminated. This function returns one of the following
values:
ccAcuSymbolDefs::eNormal
ccAcuSymbolDefs::eTime
ccAcuSymbolDefs::eNumSuccess
score
virtual double score() const;
Returns a score value for this ccAcuSymbolTuneResult object based on the values of
the ccAcuSymbolResult object returned by result(). You can override this function to
provide your own scoring function for use during tuning.
CVL Class Reference
487
ccAcuSymbolTuneResult
488
CVL Class Reference
ccAffineRectangle
#include <ch_cvl/affrect.h>
class ccAffineRectangle : public ccShape;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class describes an affine rectangle (a quadrilateral where the opposite sides are
parallel). A ccAffineRectangle can be defined by a unit square transformation, by the
locations of three of its vertices, or by its location, width, height, and skew angle. Each
of the vertices of an affine rectangle are labeled, as shown in the following figure:
Po
Px
Py
Popp
CVL Class Reference
489
ccAffineRectangle
Constructors/Destructors
ccAffineRectangle
ccAffineRectangle ();
ccAffineRectangle (const cc2Xform& affRectFromUS);
ccAffineRectangle (const cc2Vect& cornerPo,
const cc2Vect& cornerPx, const cc2Vect& cornerPy);
ccAffineRectangle (const cc2Vect& center, double xLen,
double yLen, const ccRadian& xRotation = ccRadian(0),
const ccRadian& skew = ccRadian(0));
•
ccAffineRectangle ();
Constructs a ccAffineRectangle equal to the unit square in client coordinates (a
rectangle whose vertices are the points (0,0), (1,0), (1,1), and (0,1)).
•
ccAffineRectangle (const cc2Xform& affRectFromUS);
Constructs the ccAffineRectangle defined by the application of the supplied cc2Xform
to a unit square in client coordinates. A unit square is a rectangle whose vertices are the
points (0,0), (1,0), (1,1), and (0,1).
Parameters
affRectFromUS
•
A cc2Xform that defines this ccAffineRectangle.
ccAffineRectangle (const cc2Vect& cornerPo,
const cc2Vect& cornerPx, const cc2Vect& cornerPy);
Constructs the ccAffineRectangle defined by the supplied vertices. The following
figure shows the locations of these vertices.
Po
Px
Py
490
Vertices
CVL Class Reference
ccAffineRectangle
•
Parameters
cornerPo
The location of Po in client coordinates.
cornerPx
The location of Px in client coordinates.
cornerPy
The location of Py in client coordinates.
ccAffineRectangle (const cc2Vect& center, double xLen,
double yLen, const ccRadian& xRotation = ccRadian(0),
const ccRadian& skew = ccRadian(0));
Constructs the ccAffineRectangle defined by the supplied center point location, width,
height, angle of rotation, and angle of skew. The following figure shows how these values
define the ccAffineRectangle.
Rotation angle (+15 °)
Po
Px
Skew
angle
(-35 °)
yLen
Py
Popp
Center
point
Parameters
center
xLen
The center of the affine rectangle, in client coordinates
xLen
The length of the Po-Px side of the affine rectangle, in client
coordinates
yLen
The length of the Po-Py side of the affine rectangle, in client
coordinates
xRotation
The angle between the client coordinate system x-axis and the
Po-Px side of the affine rectangle
skew
The angle between a line drawn perpendicular to the Po-Px side
of the affine rectangle and the Po-Py side of the affine rectangle
Throws
CVL Class Reference
491
ccAffineRectangle
ccAffineRectangle::BadLength
xLen or yLen is less than or equal to 0.
ccAffineRectangle::BadSkew
skew is π/2 radians or -π/2 radians (These two values are illegal;
they produce a degenerate affine rectangle.) Note that this error
is thrown if skew is within ckAffineRectangleSkewAngleTol of
π/2 radians or -π/2 radians. You can determine if a given skew
angle is valid by calling ccAffineRectangle::isBadSkew().
Operators
operator==
bool operator== (const ccAffineRectangle& rhs) const;
Return true if this ccAffineRectangle is the same as the supplied ccAffineRectangle.
Two ccAffineRectangles are considered equal if and only if they have the same Po, Px,
and Py values.
Parameters
rhs
operator!=
The other ccAffineRectangle to compare.
bool operator!= (const ccAffineRectangle& that) const;
Return true if this ccAffineRectangle is not the same as the supplied
ccAffineRectangle.
Two ccAffineRectangles are considered equal if and only if they have the same Po, Px,
and Py values.
Parameters
that
The other ccAffineRectangle to compare.
Public Member Functions
affRectFromUnitSq
const cc2Xform& affRectFromUnitSq () const;
void affRectFromUnitSq (const cc2Xform& affRectFromUS);
•
const cc2Xform& affRectFromUnitSq () const;
Returns the cc2Xform that defines the transformation from a unit square to the affine
rectangle described by this ccAffineRectangle.
492
CVL Class Reference
ccAffineRectangle
•
void affRectFromUnitSq (const cc2Xform& affRectFromUS);
Sets the cc2Xform that defines the transformation from a unit square to the affine
rectangle described by this ccAffineRectangle.
Parameters
affRectFromUS
cornerPo
A cc2Xform that describes the transformation from the unit
square to this ccAffineRectangle.
cc2Vect cornerPo () const;
void cornerPo (const cc2Vect& po);
•
cc2Vect cornerPo () const;
Returns the location of the Po vertex of this ccAffineRectangle in client coordinates.
•
void cornerPo (const cc2Vect& po);
Sets the Po vertex of this ccAffineRectangle. The remaining dimensions of the
ccAffineRectangle are unchanged. Use this function to move a ccAffineRectangle
without changing its size or shape.
Parameters
po
cornerPx
The location of the Po vertex in client coordinates.
cc2Vect cornerPx () const;
Returns the location of the Px vertex of this ccAffineRectangle in client coordinates.
cornerPy
cc2Vect cornerPy () const;
Returns the location of the Py vertex of this ccAffineRectangle in client coordinates.
cornerPopp
cc2Vect cornerPopp () const;
Returns the location of the Popp vertex of this ccAffineRectangle in client coordinates.
CVL Class Reference
493
ccAffineRectangle
center
cc2Vect center () const;
void center (const cc2Vect& ctr);
•
cc2Vect center () const;
Returns the location of the center of this ccAffineRectangle in client coordinates.
•
void center (const cc2Vect& ctr);
Sets the center point of this ccAffineRectangle. The remaining dimensions of the
ccAffineRectangle are unchanged. Use this function to move a ccAffineRectangle
without changing its size or shape.
Parameters
ctr
xLength
The center point of this ccAffineRectangle in client coordinates.
double xLength () const;
void xLength (double xLen);
•
double xLength () const;
Returns the length of the Po-Px side of this ccAffineRectangle in client coordinates.
•
void xLength (double xLen);
Sets the length of the Po-Px side of this ccAffineRectangle. The center point, height,
and angles of skew and rotation are unchanged.
Parameters
xLen
The length of the Po-Px side in client coordinates.
Throws
ccAffineRectangle::BadLength
xLen is less than or equal to 0.
yLength
double yLength () const;
void yLength (double yLen);
•
double yLength () const;
Returns the height of this ccAffineRectangle in client coordinates.
494
CVL Class Reference
ccAffineRectangle
•
void yLength (double yLen);
Sets the height of this ccAffineRectangle. The center point, width, and angles of skew
and rotation are unchanged.
Parameters
yLen
The length of the Po-Py side in client coordinates.
Throws
ccAffineRectangle::BadLength
yLen is less than or equal to 0.
xRotation
ccRadian xRotation () const;
void xRotation (const ccRadian& xRot);
•
ccRadian xRotation () const;
Returns the x rotation angle of this ccAffineRectangle. The x rotation angle is the angle
between the Po-Px side of the affine rectangle and the client coordinate system x-axis.
Notes
The value returned by this function is between -π and π radians.
•
void xRotation (const ccRadian& xRot);
Sets the x rotation angle of this ccAffineRectangle. The x rotation angle is the angle
between the Po-Px side of the affine rectangle and the client coordinate system x-axis.
The center point, height, and width of the ccAffineRectangle are not affected.
Parameters
xRot
yRotation
The angle to set.
ccRadian yRotation () const;
Returns the y rotation angle of this ccAffineRectangle. The y rotation angle is the angle
between the Po-Py side of affine rectangle and the client coordinate system y-axis.
Notes
The value returned by this function is between -π and π radians.
CVL Class Reference
495
ccAffineRectangle
skew
ccRadian skew () const;
void skew (const ccRadian& skew);
•
ccRadian skew () const;
Returns the skew angle of this ccAffineRectangle. The skew angle is the angle between
a line drawn perpendicular to the Po-Px side of the affine rectangle and the Po-Py side
of the rectangle. The skew angle is equal to the y rotation angle minus the x rotation
angle.
Notes
The value returned by this function is between -π/2 and π/2 radians.
•
void skew (const ccRadian& skew);
Sets the skew angle of this ccAffineRectangle. The skew angle is the angle between a
line drawn perpendicular to the Po-Px side of the affine rectangle and the Po-Py side of
the rectangle. The skew angle is equal to the y rotation angle minus the x rotation angle.
The center point, height, and width of the ccAffineRectangle are not affected.
Parameters
skew
The skew angle
Throws
ccAffineRectangle::BadSkew
skew is π/2 radians or -π/2 radians (These two values are illegal;
they produce a degenerate affine rectangle.) Note that this error
is thrown if skew is within ckAffineRectangleSkewAngleTol of
π/2 radians or -π/2 radians. You can determine if a given skew
angle is valid by calling ccAffineRectangle::isBadSkew().
cornersPoPxPy
void cornersPoPxPy (const cc2Vect& cornerPo,
const cc2Vect& cornerPx, const cc2Vect& cornerPy);
Sets the locations of the Po, Px, and Py vertices of this ccAffineRectangle.
Parameters
cornerPo
The location of the Po vertex, in client coordinates.
cornerPx
The location of the Px vertex, in client coordinates.
cornerPy
The location of the Py vertex, in client coordinates.
Notes
This function fully defines an affine rectangle.
496
CVL Class Reference
ccAffineRectangle
centerLengthsRotAndSkew
void centerLengthsRotAndSkew (const cc2Vect& center,
double xLen, double yLen,
const ccRadian& xRotation = ccRadian(0),
const ccRadian& skew = ccRadian(0));
Sets the location, width, height, rotation angle, and skew angle of this
ccAffineRectangle.
Parameters
center
The center of the ccAffineRectangle, in client coordinates.
xLen
The length of the Po-Px side of the ccAffineRectangle, in client
coordinates.
yLen
The length of the Po-Py side of the ccAffineRectangle, in client
coordinates.
xRotation
The rotation angle of the ccAffineRectangle.
skew
The skew angle of the ccAffineRectangle.
Throws
ccAffineRectangle::BadLength
xLen or yLen is less than or equal to 0.
ccAffineRectangle::BadSkew
skew is π/2 radians or -π/2 radians (These two values are illegal;
they produce a degenerate affine rectangle.) Note that this error
is thrown if skew is within ckAffineRectangleSkewAngleTol of
π/2 radians or -π/2 radians. You can determine if a given skew
angle is valid by calling ccAffineRectangle::isBadSkew().
Notes
This function fully defines an affine rectangle.
cornerPoLengthsRotAndSkew
void cornerPoLengthsRotAndSkew (const cc2Vect& cornerPo,
double xLen, double yLen,
const ccRadian& xRotation = ccRadian(0),
const ccRadian& skew = ccRadian(0));
Sets the location of the Po vertex and the width, height, rotation angle, and skew angle
of this ccAffineRectangle.
Parameters
cornerPo
CVL Class Reference
The location of the Po vertex, in client coordinates.
497
ccAffineRectangle
xLen
The length of the Po-Px side of the ccAffineRectangle, in client
coordinates.
yLen
The length of the Po-Py side of the ccAffineRectangle, in client
coordinates.
xRotation
The rotation angle of the ccAffineRectangle.
skew
The skew angle of the ccAffineRectangle.
Throws
ccAffineRectangle::BadLength
xLen or yLen is less than or equal to 0.
ccAffineRectangle::BadSkew
skew is π/2 radians or -π/2 radians (These two values are illegal;
they produce a degenerate affine rectangle.) Note that this error
is thrown if skew is within ckAffineRectangleSkewAngleTol of
π/2 radians or -π/2 radians. You can determine if a given skew
angle is valid by calling ccAffineRectangle::isBadSkew().
Notes
This function fully defines an affine rectangle.
map
ccAffineRectangle map(const cc2Xform& c) const;
Maps this ccAffineRectangle by the supplied cc2Xform and returns the result. None of
the dimensions of this ccAffineRectangle change. Useful for scaling.
Parameters
c
The cc2Xform by which to map this ccAffineRectangle.
encloseImageRect
ccPelRect encloseImageRect(
const cc2Xform& imageFromClientXform = cc2Xform::I)
const;
Returns the smallest rectangle aligned to the supplied coordinate system that encloses
this ccAffineRectangle. By default, this function returns the smallest enclosing
rectangle in the image coordinate system.
Parameters
imageFromClientXform
A cc2Xform that specifies the transformation from the image
coordinate system. A default parameter of the identity
transformation is supplied.
498
CVL Class Reference
ccAffineRectangle
degen
bool degen() const;
Returns true if this ccAffineRectangle is degenerate. A ccAffineRectangle is
considered degenerate if either its width or height is 0.
clone
virtual ccShapePtrh clone() const;
Returns a pointer to a copy of this affine rectangle.
isOpenContour
virtual bool isOpenContour() const;
Returns true if this shape is an open contour. For affine rectangles, this function always
returns false. See ccShape::isOpenContour() for more information.
isRegion
virtual bool isRegion() const;
For affine rectangles, this function always returns true. See ccShape::isRegion() for
more information.
isFinite
virtual bool isFinite() const;
For affine rectangles, this function always returns true. See ccShape::isFinite() for more
information.
isEmpty
virtual bool isEmpty() const;
Returns true if the set of points that lie on the boundary of this shape is empty. For affine
rectangles, this function always returns false. See ccShape::isEmpty() for more
information.
hasTangent
virtual bool hasTangent() const;
Returns true for most affine rectangles. Returns false if all four vertices are coincident,
in which case the affine rectangle collapses to a single point and there is no tangent.
See ccShape::hasTangent() for more information.
isDecomposed
virtual bool isDecomposed() const;
For affine rectangles, this function always returns false. See
ccShape::isDecomposed() for more information.
CVL Class Reference
499
ccAffineRectangle
isReversible
virtual bool isReversible() const;
For affine rectangles, this function always returns true. See ccShape::reverse() for more
information.
reverse
virtual ccShapePtrh reverse() const;
Returns the reversed version of this affine rectangle. See ccShape::reverse() for more
information.
boundingBox
virtual ccRect boundingBox() const;
Returns the smallest rectangle that encloses this affine rectangle. See
ccShape::boundingBox() for more information.
isRightHanded
virtual bool isRightHanded() const;
Returns true if this affine rectangle is right-handed. See ccShape::isRightHanded() for
more information.
nearestPoint
virtual cc2Vect nearestPoint(const cc2Vect &p) const;
Returns the nearest point on the boundary of this affine rectangle to the given point. If
the nearest point is not unique, one of the nearest points will be returned.
Parameters
p
The point.
See ccShape::nearestPoint() for more information.
sample
virtual void sample(const ccSampleParams &params,
ccSampleResult &result);
Returns sample positions, and possibly tangents, along this shape.
Parameters
params
result
Specifies details of how the sampling should be done.
Result object to which position and tangent chains are
appended.
Notes
If params.computeTangents() is true, this function ignores affine rectangles for
which hasTangent() is false.
500
CVL Class Reference
ccAffineRectangle
Throws
ccShapesError::SampleOverflow
Supplied spacing and tolerance bounds require more than
maxPoint samples to be generated. See ccSampleParams for
details.
See ccShape::sample() for more information.
mapShape
virtual ccShapePtrh mapShape(const cc2Xform& X) const;
Returns this affine rectangle mapped by X.
Parameters
X
The transformation object.
See ccShape::mapShape() for more information.
decompose
virtual ccShapePtrh decompose() const;
Returns a ccContourTree consisting of connected ccLineSegs. See
ccShape::decompose() for additional information.
within
virtual bool within(const cc2Vect& v) const;
Returns true if the given point is within this affine rectangle.
Parameters
v
The point.
See ccShape::within() for more information.
Static Functions
isBadSkew
static bool isBadSkew(const ccRadian& skew);
Returns true if the supplied value is within ckAffineRectangleSkewAngleTol radians of
π/2 radians or -π/2 radians. The function returns false otherwise.
Parameters
skew
CVL Class Reference
The skew angle to test.
501
ccAffineRectangle
Deprecated Members
encloseRect
ccRect encloseRect() const;
Use boundingBox() instead.
distToPoint
double distToPoint(const cc2Vect& v) const;
Use distanceToPoint() (inherited from the ccShape base class) instead.
502
CVL Class Reference
ccAffineSamplingParams
#include <ch_cvl/affsampl.h>
class ccAffineSamplingParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class describes affine sampling parameters. Affine sampling parameters control
how the pixels within an affine rectangle in an image are sampled. The following are
affine sampling parameters:
•
The number of x-axis and y-axis divisions within an affine rectangle
•
The sampling method
•
An affine rectangle
See the following diagram.
Popp
Sample points
Px
Py
xNumSamples = 4
yNumSamples = 3
Po
CVL Class Reference
503
ccAffineSamplingParams
Constructors/Destructors
ccAffineSamplingParams
ccAffineSamplingParams ();
ccAffineSamplingParams (
const ccAffineRectangle& affRect,
c_Int16 xNumSamples,
c_Int16 yNumSamples,
Interpolation method = kDefaultInterpolation);
ccAffineSamplingParams(const ccAffineSamplingParams&);
•
ccAffineSamplingParams ();
Default constructor.
•
ccAffineSamplingParams (
const ccAffineRectangle& affRect,
c_Int16 xNumSamples,
c_Int16 yNumSamples,
Interpolation method = kDefaultInterpolation);
Constructs a ccAffineSamplingParams using the supplied values.
Parameters
affRect
The ccAffineRectangle that defines the rectangle to sample
xNumSamples
The number of divisions into which affrect is divided along the
Po-Px side
yNumSamples
The number of divisions into which affrect is divided along the
Po-Py side
method
The interpolation method to use to compute the sampled pixel
values. method must be one of the following values:
ccAffineSamplingParams::eNone
ccAffineSamplingParams::eBilinear
ccAffineSamplingParams::eHighPrecision
Throws
ccAffineSamplingParams::BadNumSamples
xNumSamples or yNumSamples is less than 1.
504
CVL Class Reference
ccAffineSamplingParams
•
ccAffineSamplingParams(const ccAffineSamplingParams&);
Copy constructor.
Enumerations
Interpolation
enum Interpolation
This enumeration defines the sampling methods supported by the tool.
Value
Meaning
eNone = 1
Use nearest-neighbor interpolation.
eBilinear = 2
Use bilinear interpolation of four nearest
pixels. This interpolation mode
approximates true bilinear interpolation.
(Also called eBilinearApprox)
While this is the default mode (for
backward compatibility), Cognex
recommends using eBilinearAccurate.
eHighPrecision = 3
Use high-precision interpolation to
compute the interpolated value.
eBilinearAccurate = 4
Performs an accurate bilinear
interpolation of the four nearest pixels.
This method is the most accurate, and in
most cases, the fastest method.
kDefaultInterpolation = eBilinear
The default interpolation.
Operators
operator=
ccAffineSamplingParams& operator=(
const ccAffineSamplingParams& rhs);
Assignment operator. Make this object a copy of rhs.
Parameters
rhs
CVL Class Reference
The copy source.
505
ccAffineSamplingParams
operator==
bool operator==(const ccAffineSamplingParams& that);
Returns true if this object is equal to that. Returns false otherwise.
Two ccAffineSamplingParams objects are equal if their affine rectangles are the same
and the number of samples and interpolation methods are equal.
Parameters
that
The other ccAffineSamplingParams object.
Public Member Functions
affineRectangle
const ccAffineRectangle& affineRectangle () const;
void affineRectangle (const ccAffineRectangle& affRect);
•
const ccAffineRectangle& affineRectangle () const;
Returns a reference to the ccAffineRectangle associated with this
ccAffineSamplingParams.
•
void affineRectangle (const ccAffineRectangle& affRect);
Sets the ccAffineRectangle associated with this ccAffineSamplingParams.
Parameters
affRect
xNumSamples
The ccAffineRectangle to set.
c_Int16 xNumSamples () const;
void xNumSamples (c_Int16 xNum);
•
c_Int16 xNumSamples () const;
Returns the number of Po-Px divisions in this ccAffineSamplingParams. The
ccAffineRectangle associated with this ccAffineSamplingParams is divided into the
returned number of divisions along the Po-Px side.
•
void xNumSamples (c_Int16 xNum);
Sets the number of Po-Px divisions in this ccAffineSamplingParams. The
ccAffineRectangle associated with this ccAffineSamplingParams is divided into the
specified number of divisions along the Po-Px side.
506
CVL Class Reference
ccAffineSamplingParams
Parameters
xNum
The number of x-divisions
Throws
ccAffineSamplingParams:BadNumSamples
xNum is less than 1.
yNumSamples
c_Int16 yNumSamples () const;
void yNumSamples (c_Int16 yNum);
•
c_Int16 yNumSamples () const;
Returns the number of Po-Py divisions in this ccAffineSamplingParams. The
ccAffineRectangle associated with this ccAffineSamplingParams is divided into the
returned number of divisions along the Po-Py side.
•
void yNumSamples (c_Int16 yNum);
Sets the number of Po-Py divisions in this ccAffineSamplingParams. The
ccAffineRectangle associated with this ccAffineSamplingParams is divided into the
specified number of divisions along the Po-Py side.
Parameters
yNum
The number of y-divisions
Throws
ccAffineSamplingParams:BadNumSamples
yNum is less than 1.
interpolation
Interpolation interpolation () const;
void interpolation (Interpolation method);
•
Interpolation interpolation () const;
Returns the interpolation method of this ccAffineSamplingParams. The returned value
is one of the following:
ccAffineSamplingParams::eNone
ccAffineSamplingParams::eBilinear
ccAffineSamplingParams::eBilinearApprox
ccAffineSamplingParams::eBilinearAccurate
ccAffineSamplingParams::eHighPrecision
CVL Class Reference
507
ccAffineSamplingParams
•
void interpolation (Interpolation method);
Sets the interpolation method of this ccAffineSamplingParams.
Parameters
method
The interpolation method to use. method must be one of the
following values:
ccAffineSamplingParams::eNone
ccAffineSamplingParams::eBilinear
ccAffineSamplingParams::eBilinearApprox
ccAffineSamplingParams::eBilinearAccurate
ccAffineSamplingParams::eHighPrecision
willClip
bool willClip(const cc_PelBuffer& srcImg) const;
Returns true if the affine rectangle specified in this ccAffineSamplingParams would
need to access pixels outside of the valid region of srcImg. The valid region within
srcImg is defined as being all pixels in srcImg other than a two-pixel wide border around
the edge of srcImg.
508
CVL Class Reference
ccAlphaColorProp
#include <ch_cvl/prop.h>
class ccAlphaColorProp : virtual public ccPersistent;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class allows you to specify how the alpha channel value is calculated when
acquiring images into 32-bit pel buffers. The alpha channel value is also used to
calculate pixel values when a color camera is used to acquire 8-bit grey scale images.
Since this class is one of the base classes of ccAcqProps, you do not need to create
an instance of this class. All classes derived from ccAcqFifo can use
ccAcqFifo::properties() to return a properties object that includes this property.
A table showing the acquisition hardware platforms that support this property is
included in the Acquiring Images chapter of the CVL User’s Guide.
Constructors/Destructors
ccAlphaColorProp
ccAlphaColorProp();
explicit ccAlphaColorProp(bool enable,
ceAlphaSource translationMethod, c_UInt8 alphaByteValue);
•
ccAlphaColorProp();
Creates an alpha channel property not associated with any acquisition FIFO. Alpha
translation is disabled (enable = false). The default translation is
ccAlphaColorProp::defaultAlphaSource. The default alpha byte value is
ccAlphaColorProp::defaultAlphaByte.
•
explicit ccAlphaColorProp(bool enable,
ceAlphaSource translationMethod, c_UInt8 alphaByteValue);
Creates an alpha channel property not associated with any acquisition FIFO with the
specified value.
CVL Class Reference
509
ccAlphaColorProp
Parameters
enable
True to enable alpha translation; false to disable it. See
alphaEnable() on page 511.
translationMethod
Specifies the method used to calculate the alpha value from the
RGB values. Must be one of:
ccAlphaColorProp::ckAlphaByte
ccAlphaColorProp::ckRedChannel
ccAlphaColorProp::ckGreenChannel
ccAlphaColorProp::ckBlueChannel
ccAlphaColorProp::ckRedGreen
ccAlphaColorProp::ckRedBlue
ccAlphaColorProp::ckGreenBlue
ccAlphaColorProp::ckAlphaRGB
ccAlphaColorProp::ck2RedGreenBlue
ccAlphaColorProp::ckRed2GreenBlue
ccAlphaColorProp::ckRedGreen2Blue
alphaByteValue
510
The alpha byte value used by some translation methods and
used as the high byte of 32-bit pixels.
CVL Class Reference
ccAlphaColorProp
Enumerations
ceAlphaSource
enum ceAlphaSource;
Value
How the 8-bit pixel value is calculated
ckAlphaByte
Use the alpha byte value.
ckRedChannel
Use the Red value.
ckGreenChannel
Use the Green value.
ckBlueChannel
Use the Blue value.
ckRedGreen
(Red + Green) / 2
ckRedBlue
(Red + Blue) / 2
ckGreenBlue
(Green + Blue) / 2
ckAlphaRGB
(alpha byte + R + G + B) / 4
ck2RedGreenBlue
(2R + G + B) / 4
ckRed2GreenBlue
(R + 2G + B) / 4
ckRedGreen2Blue
(R + G + 2B) / 4
Public Member Functions
alphaEnable
void alphaEnable(bool enable);
bool alphaEnable() const;
•
void alphaEnable(bool enable);
Sets whether alpha translation is enabled or disabled. When alpha translation is
enabled, three-channel color input data consisting of red, green, and blue are translated
into a grey-scale value. The particular translation method used is specified by
alphaSource() on page 512. The default value is false: alpha translation disabled.
Parameters
enable
•
True to enable alpha translation; false to disable it.
bool alphaEnable() const;
Returns true if alpha translation is enabled; false if it is disabled.
CVL Class Reference
511
ccAlphaColorProp
alphaSource
void alphaSource(ceAlphaSource translationMethod);
ceAlphaSource alphaSource() const;
•
void alphaSource(ceAlphaSource translationMethod);
Sets the 8-bit translation method.
Parameters
translationMethod
Specifies the method used to calculate the alpha value from the
RGB values. Must be one of:
ccAlphaColorProp::ckAlphaByte
ccAlphaColorProp::ckRedChannel
ccAlphaColorProp::ckGreenChannel
ccAlphaColorProp::ckBlueChannel
ccAlphaColorProp::ckRedGreen
ccAlphaColorProp::ckRedBlue
ccAlphaColorProp::ckGreenBlue
ccAlphaColorProp::ckAlphaRGB
ccAlphaColorProp::ck2RedGreenBlue
ccAlphaColorProp::ckRed2GreenBlue
ccAlphaColorProp::ckRedGreen2Blue
•
ceAlphaSource alphaSource() const;
Returns the current translation method.
alphaByte
void alphaByte(c_UInt8 byteValue);
c_UInt8 alphaByte() const;
•
void alphaByte(c_UInt8 byteValue);
Sets the alpha byte value used by some translation methods.
Parameters
byteValue
•
The alpha byte value used by some translation methods and
used as the high byte of 32-bit pixels.
c_UInt8 alphaByte() const;
Returns the alpha byte value.
512
CVL Class Reference
ccAlphaColorProp
Constants
defaultAlphaSource
static const ceAlphaSource defaultAlphaSource;
The default translation method: ccAlphaColorProp::ckRed2GreenBlue.
defaultAlphaByte
static const c_UInt8 defaultAlphaByte;
The default alpha byte value: zero.
CVL Class Reference
513
ccAlphaColorProp
514
CVL Class Reference
ccAnalogAcqProps
#include <ch_cvl/prop.h>
class ccAnalogAcqProps : public ccAcqProps;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
This class is has been deprecated. Use the class ccAcqProps instead. See
ccAcqProps on page 309.
CVL Class Reference
515
ccAnalogAcqProps
516
CVL Class Reference
ccAngle8
#include <ch_cvl/units.h>
class ccAngle8;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class describes an angle as an unsigned 8-bit integer with a value from 0 to 255.
Each integer value represents a small range of angles:
Integer value
Angle in degrees
Range
0
0°
±0.703125
1
1.40625°
±0.703125
2
2.8125°
±0.703125
32
45.0°
±0.703125
Note that you can use the constructors to convert from one angle representation to
another. For example, to specify 60° as a ccAngle8, you could write:
ccAngle8 ang8(ccDegree(60.0));
When converting angles, be aware that Cognex vision tools are not entirely consistent
in their use of ccAngle8 and ccAngle16. Some tools use a truncation model when
converting between floating point angles and binary angles, and other tools use a
rounding model. The following table shows an example of the different results produced
when converting angles between floating point and ccAngle8 representations using the
truncation method as compared to the rounding method:
CVL Class Reference
Convert From
Convert To
Truncation
Rounding
1.406°
ccAngle8
0
1
-0.001°
ccAngle8
255
0
0 ccAngle8
degrees
0°
0.703125°
1 ccAngle8
degrees
1.40625°
2.109375°
517
ccAngle8
The rounding method is numerically more stable if multiple conversions will be made
between floating point and binary angles. For example, using the truncation model a
floating point computation that yields -0.0000000001° is represented as a 255
ccAngle8, which is then converted back to 358.59375°. If an iterative computation then
added another -0.0000000001° and converted back to ccAngle8, you would get a
steadily decreasing representation of 254, 253, 252, and so on.
Constructors/Destructors
ccAngle8
ccAngle8();
ccAngle8(ccRadian a);
ccAngle8(ccDegree a);
ccAngle8(ccAngle16 a);
explicit ccAngle8(c_UInt8 a);
•
ccAngle8();
Creates an uninitialized ccAngle8 object.
•
ccAngle8(ccRadian a);
Creates a ccAngle8 object from the given ccRadian object.
Parameters
a
•
The ccRadian object to convert to ccAngle8 format.
ccAngle8(ccDegree a);
Creates a ccAngle8 object from the given ccDegree object.
Parameters
a
•
The ccDegree object to convert.
ccAngle8(ccAngle16 a);
Creates a ccAngle8 object from the given ccAngle16 object.
Parameters
a
518
The ccAngle16 object to convert.
CVL Class Reference
ccAngle8
•
explicit ccAngle8(c_UInt8 a);
Creates a ccAngle8 object with the specified value.
Parameters
a
The angle as an unsigned 8-bit integer.
Operators
operator+
ccAngle8 operator+(ccAngle8 a) const;
Returns the result of adding the angle a to this angle.
Parameters
a
operator-
The angle to add to this angle.
ccAngle8 operator-(ccAngle8 a) const;
ccAngle8 operator-() const;
•
ccAngle8 operator-(ccAngle8 a) const;
Returns the result of subtracting the angle a from this angle.
Parameters
a
•
The angle to subtract from this angle.
ccAngle8 operator-() const;
Returns the negative of this angle. The unary minus operator.
operator*
ccAngle8 operator*(c_UInt8 a) const;
c_UInt8 operator*(ccAngle8 a) const;
friend ccAngle8 operator*(c_UInt8 a, ccAngle8 b);
•
ccAngle8 operator*(c_UInt8 a) const;
Returns the result of multiplying this angle by a.
Parameters
a
CVL Class Reference
The amount to multiply by.
519
ccAngle8
•
c_UInt8 operator*(ccAngle8 a) const;
Returns the result of multiplying this angle by the angle a.
Parameters
a
•
The angle to multiply by.
friend ccAngle8 operator*(c_UInt8 a, ccAngle8 b);
Returns the result of multiplying the angle b by a.
Parameters
a
b
operator/
The amount to multiply by.
The angle to multiply.
ccAngle8 operator/(c_UInt8 a) const;
c_UInt8 operator/(ccAngle8 a) const;
•
ccAngle8 operator/(c_UInt8 a) const;
Returns the result of dividing this angle by a.
Parameters
a
•
The amount to divide by.
c_UInt8 operator/(ccAngle8 a) const;
Returns the result of dividing this angle by the angle a.
Parameters
a
operator=
The angle to divide by.
ccAngle8& operator=(c_UInt8 a);
Assigns the value a to this angle.
Parameters
a
520
The value to assign.
CVL Class Reference
ccAngle8
operator*=
ccAngle8& operator*=(c_UInt8 a);
ccAngle8& operator*=(ccAngle8 a);
•
ccAngle8& operator*=(c_UInt8 a);
Multiplies this angle by a and returns the result.
Parameters
a
•
The value to multiply by.
ccAngle8& operator*=(ccAngle8 a);
Multiplies this angle by the angle a and returns the result.
Parameters
a
operator/=
The angle to multiply by.
ccAngle8& operator/=(c_UInt8 a);
ccAngle8& operator/=(ccAngle8 a);
•
ccAngle8& operator/=(c_UInt8 a);
Divides this angle by the value a and returns the result.
Parameters
a
•
The value to divide by.
ccAngle8& operator/=(ccAngle8 a);
Divides this angle by the angle a and returns the result.
Parameters
a
operator+=
The angle to divide by.
ccAngle8& operator+=(ccAngle8 a);
Adds the angle a to this angle and returns the result.
Parameters
a
CVL Class Reference
The angle to add.
521
ccAngle8
operator-=
ccAngle8& operator-=(ccAngle8 a);
Subtracts the angle a from this angle and returns the result.
Parameters
a
operator==
The angle to subtract.
bool operator!=(ccAngle8 a) const;
Returns true if this angle is exactly equal to the angle a.
Parameters
a
operator!=
The other angle.
bool operator!=(ccAngle8 a) const;
Returns true if this angle is not equal to the angle a.
Parameters
a
operator<
The other angle.
bool operator<(ccAngle8 a) const;
Returns true if this angle is less than angle a.
Parameters
a
operator<=
The other angle.
bool operator<=(ccAngle8 a) const;
Returns true if this angle is less than or equal to angle a.
Parameters
a
operator>
The other angle.
bool operator>(ccAngle8 a) const;
Returns true if this angle is greater than angle a.
Parameters
a
operator>=
The other angle.
bool operator>=(ccAngle8 a) const;
Returns true if this angle is greater than or equal to angle a.
522
CVL Class Reference
ccAngle8
Parameters
a
The other angle.
Public Member Functions
toDouble
double toDouble() const;
Returns this angle as a double.
plain
c_UInt8 plain() const;
Returns this angle as a c_UInt8.
CVL Class Reference
523
ccAngle8
524
CVL Class Reference
ccAngle16
#include <ch_cvl/units.h>
class ccAngle16;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class describes an angle as an unsigned 16-bit integer with a value from 0 to
65535. Each integer value represents a small range of angles:
Integer value
Angle in degrees
Range
0
0°
±0.00274658
1
0.00549316°
±0.00274658
2
0.010986°
±0.00274658
8192
45.0°
±0.00274658
Note that you can use the constructors to convert from one angle representation to
another. For example, to specify 60° as a ccAngle16, you could write:
ccAngle16 ang16(ccDegree(60.0));
When converting angles, be aware that Cognex vision tools are not entirely consistent
in their use of ccAngle8 and ccAngle16. Some tools use a truncation model when
converting between floating point angles and binary angles, and other tools use a
rounding model. The following table shows an example of the different results produced
when converting angles between floating point and ccAngle16 representations using
the truncation method as compared to the rounding method:
CVL Class Reference
Convert From
Convert To
Truncation
Rounding
0.00549°
ccAngle16
0
1
-0.001°
ccAngle16
65535
0
0 ccAngle16
degrees
0°
0.00274658203125°
1 ccAngle16
degrees
0.0054931640625°
0.00823974609375°
525
ccAngle16
The rounding method is numerically more stable if multiple conversions will be made
between floating point and binary angles. For example, using the truncation model a
floating point computation that yields -0.0000000001° is represented as a 65535
ccAngle16, which is then converted back to 359.9945068360375°. If an iterative
computation then added another -0.0000000001° and converted back to ccAngle16,
you would get a steadily decreasing representation of 65534, 65533, 65532, and so on.
Constructors/Destructors
ccAngle16
ccAngle16();
ccAngle16(ccRadian a);
ccAngle16(ccDegree a);
ccAngle16(ccAngle8 a);
explicit ccAngle16(c_UInt16 a);
•
ccAngle16();
Creates an uninitialized ccAngle16 object.
•
ccAngle16(ccRadian a);
Creates a ccAngle16 object from the given ccRadian object.
Parameters
a
•
The ccRadian object to convert to degrees.
ccAngle16(ccDegree a);
Creates a ccAngle16 object from the given ccDegree object.
Parameters
a
•
The ccDegree object to convert.
ccAngle16(ccAngle8 a);
Creates a ccAngle16 object from the given ccAngle8 object.
Parameters
a
526
The ccAngle8 object to convert.
CVL Class Reference
ccAngle16
•
explicit ccAngle16(c_UInt16 a);
Creates a ccAngle16 object with the specified value.
Parameters
a
The angle as an unsigned 16-bit integer.
Operators
operator+
ccAngle16 operator+(ccAngle16 a) const;
Returns the result of adding the angle a to this angle.
Parameters
a
operator-
The angle to add to this angle.
ccAngle16 operator-(ccAngle16 a) const;
ccAngle16 operator-() const;
•
ccAngle16 operator-(ccAngle16 a) const;
Returns the result of subtracting the angle a from this angle.
Parameters
a
•
The angle to subtract from this angle.
ccAngle16 operator-() const;
Returns the negative of this angle. The unary minus operator.
operator*
ccAngle16 operator*(c_UInt16 a) const;
c_UInt16 operator*(ccAngle16 a) const;
friend ccAngle16 operator*(c_UInt16 a, ccAngle16 b);
•
ccAngle16 operator*(c_UInt16 a) const;
Returns the result of multiplying this angle by a.
Parameters
a
CVL Class Reference
The amount to multiply by.
527
ccAngle16
•
c_UInt16 operator*(ccAngle16 a) const;
Returns the result of multiplying this angle by the angle a.
Parameters
a
•
The angle to multiply by.
friend ccAngle16 operator*(c_UInt16 a, ccAngle16 b);
Returns the result of multiplying the angle b by a.
Parameters
a
b
operator/
The amount to multiply by.
The angle to multiply.
ccAngle16 operator/(c_UInt16 a) const;
c_UInt16 operator/(ccAngle16 a) const;
•
ccAngle16 operator/(c_UInt16 a) const;
Returns the result of dividing this angle by a.
Parameters
a
•
The amount to divide by.
c_UInt16 operator/(ccAngle16 a) const;
Returns the result of dividing this angle by the angle a.
Parameters
a
operator=
The angle to divide by.
ccAngle16& operator=(c_UInt16 a);
Assigns the value a to this angle.
Parameters
a
528
The value to assign.
CVL Class Reference
ccAngle16
operator*=
ccAngle16& operator*=(c_UInt16 a);
ccAngle16& operator*=(ccAngle16 a);
•
ccAngle16& operator*=(c_UInt16 a);
Multiplies this angle by a and returns the result.
Parameters
a
•
The value to multiply by.
ccAngle16& operator*=(ccAngle16 a);
Multiplies this angle by the angle a and returns the result.
Parameters
a
operator/=
The angle to multiply by.
ccAngle16& operator/=(c_UInt16 a);
ccAngle16& operator/=(ccAngle16 a);
•
ccAngle16& operator/=(c_UInt16 a);
Divides this angle by the value a and returns the result.
Parameters
a
•
The value to divide by.
ccAngle16& operator/=(ccAngle16 a);
Divides this angle by the angle a and returns the result.
Parameters
a
operator+=
The angle to divide by.
ccAngle16& operator+=(ccAngle16 a);
Adds the angle a to this angle and returns the result.
Parameters
a
CVL Class Reference
The angle to add.
529
ccAngle16
operator-=
ccAngle16& operator-=(ccAngle16 a);
Subtracts the angle a from this angle and returns the result.
Parameters
a
operator==
The angle to subtract.
bool operator!=(ccAngle16 a) const;
Returns true if this angle is exactly equal to the angle a.
Parameters
a
operator!=
The other angle.
bool operator!=(ccAngle16 a) const;
Returns true if this angle is not equal to the angle a.
Parameters
a
operator<
The other angle.
bool operator<(ccAngle16 a) const;
Returns true if this angle is less than angle a.
Parameters
a
operator<=
The other angle.
bool operator<=(ccAngle16 a) const;
Returns true if this angle is less than or equal to angle a.
Parameters
a
operator>
The other angle.
bool operator>(ccAngle16 a) const;
Returns true if this angle is greater than angle a.
Parameters
a
operator>=
The other angle.
bool operator>=(ccAngle16 a) const;
Returns true if this angle is greater than or equal to angle a.
530
CVL Class Reference
ccAngle16
Parameters
a
The other angle.
Public Member Functions
toDouble
double toDouble() const;
Returns this angle as a double value.
plain
c_UInt16 plain() const;
Returns this angle as a c_UInt16.
CVL Class Reference
531
ccAngle16
532
CVL Class Reference
ccAngleRange
#include <ch_cvl/range.h>
class ccAngleRange;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
The class ccAngleRange specifies a range of orientations and provides methods for
performing the following operations:
•
Check whether a value is within a range of angles.
•
Check whether a range of angles is full, partly full, or empty.
•
Dilate ranges of angles (Minkowski sum operation).
This class is can specify a range that contains an angle whose measure is 2 * π radians.
For example, an angle range from 6.0 to 7.0 radians would contain the angle of 0.0
degrees (since 6.28 is within the range [6.0 through 7.0] and 0 ~= 6.28 (2 * π).
Constructors/Destructors
ccAngleRange
ccAngleRange ();
ccAngleRange (const ccRadian &start, const ccRadian &end);
•
ccAngleRange ();
Returns a default constructed empty angle range.
•
ccAngleRange (const ccRadian &start, const ccRadian &end);
Returns an ccAngleRange object characterized by the specified start and end values.
If (end.toDouble() - start.toDouble()) > 2 * π, then the function constructs a full range.
Otherwise, it constructs a partial range.
Parameters
start
The start position of the angle range.
end
The end position of the angle range.
CVL Class Reference
533
ccAngleRange
Operators
operator==
bool operator== (const ccAngleRange& that) const;
True if this range equals the other range; false otherwise.
Parameters
that
The other range.
Notes
Two ccAngleRange objects are considered equal if their ranges, start angles, and
end angles are equal.
operator!=
bool operator!= (const ccAngleRange& that) const;
True if this range does not equal that range; false if this range equals that range.
Parameters
that
The other range.
Notes
Two ccAngleRange objects are considered equal if their ranges, start angles, and
end angles are equal or if they are both full or both empty.
Public Member Functions
dilate
ccAngleRange dilate(const ccAngleRange &x) const;
Returns a new ccAngleRange object that is created by dilating this range with another
range specified by x. Dilation is accomplished by using the Minkowski sum of two sets
A and B. The resulting range is the set of all points which can be generated by adding
an element of A to an element of B.
Parameters
x
end
The range used to dilate this angle range.
ccRadian end() const;
Returns the end position of a partial range.
Throws
ccRangeDefs::NotPartialRange
This is not a partial angle range.
534
CVL Class Reference
ccAngleRange
isWithin
bool isWithin(const ccRadian &x) const;
Returns a bool that indicates whether or not the value x is inside this angle range.
Parameters
x
length
The value that may or may not be inside this angle range.
ccRadian length() const;
Returns the length of the angle range which is defined as one of the following:
ck2Pi if the angle range is full (range_ == eFull)
0 if the angle range is empty (range_ == eEmpty)
end_-start_ if the angle range contains some members
(range_ == ePartial).
middle
ccRadian middle() const;
Returns the middle of the given angle range.
Throws
ccRangeDefs::NotPartialRange
This is not a partial angle range.
start
ccRadian start() const;
Returns the start position of a partial angle range.
Throws
ccRangeDefs::NotPartialRange
This is not a partial angle range.
Static Functions
EmptyAngleRange
static ccAngleRange EmptyAngleRange();
Returns the default constructed empty angle range.
FullAngleRange
static ccAngleRange FullAngleRange();
Returns the default constructed full angle range.
CVL Class Reference
535
ccAngleRange
536
CVL Class Reference
ccAnnulus
#include <ch_cvl/shapes.h>
class ccAnnulus : public ccShape;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
The ccAnnulus class describes an annulus, a ring shape made up of two concentric
circles. You specify a center and the inner and outer radii to describe an annulus. The
following figure shows an annulus.
ccAnnulus(cc2Vect(100,100), 60, 90)
Center: (100,100)
Inner radius: 60
Outer radius: 90
CVL Class Reference
537
ccAnnulus
Constructors/Destructors
ccAnnulus
ccAnnulus();
ccAnnulus(const cc2Vect& c, double r1, double r2);
ccAnnulus(const ccCircle& c1, const ccCircle& c2);
•
ccAnnulus();
The default constructor creates a degenerate annulus with its center at (0,0) and inner
and outer radii set to zero.
•
ccAnnulus(const cc2Vect& c, double r1, double r2);
Creates an annulus with the specified center and radii.
Parameters
c
The center of the annulus.
r1
The inner radius. The radius must be non-negative.
r2
The outer radius. The radius must be non-negative.
Throws
ccShapesError::BadRadius
Either radius is negative.
•
ccAnnulus(const ccCircle& c1, const ccCircle& c2);
Creates an annulus from two concentric circles.
Parameters
c1
The inner circle.
c2
The outer circle.
Throws
ccShapesError::NotConcentric
Circles c1 and c2 are not concentric.
538
CVL Class Reference
ccAnnulus
Operators
operator==
bool operator==(const ccAnnulus& other) const;
Returns true if this annulus is equal to another annulus: it has the same center, inner
radius, and outer radius as the other annulus.
Parameters
other
operator!=
The other annulus.
bool operator!=(const ccAnnulus&) const;
Returns true if this annulus is not equal to another annulus.
Parameters
other
The other annulus.
Public Member Functions
center
const ccPoint& center() const;
Returns the center of the annulus.
innerRadius
double innerRadius() const;
Returns the inner radius of the annulus.
outerRadius
double outerRadius() const;
Returns the outer radius of the annulus.
innerCircle
ccCircle innerCircle() const;
Returns the inner circle of the annulus.
outerCircle
ccCircle outerCircle() const;
Returns the outer circle of the annulus.
map
ccGenAnnulus map(const cc2Xform& c) const;
Returns an annulus that is the result of mapping this annulus with the transformation
object c.
CVL Class Reference
539
ccAnnulus
Parameters
c
The transformation object.
Notes
Both of the radii of this annulus must be strictly positive, and the transform c must
be nonsingular. If both of these conditions are false, use mapshape() instead.
degen
bool degen() const;
Returns true if this annulus is degenerate. An annulus is degenerate if either both radii
are equal, or one of the radii is less than or equal to zero.
clone
virtual ccShapePtrh clone() const;
Returns a pointer to a copy of this annulus.
isOpenContour
virtual bool isOpenContour() const;
Returns true if this shape is an open contour. For annuli, this function always returns
false. See ccShape::isOpenContour() for more information.
isRegion
virtual bool isRegion() const;
For annuli, this function always returns true, even for annuli that are degenerate. See
ccShape::isRegion() for more information.
isFinite
virtual bool isFinite() const;
For annuli, this function always returns true. See ccShape::isFinite() for more
information.
isEmpty
virtual bool isEmpty() const;
Returns true if the set of points that lie on the boundary of this shape is empty. For annuli,
this function always returns false. See ccShape::isEmpty() for more information.
hasTangent
virtual bool hasTangent() const;
This function returns true if at least one of the radii of this annulus is positive. It returns
false if neither radius is positive. See ccShape::hasTangent() for more information.
540
CVL Class Reference
ccAnnulus
isDecomposed
virtual bool isDecomposed() const;
For annuli, this function always returns false. See ccShape::isDecomposed() for more
information.
isReversible
virtual bool isReversible() const;
For annuli, this function always returns false. See ccShape::reverse() for more
information.
boundingBox
virtual ccRect boundingBox() const;
Returns the smallest rectangle that encloses this annulus. See
ccShape::boundingBox() for more information.
nearestPoint
virtual cc2Vect nearestPoint(const cc2Vect &p) const;
Returns the nearest point on the boundary of this annulus to the given point. If the
nearest point is not unique, one of the nearest points is returned.
Parameters
p
The point.
See ccShape::nearestPoint() for more information.
nearestPerimPos
virtual ccPerimPos nearestPerimPos(const ccShapeInfo& info,
const cc2Vect& point) const;
Returns the nearest perimeter position on this annulus to the given point, as determined
by nearestPoint().
Parameters
info
point
Shape information for this annulus.
The point.
See ccShape::nearestPerimPos() for more information.
isRightHanded
virtual bool isRightHanded() const;
For annuli, this function always returns true. Annuli are always right-handed. See
ccShape::isRightHanded() for more information.
CVL Class Reference
541
ccAnnulus
sample
virtual void sample(const ccShape::ccSampleParams &params,
ccSampleResult &result) const;
Returns sample positions, and possibly tangents, along this shape.
Parameters
params
result
Specifies details of how the sampling should be done.
Result object to which position and tangent chains are
appended.
Notes
If params.computeTangents() is true, this function ignores annuli for which
hasTangent() is false.
See ccShape::sample() for more information.
mapShape
virtual ccShapePtrh mapShape(const cc2Xform& X) const;
Returns this annulus mapped by X.
Parameters
X
The transformation object.
Notes
If X is the identity transform, this function returns a ccAnnulus. Otherwise, if X is
singular this function returns a ccRegionTree, or if X is nonsingular and either
radius is zero, this function returns a ccEllipseAnnulus. In all other cases, it returns
a ccGenAnnulus.
See ccShape::mapShape() for more information.
decompose
virtual ccShapePtrh decompose() const;
Returns a ccContourTree consisting of connected ccEllipseArc2s. See
ccShape::decompose() for more information.
within
virtual bool within(const cc2Vect& v) const;
Returns true if the given point is within this annulus.
Parameters
v
The point.
Notes
A point is within an annulus if it is between the inner and outer circles of the annulus.
542
CVL Class Reference
ccAnnulus
subShape
virtual ccShapePtrh subShape(const ccShapeInfo &info,
const ccPerimRange &range) const;
Returns a pointer handle to the shape describing the portion of this annulus over the
given perimeter range. The perimeter of the final returned shape is equal to the absolute
value of the distance component of range, assuming the distance is not clipped.
Parameters
info
range
Shape information for this annulus.
The perimeter range.
See ccShape::subShape() for more information.
Deprecated Members
These functions are deprecated and are provided for backwards compatibility only. Use
the appropriate functions provided by ccShape instead.
encloseRect
ccRect encloseRect() const;
Use boundingBox() instead of this function.
distToPoint
double distToPoint(const cc2Vect& v) const;
Use distanceToPoint() instead of this function.
CVL Class Reference
543
ccAnnulus
544
CVL Class Reference
ccArchive
#include <ch_cvl/archive.h>
class ccArchive;
Class Properties
Copyable
No
Derivable
Yes
Archiveable
Not applicable
The ccArchive class is an abstract base class from which the concrete archive classes
ccFileArchive and ccMemoryArchive are derived. This class implements the ||, <<,
and >> operators for the built-in C++ types.
Constructors/Destructors
ccArchive
virtual ~ccArchive();
Enumerations
Direction
enum Direction;
This enumeration defines the mode for a ccArchive.
CVL Class Reference
Value
Meaning
eLoading
This archive is used to load objects.
eStoring
This archive is used to store objects.
545
ccArchive
Ordering
enum Ordering;
This enumeration defines the endianness of a ccArchive.
The endianness of an archive is the endianness with which data are stored in the
archive. Whenever an archive is loaded, if the endianness of the machine onto which it
is being loaded does not match the endianness of the archive, byte swapping is
performed as the objects are loaded.
When you instantiate a ccArchive-derived concrete class for storing, you must specify
the endianness of the archive. If the endianness of the archive does not match the
endianness of the machine from which the objects are being stored, then byte swapping
is performed as the objects are stored.
The constructors for all ccArchive-derived concrete classes provide a default value of
ccArchive::eLittleEndian for the endianness of the archive.
546
Value
Meaning
eBigEndian
Big-endian.
eLittleEndian
Little-endian.
CVL Class Reference
ccArchive
Operators
operatorII
ccArchive& operator|| (c_UInt8& val);
ccArchive& operator|| (c_Int8& val);
ccArchive& operator|| (char& val);
ccArchive& operator|| (c_UInt16& val);
ccArchive& operator|| (c_Int16& val);
ccArchive& operator|| (c_UInt32& val);
ccArchive& operator|| (c_Int32& val);
ccArchive& operator|| (unsigned int& val);
ccArchive& operator|| (int& val);
ccArchive& operator|| (float& val);
ccArchive& operator|| (double& val);
ccArchive& operator|| (cmStd string& val);
ccArchive& operator|| (bool& val);
Notes
All of the overloads of operator|| may throw the following errors:
ccArchive::BadType
The stream data do not match the expected type while loading
(the stream position after this error is unspecified).
ccArchive::Eof
There is no more input data (loading only).
ccArchive::BadBuffer
The archive is broken and unusable. If this error occurs during
storing, it may indicate that the output device (disk) is full.
•
ccArchive& operator|| (c_UInt8& val);
Serializes the supplied c_UInt8 value to or from this ccArchive. The value is serialized
to the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
CVL Class Reference
The value to serialize.
547
ccArchive
•
ccArchive& operator|| (c_Int8& val);
Serializes the supplied c_Int8 value to or from this ccArchive. The value is serialized to
the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
•
The value to serialize.
ccArchive& operator|| (char& val);
Serializes the supplied char value to or from this ccArchive. The value is serialized to
the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
•
The value to serialize.
ccArchive& operator|| (c_UInt16& val);
Serializes the supplied c_UInt16 value to or from this ccArchive. The value is serialized
to the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
•
The value to serialize.
ccArchive& operator|| (c_Int16& val);
Serializes the supplied c_Int16 value to or from this ccArchive. The value is serialized
to the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
•
The value to serialize.
ccArchive& operator|| (c_UInt32& val);
Serializes the supplied c_UInt32 value to or from this ccArchive. The value is serialized
to the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
548
The value to serialize.
CVL Class Reference
ccArchive
•
ccArchive& operator|| (c_Int32& val);
Serializes the supplied c_Int32 value to or from this ccArchive. The value is serialized
to the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
•
The value to serialize.
ccArchive& operator|| (unsigned int& val);
Serializes the supplied unsigned int value to or from this ccArchive. The value is
serialized to the archive if the ccArchive is storing; the value is serialized from the
ccArchive if the ccArchive is loading.
Parameters
val
•
The value to serialize. The value is always serialized as an
unsigned 32-bit integer.
ccArchive& operator|| (int& val);
Serializes the supplied int value to or from this ccArchive. The value is serialized to the
archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
•
The value to serialize. The value is always serialized as a 32-bit
integer.
ccArchive& operator|| (float& val);
Serializes the supplied float value to or from this ccArchive. The value is serialized to
the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
•
The value to serialize. The value is serialized using the IEEE 754
format.
ccArchive& operator|| (double& val);
Serializes the supplied double value to or from this ccArchive. The value is serialized
to the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
CVL Class Reference
549
ccArchive
Parameters
val
•
The value to serialize. The value is serialized using the IEEE 754
format.
ccArchive& operator|| (cmStd string& val);
Serializes the supplied string value to or from this ccArchive. The value is serialized to
the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
•
The value to serialize. The maximum length of a string that can be
serialized using this operator is 32,767 bytes.
ccArchive& operator|| (bool& val);
Serializes the supplied bool value to or from this ccArchive. The value is serialized to
the archive if the ccArchive is storing; the value is serialized from the ccArchive if the
ccArchive is loading.
Parameters
val
550
The value to serialize.
CVL Class Reference
ccArchive
operator<<
ccArchive& operator<< (c_UInt8 val);
ccArchive& operator<< (c_Int8 val);
ccArchive& operator<< (char val);
ccArchive& operator<< (c_UInt16 val);
ccArchive& operator<< (c_Int16 val);
ccArchive& operator<< (c_UInt32 val);
ccArchive& operator<< (c_Int32 v) val);
ccArchive& operator<< (unsigned int val);
ccArchive& operator<< (int val);
ccArchive& operator<< (float val);
ccArchive& operator<< (double val);
ccArchive& operator<< (cmStd string& val);
ccArchive& operator<< (bool& val);
Each of the overloads of the operator<< function is identical to the corresponding
operator|| function except that the ccArchive must be storing.
CVL Class Reference
551
ccArchive
operator>>
ccArchive& operator>> (c_UInt8& val);
ccArchive& operator>> (c_Int8& val);
ccArchive& operator>> (char& val);
ccArchive& operator>> (c_UInt16& val);
ccArchive& operator>> (c_Int16& val);
ccArchive& operator>> (c_UInt32& val);
ccArchive& operator>> (c_Int32& val);
ccArchive& operator>> (unsigned int& val);
ccArchive& operator>> (int& val);
ccArchive& operator>> (float& val);
ccArchive& operator>> (double& val);
ccArchive& operator>> (cmStd string& val);
ccArchive& operator>> (bool& val);
Each of the overloads of the operator>> function is identical to the corresponding
operator|| function except that the ccArchive must be loading.
Public Member Functions
raw
void raw(char* data, long count);
Stores or loads raw data to or from the ccArchive without any format modification. The
data is loaded or stored according to this ccArchive’s mode.
Parameters
data
count
Throws
ccArchive::Eof
The data to store or load. data must not be null.
The number of bytes to store or load. count must not be less than
0.
No more input data (loading only). The archive is left positioned
at the end of the input stream.
ccArchive::BadBuffer
This ccArchive is broken and is unusable (loading or storing). If
you are storing data, the disk may be full.
552
CVL Class Reference
ccArchive
mode
Direction mode() const;
void mode(Direction mode);
•
Direction mode() const;
Returns a value indicating whether this ccArchive is loading or storing. This function
returns one of the following values:
ccArchive::eLoading
ccArchive::eStoring
•
Sets this ccArchive to the specified mode (loading or storing). Cognex recommends
that you do not call this function. Instead, specify the mode when you instantiate the
ccArchive-derived concrete class.
Parameters
mode
The mode to set. mode must be one of the following values:
ccArchive::eLoading
ccArchive::eStoring
Notes
In order to call this function, ccArchive::isSeekable() must return true. If
ccArchive::isReadOnly() returns true, you cannot set this archive to storing.
isLoading
bool isLoading() const;
Returns true if this ccArchive is loading, false otherwise.
isStoring
bool isStoring() const;
Returns true if this ccArchive is storing, false otherwise.
isReadOnly
bool isReadOnly() const;
Returns true if this ccArchive is read-only, false otherwise.
getByteOrder
Ordering getByteOrder() const;
Returns the endianness of this ccArchive. This function returns one of the following
values:
ccArchive::eBigEndian
ccArchive::eLittleEndian
CVL Class Reference
553
ccArchive
append
void append();
Sets this ccArchive to storing, seeks to the end, and prepares to accept additional
stored objects. You must call append() when switching an archive constructed for
loading to storing mode. Use this function to store objects to an archive that was
constructed for loading.
Notes
This operation does not store anything into the ccArchive. In order to call this
function, ccArchive::isSeekable() must return true. If ccArchive::isReadOnly()
returns true, you cannot set this archive to storing.
sync
void sync();
Ensures that all of this ccArchive’s input or output data is flushed.
isSeekable
bool isSeekable() const;
Returns true if this ccArchive was constructed as a seekable archive.
version
c_Int32 version() const;
Returns the archive format version number of this archive.
Notes
It may not be possible to append to an archive with an old version number.
Attempting an unsupported operation will throw CannotWriteToOldArchive.
tell
cmStd streampos tell() const;
Returns the ccArchive’s current offset from its beginning.
Throws
ccArchive::BadBuffer
The ccArchive is broken and is unusable.
seek
ccArchive& seek(cmStd streampos pos);
ccArchive& seek(cmStd streamoff offset,
cmStd ios::seek_dir dir);
•
ccArchive& seek(cmStd streampos pos);
Seeks to the specified location within this ccArchive. Cognex recommends that you do
not use this function.
554
CVL Class Reference
ccArchive
Parameters
pos
•
The position to which to seek.
ccArchive& seek(cmStd streamoff offset,
cmStd ios::seek_dir dir);
Seeks to the specified offset and direction from the current seek position within this
ccArchive. Cognex recommends that you do not use this function.
Parameters
offset
dir
The offset from the current seek position.
The direction in which to seek.
Notes
You can only seek to an offset that lies within the extent of this ccArchive. A storing
archive should be written sequentially. Previously written complex-persistent
objects and pointers must not be overwritten.
Throws
ccArchive::BadBuffer
The ccArchive is broken and is unusable.
CVL Class Reference
555
ccArchive
556
CVL Class Reference
ccAtapiZipDrive
#include <ch_cvl/atapi.h>
class ccAtapiZipDrive;
Class Properties
Copyable
No
Derivable
Yes
Archiveable
No
This class provides a means for controlling an ATAPI Zip drive attached to the IDE
connector of an MVS-8200/CPCI or MVS-8200/VME. Functions are provided to eject,
lock and unlock, and check the presence of a Zip disk.
Constructors/Destructors
ccAtapiZipDrive
ccAtapiZipDrive(TCHAR driveLetter, bool removable = false,
bool temporary = true);
~ccAtapiZipDrive();
•
ccAtapiZipDrive(TCHAR driveLetter, bool removable = false,
bool temporary = true);
Creates a ccAtapiZipDrive object, one per Zip drive.
Parameters
driveLetter
CVL Class Reference
A single character denoting the drive letter of the target Zip drive.
CVL’s drive letter assignments for IDE devices are discussed in
the CVL User’s Guide.
removable
Set removable to true to make the Zip drive’s disks removable.
Set removable to false to make the current Zip disk
non-removable.
temporary
If temporary is true, the removable mode is limited to the lifetime
of this object and the previous mode is resumed when the
destructor is called. If temporary is false, the previous mode is not
resumed after the destructor is called.
557
ccAtapiZipDrive
Throws
ccAtapiZipDrive:DiskNotPresent
No disk is present in the specified Zip drive.
•
~ccAtapiZipDrive();
Destroys this object. If temporary was true on construction, then the previous removable
mode is restored. Otherwise the current removable mode is not changed.
Public Member Functions
driveLetter
TCHAR driveLetter() const;
Returns the specified Zip drive’s drive letter.
isTemp
bool isTemp() const;
Returns the last-specified scope of removable mode. Returns true if removable is limited
to the lifetime of this object; returns false if not.
lock
void lock();
Makes the Zip disk non-removable. Does nothing if the disk is already locked.
Throws
ccAtapiZipDrive:DiskNotPresent
No disk is present in the specified Zip drive.
unlock
void unlock();
Makes the Zip disk removable. Does nothing if the disk is already unlocked.
Throws
ccAtapiZipDrive:DiskNotPresent
No disk is present in the specified Zip drive.
isLock
bool isLock() const;
Returns the last-specified lock mode. Returns true if the Zip disk is non-removable, false
if removable.
eject
void eject(double ejectTime = 3.0) const;
Ejects the Zip disk, regardless of the removable mode of the drive.
558
CVL Class Reference
ccAtapiZipDrive
Parameters
ejectTime
The time to wait before ejecting the disk, in seconds. The default
is 3 seconds.
Throws
ccAtapiZipDrive:DiskNotEjected
The disk ejection failed within ejectTime.
isPresent
bool isPresent() const;
Returns true if a Zip disk is present in the drive, false if not.
CVL Class Reference
559
ccAtapiZipDrive
560
CVL Class Reference
ccAutoSelectDefs
#include <ch_cvl/autoslct.h> //
#include <ch_cvl/atslptmx.h> //
//
#include <ch_cvl/atslcnls.h> //
//
If not calling cfAutoSelect()
If calling cfAutoSelect() with
PatMax
If calling cfAutoSelect() with
CNLSearch
class ccAutoSelectDefs;
This class is a name space that holds enumerations and constants that are used with
the Auto-select tool, and errors that the tool can throw.
cfAutoSelect<>() is a template function declared in <ch_cvl/autoslct.h>. As the
definition does not provide any specialization for using this function with PatMax or
CNLSearch, you must include either <ch_cvl/atslptmx.h> or <ch_cvl/atslcnls.h> to use
this function with either of these tools.
ccAutoSelectDefs, ccAutoSelectParams, and ccAutoSelectResult, which are not
templates, are also declared in <ch_cvl/autoslct.h>. If you want to use these classes in
a compilation unit (for example, source code or header) that does not make a call to
cfAutoSelect(), you can safely include only <ch_cvl/autoslct.h>. However, if you want
to derive objects from these classes for use with PatMax or CNLSearch, you must
include either <ch_cvl/atslptmx.h> or <ch_cvl/atslcnls.h>, respectively.
For example, if your program uses these source files:
•
a.cpp --- which implements the base class, references defs, params, and results
•
b.cpp --- which implements a derived class that runs Auto-select for PatMax
•
c.cpp --- which implements a derived class that runs Auto-select for CNLSearch
then a.cpp can safely include <ch_cvl/autoslct.h>, but b.cpp must include
<ch_cvl/atslptmx.h> for PatMax support, and c.cpp must include <ch_cvl/atslcnls.cpp>
for CNLSearch support.
CVL Class Reference
561
ccAutoSelectDefs
Enumerations
Direction
enum Direction
This enumeration defines the orientation of the axes about which model symmetry and
orthogonality are measured.
Value
Meaning
eImageNormal
The axes are the image coordinate
system x-axis and y-axis.
kDefaultDirection
The default direction (the default is
eImageNormal).
ScoreCombineMethod
enum ScoreCombineMethod
This enumeration defines how the individual symmetry, orthogonality, and uniqueness
scores are combined.
562
Value
Meaning
eGeometricMean
The geometric mean is computed.
eArithmeticMean
The arithmetic mean is computed.
kDefaultScoreCombineMethod
The default combination method (the
default is eGeometricMean).
CVL Class Reference
ccAutoSelectParams
#include <ch_cvl/autoslct.h> //
#include <ch_cvl/atslptmx.h> //
//
#include <ch_cvl/atslcnls.h> //
//
If not calling cfAutoSelect()
If calling cfAutoSelect() with
PatMax
If calling cfAutoSelect() with
CNLSearch
class ccAutoSelectParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class contains the run-time parameters for the Auto-select tool.
cfAutoSelect<>() is a template function declared in <ch_cvl/autoslct.h>. As the
definition does not provide any specialization for using this function with PatMax or
CNLSearch, you must include either <ch_cvl/atslptmx.h> or <ch_cvl/atslcnls.h> to use
this function with either of these tools.
ccAutoSelectDefs, ccAutoSelectParams, and ccAutoSelectResult, which are not
templates, are also declared in <ch_cvl/autoslct.h>. If you want to use these classes in
a compilation unit (for example, source code or header) that does not make a call to
cfAutoSelect(), you can safely include only <ch_cvl/autoslct.h>. However, if you want
to derive objects from these classes for use with PatMax or CNLSearch, you must
include either <ch_cvl/atslptmx.h> or <ch_cvl/atslcnls.h>, respectively.
For example, if your program uses these source files:
•
a.cpp --- which implements the base class, references defs, params, and results
•
b.cpp --- which implements a derived class that runs Auto-select for PatMax
•
c.cpp --- which implements a derived class that runs Auto-select for CNLSearch
then a.cpp can safely include <ch_cvl/autoslct.h>, but b.cpp must include
<ch_cvl/atslptmx.h> for PatMax support, and c.cpp must include <ch_cvl/atslcnls.cpp>
for CNLSearch support.
CVL Class Reference
563
ccAutoSelectParams
Constructors/Destructors
ccAutoSelectParams
ccAutoSelectParams(bool enhancedMode = false);
Constructs a ccAutoSelectParams object that specifies whether the Auto-select tool
should run in enhanced mode or non-enhanced mode. All other parameters are set to
the following default values.
Parameter
Default Value
Direction
ccAutoSelectDefs::kDefaultDirection (currently
eImageNormal)
Model size
64x64 pixels
Sampling rate
2
Score combination method
ccAutoSelectDefs::kDefaultScoreCombineMethod
(currently eGeometricMean)
Score combination weights
Relative weight of symmetry score = 1
Relative weight of orthogonality score = 1
Relative weight of uniqueness score = 1
Maximum number of results
1
Window mask
Unbound 8-bit pel buffer
XY overlap
0.8
Parameters
enhancedMode If true, the Auto-select tool will run in enhanced mode; if false , the
tool will run in non-enhanced mode (the default). There is no
setter that will allow you to change this parameter later on.
Notes
Enhanced mode supports masking, overlap constraints, query operations on
selected locations, and blanket search operations. When run in enhanced mode,
the tool may return different results than in would be returned non-enhanced mode.
You can enable enhanced mode only at the time the ccAutoSelectParams object
is constructed.
564
CVL Class Reference
ccAutoSelectParams
Operators
operator==
bool operator==(const ccAutoSelectParams &rhs) const;
Compares two ccAutoSelectParams objects for equality. Returns true if all parameters
in both objects are equal, false otherwise.
Parameters
rhs
The ccAutoSelectParams object to be compared to this one.
Public Member Functions
direction
ccAutoSelectDefs::Direction direction() const;
void direction(ccAutoSelectDefs::Direction direction);
•
ccAutoSelectDefs::Direction direction() const;
Returns the orientation of the axes about which pattern symmetry and orthogonality are
computed. The returned direction is one of the following values:
ccAutoSelectDefs::eImageNormal
•
void direction(ccAutoSelectDefs::Direction direction);
Sets the orientation of the axes about which pattern symmetry and orthogonality are
computed.
Parameters
direction
The axis orientation to set. Must be one of the following values:
ccAutoSelectDefs::eImageNormal
ccAutoSelectDefs::kDefaultDirection
Notes
In the current release, only the direction ccAutoSelectDefs::eImageNormal works.
modelSize
ccIPair modelSize() const;
void modelSize(const ccIPair &modelSize);
•
ccIPair modelSize() const;
Returns the dimensions of the model training window in image coordinates.
CVL Class Reference
565
ccAutoSelectParams
•
void modelSize(const ccIPair &modelSize);
Sets the dimensions of the model training window in image coordinates.
Parameters
modelSize
The model dimensions to set.
Notes
Invocations of cfAutoSelect() will throw ccAutoSelectDefs::BadModel if at least
one of the components of the run parameter’s model size either too small or too
large to be able to obtain reliable data.
sample
c_Int16 sample() const;
void sample(c_Int16 sample);
•
c_Int16 sample() const;
Returns the sampling rate. The input image is sub-sampled by this factor before it is
evaluated. The larger the sampling rate, the quicker the Auto-select tool will run, and the
worse the quality of the result will be.
•
void sample(c_Int16 sample);
Sets the sampling rate. The input image is sub-sampled by this factor before it is
evaluated. The larger the sampling rate, the quicker the Auto-select tool will run, and the
worse the quality of the result will be.
Parameters
sample
The sampling rate set. Do not specify a sampling rate larger than
8.
Notes
Invocations of cfAutoSelect() will throw ccAutoSelectDefs::BadSample if the
sampling rate is less than or equal to 0.
566
CVL Class Reference
ccAutoSelectParams
scoreCombineMethod
ccAutoSelectDefs::ScoreCombineMethod scoreCombineMethod()
const;
void scoreCombineMethod(
ccAutoSelectDefs::ScoreCombineMethod method);
•
ccAutoSelectDefs::ScoreCombineMethod scoreCombineMethod()
const;
Returns the score combination method configured for this ccAutoSelectParams. The
returned value is one of the following values:
ccAutoSelectDefs::eGeometricMean
ccAutoSelectDefs::eArithmeticMean
•
void scoreCombineMethod(
ccAutoSelectDefs::ScoreCombineMethod method);
Sets the score combination method for this ccAutoSelectParams. Specify the
geometric mean if you only want a high overall score if all component scores are high;
specify the arithmetic mean if you want a high overall score if any component score is
high.
Parameters
method
The score combination method to set. Must be one of:
ccAutoSelectDefs::eGeometricMean
ccAutoSelectDefs::eArithmeticMean
scoreCombineWeights
cc3Vect scoreCombineWeights() const;
void scoreCombineWeights(const cc3Vect &weights);
•
cc3Vect scoreCombineWeights() const;
Returns a vector containing the weights to apply to the component scores when
computing the overall score. The first element of the returned vector is the weight for the
symmetry score, the second element is the weight for the orthogonality score, and the
third element is the weight for the uniqueness score.
The weights vector is normalized to a unit sum.
CVL Class Reference
567
ccAutoSelectParams
•
void scoreCombineWeights(const cc3Vect &weights);
Sets the weights to apply to the component scores when computing the overall score.
Set the first element of weights to be the weight for the symmetry score, the second
element to be the weight for the orthogonality score, and the third element to be the
weight for the uniqueness score.
scoreCombineWeights() normalizes the values you supply to a unit sum; only the
relative values of the weights is considered.
Parameters
weights
The weights to set. All of the elements of weights must be greater
than or equal to 0, and at least one of the elements must be
greater than 0.
Notes
Invocations of cfAutoSelect() will throw ccAutoSelectDefs::BadWeights if any of
the run parameter object’s weights is negative, or if all are 0.
maxNumResult
c_Int16 maxNumResult() const;
void maxNumResult(c_Int16 maxNumResult);
•
c_Int16 maxNumResult() const;
Returns the maximum number of results this ccAutoSelectParams is configured to
return. The tool might return fewer than the specified number of results; it will never
return more results than you specify.
•
void maxNumResult(c_Int16 maxNumResult);
Sets the maximum number of results that this ccAutoSelectParams returns. The tool will
never return more results than you specify, but it may return fewer.
Parameters
maxNumResult
The maximum number of results to return
Notes
Invocations of cfAutoSelect() will throw ccAutoSelectDefs::BadResult if
maxNumResult is not positive.
Only the 2*maxNumResult() results with the best symmetry scores are used to
compute overall scores. This means that if you set a low value for the maximum
number of results, you might exclude results with low symmetry scores but high
orthogonality and uniqueness scores.
568
CVL Class Reference
ccAutoSelectParams
windowMask
const ccPelBuffer_const<c_UInt8> &windowMask() const;
void windowMask(
const ccPelBuffer_const<c_UInt8> &windowMask);
•
const ccPelBuffer_const<c_UInt8> &windowMask() const;
Retrieves the window mask, an 8-bit pel buffer that is the size of the model window.
Throws
ccAutoSelectDefs::NotEnhancedMode
Enhanced mode is not enabled.
•
void windowMask(
const ccPelBuffer_const<c_UInt8> &windowMask);
Sets the window mask.
Parameters
windowMask
An 8-bit pel buffer. The window mask should either be unbound
or have the same size as the model window, as returned by
ccAutoSelectParams::modelSize().
Notes
Invocations of cfAutoSelect() will throw ccAutoSelectDefs::BadMask if the window
mask is a bound pel buffer of any size other the model size.
Throws
ccAutoSelectDefs::NotEnhancedMode
Enhanced mode is not enabled.
xyOverlap
double xyOverlap() const;
void xyOverlap(double xyOverlap);
•
double xyOverlap() const;
Retrieves the XY overlap value. The overlap value is approximately the ratio of the
overlapping area to the total area of the pattern. Two pattern instances are considered
to overlap if their overlap value is greater than the XY overlap, and only one of them will
be returned as a result from a search operation.
Notes
Meaningful XY overlap values range from 0.0 to 1.0. A value of 0.0 specifies that no
overlap is allowed. A value of 1.0 specifies that any amount of overlap is allowed
(overlap checking is disabled).
CVL Class Reference
569
ccAutoSelectParams
Throws
ccAutoSelectDefs::NotEnhancedMode
Enhanced mode is not enabled.
•
void xyOverlap(double xyOverlap);
Sets the XY overlap value that determines whether two pattern instances are considered
the same result, and only one of them will be returned from a search operation.
Parameters
xyOverlap
The XY overlap value to set. Must be in the range of 0.0 to 1.0.
Value
Meaning
0.0
No overlap is allowed.
1.0
Any amount of overlap is allowed
(overlap checking is disabled).
Throws
ccAutoSelectDefs::NotEnhancedMode
Enhanced mode is not enabled.
ccAutoSelectDefs::BadParams
xyOverlap is outside the range of 0.0 through 1.0, inclusive.
isEnhancedMode
bool isEnhancedMode() const;
Returns true if the enhanced mode is enabled, false otherwise.
Notes
Enhanced mode can be enabled only at the time the ccAutoSelectParams object
is constructed.
570
CVL Class Reference
ccAutoSelectResult
#include <ch_cvl/autoslct.h> //
#include <ch_cvl/atslptmx.h> //
//
#include <ch_cvl/atslcnls.h> //
//
If not calling cfAutoSelect()
If calling cfAutoSelect() with
PatMax
If calling cfAutoSelect() with
CNLSearch
class ccAutoSelectResult;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class contains the result of running the Auto-select tool on the input image. The
global function cfAutoSelect() returns a vector of ccAutoSelectResult objects.
cfAutoSelect<>() is a template function declared in <ch_cvl/autoslct.h>. As the
definition does not provide any specialization for using this function with PatMax or
CNLSearch, you must include either <ch_cvl/atslptmx.h> or <ch_cvl/atslcnls.h> to use
this function with either of these tools.
ccAutoSelectDefs, ccAutoSelectParams, and ccAutoSelectResult, which are not
templates, are also declared in <ch_cvl/autoslct.h>. If you want to use these classes in
a compilation unit (for example, source code or header) that does not make a call to
cfAutoSelect(), you can safely include only <ch_cvl/autoslct.h>. However, if you want
to derive objects from these classes for use with PatMax or CNLSearch, you must
include either <ch_cvl/atslptmx.h> or <ch_cvl/atslcnls.h>, respectively.
For example, if your program uses these source files:
•
a.cpp --- which implements the base class, references defs, params, and results
•
b.cpp --- which implements a derived class that runs Auto-select for PatMax
•
c.cpp --- which implements a derived class that runs Auto-select for CNLSearch
then a.cpp can safely include <ch_cvl/autoslct.h>, but b.cpp must include
<ch_cvl/atslptmx.h> for PatMax support, and c.cpp must include <ch_cvl/atslcnls.cpp>
for CNLSearch support.
CVL Class Reference
571
ccAutoSelectResult
Constructors/Destructors
ccAutoSelectResult
ccAutoSelectResult();
Constructs a default ccAutoSelectResult object with its location set to (0,0) and all
scores set to 0.0.
Notes
You should not attempt to create ccAutoSelectResult objects yourself.
Public Member Functions
location
ccIPair location() const;
Returns the upper-left corner of the returned model location window for this
ccAutoSelectResult, in image coordinates.
score
double score() const;
Returns the overall score for this ccAutoSelectResult. The overall score is computed
from the three component scores according to the weighting and combination method
parameters you specified.
symmetryScore
double symmetryScore() const;
The symmetry score for this ccAutoSelectResult. This score is a whether or not this
window is more symmetrical than nearby locations in the image.
orthoScore
double orthoScore() const;
The orthogonality score for this ccAutoSelectResult. This score is a measure of the
degree to which the model window contains a balance of strong horizontal and vertical
features. A low orthogonality score can indicate few horizontal and vertical features or
an imbalance between horizontal and vertical features.
uniqueScore
double uniqueScore() const;
The uniqueness score for this ccAutoSelectResult. The uniqueness score is a measure
of how unique the model window is when compared to the rest of the input image, using
the pattern-location tool run-time parameters you specified when you called
cfAutoSelect().
572
CVL Class Reference
ccBezierCurve
#include <ch_cvl/spline.h>
class ccBezierCurve : public ccShape;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Complex
The ccBezierCurve class is an implementation of 2D cubic Bezier curves with optional
control point weights.
The above figure shows an example of a Bezier curve with four control points.
CVL Class Reference
573
ccBezierCurve
Bezier Curves
A 2D cubic Bezier curve is a finite, continuous, and infinitely differentiable curve
specified by four 2D Bezier control points. Bezier curves interpolate the first and last
control points. It generally does not interpolate the inner two control points, although
these affect the shape of the curve.
You can assign optional positive scalar weights to the control points to produce a
rational Bezier curve. Coordinate functions along a rational Bezier curve are of the form:
x(t ) = (f(t )) ⁄ (h(t))
y( t) = ( g(t )) ⁄ ( h( t) )
where f, g, and h are cubic polynomials determined by the control points and weights.
If all weights are equal, the function h(t) is a constant, and therefore x(t) and y(t) are
themselves cubic polynomials. Weights are relative quantities, and multiplying all
control point weights by a common factor thus would have no effect on the curve.
Parameter Range
Mathematically, the range of the parameter t is arbitrary, but all ccBezierCurve class
methods that take or return parameter values assume a parameter range of 0 through
1, where 0 corresponds to the start point of the Bezier curve, and 1 corresponds to the
endpoint. Note that the parameter t does not correspond to arc length. Sampling at
uniformly spaced values of t does not in general produce points that are equally spaced
with respect to arc length along the curve.
Tangent Vectors
Some methods of the Bezier curve and spline classes refer to tangent vectors. Unless
otherwise noted, the implied meaning is the parametric tangent, given by [x’(t), y’(t)],
where ' denotes differentiation with respect to t. The parametric tangent is subtly
different from the geometric tangent to the curve at t. For example, if the first two control
points of a Bezier curve are coincident, [x’(0), y’(0)], and so the parametric tangent
vanishes. Yet the curve still has a geometric tangent at t = 0 if the second or third
derivatives of x(t) and y(t) do not all vanish. Also, the magnitude of the parametric
tangent is not generally constant along a Bezier or spline curve. What is always true is
that the parametric tangent at a given point on the curve is either zero or lies along the
geometric tangent line to the curve at that point.
574
Note
For in-depth information on the theory and use of 2D cubic Bezier
curves and splines, see any textbook on the subject, such as Curves
and Surfaces for Computer Aided Geometric Design by Gerald
Farin, Second Edition, Academic Press, 1990, ISBN 0-12-249051-7.
Note
All methods defined for this class leave a ccBezierCurve object
unchanged when they throw an error.
CVL Class Reference
ccBezierCurve
Constructors/Destructors
ccBezierCurve();
explicit
ccBezierCurve(const cmStd vector<cc2Vect> &points);
explicit
ccBezierCurve(const cmStd vector<cc2Vect> &points,
const cmStd vector<double> &weights);
explicit
ccBezierCurve(const cmStd vector<cc3Vect>
&weightedControlPoints);
•
ccBezierCurve();
Default constructor. Constructs a default Bezier curve with all four control points
coincident, equal to the origin, and with unit weights (that is, all weights equal to 1.0).
•
explicit
ccBezierCurve(const cmStd vector<cc2Vect> &points);
Constructs a ccBezierCurve with the given control points and unit weights. This
constructor is used for explicit construction only and not for implicit conversions.
Parameters
points
The vector of control points.
Notes
The control points correspond to the Bezier curve’s start point, middle two handle
points, and end point, in that order.
Throws
ccShapesError::BadParams
points does not have a size of four.
•
explicit
ccBezierCurve(const cmStd vector<cc2Vect> &points,
const cmStd vector<double> &weights);
Constructs a Bezier curve with the given control points and weights. This constructor is
used for explicit construction only and not for implicit conversions.
Parameters
points
CVL Class Reference
The four 2D Bezier control points that specify the curve.
575
ccBezierCurve
weights
Positive scalar weights assigned to the control points to produce
a rational Bezier curve (the default weight is 1.0 for all four
points).
Notes
The elements of the vectors passed in correspond to the Bezier curve’s start point,
middle two handle points, and end point, in that order.
Throws
ccShapesError::BadParams
The points and weights vectors do not both have a size of 4.
ccShapesError::NonpositiveWeight
Any element of weights is non-positive.
•
explicit
ccBezierCurve(
const cmStd vector<cc3Vect> &weightedControlPoints);
Constructs a Bezier curve with the given weighted control points. A control point (x, y)
with weight w is represented as the cc3Vect (w*x, w*y, w). This constructor is used for
explicit construction only and not for implicit conversions.
Parameters
weightedControlPoints
Vector of weighted control points.
Notes
The elements of the vector passed in correspond to the Bezier curve’s start point,
middle two handle points, and end point, in that order.
Throws
ccShapesError::BadParams
The weightedControlPoints vector does not have a size of 4.
ccShapesError::NonpositiveWeight
Any weight is non-positive.
Operators
operator==
bool operator==(const ccBezierCurve &rhs) const;
Returns true if and only if this ccBezierCurve is equal to rhs. Two ccBezierCurves are
equal if their control points and weights are all identical (no tolerance is used).
576
CVL Class Reference
ccBezierCurve
Parameters
rhs
The other ccBezierCurve.
Notes
ccBezierCurves that describe identical curves are not necessarily equal. For
example, the curve itself is invariant with respect to uniform scaling of weights, but
operator==() is not.
operator!=
bool operator!=(const ccBezierCurve &rhs) const;
Returns the opposite truth value to operator==().
Parameters
rhs
The other ccBezierCurve.
Public Member Functions
isWeighted
bool isWeighted() const;
Returns true if and only if this Bezier curve is weighted; that is, not all of the weights are
equal.
controlPoint
cc2Vect controlPoint(c_Int32 idx) const;
void controlPoint(c_Int32 idx, const cc2Vect &ctrlPt);
•
cc2Vect controlPoint(c_Int32 idx) const;
Gets the control point with the given index.
Parameters
idx
•
The index.
void controlPoint(c_Int32 idx, const cc2Vect &ctrlPt);
Sets the control point with the given index.
Parameters
idx
ctrlPt
The index.
The control point.
Throws
ccShapesError::BadIndex
idx is either less than 0 or greater than or equal to 4.
CVL Class Reference
577
ccBezierCurve
controlPoints
cmStd vector<cc2Vect> controlPoints() const;
void controlPoints(const cmStd vector<cc2Vect> &points);
•
cmStd vector<cc2Vect> controlPoints() const;
Gets the vector of Bezier control points.
•
void controlPoints(const cmStd vector<cc2Vect> &points);
Sets the vector of Bezier control points.
Parameters
points
The vector of four Bezier control points.
Throws
ccShapesError::BadParams
The control points vector does not have a size of 4.
weight
double weight(c_Int32 idx) const;
void weight(c_Int32 idx, double newWeight);
•
double weight(c_Int32 idx) const;
Gets the weight of the control point with the given index.
Parameters
idx
•
The index.
void weight(c_Int32 idx, double newWeight);
Sets the weight of the control point with given index.
Parameters
idx
newWeight
The index.
The weight.
Throws
ccShapesError::BadIndex
idx is either less than 0 or greater than or equal to 4.
ccShapesError::NonpositiveWeight
newWeight is non-positive.
578
CVL Class Reference
ccBezierCurve
weights
cmStd vector<double> weights() const;
void weights(const cmStd vector<double> &wghts);
•
cmStd vector<double> weights() const;
Gets the vector of control point weights.
•
void weights(const cmStd vector<double> &wghts);
Sets the vector of control point weights.
Parameters
wghts
The vector of four control point weights.
Throws
ccShapesError::BadParams
wghts vector does not have a size of 4.
ccShapesError::NonpositiveWeight
Any of the new weights are non-positive.
map
ccBezierCurve map(const cc2Xform& X) const;
Returns this Bezier curve mapped by X.
Parameters
X
The 2D transform used to modify this Bezier curve.
Notes
This function maps each of the four control points by X while leaving the weights
unchanged. The locus of points of the resulting mapped Bezier curve is exactly the
locus of points of the original Bezier curve mapped by X.
point
cc2Vect point(double t) const;
Returns the point at parameter value t along the Bezier curve. Values of t outside of the
range 0 through 1 are legal, but correspond to points on the extrapolation of the curve,
not on the curve itself. The value returned is an exact value, not an approximation.
Parameters
t
CVL Class Reference
The parameter value.
579
ccBezierCurve
tangent
cc2Vect tangent(double t) const;
Returns the tangent vector at parameter value t along the Bezier curve. Values of t
outside of the range 0 through 1 are legal, but correspond to points on the extrapolation
of the curve, not on the curve itself. The value returned is an exact value, not an
approximation.
Parameters
t
The parameter value.
pointAndTangent
void pointAndTangent(double t, cc2Vect &point,
cc2Vect &tangent) const;
Returns the point and tangent vector at parameter value t along the Bezier curve. Values
of t outside of the range 0 through 1 are legal, but correspond to points on the
extrapolation of the curve, not on the curve itself. The value returned is an exact value,
not an approximation.
Parameters
t
The parameter value.
Notes
Calling this routine is more efficient than calling point() and tangent() separately.
nearestPoint
cc2Vect nearestPoint(const cc2Vect &p, double &t) const;
virtual cc2Vect nearestPoint(const cc2Vect& p) const;
•
cc2Vect nearestPoint(const cc2Vect &p, double &t) const;
Returns the nearest point on this Bezier curve to the given point as well as the nearest
point’s parameter value. If the nearest point is not unique, one of the nearest points is
returned.
Parameters
p
t
•
The point.
The nearest point’s parameter value.
virtual cc2Vect nearestPoint(const c2Vect& p) const;
Returns the nearest point on this Bezier curve to the given point. If the nearest point is
not unique, one of the nearest points is returned.
580
CVL Class Reference
ccBezierCurve
Parameters
p
The point.
See ccShape::nearestPoint() for more information.
intersections
cmStd vector<double> intersections(const ccLineSeg &seg)
const;
Returns the parameter values at which this Bezier curve intersects the given line
segment.
Parameters
seg
The line segment.
Notes
Returns an empty vector if there are no intersections.
There are infinite intersections if a portion of the spline lies exactly on the line
segment. In this case, only a single intersection from this infinite set is returned.
subCurve
ccBezierCurve subCurve(double s, double t) const;
Returns the subcurve of this Bezier curve lying between the parameter values s and t.
Parameters
s
t
The first parameter value.
The second parameter value.
Notes
The cases s == t, s > t, and s < t are all legal.
Passing s = 1.0 and t = 0.0 returns the same curve as reverse().
The values of s and t are internally clipped if they fall outside the range 0 through 1.
CVL Class Reference
581
ccBezierCurve
cubicCoeffs
void cubicCoeffs(cmStd vector<double> &fCoeffs,
cmStd vector<double> &gCoeffs,
cmStd vector<double> &hCoeffs) const;
This Bezier curve is parameterized by
x(t ) = (f(t )) ⁄ (h(t))
y( t) = ( g(t )) ⁄ ( h( t) )
where f, g, and h are cubic polynomials. This method computes and returns these
cubics. Each of the returned vectors has four elements, corresponding to the cubic
coefficients, leading coefficient first.
Parameters
fCoeffs
Cubic coefficient of the polynomial f(t).
gCoeffs
Cubic coefficient of the polynomial g(t).
hCoeffs
Cubic coefficient of the polynomial h(t).
Notes
If isWeighted() is false, the polynomial h(t) is a constant.
clone
virtual ccShapePtrh clone() const;
Returns a pointer to a copy of this Bezier curve.
isOpenContour
virtual bool isOpenContour() const;
Returns true if this shape is an open contour. For Bezier curves, this function always
returns true.
See ccShape::isOpenContour() for more information.
isRegion
virtual bool isRegion() const;
Returns true if this shape is a region. For Bezier curves, this function always returns
false.
See ccShape::isRegion() for more information.
582
CVL Class Reference
ccBezierCurve
isFinite
virtual bool isFinite() const;
Returns true if this shape has finite extent. For Bezier curves, this function always returns
true.
See ccShape::isFinite() for more information.
isEmpty
virtual bool isEmpty() const;
Returns true if the set of points that lie on the boundary of this shape is empty. For Bezier
curves, this function always returns false.
See ccShape::isEmpty() for more information.
hasTangent
virtual bool hasTangent() const;
Returns true if the set of points that lie on the boundary of this shape is infinite, and there
is a well-defined tangent at all but a finite number of these points. This function returns
true for most Bezier curves. It returns false if all four control points are coincident, in
which case the curve collapses to a single point and there is no tangent.
See ccShape::hasTangent() for more information.
isReversible
virtual bool isReversible() const;
Returns true if this shape can be reversed. For Bezier curves, this function always
returns true.
See ccShape::reverse() for more information.
isDecomposed
virtual bool isDecomposed() const;
Returns true if this shape is already decomposed. For Bezier curves, this function
always returns true.
See ccShape::isDecomposed() for more information.
boundingBox
virtual ccRect boundingBox() const;
Returns the smallest rectangle that encloses this Bezier curve.
Notes
The returned shape is a tight rectangle based on the curve itself, not the control
points.
See ccShape::boundingBox() for more information.
CVL Class Reference
583
ccBezierCurve
perimeter
virtual double perimeter() const;
Returns the perimeter of this Bezier curve.
See ccShape::perimeter() for more information.
nearestPerimPos
virtual ccPerimPos nearestPerimPos(const ccShapeInfo& info,
const cc2Vect& point) const;
Returns the nearest perimeter position on this Bezier curve to the given point, as
determined by nearestPoint().
Parameters
info
point
Shape information for this shape.
The point.
See ccShape::nearestPerimPos() for more information.
startPoint
virtual cc2Vect startPoint() const;
Returns the starting point of this Bezier curve.
See ccShape::startPoint() for more information.
endPoint
virtual cc2Vect endPoint() const;
Returns the ending point of this Bezier curve.
See ccShape::endPoint() for more information.
startAngle
virtual ccRadian startAngle() const;
Returns the starting angle of this Bezier curve.
Throws
ccShapesError::NoTangent
hasTangent() is false for this Bezier curve.
See ccShape::startAngle() for more information.
endAngle
ccRadian endAngle() const;
Returns the ending angle for this Bezier curve.
Throws
584
CVL Class Reference
ccBezierCurve
ccShapesError::NoTangent
hasTangent() is false for this Bezier curve.
See ccShape::endAngle() for more information.
reverse
virtual ccShapePtrh reverse() const;
Returns the reversed version of this Bezier curve.
See ccShape::reverse() for more information.
mapShape
virtual ccShapePtrh mapShape(const cc2Xform& X) const;
Returns this Bezier curve mapped by X.
Parameters
X
The transformation object.
See ccShape::mapShape() for more information.
tangentRotation
virtual ccRadian tangentRotation() const;
Returns the net signed angle through which the tangent vector rotates along this open
contour shape from the start point to the end point.
Throws
ccShapesError::NoTangent
hasTangent() is false.
See ccShape::tangentRotation() for more information.
windingAngle
virtual ccRadian windingAngle(const cc2Vect &p) const;
Returns the net signed angle through which the vector p->t rotates as t traces the curve.
Parameters
p
The start point of the vector p->t whose angle is measured as the
end point t traces the curve.
See ccShape::windingAngle() for more information.
sample
virtual void sample(const ccShape::ccSampleParams &params,
ccSampleResult &result) const;
Returns sample positions, and possibly tangents, along this ccBezierCurve. Returned
sample points are generally not equally spaced along the curve.
CVL Class Reference
585
ccBezierCurve
Parameters
params
result
Parameters object specifying details of how the sampling should
be done.
Result object to which position and tangent chains are stored.
Notes
If params.computeTangents() is true, this function ignores Bezier curves for which
hasTangent() is false.
See ccShape::sample() for more information.
decompose
virtual ccShapePtrh decompose() const;
Returns a clone of this Bezier curve. As a Bezier curve is already a decomposed shape,
this method is equivalent to clone() for Bezier curves.
See ccShape::decompose() for more information.
subShape
virtual ccShapePtrh subShape(const ccShapeInfo &info,
const ccPerimRange &range) const;
Returns a pointer handle to the shape describing the portion of this Bezier curve over
the given perimeter range.
Parameters
info
range
Shape information for this Bezier curve.
The perimeter range.
See ccShape::subShape() for more information.
586
CVL Class Reference
ccBlob
#include <ch_cvl/blobdesc.h>
class ccBlob: public ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
A class that contains a single feature produced by performing blob analysis on an
image.
ccBlob
ccBlob();
ccBlob(const ccBlob& rhs);
•
ccBlob();
You should not create ccBlobs.
Enumerations
Direction
enum Direction
This enumeration defines the direction codes that can appear in the chain code that
describes the perimeter of a feature.
CVL Class Reference
Value
Meaning
ePlusX
Increase in x-direction
eMinusX
Decrease in x-direction
ePlusY
Increase in y-direction
eMinusY
Decrease in y-direction
eEnd
End of chain
587
ccBlob
Measure
enum Measure
This enumeration defines all the measures that can be computed for a feature.
588
Value
Meaning
eLabel
The feature label. For grey-scale
connectivity this is 1 for blobs, 0 for
holes. For labeled connectivity this is
the feature’s label.
eArea
The area of the feature in client
coordinate system units. For grey-scale
connectivity, this is the sum of the
weights of the pixels. For other types of
connectivity, it is the number of pixels.
eNumSteps
The number of steps in the chain code
that describes this feature’s perimeter
ePerimeter
The perimeter of the feature in client
coordinate system units. This value is
based on eNumSteps but is corrected
to approximate the true perimeter of the
feature. The correction formula is
described as part of the perimeter()
function on page 597.
eNumChildren
The number of features contained within
this feature
eCenterMassX
The x-coordinate of the center of mass
of the feature
eCenterMassY
The y-coordinate of the center of mass
of the feature
eInertiaX
The second moment of inertia of this
feature about an axis drawn through the
feature’s center of mass and parallel to
the image coordinate system x-axis
eInertiaY
The second moment of inertia of this
feature about an axis drawn through the
feature’s center of mass and parallel to
the image coordinate system y-axis
CVL Class Reference
ccBlob
Value
Meaning
eInertiaMin
The second moment of inertia of this
feature about its major axis
eInertiaMax
The second moment of inertia of this
feature about its minor axis
eElongation
The ratio of eInertiaMax to eInertiaMin
eAngle
The angle of the major axis of the feature
with respect to the client coordinate
system x-axis. If eElongation is 1.0
eAngle is reported as 0, although it is
actually undefined.
eAcircularity
The acircularity of the feature as
measured by dividing the square of the
feature’s perimeter by 4 times the
feature’s area times pi.
The value of eAcircularity is 1 for a
perfectly circular feature; the less
circular the feature, the greater the
value of eAcircularity.
eAcircularityRms
The acircularity of the feature as
measured by the normalized rms
deviation of the boundary point radius
values from r0, where r0 is the square
root of the feature’s area divided by pi.
The value of eAcircularityRms is 1 for a
perfectly circular feature; the less
circular the feature, the greater the
value of eAcircularityRms.
CVL Class Reference
eIsInterior
The blob is interior to the image.
eImageBoundCenterX
The x-coordinate of the center of the
rectangle defining the image coordinate
extents of the feature.
eImageBoundCenterY
The y-coordinate of the center of the
rectangle defining the image coordinate
extents of the feature
589
ccBlob
590
Value
Meaning
eImageBoundMinX
The x-coordinate of the left edge of the
rectangle defining the image coordinate
extents of this feature
eImageBoundMaxX
The x-coordinate of the right edge of the
rectangle defining the image coordinate
extents of this feature
eImageBoundMinY
The y-coordinate of the top edge of the
rectangle defining the image coordinate
extents of this feature
eImageBoundMaxY
The y-coordinate of the bottom edge of
the rectangle defining the image
coordinate extents of this feature
eImageBoundWidth
The width of the rectangle defining the
image coordinate extents of this feature
eImageBoundHeight
The height of the rectangle defining the
image coordinate extents of this feature
eImageBoundAspect
The ratio of eImageBoundHeight to
eImageBoundWidth
eMedianX
The point on the client coordinate
system x-axis through which a vertical
line which divides the feature’s area in
half passes
eMedianY
The point on the client coordinate
system y-axis through which a
horizontal line which divides the
feature’s area in half passes
eBoundCenterX
The x-coordinate of the center of a
bounding box aligned to the client
coordinate system angle specified by
the most recent call to
ccBlobSceneDescription::
extremaAngle() and respecting the
amount of area to exclude specified by
the most recent call to
ccBlobSceneDescription::
extremaExcludeArea().
CVL Class Reference
ccBlob
CVL Class Reference
Value
Meaning
eBoundCenterY
The y-coordinate of the center of a
bounding box aligned to the client
coordinate system angle specified by
the most recent call to
ccBlobSceneDescription::
extremaAngle() and respecting the
amount of area to exclude specified by
the most recent call to
ccBlobSceneDescription::
extremaExcludeArea().
eBoundMinX
The x-coordinate of the left edge of a
bounding box aligned to the client
coordinate system angle specified by
the most recent call to
ccBlobSceneDescription::
extremaAngle() and respecting the
amount of area to exclude specified by
the most recent call to
ccBlobSceneDescription::
extremaExcludeArea().
eBoundMaxX
The x-coordinate of the right edge of a
bounding box aligned to the client
coordinate system angle specified by
the most recent call to
ccBlobSceneDescription::
extremaAngle() and respecting the
amount of area to exclude specified by
the most recent call to
ccBlobSceneDescription::
extremaExcludeArea().
eBoundMinY
The y-coordinate of the top edge of a
bounding box aligned to the client
coordinate system angle specified by
the most recent call to
ccBlobSceneDescription::
extremaAngle() and respecting the
amount of area to exclude specified by
the most recent call to
ccBlobSceneDescription::
extremaExcludeArea().
591
ccBlob
592
Value
Meaning
eBoundMaxY
The y-coordinate of the bottom edge of
a bounding box aligned to the client
coordinate system angle specified by
the most recent call to
ccBlobSceneDescription::
extremaAngle() and respecting the
amount of area to exclude specified by
the most recent call to
ccBlobSceneDescription::
extremaExcludeArea().
eBoundWidth
The width of a bounding box aligned to
the client coordinate system angle
specified by the most recent call to
ccBlobSceneDescription::
extremaAngle() and respecting the
amount of area to exclude specified by
the most recent call to
ccBlobSceneDescription::
extremaExcludeArea().
eBoundHeight
The height of a bounding box aligned to
the client coordinate system angle
specified by the most recent call to
ccBlobSceneDescription::
extremaAngle() and respecting the
amount of area to exclude specified by
the most recent call to
ccBlobSceneDescription::
extremaExcludeArea().
eBoundAspect
The ratio of eBoundHeight to
eBoundWidth
eBoundPrincipalMinX
The distance, in client coordinates,
along the first principal axis of the
feature from the feature’s center of mass
in the negative X-direction to the edge of
a bounding box aligned to the feature’s
principal axes. The distance is
expressed in the modified client
coordinate system returned by
ccBlob::boundingBoxPrincipal(); the
value of this measure is negative.
CVL Class Reference
ccBlob
CVL Class Reference
Value
Meaning
eBoundPrincipalMaxX
The distance, in client coordinates,
along the first principal axis of the
feature from the feature’s center of mass
in the positive X-direction to the edge of
a bounding box aligned to the feature’s
principal axes. The distance is
expressed in the modified client
coordinate system returned by
ccBlob::boundingBoxPrincipal().
eBoundPrincipalMinY
The distance, in client coordinates,
along the second principal axis of the
feature from the feature’s center of mass
in the negative Y-direction to the edge of
a bounding box aligned to the feature’s
principal axes. The distance is
expressed in the modified client
coordinate system returned by
ccBlob::boundingBoxPrincipal(); the
value of this measure is negative.
eBoundPrincipalMaxY
The distance, in client coordinates,
along the second principal axis of the
feature from the feature’s center of mass
in the positive Y-direction to the edge of
a bounding box aligned to the feature’s
principal axes. The distance is
expressed in the modified client
coordinate system returned by
ccBlob::boundingBoxPrincipal().
eBoundPrincipalWidth
The distance, in client coordinates,
along the first principal axis of the
feature between the sides of the
bounding rectangle aligned to the
feature’s first principal axis.
593
ccBlob
Value
Meaning
eBoundPrincipalHeight
The distance, in client coordinates,
along the second principal axis of the
feature between the sides of the
bounding rectangle aligned to the
feature’s first principal axis.
eBoundPrincipalAspect
The ratio of eBoundPrincipalHeight to
eBoundPrincipalWidth
Public Member Functions
scene
const ccBlobSceneDescription* scene() const;
Returns a pointer to the ccBlobSceneDescription of which this feature is a component.
id
c_Int32 id() const;
Returns the ID value of this feature. You can use this ID to refer to the feature.
label
c_UInt8 label() const;
Returns the type of feature that this ccBlob is. For grey-scale connectivity, this function
returns 1 if the feature is a blob and 0 if it is a hole. For labelled connectivity, this function
returns the feature’s label value.
imageBoundingBox
ccPelRect imageBoundingBox() const;
Returns the smallest image-coordinate-aligned ccPelRect that encloses all of the pixels
of this feature. The origin of the rectangle is the location of this blob in the original scene.
Notes
This function requires much less time to execute than functions that compute a
feature’s area or size with respect to its principal axes.
imageBoundingBoxCenter
cc2Vect imageBoundingBoxCenter() const;
Returns the location of the center of the ccPelRect returned by imageBoundingBox()
in image coordinates.
594
CVL Class Reference
ccBlob
Notes
This function requires much less time to execute than functions that compute a
feature’s area or size with respect to its principal axes.
imageBoundingBoxAspect
double imageBoundingBoxAspect() const;
Returns the ratio of the height of the ccPelRect returned by imageBoundingBox() to its
width.
Notes
This function requires much less time to execute than functions that compute a
feature’s area or size with respect to its principal axes.
region
const ccRLEBuffer& region() const;
Returns a reference to a ccRLEBuffer that contains the feature described by this
ccBlob.
If this ccBlob refers to a blob produced by grey-scale connectivity, runs in the returned
ccRLEBuffer with nonzero values are part of the blob, while runs with a value of 0 are
parts of holes or the background. If this ccBlob refers to a hole produced by grey-scale
connectivity, runs in the returned ccRLEBuffer with a value of 1 are part of the hole,
while runs with a value of 0 are parts of the background (either parts of the blob
surrounding this hole or blobs within this hole). If this ccBlob refers to a feature
produced by labelled connectivity, runs in the returned ccRLEBuffer with a value of 1
are part of the feature, while runs with a value of 0 are part of features with other labels.
boundaryChainCode
ccIPair boundaryChainCode(
cmStd vector<ceBlobDirection>& chain) const;
Returns the location, in image coordinates, of the start (and end) of a chain code that
describes this feature’s outer boundary. The chain code itself is returned in the supplied
reference to a vector of ceBlobDirection.
The chain code is defined as the path along the outside edges of the outermost pixels
of the feature, moving in a clockwise direction. Each element of the chain code can
indicate one of four directions. The end of the chain code is marked with an eEnd code.
Parameters
chain
CVL Class Reference
The chain code. Each element of chain is one of the following
values:
595
ccBlob
ePlusX
eMinusX
ePlusY
eMinusY
eEnd
Throws
ccBlob::BadMeasure
No chain code is available. This feature was produced using
whole-image connectivity analysis.
numSteps
c_Int32 numSteps() const;
Returns the number of elements in the chain code that describes this feature’s outer
boundary.
Throws
ccBlob::BadMeasure
No chain code is available: this feature was produced using
whole-image connectivity analysis.
area
double area() const;
Returns the area of the feature described by this ccBlob. The area is computed in image
coordinates, then converted to the units of the client coordinate system.
The initial area computation is performed as follows. If the feature is a blob that was
produced by grey-scale connectivity, the area is the weighted sum of the nonzero pixels
of the blob, normalized by any scaling value that you specified. If the feature is a hole
produced by grey-scale connectivity, the area is the number of pixels in the hole. If the
feature was produced by labelled connectivity, the area is the number of pixels in the
feature.
Notes
The area is converted to client coordinate system units by calling the following
functions:
region().clientFromImageXform().mapArea()
596
CVL Class Reference
ccBlob
perimeter
double perimeter() const;
Returns the perimeter of the feature. The perimeter is computed using the following
formula:
P = 0.94806 ( Sx × N x + Sy × Ny – Sc × C )
Where:
Sx is the value returned by cc2Xform::xScale() when called on the cc2Xform
associated with this feature.
Nx is the number of ePlusX and eMinusX codes in this feature’s chain code.
Sy is the value returned by cc2Xform::yScale() when called on the cc2Xform
associated with this feature.
Ny is the number of ePlusY and eMinusY codes in this feature’s chain code.
Sc is equal to:
2
Sx + Sy – Sx + Sy
2
C is the number of convex corners in this feature’s chain code. A convex corner is
any of the following pairs of chain codes:
ePlusX followed by eMinusY
eMinusY followed by eMinusX
eMinusX followed by ePlusY
ePlusY followed by ePlusX
This formula corrects for the tendency of the raw chain code count to overstate the true
blob perimeter.
The perimeter is returned in the units of the client coordinate system associated with the
image being analyzed.
Throws
ccBlob::BadMeasure
No chain code is available: this feature was produced using
whole-image connectivity analysis.
centerOfMass
cc2Vect centerOfMass() const;
Returns the position of the center of mass of this feature in the client coordinate system.
CVL Class Reference
597
ccBlob
inertia
ccDPair inertia() const;
Returns the feature’s second moments of inertia about the horizontal and vertical axes
within the client coordinate system through the feature’s center of mass.
inertia().x() contains the moment about the vertical axis, inertia().y() contains the
moment about the horizontal axis.
inertiaPrincipal
ccDPair inertiaPrincipal() const;
Returns the feature’s second moments of inertia about its first and second principal
axes.
inertiaPrincipal().x() contains the moment about the first principal axis,
inertiaPrincipal().y() contains the moment about the second principal axis.
elongation
double elongation() const;
Returns the ratio of the feature’s second moment of inertia about its second principal
axis to the feature’s second moment of inertia about its first principal axis.
angle
ccRadian angle() const;
Returns the orientation of the feature’s first principal axis with respect to the x-axis of the
client coordinate system, in radians. The following figure shows how the angle is
reported:
+π/2 rad
Client coordinate system
0 rad
−π/2 rad
Notes
If the value returned by elongation() is exactly 1, then this function returns 0,
although the actual value for the angle is undefined. If the value returned by
elongation() is very close 1, the value for the angle may be meaningless.
598
CVL Class Reference
ccBlob
acircularity
double acircularity() const;
Returns a measure of the acircularity of this feature. The return value is computed using
the following formula:
2
p ⁄ (4 × π × A)
Where:
p is the value returned by perimeter()
A is the value returned by area()
Throws
ccBlob::BadMeasure
No perimeter information is available: this feature was produced
using whole-image connectivity analysis.
acircularityRms
double acircularityRms() const;
Returns a measure of the acircularity of this feature. The return value is the normalized
RMS deviation of boundary point radius values from r0, where r0 computed using the
following formula:
A
---π
Where:
A is the value returned by area()
Throws
ccBlob::BadMeasure
No perimeter information is available: this feature was produced
using whole-image connectivity analysis.
median
cc2Vect median(const ccRadian& angle = ccRadian(0)) const;
Returns the median point for this feature. The median point is defined as the point
through which a pair of perpendicular lines will divide the feature in half, vertically and
horizontally. By default, the lines are aligned to the x- and y-axes of the client coordinate
system. You can specify an optional angle at which to draw the horizontal line.
CVL Class Reference
599
ccBlob
Parameters
angle
boundingBox
The angle (in the client coordinate system) at which to draw the
horizontal median line. An angle of 0 is the same as the client
coordinate system x-axis.
ccDRect boundingBox(bool excludeExtrema = true,
const ccRadian& angle = ccRadian(0)) const;
Returns the smallest rectangle that completely encloses the feature described by this
ccBlob. The bounding box is computed in a new coordinate system which is a rotated
and translated version of the client coordinate system. The origin of the new coordinate
system is the blob’s center of mass, and the coordinate system is rotated by the
specified angle, positive angles indicating that the new x-axis is rotated towards the
+y-axis relative to the old x-axis.
The following diagram illustrates the effect of specifying a rotation angle:
Client coordinate system
x
x
Specified angle
y
y
No angle specified
Angle specified
You can specify the angle of the first principal axis of the feature to obtain the bounding
box aligned to the blob’s principal axis.
Parameters
excludeExtrema If excludeExtrema is true, the amount of the feature’s extrema that
you specified when you called
ccBlobSceneDescription::extremaExclude(),
ccBlobSceneDescription::extremaExcludePels(), or
ccBlobSceneDescription::extremaExcludePercent() is
excluded before the bounding box is computed.
If excludeExtrema is false, the bounding box is computed to
enclose the entire feature.
angle
600
The angle at which to align the bounding box, relative to the
x-axis of client coordinate system.
CVL Class Reference
ccBlob
Notes
Cognex recommends that you use the boundingBox().origin(),
boundingBox().width(), and boundingBox().height() functions to obtain the
bounding box dimensions.
The boundingBox().origin() function returns the location of the lower-left corner of
the returned rectangle, in a coordinate system whose origin is at the center of the
feature. Accordingly, the returned location will have negative values for both x and
y.
CVL Class Reference
601
ccBlob
boundingBoxPrincipal
ccDRect boundingBoxPrincipal(bool excludeExtrema = true)
const;
Returns the smallest rectangle that completely encloses the feature described by this
ccBlob aligned to the feature’s first principal axis. The returned ccDRect has its origin
set to the center of mass of the feature.
Unlike imageBoundingBox(), this function returns a measure of the blob that does not
vary with the angle of the blob.
The location of the rectangle returned by this function is given in terms of a new client
coordinate system. This new client coordinate system is a copy of the current client
coordinates translated and rotated such that the origin of the new coordinate system is
at the feature’s center of mass and the positive x-axis is aligned to the first principal axis
of the feature. The following figure shows how this new coordinate system is created:
Second principal axis
First principal axis
Client
coordinates
Angle of first
principal axis
Center of mass
New client
coordinates
Bounding box
The blob measures eBoundPrincipalMinX, eBoundPrincipalMaxX,
eBoundPrincipalMinY, and eBoundPrincipalMaxY are all expressed using this same
602
CVL Class Reference
ccBlob
client coordinate system, as shown in the following figure:
eBoundPrincipalMinX
eBoundPrincipalMinY
eBoundPrincipalMaxY
eBoundPrincipalMaxX
Parameters
excludeExtrema If excludeExtrema is true, the amount of the feature’s extrema that
you specified when you called
ccBlobSceneDescription::extremaExclude(),
ccBlobSceneDescription::extremaExcludePels(), or
ccBlobSceneDescription::extremaExcludePercent() is
excluded before the bounding box is computed.
If excludeExtrema is false, the bounding box is computed to
enclose the entire feature.
Notes
This function is equivalent to calling boundingBox() and specifying angle() for the
angle argument.
Cognex recommends that you use the boundingBoxPrincipal().origin(),
boundingBoxPrincipal().width(), and boundingBoxPrincipal().height()
functions to obtain the bounding box dimensions.
CVL Class Reference
603
ccBlob
center
cc2Vect center(bool excludeExtrema = true,
const ccRadian& angle = ccRadian(0)) const;
Returns the position of the center of the bounding box computed by boundingBox().
The position is returned in terms of the client coordinate system for the image which
contained this feature.
Parameters
excludeExtrema If excludeExtrema is true, the amount of the feature’s extrema that
you specified when you called
ccBlobSceneDescription::extremaExclude(),
ccBlobSceneDescription::extremaExcludePels(), or
ccBlobSceneDescription::extremaExcludePercent() is
excluded before the bounding box is computed.
If excludeExtrema is false, the bounding box is computed to
enclose the entire feature.
angle
The angle at which to align the bounding box, relative to the
x-axis of client coordinate system.
centerPrincipal
cc2Vect centerPrincipal(bool excludeExtrema = true) const;
Returns the position of the center of the bounding box computed by
boundingBoxPrincipal(). The position is returned in terms of the client coordinate
system for the image which contained this feature.
Parameters
excludeExtrema If excludeExtrema is true, the amount of the feature’s extrema that
you specified when you called
ccBlobSceneDescription::extremaExclude(),
ccBlobSceneDescription::extremaExcludePels(), or
ccBlobSceneDescription::extremaExcludePercent() is
excluded before the bounding box is computed.
If excludeExtrema is false, the bounding box is computed to
enclose the entire feature.
aspect
double aspect(bool excludeExtrema = true,
const ccRadian& angle = ccRadian(0)) const;
Returns the aspect ratio of the bounding box computed by boundingBox(). This is
equal to the ratio of the value returned by ccDRect::height() to the value returned by
ccDRect::width() when called on the ccDRect returned by boundingBox().
604
CVL Class Reference
ccBlob
Parameters
excludeExtrema If excludeExtrema is true, the amount of the feature’s extrema that
you specified when you called
ccBlobSceneDescription::extremaExclude(),
ccBlobSceneDescription::extremaExcludePels(), or
ccBlobSceneDescription::extremaExcludePercent() is
excluded before the bounding box is computed.
If excludeExtrema is false, the bounding box is computed to
enclose the entire feature.
angle
isInterior
The angle at which to align the bounding box, relative to the
x-axis of client coordinate system.
bool isInterior() const;
This function tests whether the blob is interior to the image. The function may, or may not
use the mask ccBlobParams::mask().
If ccBlobParams::useMaskForInterior() is true and the mask is not degenerate, the
mask is used. Otherwise the mask is not used.
When the mask is not used, the function returns false if some blob pixel is a boundary
pixel of the input image. When the mask is used the function returns false if some blob
pixel is 8-connected to some don’t care pixel of the mask. In all other cases the function
returns true.
aspectPrincipal
double aspectPrincipal(bool excludeExtrema = true) const;
Returns the aspect ratio of the bounding box computed by boundingBoxPrincipal().
This is equal to the ratio of the value returned by ccDRect::height() to the value returned
by ccDRect::width() when called on the ccDRect returned by
boundingBoxPrincipal().
Parameters
excludeExtrema If excludeExtrema is true, the amount of the feature’s extrema that
you specified when you called
ccBlobSceneDescription::extremaExclude(),
ccBlobSceneDescription::extremaExcludePels(), or
ccBlobSceneDescription::extremaExcludePercent() is
excluded before the bounding box is computed.
If excludeExtrema is false, the bounding box is computed to
enclose the entire feature.
CVL Class Reference
605
ccBlob
Notes
The value returned by this function is typically less than or equal to 1 while the value
returned by elongation() is always greater than or equal to 1.
measure
double measure(theMeasure) const;
Returns the specified measure for this feature. Measures are always computed and
returned in terms of the client coordinate system.
Parameters
theMeasure
The measure to obtain. theMeasure must be one of the following
values:
ccBlob::eLabel
ccBlob::eArea
ccBlob::eNumSteps
ccBlob::ePerimeter
ccBlob::eNumChildren
ccBlob::eCenterMassX
ccBlob::eCenterMassY
ccBlob::eInertiaX
ccBlob::eInertiaY
ccBlob::eInertiaMin
ccBlob::eInertiaMax
ccBlob::eElongation
ccBlob::eAngle
ccBlob::eAcircularity
ccBlob::eAcircularityRms
ccBlob::eImageBoundCenterX
ccBlob::eImageBoundCenterY
ccBlob::eImageBoundMinX
ccBlob::eImageBoundMaxX
ccBlob::eImageBoundMinY
ccBlob::eImageBoundMaxY
ccBlob::eImageBoundWidth
ccBlob::eImageBoundHeight
ccBlob::eImageBoundAspect
ccBlob::eMedianX
ccBlob::eMedianY
ccBlob::eBoundCenterX
ccBlob::eBoundCenterY
ccBlob::eBoundMinX
ccBlob::eBoundMaxX
ccBlob::eBoundMinY
ccBlob::eBoundMaxY
ccBlob::eBoundWidth
606
CVL Class Reference
ccBlob
ccBlob::eBoundHeight
ccBlob::eBoundAspect
ccBlob::eBoundPrincipalMinX
ccBlob::eBoundPrincipalMaxX
ccBlob::eBoundPrincipalMinY
ccBlob::eBoundPrincipalMaxY
ccBlob::eBoundPrincipalWidth
ccBlob::eBoundPrincipalHeight
ccBlob::eBoundPrincipalAspect
Notes
This function is called internally by the Blob tool if you have defined sorting or
filtering criteria in the ccBlobSceneDescription that contains this feature.
Throws
ccBlob::BadMeasure
The requested measure is not available: this feature was
produced using whole-image connectivity analysis.
parent
const ccBlob* parent() const;
Returns a pointer to the feature that encloses this feature. If no feature encloses this one,
this function returns NULL.
nextSibling
const ccBlob* nextSibling(bool filtered = true) const;
Returns a pointer to the next feature that is contained within this feature’s parent. The
order in which features are returned by this function is determined by the current sort
order, which you can set by calling scene().setSort(). If this feature has no siblings, this
function returns NULL.
Parameters
filtered
prevSibling
If true, only features that meet the current filtering criteria are
returned, and features are sorted according to the current sort
criteria. If false, no filtering or sorting is performed.
const ccBlob* prevSibling(bool filtered = true) const;
Returns a pointer to the previous feature that is contained within this feature’s parent.
The order in which features are returned by this function is determined by the current
sort order, which you can set by calling scene().setSort(). If this feature has no siblings,
this function returns NULL.
CVL Class Reference
607
ccBlob
Parameters
filtered
numChildren
If true, only features that meet the current filtering criteria are
returned, and features are sorted according to the current sort
criteria. If false, no filtering or sorting is performed.
c_Int32 numChildren(bool filtered=true) const;
Returns the number of features that are enclosed within this feature.
Parameters
filtered
firstChild
If true, only features that meet the current filtering criteria are
returned, and features are sorted according to the current sort
criteria. If false, no filtering or sorting is performed.
const ccBlob* firstChild(bool filtered = true) const;
Returns a pointer to the first feature that is contained within this feature. The order in
which features are returned by this function is determined by the current sort order,
which you can set by calling scene().setSort(). If this feature does not contain any
features, this function returns NULL.
Parameters
filtered
lastChild
If true, only features that meet the current filtering criteria are
returned, and features are sorted according to the current sort
criteria. If false, no filtering or sorting is performed.
const ccBlob* lastChild(bool filtered = true) const;
Returns a pointer to the last feature that is contained within this feature. The order in
which features are returned by this function is determined by the current sort order,
which you can set by calling scene().setSort(). If this feature does not contain any
features, this function returns NULL.
Parameters
filtered
draw
If true, only features that meet the current filtering criteria are
returned, and features are sorted according to the current sort
criteria. If false, no filtering or sorting is performed.
void draw(ccGraphicList& graphList,
c_UInt32 drawMode=ccBlobDefs::eDrawStandard,
const ccCvlString& label=ccCvlString()) const;
Appends result graphics for this blob to the supplied ccGraphicList.
The graphics are drawn in client coordinates.
608
CVL Class Reference
ccBlob
Parameters
graphList
drawMode
The graphics list to append the graphics to.
The drawing mode to use. drawMode must be composed by
ORing together one or more of the following values:
ccBlobDefs::eDrawImageCenterOfMass
ccBlobDefs::eDrawCenterOfMass
ccBlobDefs::eDrawLabel
ccBlobDefs::eDrawImageBoundingBox
ccBlobDefs::eDrawBoundingBox
ccBlobDefs::eDrawBoundingTrace
ccBlobDefs::eDrawStandard
label
CVL Class Reference
If you include ccBlobDefs::eDrawLabel in drawMode, then the
contents of label are used to label the center of mass.
609
ccBlob
610
CVL Class Reference
ccBlobDefs
#include <blobdesc.h>
class ccBlobDefs;
A name space that holds enumerations and constants used with the Blob tool.
Enumerations
DrawMode
enum DrawMode
This enumeration defines the types of result graphics you can draw for blobs and blob
scene descriptions.
Value
Meaning
eDrawImageCenterOfMass
Draws a cross at the center of mass.
eDrawCenterOfMass
Draws a cross at the center of mass
aligned to the angle of the principal axis.
(Used with eDrawBoundingBox.)
eDrawLabel
Draws a text label at the center of mass.
eDrawImageBoundingBox
Draws a box that encloses all of the
feature’s pixels. The box is
image-aligned.
eDrawBoundingBox
Draws a box that encloses all of the
feature’s pixels. The box is aligned to the
angle of the principal axis.
eDrawBoundingTrace
Draws the bounding trace (feature
perimeter) that describes this feature.
eDrawStandard
Draws an image-aligned bounding box,
image-aligned cross at the center of
mass, and a text label at the center of
mass.
Notes
All graphics are drawn in ccColor::greenColor() by default, except for
eDrawBoundingTrace, which is drawn in ccColor::cyanColor().
CVL Class Reference
611
ccBlobDefs
612
CVL Class Reference
ccBlobParams
#include <ch_cvl/blobtool.h>
class ccBlobParams: public ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class contains all of the parameters required to perform blob analysis on an image.
CVL Class Reference
613
ccBlobParams
Constructors/Destructors
ccBlobParams
ccBlobParams();
Constructs a ccBlobParams with the following default values:
Parameter
Default value
segmentationType
eNone
Assumes a binary segmented image
scaleVal
1
Assumes a binary segmented image
keepRLE
False
mask
Degenerate (none)
keepMasked
False
morph
0-sized (none)
connectivityType
eGreyScale
connectivityCleanup
eNone
connectivityMinPels
0
useMaskForInterior
False
Each of these parameters may be examined and changed using ccBlobParams
member functions.
Enumerations
MorphOp
enum MorphOp
This enumeration defines the grey-scale morphological operations that are supported
as part of the image segmentation process.
614
Value
Meaning
eMinH
Replace the target pixel with the minimum value of the 3
horizontal pixels centered on the target pixel.
eMinV
Replace the target pixel with the minimum value of the 3 vertical
pixels centered on the target pixel.
CVL Class Reference
ccBlobParams
Segmentation
Value
Meaning
eMinS
Replace the target pixel with the minimum value of the 9 square
pixel area centered on the target pixel.
eMaxH
Replace the target pixel with the maximum value of the 3
horizontal pixels centered on the target pixel.
eMaxV
Replace the target pixel with the maximum value of the 3
vertical pixels centered on the target pixel.
eMaxS
Replace the target pixel with the maximum value of the 9 square
pixel area centered on the target pixel.
eMinMaxH
Perform an eMaxH followed by an eMinH; also called closing.
eMinMaxV
Perform an eMaxV followed by an eMinV; also called closing.
eMinMaxS
Perform an eMaxS followed by an eMinS also called closing.
eMaxMinH
Perform an eMinH followed by an eMaxH; also called opening.
eMaxMinV
Perform an eMinV followed by an eMaxV; also called opening.
eMaxMinS
Perform an eMinS followed by an eMaxS; also called opening.
enum Segmentation
This enumeration defines the segmentation types supported in ccBlobParams. You can
only set the segmentation type by calling a member function that includes all of the
parameters required for that segmentation type.
CVL Class Reference
Value
Meaning
eNone
No segmentation is performed; the input image is already
segmented.
eMap
Segment using a pixel map.
eHardThresh
Segment using a hard binary threshold; you can specify an
absolute or relative threshold value.
eSoftThresh
Segment using a soft binary threshold; you can specify an
absolute or relative threshold value.
eThreshImage
Segment using a threshold image.
615
ccBlobParams
Public Member Functions
setSegmentationNone
void setSegmentationNone(c_UInt8 scaleVal);
Sets this ccBlobParams to perform no segmentation on the input image. Use this
function if the input image is already segmented.
You specify a scaling value to indicate the pixel value in the input image that represents
a weight of 1.0. All pixels in the input image are interpreted on a linear scale relative to
the scaling value. No pixel in the input image should have a value greater than scaleVal.
Parameters
scaleVal
The scaling value.
Throws
ccBlobDefs::BadParams
scaleVal is equal to zero.
setSegmentationMap
void setSegmentationMap(const cmStd vector<c_UInt8>& map,
c_UInt8 scaleVal);
Sets this ccBlobParams to segment the input image using the supplied pixel map. Each
pixel in the input image is assigned a weight equal to the value within the pixel map at
the index equal to the input image pixel value.
You specify a scaling value to indicate the pixel value in the resulting mapped image
that represents a weight of 1.0. All pixels in the mapped image are interpreted on a linear
scale relative to the scaling value; no pixel in the input image should have a value
greater than scaleVal.
Parameters
map
scaleVal
The pixel map. map must have at least as many elements as the
largest pixel value in the input image.
The scaling value.
Notes
This function creates an internal copy of the supplied pixel map.
Throws
ccBlobDefs::BadParams
scaleVal is equal to zero.
map size is equal to zero.
616
CVL Class Reference
ccBlobParams
setSegmentationHardThresh
void setSegmentationHardThresh(c_UInt8 thresh,
bool invert=false);
void setSegmentationHardThresh(c_Int32 lowTailPercent,
c_Int32 highTailPercent, c_Int32 threshPercent,
bool invert = false);
•
void setSegmentationHardThresh(c_UInt8 thresh,
bool invert=false);
Sets this ccBlobParams to segment the input image using the supplied hard threshold.
Each pixel in the input image with a value below the threshold is assigned a weight of 0;
each pixel in the input image with a value greater than or equal to the threshold is
assigned a weight of 1.
You can specify an invert flag to specify that pixels below the threshold are assigned a
weight of 1 and pixels at or above the threshold are assigned a weight of 0.
Parameters
thresh
invert
•
The threshold value.
If invert is true, then all pixels in image with values greater than or
equal to the supplied threshold are set to 0; pixels with values
less than the threshold are set to 1. If invert is false, then all pixels
in image with values greater than or equal to the supplied
threshold are set to 1; pixels with values less than the threshold
are set to 0.
void setSegmentationHardThresh(c_Int32 lowTailPercent,
c_Int32 highTailPercent, c_Int32 threshPercent,
bool invert = false);
Sets this ccBlobParams to segment the input image using the supplied relative
threshold value. The specified percentage of low tail and high tail pixels are discarded,
then the threshold pixel value is computed by determining the pixel value which lies at
the specified percentage of the distance between the low tail pixel value and the high
tail pixel value.
Each pixel in the input image with a value below the computed threshold is assigned a
weight of 0; each pixel in the input image with a value greater than or equal to the
computed threshold is assigned a weight of 1.
You can specify an invert flag to specify that pixels below the computed threshold are
assigned a weight of 1 and pixels at or above the threshold are assigned a weight of 0.
CVL Class Reference
617
ccBlobParams
Parameters
lowTailPercent
The percentage of low tail pixels to discard before computing the
threshold.
highTailPercent
The percentage of pixels above which to discard high tail pixels
before computing the threshold.
threshPercent
The pixel value that lies threshPercent of the distance between
the low tail pixel value and the high tail pixel value is used as the
threshold value.
invert
If invert is true, then all pixels in image with values greater than or
equal to the computed threshold are set to 0; pixels with values
less than the threshold are set to 1. If invert is false, then all pixels
in image with values greater than or equal to the computed
threshold are set to 1; pixels with values less than the threshold
are set to 0.
Throws
ccBlobDefs::BadParams
Any percentage is not in the range 0 through 100, inclusive.
setSegmentationSoftThresh
void setSegmentationSoftThresh(c_UInt8 loThresh,
c_UInt8 hiThresh, c_UInt8 softness, bool invert=false);
void setSegmentationSoftThresh(c_Int32 lowTailPercent,
c_Int32 highTailPercent, c_Int32 lowThreshPercent,
c_Int32 highThreshPercent, c_UInt8 softness,
bool invert = false);
•
void setSegmentationSoftThresh(c_UInt8 loThresh,
c_UInt8 hiThresh, c_UInt8 softness, bool invert=false);
Sets this ccBlobParams to segment the input image using the supplied soft threshold
values.
Each pixel in the input image with a value below the low threshold is assigned a weight
of 0; each pixel in the input image with a value greater than or equal to the high threshold
is assigned a weight of softness+1. The range of pixel values between the low and high
threshold is divided into softness equally sized ranges. Pixels with values in each of
these ranges are assigned values between 1 and softness.
You can specify an invert flag to specify that pixels below the computed low threshold
are assigned a weight of softness+1 and pixels at or above the computed high threshold
are assigned a weight of 0.
618
CVL Class Reference
ccBlobParams
Parameters
loThresh
The low threshold. Pixels with values below loThresh are
assigned a value of 0.
hiThresh
The high threshold. Pixels with values greater than or equal to
hiThresh are assigned a value of softness+1.
softness
The number of intermediate pixel weights. The range of loThresh
to hiThresh is divided into softness ranges. Pixels in each range
receive a value equal to the number of the range in which they
are.
softness should be in the range [1, hiThresh - loThresh]. Zero can
be used, and is equivalent to hard thresholding with hiThresh.
Higher softness values provide more accurate results, but
processing may be slower than with a lower softness value.
invert
If invert is true, then pixels with values greater than or equal to the
high threshold are set to 0; pixels with values less than the low
threshold are set to softness+1. If invert is false, then pixels with
values greater than or equal to the high threshold are set to
softness+1; pixels with values less than the low threshold are set
to 0.
Throws
ccBlobDefs::BadParams
softness is equal to 255.
loThresh is greater than or equal to hiThresh.
softness is greater than (hiThresh minus loThresh).
•
void setSegmentationSoftThresh(c_Int32 lowTailPercent,
c_Int32 highTailPercent, c_Int32 lowThreshPercent,
c_Int32 highThreshPercent, c_UInt8 softness,
bool invert = false);
Sets this ccBlobParams to segment the input image using the supplied soft threshold
parameters. The specified percentage of low tail and high tail pixels are discarded, then
two threshold pixel values are computed by determining the pixel values which lie at the
specified percentages of the distance between the low tail pixel value and the high tail
pixel value.
Each pixel in the input image with a value below the computed low threshold is assigned
a weight of 0; each pixel in the input image with a value greater than or equal to the
computed high threshold is assigned a weight of softness+1. The range of pixel values
CVL Class Reference
619
ccBlobParams
between the computed low and computed high threshold is divided into softness
equally sized ranges. Pixels with values in each of these ranges are assigned values
between 1 and softness.
You can specify an invert flag to specify that pixels below the computed low threshold
are assigned a weight of softness+1 and pixels at or above the computed high threshold
are assigned a weight of 0.
Parameters
lowTailPercent
highTailPercent
The percentage of low tail pixels to discard before computing the
threshold.
The percentage of pixels above which to discard high tail pixels
before computing the threshold.
lowThreshPercent
The pixel value that lies lowThreshPercent of the distance
between the low tail pixel value and the high tail pixel value is
used as the computed low threshold value.
highThreshPercent
The pixel value that lies highThreshPercent of the distance
between the low tail pixel value and the high tail pixel value is
used as the computed high threshold value.
softness
The number of intermediate pixel weights. The range between
the computed low and high thresholds is divided into softness
ranges. Pixels in each range receive a value equal to the number
of the range in which they are.
softness should be in the range [1, hiThresh - loThresh], where
hiThresh and loThresh are the pixel values calculated from
lowThreshPercent and highThreshPercent. If you believe you
have images where these computed thresholds may lie close
together, use a small softness value such as 1, 2, or 3.
invert
If invert is true, then pixels with values greater than or equal to the
computed high threshold are set to 0; pixels with values less than
the computed low threshold are set to softness+1. If invert is
false, then pixels with values greater than or equal to the
computed high threshold are set to softness+1; pixels with values
less than the computed low threshold are set to 0.
Notes
lowTailPercent must be less than highTailPercent, lowThreshPercent must be less
than highTailPercent, and softness must be greater than or equal to 0.
620
CVL Class Reference
ccBlobParams
Throws
ccBlobDefs::BadParams
softness is equal to 255.
Any percentage is not in the range of 0 through 100 inclusive.
lowTailPercent plus highTailPercent is greater than 100.
lowThreshPercent is greater than highThreshPercent.
setSegmentationThreshImage
void setSegmentationThreshImage(
const cmStd vector<c_UInt8>& preMap,
const ccPelBuffer_const<c_UInt8>& threshImg,
const cmStd vector<c_UInt8>& postMap, c_UInt8 scaleVal);
Sets this ccBlobParams to segment the input image using the supplied threshold
image and threshold image parameters.
The supplied pixel map is applied to the input image, then each pixel in the threshold
image is subtracted from the corresponding pixel in the input image. A second pixel
map is applied to the results of this subtraction.
You specify a scaling value to indicate the pixel value in the resulting image that
represents a weight of 1.0. All pixels in the resulting image are interpreted on a linear
scale relative to the scaling value; no pixel in the image should have a value greater than
scaleVal.
Parameters
preMap
The pixel map to apply to the input image. Each pixel in the input
image is used as an index into preMap. The input pixel value is
replaced with the value from preMap.
preMap must be at least as large as the largest pixel value in the
input image.
threshImg
The threshold image. threshImg must have the same dimensions
as the input image. The value of each pixel in threshImg is
subtracted from the corresponding pixel in the input image with
the result clamped to 0. The image that results from this operation
is mapped using postMap.
postMap
The pixel map to apply to the result of the image subtraction.
Each pixel value that results from the subtraction of the threshImg
from the input image is used as an index into postMap. The pixel
value in the encoded image is the value found at that pixel value
index in postMap.
postMap must be at least as large as the largest difference in
pixel values between the input image and threshImg.
CVL Class Reference
621
ccBlobParams
scaleVal
The pixel value in the resulting image that represents a weight of
1.0. All pixels in the resulting image are interpreted on a linear
scale relative to scaleVal; no pixel in postMap should have a
value greater than scaleVal.
Notes
This function makes copies of preMap, thresh, and postMap. threshImg must be
bound and located and is not copied. Any change to the pixels in threshImg’s root
image will affect the segmentation.
Throws
ccBlobDefs::BadParams
scaleVal is equal to zero.
threshImg is unbound.
segmentationType
Segmentation segmentationType() const;
Returns the segmentation type of this ccBlobParams, one of the following values:
ccBlobParams::eNone
ccBlobParams::eMap
ccBlobParams::eHardThresh
ccBlobParams::eSoftThresh
ccBlobParams::eThreshImage
map
const cmStd vector<c_UInt8>& map() const;
If you called setSegmentationMap() to configure this ccBlobParams, this function
returns the pixel map you specified.
If you called setSegmentationThreshImage() to configure this ccBlobParams, this
function returns the pixel pre-map you specified.
Throws
ccBlobDefs::BadParams
Segmentation type is neither ccBlobParams::eMap nor
ccBlobParams::eThreshImage.
postMap
const cmStd vector<c_UInt8>& postMap() const;
If you called setSegmentationThreshImage() to configure this ccBlobParams, this
function returns the pixel post-map you specified.
622
CVL Class Reference
ccBlobParams
Throws
ccBlobDefs::BadParams
Segmentation type is not ccBlobParams::eThreshImage.
thresh
c_UInt8 thresh() const;
If you called setSegmentationHardThresh() to configure this ccBlobParams, this
function returns the threshold value.
If you called setSegmentationSoftThresh() to configure this ccBlobParams, this
function returns the low threshold value.
Throws
ccBlobDefs::BadParams
Segmentation type is neither ccBlobParams::eHardThresh nor
ccBlobParams::eSoftThresh.
hiThresh
c_UInt8 hiThresh() const;
If you called setSegmentationSoftThresh() to configure this ccBlobParams, this
function returns the high threshold value.
Throws
ccBlobDefs::BadParams
Segmentation type is not ccBlobParams::eSoftThresh.
invert
bool invert() const;
If you called setSegmentationSoftThresh() or setSegmentationHardThresh() to
configure this ccBlobParams, this function returns the value of the invert flag.
Throws
ccBlobDefs::BadParams
Segmentation type is neither ccBlobParams::eHardThresh nor
ccBlobParams::eSoftThresh.
softness
c_UInt8 softness() const;
If you called setSegmentationSoftThresh() to configure this ccBlobParams, this
function returns the softness value.
Throws
ccBlobDefs::BadParams
Segmentation type is not ccBlobParams::eSoftThresh.
CVL Class Reference
623
ccBlobParams
isThreshPercent
bool isThreshPercent() const;
If you called setSegmentationSoftThresh() or setSegmentationHardThresh() to
configure this ccBlobParams, this function returns true if you specified relative
(percentage) thresholds, false if you specified absolute (pixel value) thresholds.
Throws
ccBlobDefs::BadParams
Segmentation type is neither ccBlobParams::eHardThresh nor
ccBlobParams::eSoftThresh.
lowTailPercent
c_Int32 lowTailPercent() const;
If you called setSegmentationSoftThresh() or setSegmentationHardThresh() to
configure this ccBlobParams and specified relative (percentage) thresholds, this
function returns the low tail percentage value you specified.
Throws
ccBlobDefs::BadParams
Segmentation type is neither ccBlobParams::eHardThresh nor
ccBlobParams::eSoftThresh.
Segmentation was not done with percentages.
hiTailPercent
c_Int32 hiTailPercent() const;
If you called setSegmentationSoftThresh() or setSegmentationHardThresh() to
configure this ccBlobParams and you specified relative (percentage) thresholds, this
function returns the high tail percentage value you specified.
Throws
ccBlobDefs::BadParams
Segmentation type is neither ccBlobParams::eHardThresh nor
ccBlobParams::eSoftThresh.
Segmentation was not done with percentages.
threshImage
const ccPelBuffer_const<c_UInt8>& threshImage() const;
If you called setSegmentationThreshImage() to configure this ccBlobParams, this
function returns the threshold image you specified.
Throws
ccBlobDefs::BadParams
Segmentation type is not ccBlobParams::eThreshImage.
624
CVL Class Reference
ccBlobParams
scaleVal
c_UInt8 scaleVal() const;
If you called setSegmentationNone(), setSegmentationMap or
setSegmentationThreshImage() to configure this ccBlobParams, this function returns
the scaling value.
keepRLE
bool keepRLE() const;
void keepRLE(bool keep);
•
bool keepRLE() const;
Returns true if this ccBlobParams is configured to retain the ccRLEBuffer created
when the input image is segmented.
•
void keepRLE(bool keep);
Configures this ccBlobParams to either retain or discard the ccRLEBuffer created
when the input image is segmented.
Parameters
keep
mask
If true, this ccBlobParams will retain a copy of the ccRLEBuffer,
if false the ccRLEBuffer will be discarded.
const ccRLEBuffer& mask() const;
void mask(const ccRLEBuffer& m);
•
const ccRLEBuffer& mask() const;
Returns a reference to a ccRLEBuffer that contains the mask image that will be applied
to the input image during segmentation.
If no mask image has been specified for this ccBlobParams, calling
mask().isDegenerate() returns true.
•
void mask(const ccRLEBuffer& theMask);
Specifies the mask to be applied to the input image before the image is segmented.
Only pixels in the input image that correspond to nonzero pixels in theMask are included
in the image to be segmented.
Parameters
theMask
CVL Class Reference
The mask image. theMask must have the same dimensions as the
input image.
625
ccBlobParams
keepMasked
bool keepMasked() const;
void keepMasked(bool keep);
•
bool keepMasked() const;
Returns true if this ccBlobParams is configured to retain the ccRLEBuffer created by
applying a mask image before the input image is segmented.
•
void keepMasked(bool keep);
Configures this ccBlobParams to either retain or discard the ccRLEBuffer image
created by applying a mask image before the input image is segmented.
Parameters
keep
morph
If true, this ccBlobParams will retain a copy of the masked
image, if false the masked image will be discarded.
const cmStd vector<ceBlobParamsMorphOp>& morph() const;
void morph(const cmStd vector<ceBlobParamsMorphOp>& mOps);
•
const cmStd vector<ceBlobParamsMorphOp>& morph() const;
Returns a vector of ccBlobParams::ceBlobParamsMophOp that specifies the
morphological operations that will be applied to the input image. Each element of the
vector will have one of the following values:
ccBlobParams::eMinH
ccBlobParams::eMinV
ccBlobParams::eMinS
ccBlobParams::eMaxH
ccBlobParams::eMaxV
ccBlobParams::eMaxS
ccBlobParams::eMinMaxH
ccBlobParams::eMinMaxV
ccBlobParams::eMinMaxS
ccBlobParams::eMaxMinH
ccBlobParams::eMaxMinV
ccBlobParams::eMaxMinS
If no morphological operations are specified, the returned vector has a length of 0. For
more information, see the description of ccBlobParams::ceBlobParamsMophOp.
626
CVL Class Reference
ccBlobParams
•
void morph(const cmStd vector<ceBlobParamsMorphOp>& mOps);
Specifies the morphological operations to be applied to the input image. You specify the
morphological operations by supplying a vector of
ccBlobParams::ceBlobParamsMophOp. Each element of the vector must have one of
the following values:
ccBlobParams::eMinH
ccBlobParams::eMinV
ccBlobParams::eMinS
ccBlobParams::eMaxH
ccBlobParams::eMaxV
ccBlobParams::eMaxS
ccBlobParams::eMinMaxH
ccBlobParams::eMinMaxV
ccBlobParams::eMinMaxS
ccBlobParams::eMaxMinH
ccBlobParams::eMaxMinV
ccBlobParams::eMaxMinS
To specify no morphological operations, supply a vector with a length of 0.
Parameters
mOps
keepMorphed
The morphological operations to perform.
bool keepMorphed() const;
void keepMorphed(bool keep);
•
bool keepMorphed() const;
Returns true if this ccBlobParams is configured to retain the ccRLEBuffer created
when the specified morphological operations are applied to the input image.
•
void keepMorphed(bool keep);
Configures this ccBlobParams to either retain or discard the ccRLEBuffer created
when the specified morphological operations are applied to the input image.
Parameters
keep
CVL Class Reference
If true, this ccBlobParams will retain a copy of the image
produced by the morphological operations, if false the image will
be discarded.
627
ccBlobParams
connectivityType
ccBlobSceneDescription::Analysis connectivityType() const;
void connectivityType(
ccBlobSceneDescription::Analysis cType);
•
ccBlobSceneDescription::Analysis connectivityType() const;
Returns the connectivity type configured for this ccBlobParams. The connectivity type
is one of the following values:
ccBlobSceneDescription::eGreyScale
ccBlobSceneDescription::eLabelled
ccBlobSceneDescription::eWholeImageGreyScale
•
void connectivityType(
ccBlobSceneDescription::Analysis cType);
Sets the connectivity type for this ccBlobParams. The connectivity type must be one of
the following values:
ccBlobSceneDescription::eGreyScale
ccBlobSceneDescription::eLabelled
ccBlobSceneDescription::eWholeImageGreyScale
Parameters
cType
The connectivity type to set.
connectivityCleanup
ccBlobSceneDescription::ConnectCleanup
connectivityCleanup() const;
void connectivityCleanup(
ccBlobSceneDescription::ConnectCleanup cType);
•
ccBlobSceneDescription::ConnectCleanup
connectivityCleanup() const;
Returns the connectivity cleanup type configured for this ccBlobParams. The
connectivity cleanup type is one of the following values:
ccBlobSceneDescription::eNone
ccBlobSceneDescription::ePrune
ccBlobSceneDescription::eFill
628
CVL Class Reference
ccBlobParams
•
void connectivityCleanup(
ccBlobSceneDescription::ConnectCleanup cType);
Sets the connectivity cleanup type for this ccBlobParams. The connectivity cleanup
type must be one of the following values:
ccBlobSceneDescription::eNone
ccBlobSceneDescription::ePrune
ccBlobSceneDescription::eFill
Parameters
cType
The connectivity cleanup type to set.
connectivityMinPels
c_Int32 connectivityMinPels() const;
void connectivityMinPels(c_Int32 min);
Specifies the minimum size, in pixels, of features returned by cfBlobAnalysis() when
the ccBlobSceneDescription::ConnectCleanup value in effect is not eNone.
•
c_Int32 connectivityMinPels() const;
Returns the minimum feature size configured for this ccBlobParams.
•
void connectivityMinPels(c_Int32 min);
Sets the minimum feature size for this ccBlobParams.
Parameters
min
The minimum feature size, in pixels.
Throws
ccBlobDefs::BadParams
min is less than zero.
useMaskForInterior
bool useMaskForInterior() const;
void useMaskForInterior(bool useMaskForInterior);
This flag determines whether the image mask contained in this object will be used
during the computation of ccBlob::isInterior(). If this flag is true and the mask is not
degenerate, the mask is used. Otherwise, the mask is not used.
CVL Class Reference
629
ccBlobParams
•
bool useMaskForInterior() const;
Returns the current useMaskForInterior flag, true or false.
•
void useMaskForInterior(bool useMaskForInterior);
Sets the useMaskForInterior flag, true or false.
Parameters
useMaskForInterior
The new flag.
630
CVL Class Reference
ccBlobResults
#include <ch_cvl/blobtool.h>
class ccBlobResults: public ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class contains the results from a blob analysis.
Constructors/Destructors
ccBlobResults
ccBlobResults();
~ccBlobResults();
•
ccBlobResults();
Constructs a ccBlobResults with the following default values:
•
All timing information set to 0.
•
All intermediate images (RLE image, masked image, morphology output image) set
to degenerate images.
•
Blob scene description set to NULL.
Operators
operator=
ccBlobResults& operator= (const ccBlobResults& rhs);
Assignment.
Public Member Functions
connectedBlobs
ccBlobSceneDescription * connectedBlobs() const;
Returns a pointer to the ccBlobSceneDescription produced by blob analysis.
CVL Class Reference
631
ccBlobResults
Notes
The result structure retains ownership of the BSD object.
relinquishBSDOwnership
void relinquishBSDOwnership();
Sets this ccBlobResults’s internal ccBlobSceneDescription pointer to NULL. If you
call this function, you must have already called
ccBlobSceneDescription::connectedBlobs(), and you are responsible for deleting
the ccBlobSceneDescription created by the call.
If you call this function without having called
ccBlobSceneDescription::connectedBlobs(), you will not be able to obtain the results
of the blob analysis, and your application will be unable to recover the memory allocated
for the ccBlobSceneDescription.
RLETime
double RLETime() const;
Returns the amount of time, in seconds, required to encode the input image as a
ccRLEBuffer.
rle
const ccRLEBuffer& rle() const;
Returns a ccRLEBuffer that contains the image produced during the segmentation step
of this blob analysis.
maskTime
double maskTime() const;
Returns the amount of time, in seconds, required to apply the mask image to the input
image.
masked
const ccRLEBuffer& masked() const;
Returns a ccRLEBuffer that contains the image produced by applying the mask image.
morphTime
double morphTime() const;
Returns the amount of time, in seconds, required to apply the specified morphological
operations to the input image.
morphed
const ccRLEBuffer& morphed() const;
Returns a ccRLEBuffer that contains the image produced by applying the
morphological operations.
632
CVL Class Reference
ccBlobResults
connectTime
double connectTime() const;
Returns the amount of time, in seconds, required to perform the connectivity analysis.
CVL Class Reference
633
ccBlobResults
634
CVL Class Reference
ccBlobSceneDescription
#include <ch_cvl/blobdesc.h>
class ccBlobSceneDescription: public ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class contains a ccBlob for each feature that was identified by the blob analysis.
Information about individual ccBlobs within a ccBlobSceneDescription can be
obtained using the ccBlob member functions.
Constructors/Destructors
ccBlobSceneDescription
ccBlobSceneDescription();
~ccBlobSceneDescription();
ccBlobSceneDescription(const ccBlobSceneDescription& rhs);
•
ccBlobSceneDescription();
Constructs an empty ccBlobSceneDescription.
•
~ccBlobSceneDescription();
Destroys this ccBlobSceneDescription and all of its contained ccBlob objects.
CVL Class Reference
635
ccBlobSceneDescription
Enumerations
Analysis
enum Analysis;
This enumeration defines the types of connectivity analysis that can be performed on an
image.
Value
Meaning
eGreyScale
Connected object pixels are grouped
and analyzed as individual features
(blobs and holes).
Blobs (made up of object pixels) are
8-connected. Holes (made up of
background pixels) are 4-connected.
eLabelled
All pixels with the same label value are
connected into individual features. No
concept of object and background.
All features are 6-connected.
eWholeImageGreyScale
All of the object pixels in the image are
analyzed as a single object, regardless
of whether or how they are connected to
each other.
No connectivity is performed.
ConnectCleanup
enum ConnectCleanup;
This enumeration defines the types of connectivity cleanup that can be performed
during blob analysis.
636
Value
Meaning
eNone
No connectivity cleanup.
CVL Class Reference
ccBlobSceneDescription
SortOrder
Value
Meaning
ePrune
Features below a specified size
threshold are not counted as part of the
topology of the blob scene. The size and
shape measures of features that contain
pruned features are reported taking into
account the area of the pruned features.
eFill
Features below a specified size
threshold are filled in with the pixel value
of the surrounding feature.
enum SortOrder;
This enumeration defines the available sort orders. You can specify the sort order and
measure that determines the order in which features are returned to you.
Value
Meaning
eDescending
Features are returned from largest to
smallest value.
eAscending
Features are returned from smallest to
largest value.
Public Member Functions
isDegenerate
bool isDegenerate() const;
Returns true if this ccBlobSceneDescription was default constructed.
connectivityKind
Analysis connectivityKind() const;
Returns the type of connectivity analysis used to generate the information in this
ccBlobSceneDescription. Returns one of the following values:
ccBlobSceneDescription::eGreyScale
ccBlobSceneDescription::eLabelled
ccBlobSceneDescription::eWholeImageGreyScale
CVL Class Reference
637
ccBlobSceneDescription
scaleVal
c_UInt8 scaleVal() const;
Returns the scaling value used to perform the grey-scale connectivity analysis that
produced this ccBlobSceneDescription.
cleanupKind
ConnectCleanup cleanupKind() const;
Returns the type of connectivity cleanup performed to generate the information in this
ccBlobSceneDescription. Returns one of the following values:
ccBlobSceneDescription::eNone
ccBlobSceneDescription::ePrune
ccBlobSceneDescription::eFill
minPels
c_Int32 minPels() const;
Returns the minimum feature size applied during the connectivity cleanup operation
performed to generate the information in this ccBlobSceneDescription.
sceneWindow
ccPelRect sceneWindow() const;
Returns the dimensions of the ccRLEBuffer upon which connectivity analysis was
performed.
clientFromImageXformBase
cc2XformBasePtrh_const clientFromImageXformBase() const;
void clientFromImageXformBase(
const cc2XformBasePtrh_const& xform, bool copy = true);
void clientFromImageXformBase(const cc2XformBase& xform);
•
cc2XformBasePtrh_const clientFromImageXformBase() const;
Returns the transformation object that it is suitable for transforming the ccRLEBuffer
coordinates to the client’s reference coordinates.
•
void clientFromImageXformBase(
const cc2XformBasePtrh_const& xform, bool copy = true);
Sets this ccBlobSceneDescription’s transformation object suitable for transforming the
ccRLEBuffer coordinates to the client’s reference coordinates.
638
CVL Class Reference
ccBlobSceneDescription
Parameters
xform
copy
A pointer handle to the transformation object.
If true, this window is assigned a copy of xform. If false, this
window is assigned a reference to xform.
Notes
If copy is false, you must ensure that xform will not change during this
ccBlobSceneDescription’s lifetime.
•
void clientFromImageXformBase(const cc2XformBase& xform);
Sets this window’s transformation object suitable for transforming the ccRLEBuffer
coordinates to the client’s reference coordinates.
Parameters
xform
A transformation object.
Notes
This setter always makes a copy of xform.
Both imageFromClientXformBase() and clientFromImageXformBase() setters
set the same object. Use one or the other, but not both. The deprecated functions
imageFromClientXform() and clientFromImageXform() setters also operate on
the same object.
imageFromClientXformBase
cc2XformBasePtrh_const imageFromClientXformBase() const;
void imageFromClientXformBase(
const cc2XformBasePtrh_const& xform, bool copy = true);
void imageFromClientXformBase(const cc2XformBase& xform);
•
cc2XformBasePtrh_const imageFromClientXformBase() const;
Returns the transformation object suitable for transforming the client’s reference
coordinates to the ccRLEBuffer’s coordinates.
•
void imageFromClientXformBase(
const cc2XformBasePtrh_const& xform, bool copy = true);
Sets this ccBlobSceneDescription’s transformation object suitable for transforming the
client’s reference coordinates to the ccRLEBuffer’s coordinates.
CVL Class Reference
639
ccBlobSceneDescription
Parameters
xform
copy
A pointer handle to the transformation object.
If true, this window is assigned a copy of xform. If false, this
window is assigned a reference to xform.
Notes
If copy is false, you must ensure that xform will not change during this window’s
lifetime.
•
void imageFromClientXformBase(const cc2XformBase& xform);
Sets this ccBlobSceneDescription’s transformation object suitable for transforming the
client’s reference coordinates to the ccRLEBuffer’s coordinates.
Parameters
xform
A transformation object.
Notes
This setter always makes a copy of xform.
Both imageFromClientXformBase() and clientFromImageXformBase() setters
set the same object. Use one or the other, but not both. The deprecated functions
imageFromClientXform() and clientFromImageXform() setters also operate on
the same object.
imageFromClientXform
cc2Xform imageFromClientXform() const;
void imageFromClientXform(
const cc2Xform& imageFromClient);
•
cc2Xform imageFromClientXform() const;
Returns a cc2Xform that describes the transformation between the client coordinate
system associated with the ccRLEBuffer upon which connectivity analysis was
performed and its image coordinate system.
Notes
This function is deprecated; use imageFromClientXformBase() instead.
640
CVL Class Reference
ccBlobSceneDescription
•
void imageFromClientXform(
const cc2Xform& imageFromClient);
Sets the cc2Xform that describes the transformation between the client coordinate
system associated with the ccRLEBuffer upon which connectivity analysis was
performed and its image coordinate system.
Setting this cc2Xform also sets the cc2Xform that describes the transformation
between image coordinates and client coordinates.
Parameters
imageFromClient The transformation to set.
Notes
This function is deprecated; use imageFromClientXformBase() instead.
clientFromImageXform
cc2Xform clientFromImageXform() const;
void clientFromImageXform(
const cc2Xform& clientFromImage);
•
cc2Xform clientFromImageXform() const;
Returns a cc2Xform that describes the transformation between the image coordinate
system associated with the ccRLEBuffer upon which connectivity analysis was
performed and its client coordinate system.
Notes
This function is deprecated; use clientFromImageXformBase() instead.
•
void clientFromImageXform(
const cc2Xform& clientFromImage);
Sets the cc2Xform that describes the transformation between the image coordinate
system associated with the ccRLEBuffer upon which connectivity analysis was
performed and its client coordinate system.
Setting this cc2Xform also sets the cc2Xform that describes the transformation
between client coordinates and image coordinates.
Parameters
clientFromImage The transformation to set.
Notes
This function is deprecated; use clientFromImageXformBase() instead.
CVL Class Reference
641
ccBlobSceneDescription
numBlobs
c_Int32 numBlobs(bool filtered = true) const;
Returns the number of features in this ccBlobSceneDescription. In the case of
grey-scale connectivity, this includes both blobs and holes.
Parameters
filtered
getBlob
If filtered is true, only features that meet the current filtering
criteria are included in the returned count.
const ccBlob* getBlob(c_Int32 id) const;
Returns a pointer to the ccBlob that has the specified ID.
Parameters
id
preCompute
The ID of the ccBlob to return. id must be between 1 and the
number of features in this ccBlobSceneDescription, inclusive.
void preCompute(ccBlob::Measure theMeasure,
bool filtered = true) const;
Pre-computes the specified measure for all features in this ccBlobSceneDescription.
Ordinarily, a particular measure for a particular feature is not computed until you
specifically request it, or until the measure is used as a sorting or filtering criterion. You
call this function to force the computation of a particular measure for all of the features
in this ccBlobSceneDescription.
Parameters
theMeasure
The blob measure to pre-compute. theMeasure must be one of
the following values:
ccBlob::eLabel
ccBlob::eArea
ccBlob::eNumSteps
ccBlob::ePerimeter
ccBlob::eNumChildren
ccBlob::eCenterMassX
ccBlob::eCenterMassY
ccBlob::eInertiaX
ccBlob::eInertiaY
ccBlob::eInertiaMin
ccBlob::eInertiaMax
ccBlob::eElongation
ccBlob::eAngle
ccBlob::eAcircularity
ccBlob::eAcircularityRms
ccBlob::eImageBoundCenterX
642
CVL Class Reference
ccBlobSceneDescription
ccBlob::eImageBoundCenterY
ccBlob::eImageBoundMinX
ccBlob::eImageBoundMaxX
ccBlob::eImageBoundMinY
ccBlob::eImageBoundMaxY
ccBlob::eImageBoundWidth
ccBlob::eImageBoundHeight
ccBlob::eImageBoundAspect
ccBlob::eMedianX
ccBlob::eMedianY
ccBlob::eBoundCenterX
ccBlob::eBoundCenterY
ccBlob::eBoundMinX
ccBlob::eBoundMaxX
ccBlob::eBoundMinY
ccBlob::eBoundMaxY
ccBlob::eBoundWidth
ccBlob::eBoundHeight
ccBlob::eBoundAspect
ccBlob::eBoundPrincipalMinX
ccBlob::eBoundPrincipalMaxX
ccBlob::eBoundPrincipalMinY
ccBlob::eBoundPrincipalMaxY
ccBlob::eBoundPrincipalWidth
ccBlob::eBoundPrincipalHeight
ccBlob::eBoundPrincipalAspect
filtered
setFilter
If filtered is true, then theMeasure is pre-computed only for
features that meet the current filtering criteria.
void setFilter(ccBlob::Measure theMeasure, double loLimit,
double hiLimit, bool invert=false);
Sets a filtering criterion for the specified measure. Only features which meet the
specified criterion will be considered and/or returned by certain ccBlob and
ccBlobSceneDescription member functions that, optionally, take filtering into account.
You can specify only one filter per measure. If you specify a filter for a measure which
already has a filter, the error ccBlobSceneDescription:DuplicateFilter is thrown.
You can specify any number of filters for a single ccBlobSceneDescription. Each filter
you specify is assigned an index value, starting with 0.
CVL Class Reference
643
ccBlobSceneDescription
Parameters
theMeasure
The measure on which to apply a filter. theMeasure must be one
of the following values:
ccBlob::eLabel
ccBlob::eArea
ccBlob::eNumSteps
ccBlob::ePerimeter
ccBlob::eNumChildren
ccBlob::eCenterMassX
ccBlob::eCenterMassY
ccBlob::eInertiaX
ccBlob::eInertiaY
ccBlob::eInertiaMin
ccBlob::eInertiaMax
ccBlob::eElongation
ccBlob::eAngle
ccBlob::eAcircularity
ccBlob::eAcircularityRms
ccBlob::eImageBoundCenterX
ccBlob::eImageBoundCenterY
ccBlob::eImageBoundMinX
ccBlob::eImageBoundMaxX
ccBlob::eImageBoundMinY
ccBlob::eImageBoundMaxY
ccBlob::eImageBoundWidth
ccBlob::eImageBoundHeight
ccBlob::eImageBoundAspect
ccBlob::eMedianX
ccBlob::eMedianY
ccBlob::eBoundCenterX
ccBlob::eBoundCenterY
ccBlob::eBoundMinX
ccBlob::eBoundMaxX
ccBlob::eBoundMinY
ccBlob::eBoundMaxY
ccBlob::eBoundWidth
ccBlob::eBoundHeight
ccBlob::eBoundAspect
ccBlob::eBoundPrincipalMinX
ccBlob::eBoundPrincipalMaxX
ccBlob::eBoundPrincipalMinY
ccBlob::eBoundPrincipalMaxY
ccBlob::eBoundPrincipalWidth
ccBlob::eBoundPrincipalHeight
ccBlob::eBoundPrincipalAspect
644
CVL Class Reference
ccBlobSceneDescription
loLimit
The low limit for the filter. Only features with values for the
specified measure that are greater than or equal to loLimit are
returned.
hiLimit
The high limit for the filter. Only features with values for the
specified measure that are less than or equal to hiLimit are
returned.
invert
If invert is false (the default), then only features where the value
of theMeasure is between loLimit and hiLimit are returned. If
invert is true, then only features where the value of theMeasure is
less than loLimit or greater than hiLimit are returned.
Throws
ccBlobSceneDescription::DuplicateFilter
You have specified a measure for which there already is a filter.
getFilter
bool getFilter(ccBlob::Measure theMeasure, double& loLimit,
double& hiLimit, bool& invert) const;
void getFilter(c_Int32 index, ccBlob::Measure& theMeasure,
double& loLimit, double& hiLimit, bool& invert) const;
•
bool getFilter(ccBlob::Measure theMeasure, double& loLimit,
double& hiLimit, bool& invert) const;
Gets the currently specified filtering criteria for the specified measure.
Parameters
theMeasure
The measure about which to obtain filter information. theMeasure
must be one of the following values:
ccBlob::eLabel
ccBlob::eArea
ccBlob::eNumSteps
ccBlob::ePerimeter
ccBlob::eNumChildren
ccBlob::eCenterMassX
ccBlob::eCenterMassY
ccBlob::eInertiaX
ccBlob::eInertiaY
ccBlob::eInertiaMin
ccBlob::eInertiaMax
ccBlob::eElongation
ccBlob::eAngle
ccBlob::eAcircularity
ccBlob::eAcircularityRms
CVL Class Reference
645
ccBlobSceneDescription
ccBlob::eImageBoundCenterX
ccBlob::eImageBoundCenterY
ccBlob::eImageBoundMinX
ccBlob::eImageBoundMaxX
ccBlob::eImageBoundMinY
ccBlob::eImageBoundMaxY
ccBlob::eImageBoundWidth
ccBlob::eImageBoundHeight
ccBlob::eImageBoundAspect
ccBlob::eMedianX
ccBlob::eMedianY
ccBlob::eBoundCenterX
ccBlob::eBoundCenterY
ccBlob::eBoundMinX
ccBlob::eBoundMaxX
ccBlob::eBoundMinY
ccBlob::eBoundMaxY
ccBlob::eBoundWidth
ccBlob::eBoundHeight
ccBlob::eBoundAspect
ccBlob::eBoundPrincipalMinX
ccBlob::eBoundPrincipalMaxX
ccBlob::eBoundPrincipalMinY
ccBlob::eBoundPrincipalMaxY
ccBlob::eBoundPrincipalWidth
ccBlob::eBoundPrincipalHeight
ccBlob::eBoundPrincipalAspect
•
loLimit
A reference to a double into which the low limit for the filter is
written.
hiLimit
A reference to a double into which the high limit for the filter is
written.
invert
A bool into which the value of the invert flag is written.
void getFilter(c_Int32 index, ccBlob::Measure& theMeasure,
double& loLimit, double& hiLimit, bool& invert) const;
Gets the filtering criteria for the specified filter. As you apply filters to a
ccBlobSceneDescription, the filters are assigned an index value, starting with 0 for the
first filter you apply. This function lets you obtain information about a filter based on its
index value.
646
CVL Class Reference
ccBlobSceneDescription
Parameters
index
unSetFilter
The index of the filter. This value must be greater than or equal to
0 and less than or equal to the number of filters.
theMeasure
A reference to a ccBlob::Measure into which the measure
associated with this filter is written.
loLimit
A reference to a double into which the low limit for the filter is
written.
hiLimit
A reference to a double into which the high limit for the filter is
written.
invert
A bool into which the value of the invert flag is written.
void unSetFilter(ccBlob::Measure theMeasure);
Clears the filter associated with the specified measure. The indices of other filters may
change as a result of calling this function.
Parameters
theMeasure
The measure to clear. theMeasure must be one of the following
values:
ccBlob::eLabel
ccBlob::eArea
ccBlob::eNumSteps
ccBlob::ePerimeter
ccBlob::eNumChildren
ccBlob::eCenterMassX
ccBlob::eCenterMassY
ccBlob::eInertiaX
ccBlob::eInertiaY
ccBlob::eInertiaMin
ccBlob::eInertiaMax
ccBlob::eElongation
ccBlob::eAngle
ccBlob::eAcircularity
ccBlob::eAcircularityRms
ccBlob::eImageBoundCenterX
ccBlob::eImageBoundCenterY
ccBlob::eImageBoundMinX
ccBlob::eImageBoundMaxX
ccBlob::eImageBoundMinY
ccBlob::eImageBoundMaxY
ccBlob::eImageBoundWidth
ccBlob::eImageBoundHeight
CVL Class Reference
647
ccBlobSceneDescription
ccBlob::eImageBoundAspect
ccBlob::eMedianX
ccBlob::eMedianY
ccBlob::eBoundCenterX
ccBlob::eBoundCenterY
ccBlob::eBoundMinX
ccBlob::eBoundMaxX
ccBlob::eBoundMinY
ccBlob::eBoundMaxY
ccBlob::eBoundWidth
ccBlob::eBoundHeight
ccBlob::eBoundAspect
ccBlob::eBoundPrincipalMinX
ccBlob::eBoundPrincipalMaxX
ccBlob::eBoundPrincipalMinY
ccBlob::eBoundPrincipalMaxY
ccBlob::eBoundPrincipalWidth
ccBlob::eBoundPrincipalHeight
ccBlob::eBoundPrincipalAspect
clearFilters
void clearFilters();
Clears all filters associated with this ccBlobSceneDescription.
numFilters
c_Int32 numFilters() const;
Returns the number of filters applied to this ccBlobSceneDescription.
setSort
void setSort(ccBlob::Measure theMeasure,
SortOrder theOrder);
Sets the sort order for this ccBlobSceneDescription. The sort order controls the order
in which individual ccBlobs are returned.
Parameters
theMeasure
The measure upon which to sort the features. theMeasure must
be one of the following values:
ccBlob::eLabel
ccBlob::eArea
ccBlob::eNumSteps
ccBlob::ePerimeter
ccBlob::eNumChildren
ccBlob::eCenterMassX
ccBlob::eCenterMassY
648
CVL Class Reference
ccBlobSceneDescription
ccBlob::eInertiaX
ccBlob::eInertiaY
ccBlob::eInertiaMin
ccBlob::eInertiaMax
ccBlob::eElongation
ccBlob::eAngle
ccBlob::eAcircularity
ccBlob::eAcircularityRms
ccBlob::eImageBoundCenterX
ccBlob::eImageBoundCenterY
ccBlob::eImageBoundMinX
ccBlob::eImageBoundMaxX
ccBlob::eImageBoundMinY
ccBlob::eImageBoundMaxY
ccBlob::eImageBoundWidth
ccBlob::eImageBoundHeight
ccBlob::eImageBoundAspect
ccBlob::eMedianX
ccBlob::eMedianY
ccBlob::eBoundCenterX
ccBlob::eBoundCenterY
ccBlob::eBoundMinX
ccBlob::eBoundMaxX
ccBlob::eBoundMinY
ccBlob::eBoundMaxY
ccBlob::eBoundWidth
ccBlob::eBoundHeight
ccBlob::eBoundAspect
ccBlob::eBoundPrincipalMinX
ccBlob::eBoundPrincipalMaxX
ccBlob::eBoundPrincipalMinY
ccBlob::eBoundPrincipalMaxY
ccBlob::eBoundPrincipalWidth
ccBlob::eBoundPrincipalHeight
ccBlob::eBoundPrincipalAspect
theOrder
The order in which to sort the features. theOrder must be one of
the following values:
ccBlobSceneDescription::eAscending
ccBlobSceneDescription::eDescending
CVL Class Reference
649
ccBlobSceneDescription
getSort
bool getSort(ccBlob::Measure& theMeasure,
SortOrder& theOrder) const;
Returns true if a call to setSort() has been made to enable sorting for this
ccBlobSceneDescription. Otherwise the function returns false. If the function returns
true, the current sort order and sort measure are placed in theOrder and theMeasure.
Parameters
theMeasure
theOrder
disableSort
A reference to a ccBlob::Measure into which is written the
measure upon which the features in this
ccBlobSceneDescription are sorted.
A reference to a ccBlobSceneDescription::SortOrder into
which the sort order is written.
void disableSort();
Disables sorting for this ccBlobSceneDescription. If sorting is disabled, then features
are returned in an unspecified order and getSort() returns false.
Calling this function is the only way to prevent the Blob tool from sorting features. If you
have never made a call to setSort(), features are sorted by area. If you call clearSort(),
features will be sorted using the measure supplied to the most recent call to setSort(),
or by area if no call to setSort() has been made.
Calling this function if sorting is already disabled has no effect.
clearSort
void clearSort();
Calling this function causes getSort() to return false, but it does not actually disable the
sorting of features. To disable the sorting of features, use disableSort().
If you call this function, features will still be sorted using the measure supplied to the
most recent call to setSort(). If no calls have been made to setSort(), then the features
are sorted by area.
This function is present for backward compatibility only.
firstTop
const ccBlob* firstTop(bool filtered = true) const;
Returns a pointer to a ccBlob representing the first top-level feature in this
ccBlobSceneDescription. You can specify that only features meeting the current
filtering criteria be returned by this function.
650
CVL Class Reference
ccBlobSceneDescription
Parameters
filtered
lastTop
If true, only features that meet the current filtering criteria are
returned, and features are sorted according to the current sort
criteria. If false, no filtering or sorting is performed.
const ccBlob* lastTop(bool filtered = true) const;
Returns a pointer to a ccBlob representing the last top-level feature in this
ccBlobSceneDescription. You can specify that only features meeting the current
filtering criteria be returned by this function.
Parameters
filtered
allBlobs
If true, only features that meet the current filtering criteria are
returned, and features are sorted according to the current sort
criteria. If false, no filtering or sorting is performed.
cmStd vector<const ccBlob*> allBlobs(bool filtered = true)
const;
Returns a vector of pointers to ccBlob. The vector contains pointers to all the features
in this ccBlobSceneDescription, in the current sort order. You can specify that only
features meeting the current filtering criteria be returned by this function.
Parameters
filtered
If true, only features that meet the current filtering criteria are
returned, and features are sorted according to the current sort
criteria. If false, no filtering or sorting is performed.
Notes
There is no relationship between a feature’s ID and its position in the vector returned
by allBlobs().
makeImage
ccPelBuffer<c_UInt8> makeImage(bool filtered = true,
c_UInt8 background=0) const;
Returns a ccPelBuffer<c_UInt8> that contains an image of this
ccBlobSceneDescription.
Parameters
filtered
background
CVL Class Reference
If true, only features that meet the current filtering criteria are
returned, and features are sorted according to the current sort
criteria. If false, no filtering or sorting is performed.
Specifies the pixel value for the background of the returned
image.
651
ccBlobSceneDescription
extremaExcludeArea
void extremaExcludeArea(double clientArea);
double extremaExcludeArea(bool& isClient, bool& isPercent)
const;
•
void extremaExcludeArea(double clientArea);
Sets the amount of each feature to exclude when computing measures related to the
arbitrarily aligned bounding box.
Parameters
clientArea
•
The amount of the feature to exclude in terms of client coordinate
system-sized pixels.
double extremaExcludeArea(bool& isClient, bool& isPercent)
const;
Returns the amount of each feature that this ccBlobSceneDescription is currently
configured to exclude when computing the arbitrarily aligned bounding box.
Parameters
isClient
isPercent
A reference to a bool into which true is written if the returned
value is given in client coordinate-sized pixels. If isClient is set to
false, then the return value is given in image coordinate-sized
pixels.
A reference to a bool into which true is written if the returned
value is given in as a percentage of the area of the feature. If
isPercent is set to false, the return value is given in terms of pixel
area.
extremaExcludeAreaPels
void extremaExcludeAreaPels(double pelArea);
Sets the amount of each feature to exclude when computing the arbitrarily aligned
bounding box.
Parameters
clientArea
652
The amount of the feature to exclude in terms of image coordinate
system-sized pixels.
CVL Class Reference
ccBlobSceneDescription
extremaExcludeAreaPercent
void extremaExcludeAreaPercent(double percent);
Sets the amount of each feature to exclude when computing the arbitrarily aligned
bounding box.
Parameters
clientArea
extremaAngle
The amount of the feature to exclude in terms of the percentage
of pixels to exclude.
ccRadian extremaAngle() const;
void extremaAngle(const ccRadian& angle);
•
ccRadian extremaAngle() const;
Returns the angle at which various measures are computed, relative to the client
coordinate system’s x-axis, in radians, for all features in this ccBlobSceneDescription.
•
void extremaAngle(const ccRadian& angle);
Sets the angle at which the bounding box is computed, relative to the client coordinate
system’s x-axis, in radians, for all features in this ccBlobSceneDescription. The
following diagram illustrates the effect of specifying an angle value:
Image coordinate system
Specified angle
No angle specified
Parameters
angle
CVL Class Reference
Angle specified
The angle at which to compute bounding boxes and bounding
box-related measures for features in this
ccBlobSceneDescription.
653
ccBlobSceneDescription
draw
void draw(ccGraphicList& graphList,
c_UInt32 drawMode = ccBlobDefs::eDrawStandard,
bool filtered=true) const;
Appends result graphics for all of the features in this ccBlobSceneDescription to the
supplied ccGraphicList. To append result graphics for only those features that meet the
current filtering criteria, specify true for the filtered argument.
The graphics are drawn in client coordinates.
Parameters
graphList
drawMode
The graphics list to append the graphics to.
The drawing mode to use. drawMode must be composed by
ORing together one or more of the following values:
ccBlobDefs::eDrawImageCenterOfMass
ccBlobDefs::eDrawCenterOfMass
ccBlobDefs::eDrawLabel
ccBlobDefs::eDrawImageBoundingBox
ccBlobDefs::eDrawBoundingBox
ccBlobDefs::eDrawBoundingTrace
ccBlobDefs::eDrawStandard
filtered
654
If true, only features which meet the current filtering criteria have
results drawn.
CVL Class Reference
ccBoard
#include <ch_cvl/board.h>
class ccBoard;
Class Properties
Copyable
No
Derivable
Cognex-supplied classes
only
Archiveable
No
This abstract class is used to describe Cognex hardware such as vision processors and
frame grabbers. For each physical Cognex vision device (vision processor or frame
grabber) installed on your PC, there is a single object derived from ccBoard that refers
to it.
For cameras that do not use frame grabbers, such as IEEE 1394 cameras and GigE
Vision cameras, there is a single ccBoard object that represents all cameras of the
same type.
Your application can get a ccBoard object by using the get() function.
Constructors/Destructors
Construction and destruction of derived classes is done automatically.
Public Member Functions
name
const TCHAR* name();
Return the name of this board as a null-terminated string.
serialNumber
ccCvlString serialNumber() const;
Returns an ASCII string containing the serial number of the Cognex hardware device
represented by this ccBoard.
Throws
ccBoard::BadEERAMContents
The board serial number cannot be read because the EERAM
contents are invalid.
CVL Class Reference
655
ccBoard
upgradeCode
virtual ccCvlString upgradeCode() const;
Returns the upgrade code for this board.
Notes
If this board does not have an upgrade code, this function returns a zero-length
string.
Throws
ccBoard::BadEERAMContents
The EERAM cannot be read.
writeEERAMData
void writeEERAMData(c_Int32 offset,
const cmStd vector<c_UInt8> &data);
Write user-defined data into EERAM starting at the specified offset.
Parameters
offset
data
The location within user EERAM area at which to start writing
data. Must be in the range 0 through sizeEERAMData().
The data to write.
Throws
ccBoard::BadParams
data is too big to fit into user EERAM area.
readEERAMData
void readEERAMData(c_Int32 offset,
cmStd vector<c_UInt8> &data, c_Int32 nBytes);
Read data from the user EERAM area.
Parameters
offset
The location within user EERAM area at which to start reading
data. Must be in the range 0 through sizeEERAMData().
data
The data read from user EERAM.
nBytes
The number of bytes to read.
Throws
ccBoard::BadParams
nBytes is too big and would read beyond the end of user EERAM.
sizeEERAMData
c_Int32 sizeEERAMData() const;
Return the size of the user EERAM data area.
656
CVL Class Reference
ccBoard
Notes
Not all hardware devices provide a user EERAM area. If a device does not support
a user EERAM data area, this function returns zero.
Static Functions
count
static c_Int32 count();
Returns the number of Cognex boards installed.
Notes
This function is not available at static initialization time.
For cameras that appear as boards to CVL (GigE Vision cameras, for example, the
count of the number of cameras is available only after the cameras have finished
their network negotiation. Use isEnumerationComplete() to determine when this is
the case.
This function is intended for host use. If you call count() from an application running
on an embedded system, such as the Cognex MVS-82400, it always returns 1 no
matter how many boards are installed in the host system.
Throws
ccBoard::StaticInitDisorder
This function was called during static initialization time.
get
static ccBoard& get(c_Int32 i = 0);
Return the ith board installed. Board numbering starts at 0.
Parameters
i
The board number.
Throws
ccBoard::BadParams
i is not within the range of 0 through count() - 1, or
no boards are installed (count() returns 0).
ccBoard::StaticInitDisorder
This function was called during static initialization time.
Notes
This function is not available at static initialization time.
Boards are sorted alphabetically in increasing order according to board type.
Within a given board type, the order may be operating-system and CVL-version
dependent.
CVL Class Reference
657
ccBoard
isEnumerationComplete
static bool isEnumerationComplete(double limitSec=0.0);
Returns True if the enumeration of boards is complete.
Parameters
limitSec
The number of seconds to wait before returning if enumeration is
not complete.
Global Exceptions
A number of hardware-related global exceptions are defined as nested classes of
ccBoard. These exceptions can be thrown by any member function in this class, or in
classes derived from this class. These global exceptions include the following.
Throws
ccBoard::HardwareNotResponding
The frame grabber or vision processor did not respond to the
current access request. This can be the result of a problem with
the hardware or the hardware’s driver. Check that the board is
installed and powered on correctly according to its hardware
manual. Make sure there are no overcurrent conditions on
parallel I/O lines. Check that the board’s driver is running; check
the Windows Event Log for any messages from the device driver.
ccBoard::HardwareInUse
The current process tried to access frame grabber or vision
processor hardware that is already owned by another running
process. To avoid this error, a process that touches the hardware
(such as a CVM ID query, number of camera ports query, or
image acquisition request) must exit before another process can
access the same hardware.
ccBoard::HardwareNotInitialized
The current access request received a response from the
board’s driver, but the board reports itself as not yet initialized.
Make sure the current process has instantiated the right frame
grabber class (cc8100m, cc8504, and so on). Power the host PC
all the way off and back on and try the request again.
ccBoard::BadEERAMContents
The EERAM chip on the board that contains the board’s serial
number and other information could not be read.
ccBoard::FpgaLoadFailure
An error occurred while loading the FPGA on the board. On some
frame grabbers, including the MVS-8100M and MVS-8100C, this
658
CVL Class Reference
ccBoard
error can occur if external camera power is incorrectly applied to
the board. Check the setting of the jumper that determines
whether camera power is to be pulled from the PCI bus or from
an external power cable, as described in the frame grabber’s
hardware manual. Make sure the external power cable, if used, is
plugged into the board and the PC’s power supply.
CVL Class Reference
659
ccBoard
660
CVL Class Reference
ccBoundary
#include <ch_cvl/pmibnd.h>
class ccBoundary;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class contains boundary data. The member functions of the class return information
about the geometrical properties of the boundary and allow for geometrical
comparisons between two boundaries. This ccBoundary can be the trained, matched,
extra or missing boundary returned by PatInspect. The boundary information embodied
by the class includes:
•
The position of each boundary point
•
The direction of each boundary point
•
The weight of each boundary point
•
The matchQuality value of each boundary point
•
The minimum enclosing rectangle of the boundary
•
The mean position of the boundary
•
The weighted mean position of the boundary.
Constructors/Destructors
ccBoundary
ccBoundary();
ccBoundary(const cmStd vector<ccInspectBPoint>& points,
ccBoundaryDefs::BoundaryType type=
ccBoundaryDefs::eTrained,
const cc2Xform &pose=cc2Xform::I);
ccBoundary(const cmStd vector<cc2Vect>& points,
const cc2Xform &pose=cc2Xform::I);
•
ccBoundary();
Creates a ccBoundary that has no points.
CVL Class Reference
661
ccBoundary
•
ccBoundary(const cmStd vector<ccInspectBPoint>& points,
ccBoundaryDefs::BoundaryType type=
ccBoundaryDefs::eTrained,
const cc2Xform &pose=cc2Xform::I);
Creates a ccBoundary from the boundary type specified by type.
Parameters
points
The list of boundary points of this ccBoundary.
type
The type of boundary. type must be one of the following:
ccBoundaryDefs::eTrainedt
ccBoundaryDefs::eMatch
ccBoundaryDefs::eMissing
ccBoundaryDefs::eExtra
pose
The cc2Xform that maps the boundary to client coordinates.
Notes
If type is ccBoundaryDefs::eTrained only the boundary points from the trained
pattern that are matched at run-time are included in this ccBoundary.
•
ccBoundary(const cmStd vector<cc2Vect>& points,
const cc2Xform &pose=cc2Xform::I);
Creates a ccBoundary from the points list. The direction associated with each boundary
point is computed from the supplied list of points. The weight of each boundary point is
set to 1.0. The matchQuality value of each boundary point is set to 0.0.
Parameters
points
pose
The list of points that make up the boundary.
The cc2Xform that maps points to client coordinates.
Notes
This constructor is provided for testing purposes.
Public Member Functions
unweightedMeanPosition
cc2Vect unweightedMeanPosition() const;
Returns the unweighted mean position of this ccBoundary.
Notes
The unweighted mean position may not lie on the boundary. The unweighted mean
position is computed by the constructor.
662
CVL Class Reference
ccBoundary
weightedMeanPosition
cc2Vect weightedMeanPosition() const;
Returns the weighted mean position of this ccBoundary.
Notes
The weighted mean position may not lie on the boundary. The weighted mean
position is computed by the constructor.
area
double area(
ccBoundaryDefs::AreaMethod method=
ccBoundaryDefs::eSimple)const;
Returns the area of this ccBoundary according to the modality specified by method. If
method is ccBoundaryDefs::eSimple the function computes the area of the polygon
resulting from connecting adjacent boundary points with straight segments (if the
boundary is open the two end-points are connected with a straight segment to close the
polygon). If method is ccBoundaryDefs::eConvex the function computes the area of the
convex hull of this ccBoundary (the convex hull of a boundary is the smallest enclosing
polygon of the boundary, see ccBoundaryDefs).
Parameters
method
The modality used to compute the area of this ccBoundary.
method must be one of the following:
ccBoundaryDefs::eSimplet
ccBoundaryDefs::eConvex
Throws
ccBoundaryDefs::DegenerateShape
method is ccBoundaryDefs::eSimple and the shape of the
polygon that connects the boundary points is not simple (this
means that the straight line that closes the boundary intersect the
boundary).
Notes
The area cannot be computed if this ccBoundary crosses on itself.
convexHull
ccBoundary convexHull() const;
Returns the boundary that is the convex hull of this ccBoundary. The convex hull is the
minimum enclosing polygon of this ccBoundary.
rect
ccRect rect() const;
Returns the minimum enclosing rectangle of this ccBoundary in client coordinates. The
minimum enclosing rectangle of this ccBoundary is computed by the constructor.
CVL Class Reference
663
ccBoundary
draw
void draw(ccUITablet &tablet,
bool connected=true,
const ccColor &color=ccColor::greenColor(),
const ccUITablet::Layers &layer=
ccUITablet::eImageLayer) const;
Draws this ccBoundary in the supplied ccUITablet tablet.
Parameters
tablet
minDist
The tablet used to draw this ccBoundary.
connected
If true the function draws the polygon obtained by connecting the
adjacent boundary points of this ccBoundary with straight
segments.
color
The color of this ccBoundary.
layer
The layer into which this ccBoundary is drawn.
double minDist(const ccBoundary &bnd2,
cc2Vect &pnt1,cc2Vect &pnt2,
ccBoundaryDefs::DistanceMethod method=
ccBoundaryDefs::eExhaustive) const;
Returns the distance between this ccBoundary and the boundary bnd2 according to
the modality specified by method. The positions of the two closest points are stored in
pnt1 (for this ccBoundary) and pnt2 (for bnd2). The two closest points depend on the
modality chosen to measure the distance between the two boundaries (see
ccBoundaryDefs).
Parameters
method
The mode used to compute the distance between boundaries.
method must be one of the following:
ccBoundaryDefs::eExhaustive
ccBoundaryDefs::eMinEndPnt
ccBoundaryDefs::eMeanPosition
pnt1
The closest boundary point of this ccBoundary to bnd2.
pnt2
The closest boundary point of bnd2 to this ccBoundary.
Throws
ccBoundaryDefs::DegenerateShape
This ccBoundary or bnd2 or both have no points.
length
double length(bool assumeClosed=false) const;
Returns the length of this ccBoundary in client coordinates.
664
CVL Class Reference
ccBoundary
Parameters
assumeClosed
If true the function returns the length of the closed shape
obtained by joining the first and last point of this ccBoundary
with a straight line.
Notes
The length returned is not the number of points in this ccBoundary.
inside
bool inside(const cc2Vect &pnt1) const;
Returns true if the point pnt1 is inside this ccBoundary. Returns false if pnt1 is outside
or exactly on this ccBoundary.
Parameters
pnt1
The point whose position relative to this ccBoundary is
evaluated.
angleBetweenSegments
ccRadian angleBetweenSegments(const ccBoundary &bnd2)
const;
Returns the angle between this ccBoundary and bnd2. The angle between the two
boundaries is defined as the angle between the best fitting line of this ccBoundary and
the best fitting line of bnd2. The angle returned is from 0 through 2π radians.
Parameters
bnd2
The boundary whose best fitting line is used together with the
best fitting line of this ccBoundary to compute the angle between
the two boundaries.
Throws
ccBoundaryDefs::InvalidBoundaryCondition
The line fit to this ccBoundary or bnd2 fails.
ccBoundaryDefs::DegenerateShape
This ccBoundary or bnd2 or both have only one point.
measureDifferences
cmStd vector <cc2Vect> measureDifferences(
const ccBoundary &bnd,
ccBoundaryDefs::MeasurementMethod method =
CVL Class Reference
665
ccBoundary
ccBoundaryDefs::eParallel,
ccBoundaryDefs::MeasurementAccuracy acc =
ccBoundaryDefs::eFast) const;
Returns the vector of distances between the boundary points of this ccBoundary and
the corresponding boundary points of bnd. The distances are computed according to
the modalities specified by method and acc (see ccBoundaryDefs).
Parameters
bnd
position
The boundary from which the distance of this ccBoundary is
measured.
method
The measurement mode used to compute boundary point
distances. method must be one of the following:
ccBoundaryDefs::eRadial
ccBoundaryDefs::eParallel
acc
The matching modality used to match the boundary points of this
ccBoundary to the boundary points of bnd. acc must be one of
the following:
ccBoundaryDefs::eFast
ccBoundaryDefs::eAccurate
const cmStd vector <cc2Vect> &position() const;
Returns a list of all the positions of the boundary points in this ccBoundary.
angle
const cmStd vector <ccRadian>& angle() const;
Returns a list of all the direction angles of the boundary points in this ccBoundary.
weight
const cmStd vector <double>& weight() const;
Returns a list of all the weights of the boundary points in this ccBoundary.
matchQuality
const cmStd vector <double>& matchQuality() const;
Returns a list of all the matchQuality values of the boundary points in this ccBoundary.
666
CVL Class Reference
ccBoundaryDefs
#include <ch_cvl/pmibnd.h>
class ccBoundaryDefs;
A name space that holds enumerations and constants used with PatInspect.
Enumerations
MeasurementMethod
enum MeasurementMethod
This enumeration defines the measurement methods used to compute the distance
between two boundary points belonging to two distinct boundaries.
Value
Meaning
eRadial
The radial distance between boundary
points is computed.
eParallel
The distance between boundary points
is computed on parallel lines.
The following figure illustrates the difference between radial distance (eRadial) and
parallel distance (eParallel).
Boundary 2
Boundary 1
Boundary 2
P2
Boundary 1
P2
P1
Tangent line at P1
P1
Parallel distance
Radial distance of P2 from P1
CVL Class Reference
Normal line
at P1
Parallel distance of P2 from P1
667
ccBoundaryDefs
MeasurementAccuracy
enum MeasurementAccuracy
This enumeration defines the method used to determine the matching points of two
boundaries.
Value
Meaning
eFast
The matching is based on a local
distance-comparison strategy.
eAccurate
The matching is based on an exhaustive
distance-comparison strategy.
The following illustrations show the difference between the two methods:
•
eFast
In this mode points of Boundary 1 are matched to points of Boundary 2 on the basis
of a local distance comparison strategy. The distances between a point in
Boundary 1 and two points in Boundary 2 are computed and the point in Boundary
2 with the shortest distance is matched to the point in Boundary 1. The matching
process is serial, starting from the first point of Boundary 1 as illustrated in the
following figure (in the figure matching boundary points are circled).
Boundary 2
Boundary 1
668
Boundary 2
Boundary 1
Boundary 2
Boundary 1
CVL Class Reference
ccBoundaryDefs
•
eAccurate
In this mode points of Boundary 1 are matched to points of Boundary 2 on the basis
of a comprehensive distance comparison strategy. A point in Boundary 1 is
matched to the closest point in Boundary 2 as illustrated in the following figure (in
the figure matching boundary points are circled).
Boundary 2
Boundary 1
AreaMethod
enum AreaMethod
This enumeration defines the method used to measure the area contained by an open
or closed boundary.
Value
Meaning
eSimple
The area of the polygon defined by the
line segments between boundary points
is computed.
eConvex
The area of the minimum polygon
enclosing the boundary is computed.
The following illustrations show the difference between the two methods:
CVL Class Reference
669
ccBoundaryDefs
•
eSimple
The area of the polygon resulting from connecting adjacent boundary points is
measured. If the boundary is open, the first and last boundary point are connected
by a straight segment.
First boundary point
Last boundary point
Area of the polygon connecting
the boundary points
•
eConvex
The area of the minimum polygon enclosing the boundary is measured.
Minimum enclosing
polygon
Area of the minimum enclosing
polygon
Boundary
670
CVL Class Reference
ccBoundaryDefs
BoundaryType
enum BoundaryType
This enumeration defines what boundary data to retain when ccBoundary constructors
are called.
DistanceMethod
Value
Meaning
eTrained
The training boundary data associated
with the matched boundary data are
retained.
eMatch
The matching boundary data are
retained.
eMissing
The missing boundary data that were
trained but not found at run-time are
retained.
eExtra
The extra boundary data that were not
trained but were found at run-time are
retained.
enum DistanceMethod
This enumeration defines the method used to determine the distance between two
boundaries.
Value
Meaning
eExhaustive
The distance between two boundaries is
defined by the smallest distance
between the boundary points.
eMinEndPnt
The distance between two boundaries is
defined by the smallest distance
between the end-points of the
boundaries.
eMeanPosition
The distance between two boundaries is
defined by the distance between the
mean positions of the boundaries.
The following illustrates the difference between the three methods:
CVL Class Reference
671
ccBoundaryDefs
•
eExhaustive
This is the distance between
Boundary 1 and Boundary 2
according to the eExhaustive
method. The distance between
the two circled boundary points
is the shortest one.
Boundary 1
•
Boundary 2
eMinEndPnt
This is the distance between
Boundary 1 and Boundary 2
according to the eMinEndPnt
method. The distance between
the two circled end-points
is the shortest one.
Boundary 1
672
Boundary 2
CVL Class Reference
ccBoundaryDefs
•
eMeanPosition.
This is the distance between
Boundary 1 and Boundary 2
according to the eMeanPosition
method. It is the distance between
the mean position of Boundary 1
and
the mean position of Boundary 2.
.
Mean position of
Boundary 1
Boundary 1
CVL Class Reference
Mean position of
Boundary 2
Boundary 2
673
ccBoundaryDefs
674
CVL Class Reference
ccBoundaryInspector
#include <ch_cvl/bndrinsp.h>
class ccBoundaryInspector
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class encapsulates the Boundary Inspection tool. You train this tool with a ccShape
model and then run the tool on images to determine if the image boundaries (contours)
match the model boundaries. The inspection tool returns all of the matching contours
and also non-matching contours in both the model and the image. The non-matching
contours enable you to evaluate the match between the model and the image.
Constructors/Destructors
ccBoundaryInspector
ccBoundaryInspector();
ccBoundaryInspector(const ccBoundaryInspector &that);
~ccBoundaryInspector();
•
ccBoundaryInspector();
Constructs an untrained ccBoundaryInspector tool.
•
ccBoundaryInspector(const ccBoundaryInspector &that);
Copy constructor. Performs a deep copy.
•
~ccBoundaryInspector();
Destructor.
CVL Class Reference
675
ccBoundaryInspector
Operators
operator=
ccBoundaryInspector & operator=(
const ccBoundaryInspector &that);
Deep copy assignment operator.
operator==
bool operator==(const ccBoundaryInspector& that) const;
Equality test operator. Returns true if this object is exactly equal to that. Returns false
otherwise.
Parameters
that
operator!=
The object to compare with this object.
bool operator!=(const ccBoundaryInspector& that) const;
Inequality test operator. Returns true if this object is not exactly equal to that. Returns
false otherwise.
Parameters
that
The object to compare with this object.
Public Member Functions
train
void train(
const ccShape &modelBoundary,
const cc2XformBase &clientFromImage,
const ccShapeTol &shapeTolerance,
const ccBoundaryInspectorTrainParams &trainParams,
ccDiagObject* obj = 0,
c_UInt32 diagFlags = 0);
void train(
const ccShape &modelBoundary,
const ccShapeMask &shapeMask,
const cc2XformBase &clientFromImage,
const ccShapeTol &shapeTolerance,
const ccBoundaryInspectorTrainParams &trainParams,
ccDiagObject* obj = 0,
c_UInt32 diagFlags = 0);
•
676
void train(
const ccShape &modelBoundary,
const cc2XformBase &clientFromImage,
CVL Class Reference
ccBoundaryInspector
const ccShapeTol &shapeTolerance,
const ccBoundaryInspectorTrainParams &trainParams,
ccDiagObject* obj = 0,
c_UInt32 diagFlags = 0);
Train this tool with the given parameters. The model boundary may be any CVL shape
description, including a hierarchical shape. The shape description is specified in model
coordinates. The relationship between the client space and image space at train time is
specified by the clientFromImage transform. The model boundary tolerances, which are
in model coordinates, are specified by the shapeTolerance object.
If the object is currently trained, it untrains and then trains again.
Notes
Shape descriptions or shape description portions without a defined tangent angle
are ignored by this tool.
Parameters
modelBoundary A ccShape object that contains the model boundary.
clientFromImage The expected client transform of the images to be inspected.
shapeTolerance The allowed shape boundary tolerances. If you are doing
statistical training this will be a reference to a ccShapeTolStats
object you have created using good test images. If you are doing
manual training this will be a reference to a ccShapeTolTable
object you have created manually.
trainParams
The training parameters.
obj
A container class object that holds diagnostic records created
during the inspection. obj must point to a valid memory location
or it must be NULL. If you supply a value, the tool records
diagnostic information as specified by diagFlags.
diagFlags
Set to 0 to record no diagnostic information. Otherwise diagFlags
is composed by ORing together one or more of the following
values:
ccDiagDefs::eInputs
ccDiagDefs::eIntermediate
ccDiagDefs::eResults
with one of the following values:
ccDiagDefs::eRecordOn
ccDiagDefs::eRecordOff
CVL Class Reference
677
ccBoundaryInspector
Throws
ccBoundaryInspectorDefs::BadParams
If the model boundary is infinite and not a primitive,
or if the model boundary is infinite and
trainParams().clipRegion() is not a valid clipping region,
or if the shapeTolerance object is detectably invalid for this
model boundary.
ccMathError::Singular
If clientFromImage or its inverse is singular.
Notes
The tool becomes untrained if it throws.
•
void train(
const ccShape &modelBoundary,
const ccShapeMask &shapeMask,
const cc2XformBase &clientFromImage,
const ccShapeTol &shapeTolerance,
const ccBoundaryInspectorTrainParams &trainParams,
ccDiagObject* obj = 0,
c_UInt32 diagFlags = 0);
Train as described above, but include a shape mask. A shape mask is applied to the
ccShape model and allows you to ignore (mask out) portions of the model boundary.
Parameters
modelBoundary A ccShape object that contains the model boundary.
shapeMask
The shape mask to apply to modelBoundary. Note that
ccShapeTol is a typedef as follows:
typedef
ccShapePerimData<ccShapeMaskValue> ccShapeMask
Please see the ccShapeMaskValue reference page for more
information about shape masks.
clientFromImage The expected client transform of the images to be inspected.
shapeTolerance The allowed shape boundary tolerances. If you are doing
statistical training this will be a reference to a ccShapeTolStats
object you have created using good test images. If you are doing
manual training this will be a reference to a ccShapeTolTable
object you have created manually.
trainParams
678
The training parameters.
CVL Class Reference
ccBoundaryInspector
obj
A container class object that holds diagnostic records created
during the inspection. obj must point to a valid memory location
or it must be NULL. If you supply a value, the tool records
diagnostic information as specified by diagFlags.
diagFlags
Set to 0 to record no diagnostic information. Otherwise diagFlags
is composed by ORing together one or more of the following
values:
ccDiagDefs::eInputs
ccDiagDefs::eIntermediate
ccDiagDefs::eResults
with one of the following values:
ccDiagDefs::eRecordOn
ccDiagDefs::eRecordOff
Throws
ccBoundaryInspectorDefs::BadParams
If the model boundary is infinite and not a primitive,
or if the model boundary is infinite and
trainParams().clipRegion() is not a valid clipping region,
or if the shapeTolerance object or shapeMask are detectably
invalid for this model boundary.
ccMathError::Singular
If clientFromImage or its inverse is singular.
Notes
The tool becomes untrained if it throws.
isTrained
bool isTrained() const;
Returns true if train() was called successfully on this object.
trainParams
const ccBoundaryInspectorTrainParams &trainParams() const;
Returns the ccBoundaryInspectorTrainParams object used in training.
Throws
ccBoundaryInspectorDefs::NotTrained
If this object is not trained.
modelBoundary
ccShapePtrh_const modelBoundary() const;
Returns the ccShape object used in training.
CVL Class Reference
679
ccBoundaryInspector
Throws
ccBoundaryInspectorDefs::NotTrained
If this object is not trained.
clientFromImage
cc2XformBasePtrh_const clientFromImage() const;
Returns the client-from-image transform used in training.
Throws
ccBoundaryInspectorDefs::NotTrained
If this object is not trained.
shapeTolerance
ccShapeTolPtrh_const shapeTolerance() const;
Returns the ccShapeTol object used in training.
Throws
ccBoundaryInspectorDefs::NotTrained
If this object is not trained.
shapeMask
ccShapeMaskPtrh_const shapeMask() const;
Returns the shape mask used in training. The portions of the model boundary masked
by this shape mask will be ignored by the ccBoundaryInspector tool.
Throws
ccBoundaryInspectorDefs::NotTrained
If this object is not trained,
or if this object was not trained with a shape mask.
run
void run(
const ccPelBuffer_const<c_UInt8> &image,
const cc2XformBase &pose,
ccBoundaryInspectorResult &results,
ccDiagObject* obj = 0,
c_UInt32 diagFlags = 0) const;
void run(
const ccPelBuffer_const<c_UInt8> &image,
const cc2XformBase &pose,
const ccFeatureletFilter &featureletFilter,
680
CVL Class Reference
ccBoundaryInspector
ccBoundaryInspectorResult &results,
ccDiagObject* obj = 0,
c_UInt32 diagFlags = 0) const;
•
void run(
const ccPelBuffer_const<c_UInt8> &image,
const cc2XformBase &pose,
ccBoundaryInspectorResult &results,
ccDiagObject* obj = 0,
c_UInt32 diagFlags = 0) const;
Performs the geometric boundary inspection on the given image with the given
parameters. The relationship between the client coordinates and the model coordinates
of the trained boundary is specified by the pose transform.
The scaling factors of pose should be close to 1.0 for correct operation.
Parameters
image
The image to be inspected.
pose
A transform that specifies the relationship between client
coordinates and the model coordinates of the trained boundary.
results
Where to put the inspection results.
obj
A container class object that holds diagnostic records created
during the inspection. obj must point to a valid memory location
or it must be NULL. If you supply a value, the tool records
diagnostic information as specified by diagFlags.
diagFlags
Set to 0 to record no diagnostic information. Otherwise diagFlags
is composed by ORing together one or more of the following
values:
ccDiagDefs::eInputs
ccDiagDefs::eIntermediate
ccDiagDefs::eResults
with one of the following values:
ccDiagDefs::eRecordOn
ccDiagDefs::eRecordOff
Throws
ccBoundaryInspectorDefs::BadParams
If image is not bound.
ccBoundaryInspectorDefs::NotTrained
If this object is not trained.
CVL Class Reference
681
ccBoundaryInspector
ccMathError::Singular
If pose, image.clientFromImageXformBase(), or their inverses
are singular.
This function will not mask any exceptions that the featurelet filter might throw.
•
void run(
const ccPelBuffer_const<c_UInt8> &image,
const cc2XformBase &pose,
const ccFeatureletFilter &featureletFilter,
ccBoundaryInspectorResult &results,
ccDiagObject* obj = 0,
c_UInt32 diagFlags = 0) const;
Same as above except a featurelet filter is specified. The featurelet filter is applied to the
image contours after the contours are transformed into the coordinate system in which
the model boundary is defined.
See ccFeatureletFilter for information on featurelet filters.
Parameters
image
The image to be inspected.
pose
A transform that specifies the relationship between client
coordinates and the model coordinates of the trained boundary.
featureletFilter
The featurelet filter to be applied to image.
results
Where to put the inspection results.
obj
A container class object that holds diagnostic records created
during the inspection. obj must point to a valid memory location
or it must be NULL. If you supply a value, the tool records
diagnostic information as specified by diagFlags.
diagFlags
Set to 0 to record no diagnostic information. Otherwise diagFlags
is composed by ORing together one or more of the following
values:
ccDiagDefs::eInputs
ccDiagDefs::eIntermediate
ccDiagDefs::eResults
with one of the following values:
ccDiagDefs::eRecordOn
ccDiagDefs::eRecordOff
682
CVL Class Reference
ccBoundaryInspector
Throws
ccBoundaryInspectorDefs::BadParams
If image is not bound.
ccBoundaryInspectorDefs::NotTrained
If this object is not trained.
ccMathError::Singular
If pose, image.clientFromImageXformBase(), or their inverses
are singular.
This function will not mask any exceptions that the featurelet filter might throw.
CVL Class Reference
683
ccBoundaryInspector
684
CVL Class Reference
ccBoundaryInspectorResult
#include <ch_cvl/bndrinsp.h>
class ccBoundaryInspectorResult
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class encapsulates the results of a boundary inspection
(see ccBoundaryInspector). It contains both matched and unmatched results of the
trained model against an image. Unmatched results include image contours, expressed
as featurelet chain sets, that were not matched to the trained model. Unmatched model
boundaries are expressed as perimeter ranges.
Matched image contours are also expressed as featurelet chain sets and matched
model boundaries are expressed as perimeter ranges. For matched results, the class
holds an array of image contours that corresponds to an array of model perimeter
ranges where each image contour is a match to a corresponding model perimeter
range.
Constructors/Destructors
ccBoundaryInspectorResult
ccBoundaryInspectorResult();
Constructs an empty ccBoundaryInspectorResult object.
Operators
operator==
bool operator==(
const ccBoundaryInspectorResult& that) const;
Equality test operator. Returns true if this object is exactly equal to that. Returns false
otherwise.
Parameters
that
CVL Class Reference
The object to compare with this object.
685
ccBoundaryInspectorResult
operator!=
bool operator!=(
const ccBoundaryInspectorResult& that) const;
Inequality test operator. Returns true if this object is not exactly equal to that. Returns
false otherwise.
Parameters
that
The object to compare with this object.
Public Member Functions
extraImageContours
ccFeatureletChainSetPtrh_const extraImageContours() const;
Returns the extra (unmatched) image contours as a featurelet chain set, in client
coordinates.
unmatchedModelBoundary
const cmStd vector<ccPerimRange> &unmatchedModelBoundary()
const;
Returns the vector of model boundary perimeter ranges that were unmatched during the
inspection.
matchedImageContours
const cmStd vector<ccFeatureletChainSetPtrh_const> &
matchedImageContours() const;
Returns a vector of matched image contours as a vector of featurelet chain sets. The
featurelet chain set at matchedImageContours()[i] matches the vector of perimeter
ranges at matchedModelBoundary()[i].
matchedModelBoundary
const cmStd vector<ccPerimRange> &matchedModelBoundary()
const;
Returns a vector of matched model boundary perimeter ranges. The vector of perimeter
ranges at matchedModelBoundary()[i] matches the featurelet chain set at
matchedImageContours()[i].
686
CVL Class Reference
ccBoundaryInspectorTrainParams
#include <ch_cvl/bndrinsp.h>
class ccBoundaryInspectorTrainParams
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class encapsulates the Boundary Inspection tool training parameters.
See ccBoundaryInspector.
There are two training parameters; granularity, and clipRegion. Granularity specifies the
degree to which inspection images are smoothed and subsampled before edges are
extracted. Specifying a clip region is optional. A clip region is a closed ccPolyline that
is applied to the model before model training. Only the model boundary within the clip
region is trained.
Constructors/Destructors
ccBoundaryInspectorTrainParams
explicit ccBoundaryInspectorTrainParams(
double granularity = 1.0,
const ccPolyline &clipRegion = ccPolyline(true));
Constructs a ccBoundaryInspectorTrainParams object with the given parameters.
The default granularity is 1.0, very fine granularity.
A valid clip region is a closed convex ccPolyline specified in model coordinates.
Parameters
granularity
clipRegion
CVL Class Reference
The smoothing and subsampling factor applied to inspection
images. Must be in the range 1.0 through 25.0. A setting of 1.0
specifies fine granularity and a setting of 25.0 specifies very
coarse granularity.
A closed region that specifies a subset of the model for training.
Use a clip region to omit parts of a model you do not wish to train.
687
ccBoundaryInspectorTrainParams
Throws
ccBoundaryInspectorDefs::BadParams
If granularity < 1.0 or granularity > 25.0,
or if the clip region is open.
Operators
operator==
bool operator==(
const ccBoundaryInspectorTrainParams& that) const;
Equality test operator. Returns true if this object is exactly equal to that. Returns false
otherwise.
Parameters
that
operator!=
The object to compare with this object.
bool operator!=(
const ccBoundaryInspectorTrainParams& that) const;
Inequality test operator. Returns true if this object is not exactly equal to that. Returns
false otherwise.
Parameters
that
The object to compare with this object.
Public Member Functions
granularity
double granularity() const;
void granularity(double granularity);
Granularity specifies the degree to which inspection images are smoothed and
subsampled before edges are extracted. Must be in the range 1.0 through 25.0. A
setting of 1.0 specifies fine granularity and a setting of 25.0 specifies very coarse
granularity. The default granularity value is 1.0.
•
double granularity() const;
Returns the current granularity setting.
•
void granularity(double granularity);
Sets the granularity.
688
CVL Class Reference
ccBoundaryInspectorTrainParams
Parameters
granularity
The new granularity setting.
Throws
ccBoundaryInspectorDefs::BadParams
If granularity < 1.0 or granularity > 25.0.
clipRegion
const ccPolyline& clipRegion() const;
void clipRegion(const ccPolyline& clipRegion);
Specifying a clipping region is optional. A valid clipping region is a closed, convex
ccPolyline that is applied to the model before model training. Only the model boundary
within the clipping region is trained. The clipping region is specified in the model
coordinates.
If clipping is performed, the missing and matching model boundaries found during
boundary inspection are reported only if they are within the clipping region.
No clipping is performed during training unless a valid clipping region is provided here.
A valid clipping region is a closed, convex ccPolyline with at least 3 vertices.
The default clipping region is a closed polyline with no vertices (no clipping is
performed).
•
const ccPolyline& clipRegion() const;
Returns the ccPolyline that defines the clipping region.
•
void clipRegion(const ccPolyline& clipRegion);
Defines a new clipping region.
Parameters
clipRegion
The new clipping region.
Throws
ccBoundaryInspectorDefs::BadParams
If the clipping region is open.
CVL Class Reference
689
ccBoundaryInspectorTrainParams
690
CVL Class Reference
ccBoundarySet
#include <ch_cvl/pmibnd.h>
class ccBoundarySet;
Class Properties
Copyable
Yes
Derivable
Not intended
Archiveable
Simple
This class contains the set of boundary results returned by PatInspect. The class holds
data from the following four sets of boundaries:
•
The boundary of trained features (the boundary features that have been trained)
•
The boundary of matched features (the boundary features that are present in both
run-time and template image)
•
The boundary of extra features (the boundary features that are present in the
run-time image but not in the template image)
•
The boundary of missing features (the boundary features that are present in the
template image but not in the run-time image).
CVL Class Reference
691
ccBoundarySet
Constructors/Destructors
ccBoundarySet
ccBoundarySet();
ccBoundarySet(ccPMInspectResult &result);
ccBoundarySet(const ccPMInspectBoundaryData &diffData,
const cc2Xform &pose=cc2Xform::I);
ccBoundarySet(const cmStd vector <ccBoundary>& points,
ccBoundaryDefs::BoundaryType
type=ccBoundaryDefs::eTrained,
const cc2Xform &pose=cc2Xform::I);
ccBoundarySet(const cmStd vector <cc2Vect>& points,
ccBoundaryDefs::BoundaryType type,
const cc2Xform &pose=cc2Xform::I);
ccBoundarySet(const ccPMInspectAbsenceData &points,
const cc2Xform & pose=cc2Xform::I);
•
ccBoundarySet();
Creates a ccBoundarySet with empty boundaries. The boundaries of trained, matched,
extra and missing features of this ccBoundarySet have no points.
•
ccBoundarySet(ccPMInspectResult &result);
Creates the boundaries of trained, matched, extra and missing features of this
ccBoundarySet from the corresponding boundaries returned by result. The four
boundaries are expressed in client coordinates. The transformation that maps the
boundaries to client coordinates is included in results.
Parameters
result
•
The ccPMInspectResult object to which this ccBoundarySet is
initialized.
ccBoundarySet(const ccPMInspectBoundaryData &diffData,
const cc2Xform &pose=cc2Xform::I);
Creates the boundaries of trained, matched, extra and missing features of this
ccBoundarySet from the corresponding boundaries returned by diffData. The four
boundaries are expressed in client coordinates. The transformation that maps the
boundaries to client coordinates is provided by pose.
Parameters
diffData
692
The ccPMInspectBoundaryData object to which this
ccBoundarySet is initialized.
CVL Class Reference
ccBoundarySet
pose
•
The cc2Xform that maps the boundary features to client
coordinates.
ccBoundarySet(const cmStd vector <ccBoundary>& points,
ccBoundaryDefs::BoundaryType
type=ccBoundaryDefs::eTrained,
const cc2Xform &pose=cc2Xform::I);
Creates the boundary specified by type of this ccBoundarySet from the vector of
ccBoundary points. The three remaining boundaries are all initialized to a boundary
with no points. The transformation that maps the boundaries to client coordinates is
provided by pose.
Parameters
points
•
The vector of ccBoundary points used to initialize this
ccBoundarySet.
type
The modifier that specifies which boundary of this
ccBoundarySet is set to points. type must be one of the
following:
ccBoundaryDefs::eTrainedt
ccBoundaryDefs::eMatch
ccBoundaryDefs::eMissing
ccBoundaryDefs::eExtra
pose
The cc2Xform that maps the boundary features to client
coordinates.
ccBoundarySet(const cmStd vector <cc2Vect>& points,
ccBoundaryDefs::BoundaryType type,
const cc2Xform &pose=cc2Xform::I);
Sets the boundary specified by type of this ccBoundarySet to the vector of points
points. The three remaining boundaries are all initialized to a boundary with no points.
The transformation that maps the boundaries to client coordinates is provided by pose.
Parameters
points
CVL Class Reference
The vector of points used to initialize this ccBoundarySet.
type
The modifier that specifies which boundary of this
ccBoundarySet is set to points.
pose
The cc2Xform that maps the boundary features to client
coordinates.
693
ccBoundarySet
•
ccBoundarySet(const ccPMInspectAbsenceData &points,
const cc2Xform & pose=cc2Xform::I);
Constructs a ccBoundarySet from the supplied ccPMInspectAbsenceData object.
The points are transformed by the supplied pose.
Parameters
points
pose
The ccPMInspectAbsenceData used to initialize this
ccBoundarySet.
The cc2Xform that maps the boundary features to client
coordinates.
Public Member Functions
draw
void draw(ccUITablet &tablet,
bool connected=true,
const ccColor &trainedColor =ccColor::blueColor(),
const ccColor &matchColor =ccColor::greenColor(),
const ccColor &missingColor =ccColor::yellowColor(),
const ccColor &extraColor=ccColor::redColor(),
const ccUITablet::Layers &layer=
ccUITablet::eImageLayer) const;
Draws all the boundaries of this ccBoundarySet in the supplied ccUITablet tablet.
Parameters
tablet
694
The tablet used to draw this ccBoundarySet.
connected
If true the function draws the polygon formed by connecting the
adjacent boundary points of this ccBoundarySet.
trainedColor
The color of the trained boundary features of this
ccBoundarySet.
matchColor
The color of the matching boundary features of this
ccBoundarySet.
missingColor
The color of the missing boundary features of this
ccBoundarySet.
extraColor
The color of the extra boundary features of this ccBoundarySet.
layer
The layer into which this ccBoundarySet is drawn.
CVL Class Reference
ccBoundarySet
boundaryVect
cmStd vector <ccBoundary> & boundaryVect(
ccBoundaryDefs::BoundaryType
type=ccBoundaryDefs::eTrained);
const cmStd vector <ccBoundary> & boundaryVect(
ccBoundaryDefs::BoundaryType
type=ccBoundaryDefs::eTrained) const;
•
cmStd vector <ccBoundary> & boundaryVect(
ccBoundaryDefs::BoundaryType
type=ccBoundaryDefs::eTrained);
Returns the boundary of this ccBoundarySet specified by type.
Parameters
type
•
The modifier that specifies which boundary of this
ccBoundarySet is returned by the function.
const cmStd vector <ccBoundary> & boundaryVect(
ccBoundaryDefs::BoundaryType
type=ccBoundaryDefs::eTrained) const;
Returns the boundary of this ccBoundarySet specified by type.
Parameters
type
CVL Class Reference
The modifier that specifies which boundary of this
ccBoundarySet is returned by the function.
695
ccBoundarySet
696
CVL Class Reference
ccBoundaryTol
#include <ch_cvl/shapetol.h>
class ccBoundaryTol
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
ccBoundaryTol is a container class for representing the acceptable (tolerable)
positional and angular difference between a shape boundary point and a 2D point with
a tangent angle. The Boundary Inspection tool requires that you provide acceptable
variations of the boundaries to be inspected. These acceptable variations are called
shape tolerances. ccBoundaryTol is used as a data type to instantiate the templated
classes ccShapePerimData and ccShapePerimDataTable for creating the
ccShapeTol and ccShapeTolTable classes. Typedefs creating the ccShapeTol and
ccShapeTolTable classes are located on the ccShapePerimData and
ccShapePerimDataTable reference pages.
The absolute value of the positional difference between a boundary point and a 2D point
is the Euclidean distance between them. If the boundary point has a defined tangent
angle, then the positional difference has a sign which is positive if the 2D point is on the
positive side of the boundary point and negative if the 2D point is on the negative side.
In standard CVL notation, the positive side of a boundary point is the +90° direction from
the tangent direction of the boundary point. Similarly, the negative side is the -90°
direction from the tangent. All the points that are on the tangent line of the boundary
point are assumed to have positive distance signs. Please see comments for ccShape
for a description of tangent direction.
In a right-handed coordinate system, the +90° and -90° directions correspond to
counterclockwise and clockwise rotations from the tangent vector, respectively.
The above definition of positive and negative side implies that the inside regions of
right-handed closed shape descriptions (all primitive shape regions such as circles and
rectangles) are the positive sides, and outside regions are the negative sides.
As an example, consider the rectangle and the boundary point A shown in the
right-handed coordinate system below. The distances from boundary point A to points
B and F are negative because the points B and F are in the +90° direction side from the
CVL Class Reference
697
ccBoundaryTol
tangent direction of boundary point A. The points C, D, and E are a positive distance
away from the boundary point A. Note that being inside or outside of a boundary region
does not determine the sign of the distance to the point by itself.
y
+
C
E
+
A
B
+
D
F
x
Positive and negative sides of a shape should not be confused with the shape polarity
defined by ccShapeModelProps. In particular, the positive and negative sides of a
shape depend only on the shape tangent direction and cannot be changed by reversing
the shape model polarity flag.
The angular difference between the angles of a boundary point and a 2D point is
calculated depending on the ignorePolarity flag. If the ignorePolarity flag is false, the
angular difference is calculated by taking the absolute value of the difference of the
angles in the range 0 through pi. If the ignorePolarity flag is true, the angles are first
mapped to the range 0 through pi, and then the difference is taken in range 0 through
pi/2.
Constructors/Destructors
ccBoundaryTol
explicit ccBoundaryTol(
const ccRange & distanceTol = ccRange::FullRange(),
const ccRadian &angleTol = ccRadian(ckPI),
bool ignorePolarity = false);
Constructs a ccBoundaryTol object with the given parameters.
Parameters
distanceTol
angleTol
698
The maximum tolerable distance between a model boundary
point and a corresponding image point.
The maximum tolerable angular difference between a model
boundary featurelet and a corresponding image featurelet.
CVL Class Reference
ccBoundaryTol
ignorePolarity
If true, polarity is ignored when calculating the featurelet angular
difference described above. If false, featurelet polarity is used in
the calculation.
Throws
ccShapePerimDataDefs::BadParams
If angleTol < ccRadian(0.0).
Operators
operator==
bool operator== (const ccBoundaryTol &that) const;
Equality test operator. Returns true if this object is exactly equal to that. Returns false
otherwise.
Parameters
that
operator!=
The object to compare with this object.
bool operator!= (const ccBoundaryTol &that) const;
Inequality test operator. Returns true if this object is not exactly equal to that. Returns
false otherwise.
Parameters
that
The object to compare with this object.
Public Member Functions
distanceTol
ccRange distanceTol() const;
void distanceTol(const ccRange &distanceTol);
The maximum tolerable distance between a model boundary point and a corresponding
image point.
The default value is ccRange::FullRange().
•
ccRange distanceTol() const;
Returns the current distance tolerance.
•
void distanceTol(const ccRange &distanceTol);
Sets a new distance tolerance.
CVL Class Reference
699
ccBoundaryTol
Parameters
distanceTol
angleTol
The new distance tolerance.
ccRadian angleTol() const;
void angleTol(const ccRadian &angleTol);
The maximum tolerable angular difference between a model boundary featurelet and a
corresponding image featurelet.
The default angle tolerance value is ccRadian(ckPI).
•
ccRadian angleTol() const;
Returns the current angle tolerance.
•
void angleTol(const ccRadian &angleTol);
Sets a new angle tolerance.
Parameters
angleTol
The new angle tolerance.
Throws
ccShapePerimDataDefs::BadParams
If angleTol < ccRadian(0.0).
Note: The state of this object remains unchanged if it throws.
ignorePolarity
bool ignorePolarity() const;
void ignorePolarity(bool ignorePolarity);
If true, polarity is ignored when calculating the featurelet angular difference described
above for angle tolerance. If false, featurelet polarity is used in the calculation.
The default ignorePolarity flag value is false.
•
bool ignorePolarity() const;
Returns the state of the ignore polarity flag, true or false.
•
void ignorePolarity(bool ignorePolarity);
Sets the ignore polarity flag, true of false.
700
CVL Class Reference
ccBoundaryTol
Parameters
ignorePolarity
CVL Class Reference
The new ignore polarity flag.
701
ccBoundaryTol
702
CVL Class Reference
ccBoundaryTrackerDefs
#include <ch_cvl/bndtrckr.h>
class ccBoundaryTrackerDefs;
A name space that holds enumerations and constants used with the Symbol tool
classes.
Enumerations
ModeFlags
enum ModeFlags;
This enumeration defines the Boundary Tracker tool modes.
CVL Class Reference
Value
Meaning
eWhiteOnBlack
Specifies light object on dark
background (default is dark object on
light background)
eGradientThreshold
Specifies gradient tracking (default is
threshold tracking)
eStopAtImageEdge
Stop tracking at image edge (default is to
return to start point and tracking in the
other direction)
kDefaulttFlags
Default modes (dark object on light
background; threshold tracking; re-start
tracking if image edge encountered)
703
ccBoundaryTrackerDefs
704
CVL Class Reference
ccBoundaryTrackerPoint
#include <ch_cvl/bndtrckr.h>
class ccBoundaryTrackerPoint;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
No
A class that describes a single boundary point used by the Boundary Tracker tool. A
boundary point contains a subpixel location and a direction.
Constructors/Destructors
ccBoundaryTrackerPoint
ccBoundaryTrackerPoint();
ccBoundaryTrackerPoint(const cc2Vect& c,
const ccRadian& a);
•
ccBoundaryTrackerPoint();
Constructs a ccBoundaryTrackerPoint with a location of (0, 0) and an angle of 0.
•
ccBoundaryTrackerPoint(const cc2Vect& c,
const ccRadian& a);
Constructs a ccBoundaryTrackerPoint using the supplied location and angle.
Parameters
c
CVL Class Reference
The location of the ccBoundaryTrackerPoint.
705
ccBoundaryTrackerPoint
a
The angle of the ccBoundaryTrackerPoint. A
ccBoundaryTrackerPoint’s angle is tangent to the object
boundary and in the tracking direction, as shown in this figure:
Object
Boundary point
A ccBoundaryTrackerPoint’s angle is in the image’s client
coordinate system.
Operators
operator==
bool operator==(const ccBoundaryTrackerPoint& rhs);
Two ccBoundaryTrackerPoints are equal if their locations and angles are the same.
706
CVL Class Reference
ccBoundaryTrackerResult
#include <ch_cvl/bndtrckr.h>
class ccBoundaryTrackerResult;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
No
A class that contains information about a single object boundary measured by the
Boundary Tracker tool. You supply an object of type ccBoundaryTrackerResult to the
function cfBoundaryTracker().
Constructors/Destructors
ccBoundaryTrackerResult
ccBoundaryTrackerResult();
Constructs a ccBoundaryTrackerResult with no result information.
Enumerations
StatusFlags
enum StatusFlags;
This enumeration defines the status flags returned by statusFlags().
CVL Class Reference
Value
Meaning
eSuccess
Valid boundary was found and tracked.
eOpenBoundary
Boundary track did not return to start
point.
707
ccBoundaryTrackerResult
Value
Meaning
eMaxPoints
Boundary tracking stopped because the
maximum number of points were
tracked.
If the tool is tracking an open boundary
that extends to the edge of the image,
this flag may not be set until up to twice
the maximum specified number of points
have been tracked.
eWeakGradient
Boundary tracking stopped because
gradient fell below threshold.
Public Member Functions
area
double area() const;
Returns the area of the object enclosed by this boundary. The area is the number of
pixels within the boundary, transformed into client coordinate system units.
Throws
ccBoundaryTrackerDefs::UninitializedData
No valid boundary has been tracked.
boundaryPoints
const cmStd vector<ccBoundaryTrackerPoint>&
boundaryPoints() const;
Returns a vector of ccBoundaryTrackerPoints describing the boundary. The angle
information in the returned ccBoundaryTrackerResult is valid only if
isAngleDataValid() returns true.
Throws
ccBoundaryTrackerDefs::UninitializedData
No valid boundary has been tracked.
centerOfMass
const cc2Vect& centerOfMass() const;
Returns the center of mass of the object enclosed by this boundary in client coordinates.
Throws
ccBoundaryTrackerDefs::UninitializedData
No valid boundary has been tracked.
708
CVL Class Reference
ccBoundaryTrackerResult
physExtent
const ccRect& physExtent() const;
Returns the smallest rectangle that both is aligned in the image coordinate system and
completely encloses this boundary. The rectangle is returned in client coordinates.
Throws
ccBoundaryTrackerDefs::UninitializedData
No valid boundary has been tracked.
firstBoundaryPointIndex
c_Int32 firstBoundaryPointIndex() const;
Returns the index into the vector of boundary points returned by boundaryPoints() of
the first boundary point found by the Boundary Tracker tool. If you used track-only mode,
this point is the same point you specified as the starting point.
If this function returns 0, it means that the second side of the boundary was not tracked.
Notes
Due to the subpixel interpolation, the coordinates of the returned point may differ
slightly from the coordinates the starting point you supplied in track-only mode.
Throws
ccBoundaryTrackerDefs::UninitializedData
No valid boundary has been tracked.
trackTime
double trackTime() const;
Returns the time, in seconds, it took to find and track this boundary.
Throws
ccBoundaryTrackerDefs::UninitializedData
No valid boundary has been tracked.
dominantAngle
const ccRadian& dominantAngle() const;
Returns the dominant (peak) angle from the angle histogram.
Throws
ccBoundaryTrackerDefs::UninitializedData
No valid boundary has been tracked or no angle data was
computed for this boundary.
Notes
This function only returns valid data if you have computed angle data for this
boundary.
CVL Class Reference
709
ccBoundaryTrackerResult
dominantFoldedAngle
const ccRadian& dominantFoldedAngle() const;
Returns the dominant (peak) angle from the folded angle histogram.
Throws
ccBoundaryTrackerDefs::UninitializedData
No valid boundary has been tracked or no angle data was
computed for this boundary.
Notes
This function only returns valid data if you have computed angle data for this
boundary.
xProjection
const cmStd vector<c_Int32>& xProjection() const;
Returns the x-projection of the portion of the input image enclosed by the smallest
rectangle that both is aligned in the image coordinate system and completely encloses
this boundary.
The returned 1-dimensional image is the same size as the x-dimension of the enclosing
rectangle. Each pixel in the returned image is set to the sum of all of the object pixels in
the corresponding column of the input rectangle.
Throws
ccBoundaryTrackerDefs::UninitializedData
No valid boundary has been tracked.
Notes
This function only returns valid data if you have computed angle data for this
boundary.
yProjection
const cmStd vector<c_Int32>& yProjection() const;
Returns the y-projection of the portion of the input image enclosed by the smallest
rectangle that both is aligned in the image coordinate system and completely encloses
this boundary.
The returned 1-dimensional image is the same size as the y-dimension of the enclosing
rectangle. Each pixel in the returned image is set to the sum of all of the object pixels in
the corresponding row of the input rectangle.
Throws
ccBoundaryTrackerDefs::UninitializedData
No valid boundary has been tracked or no angle data was
computed for this boundary.
710
CVL Class Reference
ccBoundaryTrackerResult
Notes
This function only returns valid data if you have computed angle data for this
boundary.
isAngleDataValid
bool isAngleDataValid() const;
Returns true if angle information has been computed for this boundary, false otherwise.
Whether or not angles are computed is controlled by the
ccBoundaryTrackerRunParams used to track this boundary.
statusFlags
c_UInt32 statusFlags() const;
Returns the result status flags for this boundary. The returned value is computed by
ORing together one or more of the following values:
ccBoundaryTrackerResult::eSuccess
ccBoundaryTrackerResult::eOpenBoundary
ccBoundaryTrackerResult::eMaxPoints
ccBoundaryTrackerResult::eWeakGradient
ccBoundaryTrackerResult::eInternalError
CVL Class Reference
711
ccBoundaryTrackerResult
712
CVL Class Reference
ccBoundaryTrackerRunParams
#include <ch_cvl/bndtrckr.h>
class ccBoundaryTrackerRunParams: public ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
A class that contains the run-time parameters for the Boundary Tracker tool. You must
specify whether this ccBoundaryTrackerRunParams is for track-only or
search-and-track mode use at construction-time. You supply an object of type
ccBoundaryTrackerRunParams to the function cfBoundaryTracker().
Constructors/Destructors
ccBoundaryTrackerRunParams
ccBoundaryTrackerRunParams();
ccBoundaryTrackerRunParams(
const ccBoundaryTrackerPoint& firstBoundaryPoint,
c_Int32 threshold,
c_UInt32 flags = ccBoundaryTrackerDefs::kDefaultFlags,
bool decreasingAngleSideFirst = true,
c_Int32 maxBoundaryPoints = 0,
const ccRange& areaRange = ccRange(0, HUGE_VAL),
c_Int32 preAnglePoints = 1, c_Int32 postAnglePoints = 1);
ccBoundaryTrackerRunParams(
const cmStd vector<ccLineSeg>& searchVectors,
c_Int32 threshold,
c_UInt32 flags = ccBoundaryTrackerDefs::kDefaultFlags,
bool decreasingAngleSideFirst = true,
c_Int32 maxBoundaryPoints = 0,
const ccRange& areaRange = ccRange(0, HUGE_VAL),
c_Int32 preAnglePoints = 1, c_Int32 postAnglePoints = 1);
•
ccBoundaryTrackerRunParams();
Constructs a ccBoundaryTrackerRunParams that cannot be used to track object
boundaries.
CVL Class Reference
713
ccBoundaryTrackerRunParams
•
ccBoundaryTrackerRunParams(
const ccBoundaryTrackerPoint& firstBoundaryPoint,
c_Int32 threshold,
c_UInt32 flags = ccBoundaryTrackerDefs::kDefaultFlags,
bool decreasingAngleSideFirst = true,
c_Int32 maxBoundaryPoints = 0,
const ccRange& areaRange = ccRange(0, HUGE_VAL),
c_Int32 preAnglePoints = 1, c_Int32 postAnglePoints = 1);
Constructs a ccBoundaryTrackerRunParams for track-only mode. For track-only
mode, you must specify a starting point on the object boundary; the tool does not search
for the boundary.
Parameters
firstBoundaryPoint
The starting boundary point. firstBoundaryPoint is given in client
coordinates and must lie within a boundary pixel. The angle
component of firstBoundaryPoint must specify an angle that is
tangent to the boundary in the direction of the search, as shown
in the following figure:
Object
Boundary point showing search direction
threshold
The threshold value to use for object tracking. If flags specifies
gradient tracking mode, then threshold is interpreted as the
gradient threshold (a pixel value difference). Otherwise,
threshold is treated as a hard binary threshold.
If threshold is a hard binary threshold and flags specifies a light
object on a dark background, then threshold is the minimum pixel
value for an object pixel. If threshold is a hard binary threshold
and flags specifies a dark object on a light background, then
threshold is the maximum pixel value for an object pixel.
flags
714
The mode flags for this ccBoundaryTrackerRunParams. flags
must be either ccBoundaryTrackerDefs::kDefaultFlags or a value
formed by ORing together one or more of the following values:
CVL Class Reference
ccBoundaryTrackerRunParams
ccBoundaryTrackerDefs::eWhiteOnBlack
ccBoundaryTrackerDefs::eGradientThreshold
ccBoundaryTrackerDefs::eStopAtImageEdge
decreasingAngleSideFirst
Set decreasingAngleSideFirst to true to track the boundary in the
direction of decreasing client coordinate system angle. Set
decreasingAngleSideFirst to false to track the boundary in the
direction of increasing client coordinate system angle. The
tracking direction is illustrated in the following figure:
Direction of
increasing angle
X
decreasingAngleSideFirst
is true.
decreasingAngleSideFirst
is false.
Left-handed coordinate system
Y
Y
Right-handed coordinate system
decreasingAngleSideFirst
is false.
decreasingAngleSideFirst
is true.
X
Direction of
increasing angle
CVL Class Reference
715
ccBoundaryTrackerRunParams
maxBoundaryPoints
Specifies the maximum number of boundary points to track. The
Boundary Tracker tool stops tracking after it tracks the specified
number of points.
If the tool is tracking an open boundary that extends to the edge
of the image, the tool may stop after it tracks up to twice as many
points as you specify for maxBoundaryPoints.
areaRange
Specifies the minimum and maximum object area size. Object
sizes are positive while hole sizes are negative. To prevent the
tool from tracking holes, specify a minimum object size greater
than or equal to zero. To prevent the tracking of open boundaries,
specify an areaRange that does not include 0.
For more information, see the areaRange definition for the
ccBoundaryTrackerRunParams object for search-and-track
mode.
preAnglePoints
Specifies the number of boundary points preceding each
boundary point that are used to compute that point’s angle. The
more points you specify, the more accurate the angle
computation.
postAnglePoints Specifies the number of boundary points following each
boundary point that are used to compute that point’s angle. The
more points you specify, the more accurate the angle
computation.
Specify 0 for both preAnglePoints and postAnglePoints to not
compute any angle information.
Throws
ccBoundaryTrackerDefs::ThresholdOutOfRange
threshold is greater than 255 or less than 0.
ccBoundaryTrackerDefs::BadFlags
An invalid value was specified for flags.
ccRangeDefs::BadParams
The value returned by areaRange.start() is greater than that
returned by areaRange.end().
ccBoundaryTrackerDefs::BadPrePostAnglePoints
preAnglePoints or postAnglePoints is less than 0.
ccBoundaryTrackerDefs::MaxBoundaryPointsOutOfRange
maxBoundaryPoints is less than 0.
716
CVL Class Reference
ccBoundaryTrackerRunParams
•
ccBoundaryTrackerRunParams(
const cmStd vector<ccLineSeg>& searchVectors,
c_Int32 threshold,
c_UInt32 flags = ccBoundaryTrackerDefs::kDefaultFlags,
c_Int32 maxBoundaryPoints = 0,
const ccRange& areaRange = ccRange(0, HUGE_VAL),
c_Int32 preAnglePoints = 1, c_Int32 postAnglePoints = 1);
Constructs a ccBoundaryTrackerRunParams object for search-and-track mode. In
search-and-track mode, you provide the tool with search parameters using this object.
The tool then returns the first boundary that meets all specified conditions.
The tool tracks any boundary that it finds, and then evaluates whether the boundary
meets the specified conditions. If the boundary does not meet these conditions, the tool
does not return data about the boundary and continues its search for a boundary that
does.
Parameters
searchVectors
threshold
A vector of search lines. Each search line should start inside an
object and extend across the object boundary. Each search line
is searched for transitions of the correct polarity that exceed the
specified threshold value. Each transition is used as a start point
for a boundary track.
The threshold value to use for object tracking. If flags specifies
gradient tracking mode, then threshold is interpreted as the
gradient threshold (a pixel value difference). Otherwise,
threshold is treated as a hard binary threshold.
If threshold is a hard binary threshold and flags specifies a light
object on a dark background, then threshold is the minimum pixel
value for an object pixel. If threshold is a hard binary threshold
and flags specifies a dark object on a light background, then
threshold is the maximum pixel value for an object pixel.
flags
The mode flags for this ccBoundaryTrackerRunParams. flags
must be either ccBoundaryTrackerDefs::kDefaultFlags or a value
formed by ORing together one or more of the following values:
ccBoundaryTrackerDefs::eWhiteOnBlack
ccBoundaryTrackerDefs::eGradientThreshold
ccBoundaryTrackerDefs::eStopAtImageEdge
decreasingAngleSideFirst
Set decreasingAngleSideFirst to true to track the boundary in the
direction of decreasing client coordinate system angle. Set
decreasingAngleSideFirst to false to track the boundary in the
direction of increasing client coordinate system angle. The
CVL Class Reference
717
ccBoundaryTrackerRunParams
decreasingAngleSideFirst parameter refers to the direction of the
angle created if the search vector were to be rotated in an
increasing or decreasing angle direction in the client coordinate
system.
The tracking direction is illustrated in the following figure:
Direction of
increasing angle
Right-handed coordinate system
X
Counterclockwise
tracking direction
decreasingAngleSideFirst
is false.
Y
Counterclockwise
tracking direction
decreasingAngleSideFirst
is true.
Clockwise
tracking direction
Clockwise
tracking direction
decreasingAngleSideFirst
is false.
Y
decreasingAngleSideFirst
is true.
Left-handed coordinate system
X
Direction of
increasing angle
maxBoundaryPoints
Specifies the maximum number of boundary points to track. The
Boundary Tracker tool will stop tracking after it tracks the
specified number of points.
If the tool is tracking an open boundary that extends to the edge
of the image, the tool may stop after it tracks up to twice as many
points as you specify for maxBoundaryPoints.
areaRange
718
Specifies the minimum and maximum object area size. Object
areas are positive; hole areas are negative; and the areas of open
boundaries equal 0.
CVL Class Reference
ccBoundaryTrackerRunParams
Use the following table to determine the ranges that you can
specify to track objects, holes, or open boundaries:
Region 1:
Holes
Region 2: Open
Boundaries
Region 3:
Objects
areaRange < 0
(Minimum and
maximum < 0.)
areaRange = 0
(Minimum and
maximum = 0.)
areaRange > 0
(Minimum and
maximum = 0.)
Track the
boundaries of
holes only.
Track open
boundaries only.
Track the
boundaries of
objects only.
To track a combination objects, create ranges with overlapping
regions. The following table provides examples of different
ranges:
Range
Meaning
range [1 to 10000]
Track closed object boundaries only.
(Do not track nonhole and open
boundaries.)
range [0 to 0]
Track open boundaries only.
range [0 to 10000]
Track open and closed boundaries,
but not holes.
range [-100 to 200]
Track holes whose area is smaller
than 100, open boundaries, and
object boundaries whose area is
smaller than 200.
To prevent the tool from tracking holes, specify a minimum object
size greater than or equal to zero. To prevent the tracking of open
boundaries, specify that areaRange not include 0.
preAnglePoints
Specifies the number of boundary points preceding each
boundary point that are used to compute that point’s angle.
postAnglePoints Specifies the number of boundary points following each
boundary point that are used to compute that point’s angle.
Specify 0 for both preAnglePoints and postAnglePoints to not
compute any angle information.
CVL Class Reference
719
ccBoundaryTrackerRunParams
Throws
ccBoundaryTrackerDefs::ThresholdOutOfRange
threshold is greater than 255 or less than 0.
ccBoundaryTrackerDefs::BadFlags
An invalid value was specified for flags.
ccRangeDefs::BadParams
The value returned by areaRange.start() is greater than that
returned by areaRange.end()
ccBoundaryTrackerDefs::BadPrePostAnglePoints
preAnglePoints or postAnglePoints is less than 0.
ccBoundaryTrackerDefs::MaxBoundaryPointsOutOfRange
maxBoundaryPoints is less than 0.
ccBoundaryTrackerDefs::NoSearchVectors
searchVectors contains no elements.
Public Member Functions
searchVectors
const cmStd vector<ccLineSeg>& searchVectors() const;
void searchVectors(
const cmStd vector<ccLineSeg>& searchVectors);
•
const cmStd vector<ccLineSeg>& searchVectors() const;
Returns the vector of search lines for this ccBoundaryTrackerRunParams. This
ccBoundaryTrackerRunParams must have been constructed using the
search-and-track mode constructor.
Throws
ccBoundaryTrackerDefs::UninitializedData
This object was not constructed using the search-and-track
mode constructor.
•
void searchVectors(
const cmStd vector<ccLineSeg>& searchVectors);
Sets the vector of search lines for this ccBoundaryTrackerRunParams. This
ccBoundaryTrackerRunParams must have been constructed using the
search-and-track mode constructor.
720
CVL Class Reference
ccBoundaryTrackerRunParams
Parameters
searchVectors
A vector of search lines. A search line can start inside or outside
of an object. Along each search line, the tool looks for transitions
of the correct polarity that exceed the specified threshold value.
Each transition is used as a start point for a boundary track.
Throws
ccBoundaryTrackerDefs::UninitializedData
This object was not constructed using the search-and-track
mode constructor.
decreasingAngleSideFirst
bool decreasingAngleSideFirst() const;
void decreasingAngleSideFirst(
bool decreasingAngleSideFirst);
•
bool decreasingAngleSideFirst() const;
Returns true if the tracking direction is in the decreasing client coordinate system angle
direction, false if the tracking direction is in the increasing client coordinate system
angle direction.
•
void decreasingAngleSideFirst(
bool decreasingAngleSideFirst);
Sets the boundary tracking direction.
Parameters
decreasingAngleSideFirst
Specify true to track in the decreasing client coordinate system
angle direction, false to track in the increasing client coordinate
system direction.
threshold
c_Int32 threshold() const;
void threshold(c_Int32 threshold);
•
c_Int32 threshold() const;
Returns the threshold value for object pixels.
CVL Class Reference
721
ccBoundaryTrackerRunParams
•
void threshold(c_Int32 threshold);
Sets the threshold value for object pixels.
Parameters
threshold
The threshold value to use for object tracking. If flags specifies
gradient tracking mode, then threshold is interpreted as the
gradient threshold (a pixel value difference). Otherwise,
threshold is treated as a hard binary threshold.
Throws
ccBoundaryTrackerDefs::ThresholdOutOfRange
threshold is greater than 255 or less than 0.
flags
c_UInt32 flags() const;
void flags(c_UInt32 flags);
•
c_UInt32 flags() const;
Returns the mode flags for this ccBoundaryTrackerRunParams. The returned value is
either ccBoundaryTrackerDefs::kDefaultFlags or a value formed by ORing together one
or more of the following values:
ccBoundaryTrackerDefs::eWhiteOnBlack
ccBoundaryTrackerDefs::eGradientThreshold
ccBoundaryTrackerDefs::eStopAtImageEdge
•
void flags(c_UInt32 flags);
Sets the mode flags for this ccBoundaryTrackerRunParams.
Parameters
flags
The flags to set. flags must be either
ccBoundaryTrackerDefs::kDefaultFlags or a value formed by
ORing together one or more of the following values:
ccBoundaryTrackerDefs::eWhiteOnBlack
ccBoundaryTrackerDefs::eGradientThreshold
ccBoundaryTrackerDefs::eStopAtImageEdge
Throws
ccBoundaryTrackerDefs::BadFlags
flags is not a legal value, as described above.
722
CVL Class Reference
ccBoundaryTrackerRunParams
areaRange
const ccRange& areaRange() const;
void areaRange(const ccRange& areaRange);
•
const ccRange& areaRange() const;
Returns the minimum and maximum object area, in client units, for this
ccBoundaryTrackerRunParams. In track-only mode, the tool will only return a
boundary track if it describes an object within the specified size range. In
search-and-track mode, the tool tracks boundaries until it finds an object within the
specified limits.
•
void areaRange(const ccRange& areaRange);
Sets the minimum and maximum object area, in client units, for this
ccBoundaryTrackerRunParams. In track-only mode, the tool returns a boundary track
only if it describes an object within the specified size range. In search-and-track mode,
the tool tracks boundaries until it finds an object within the specified limits.
The minimum area is equal to the start of the range and the maximum area is equal to
the end of the range.
Object sizes are positive while hole sizes are negative. To prevent the tool from tracking
holes, specify a minimum object size greater than or equal to zero. To prevent the
tracking of open boundaries, specify a maximum object size of 0.
Parameters
areaRange
preAnglePoints
The minimum and maximum object size, in client units.
c_Int32 preAnglePoints() const;
void preAnglePoints(c_Int32 preAnglePoints);
•
c_Int32 preAnglePoints() const;
Returns the number of boundary points preceding each boundary point that are used to
compute that point’s angle.
•
void preAnglePoints(c_Int32 preAnglePoints);
Sets the number of boundary points preceding each boundary point that are used to
compute that point’s angle.
Parameters
preAnglePoints
CVL Class Reference
The number of points.
723
ccBoundaryTrackerRunParams
Throws
ccBoundaryTrackerDefs::BadPrePostAnglePoints
preAnglePoints is less than 0.
Notes
Specify 0 for both the number of preceding and the number of following points to
suppress the calculation of angle information for boundary points.
postAnglePoints
c_Int32 postAnglePoints() const;
void postAnglePoints(c_Int32 postAnglePoints);
•
c_Int32 postAnglePoints() const;
Returns the number of boundary points following each boundary point that are used to
compute that point’s angle.
•
void postAnglePoints(c_Int32 postAnglePoints);
Sets the number of boundary points following each boundary point that are used to
compute that point’s angle.
Parameters
postAnglePoints The number of points.
Throws
ccBoundaryTrackerDefs::BadPrePostAnglePoints
preAnglePoints is less than 0.
Notes
Specify 0 for both the number of preceding and the number of following points to
suppress the calculation of angle information for boundary points.
maxBoundaryPoints
c_Int32 maxBoundaryPoints() const;
Returns the maximum number of boundary points that will be tracked. This parameter
can only be set at construction.
If the tool is tracking an open boundary that extends to the edge of the image, the tool
may stop after it tracks up to twice as many points as you specify for
maxBoundaryPoints.
724
CVL Class Reference
ccBoundaryTrackerRunParams
searchAndTrack
bool searchAndTrack() const;
Returns true if this ccBoundaryTrackerRunParams was constructed using the
search-and-track mode constructor. Returns false if this
ccBoundaryTrackerRunParams was constructed using the track-only mode
constructor.
firstBoundaryPoint
const ccBoundaryTrackerPoint& firstBoundaryPoint() const;
void firstBoundaryPoint(
const ccBoundaryTrackerPoint& firstBoundaryPoint);
•
const ccBoundaryTrackerPoint& firstBoundaryPoint() const;
Returns the starting boundary tracking point for this ccBoundaryTrackerRunParams.
This ccBoundaryTrackerRunParams must have been constructed using the track-only
mode constructor.
Throws
ccBoundaryTrackerDefs::UnintializedData,
This object was constructed with search-and track interface and
no successful tracking has been done
Notes
If this ccBoundaryTrackerRunParams was constructed using the track-only mode
constructor, this function will return the same starting point that was supplied to the
constructor even if no valid boundary track was found.
•
void firstBoundaryPoint(
const ccBoundaryTrackerPoint& firstBoundaryPoint);
Sets the starting boundary point for this ccBoundaryTrackerRunParams. This
ccBoundaryTrackerRunParams must have been constructed using the track-only
mode constructor.
Parameters
firstBoundaryPoint
The starting point, specified in the client coordinate system.
Throws
ccBoundaryTrackerDefs::UnintializedData,
This object was constructed with search-and track interface.
CVL Class Reference
725
ccBoundaryTrackerRunParams
Notes
Call this function to specify a new starting point for track-only mode boundary
tracking.
726
CVL Class Reference
ccCADFile
#include <ch_cvl/cadfile.h>
class ccCADFile;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
Behavior
This class encapsulates the conversion of a DXF format CAD file into a
ccGeneralShapeTree. Currently only a subset of Autodesk, Inc.’s standard ASCII DXF
file format is supported. Binary DXF files are not supported. DXF files with format
versions not supported result in a throw from the converter.
Returned shape trees can represent the entire file, or specific layers or groups within the
file. The tree representing the entire file is organized such that each layer of the drawing
is represented as a ccGeneralShapeTree on a separate branch of the returned parent
tree.
A ccGeneralShapeTree representing a particular layer or group will itself contain the
various primitive shapes and custom objects within that layer or group. Each ccShape
representing a custom object will itself be a ccGeneralShapeTree pointer object
containing the set of primitive shapes and custom objects within the custom object. If a
custom object is repeated more than once within the DXF file, it will result in the creation
of a new ccGeneralShapeTree (the object will be replicated, not shared).
Transformations (including handedness information and coordinate system information)
are supported by mapping all the supported primitive shapes into a single shape
coordinate system, and are not explicitly represented. Primitives that are not supported
are simply ignored.
DXF Versions Supported
Currently only a subset of the Autodesk standard ASCII DXF file format is supported.
ccCADFile supports DXF formats corresponding to AutoCAD versions R12, R13, R14,
and 2000. DXF versions corresponding to AutoCAD versions R11, 2000i, and 2002
should also work, but are not tested.
CVL Class Reference
727
ccCADFile
DXF File Organization
DXF files are organized into sections. The following table identifies these sections and
shows what information is parsed from each one.
Sections
Contents
HEADER
Units, handedness, and base angle of the drawing.
TABLES
Layer information.
BLOCKS
Custom object name and definition.
ENTITIES
Visible objects that make up the basic geometric shapes of the
drawing, as listed in the following table.
CLASSES
Application-specific, non-geometric information, not used by
ccCADFile.
OBJECTS
Information about groups.
The following DXF entities are recognized by ccCADFile and are converted into the
ccShape(s) shown.
728
DXF Entity
ccShape
ARC
ccEllipseArc2
CIRCLE
ccEllipse2
ELLIPSE
ccEllipseArc2
INSERT
ccGeneralShapeTree
LINE
ccLineSeg
LWPOLYLINE
ccPolyline or ccCountourTree (see notes below)
MLINE
ccPolyline
POLYLINE
ccPolyline or ccCountourTree (see notes below)
RAY
ccLine
SOLID
ccPolyline
SPLINE
ccDeBoorSpline
POINT
cc2Point (any Z position information is ignored)
XLINE
ccLine
CVL Class Reference
ccCADFile
The following DXF entity information is ignored:
•
DXF entities not in the table above
•
All three dimensional information
•
Fill and style information
•
Rounded corner and spline representations using POLYLINE
POLYLINE and LWPOLYLINE entities are represented as either ccPolyline or
ccCountourTree objects. If the DXF entity consists of straight lines, a ccPolyline object
is returned. If the DXF object contains any arcs, a ccCountourTree object consisting of
ccEllipseArc2 and ccLineSeg objects is returned.
The INSERT entity provides a mechanism for displaying a transformed version of a
custom object from the BLOCKS section. Its ccShape is a ccGeneralShapeTree whose
children consist of the transformed ccShape versions of its defining entities (which can
include other INSERTs or trees). If a BLOCK is used more than once, it is replicated into
a new ccGeneralShapeTree.
Constructors/Destructors
ccCADFile
ccCADFile();
ccCADFile(
const ccCvlString &fileName,
c_Int32 mode = cmStd ios::in);
~ccCADFile();
ccCADFile(const ccCADFile& rhs);
•
ccCADFile();
Default constructor. Creates an empty, closed ccCADFile object.
•
ccCADFile(
const ccCvlString &fileName,
c_Int32 mode = cmStd ios::in);
Opens and loads fileName containing the specified DXF format text file.
Parameters
fileName
mode
CVL Class Reference
The pathname of the DXF format text file.
The operating mode. ios::in is currently the only supported mode.
729
ccCADFile
Throws
ccCADFile::NotImplemented
If mode is not ios::in.
ccCADFile::CanNotOpenFile
If fileName cannot found or cannot be opened for any reason.
ccCADFile::CanNotLoadFile
If there is a parsing error while reading the file.
ccCADFile::FileFormatNotSupported
If fileName is not a DXF format file.
•
~ccCADFile();
Destructor. Deletes this object and closes any open DXF file.
•
ccCADFile(const ccCADFile& rhs);
Copy constructor. Initialize this object using rhs.
Parameters
rhs
The source of the copy.
Enumerations
UnitTypes
enum UnitTypes
This enumeration defines the DXF file unit IDs.
Values
eUknown = 0
eScientific = 1
eDecimal = 2
eEngineering = 3
eArchitectural = 4
eFractional = 5
eWindowsdesktop = 6
730
CVL Class Reference
ccCADFile
Operators
operator=
ccCADFile& operator=(const ccCADFile& rhs);
Assignment operator.
Parameters
rhs
Source of the assignment.
Public Member Functions
open
void open(
const ccCvlString &fileName,
c_Int32 mode = cmStd ios::in);
Opens fileName and loads the DXF format text file.
Parameters
fileName
mode
The path to the DXF format file to open.
The operating mode. ios::in is currently the only supported mode.
Throws
ccCADFile::NotImplemented
If mode is not ios::in.
ccCADFile::CanNotOpenFile
If fileName cannot found or cannot be opened for any reason.
ccCADFile::CanNotLoadFile
If there is a parsing error while reading the file.
ccCADFile::FileFormatNotSupported
If fileName is not a DXF format file.
isOpen
bool isOpen() const;
Returns true if the specified DXF file is open; otherwise returns false.
close
void close();
Closes the currently open DXF file.
Throws
ccCADFile::FileNotOpen
If there is no open DXF file.
CVL Class Reference
731
ccCADFile
getUnits
UnitTypes getUnits() const;
Returns the unit ID of the currently open DXF file.
Throws
ccCADFile::FileNotOpen
If there is no open DXF file.
layerNames
void layerNames(
cmStd vector<ccCvlString> &names) const;
Returns a vector of the layer names in the currently open DXF file.
The returned names are in the same order that the layer subtrees are added to a general
shape tree using the method shapeTree() described below. For example, names[0]
contains the name of the layer corresponding to the first added subtree. The layer
corresponding to names[i] can be accessed directly by passing names[i] or the integer
index i as the first argument to layerShapeTree().
Parameters
names
A vector of layer names contained in the currently open DXF file.
ccCADFile::FileNotOpen
If there is no open DXF file.
groupNames
void groupNames(
cmStd vector<ccCvlString> &names) const;
Returns a vector of the group names in the currently open DXF fi e.
The group corresponding to names[i] can be accessed directly by passing names[i] or
the integer index i as the first argument to groupShapeTree().
Parameters
names
Group names contained in the currently open DXF file.
Throws
ccCADFile::FileNotOpen
If there is no open DXF file.
numLayers
c_Int32 numLayers() const;
Returns the number of layers in the currently open DXF file.
Throws
ccCADFile::FileNotOpen
If there is no open DXF file.
732
CVL Class Reference
ccCADFile
numGroups
c_Int32 numGroups() const;
Returns the number of groups in the currently open DXF file.
Throws
ccCADFile::FileNotOpen
If there is no open DXF file.
shapeTree
void shapeTree(ccGeneralShapeTree& tree) const;
Adds the contents of the currently open DXF file to tree. Each DXF file layer is added to
a separate branch of the tree.
Parameters
tree
The shape tree where the DXF file’s contents are to be added.
Throws
ccCADFile::FileNotOpen
If there is no open DXF file.
layerShapeTree
void layerShapeTree(c_Int32 layer,
ccGeneralShapeTree& tree) const;
void layerShapeTree(const ccCvlString& name,
ccGeneralShapeTree& tree) const;
Adds the contents of a specified layer of the open DXF file to tree, where the layer is
specified by name or index. The index of a layer is the zero-based position of its name
in the vector returned by layerNames(). The contents of the layer are added on separate
branches of the passed tree.
•
void layerShapeTree(c_Int32 layer,
ccGeneralShapeTree& tree) const;
Parameters
layer
tree
The index number of a layer in the vector of layer names returned
by layerNames().
The shape tree where the layer is to be added.
Throws
ccCADFile::FileNotOpen
If there is no open DXF file.
ccCADFile::BadIndex
If layer is invalid.
CVL Class Reference
733
ccCADFile
•
void layerShapeTree(const ccCvlString& name,
ccGeneralShapeTree& tree) const;
Parameters
name
tree
The name of the layer in the currently open DXF file to be added.
The shape tree where the layer is to be added.
Throws
ccCADFile::FileNotOpen
If there is no open DXF file.
ccCADFile::BadIndex
If name is invalid.
groupShapeTree
void groupShapeTree(
c_Int32 group,
ccGeneralShapeTree& tree) const;
void groupShapeTree(
const ccCvlString& grpName,
ccGeneralShapeTree& tree) const;
Adds the contents of a specified group of the currently open DXF file to tree. The
contents of the group are added on separate branches of the passed tree.
A group is an AutoCAD feature that allows for an arbitrary collection of DXF entities on
any layer to be grouped together for display or processing. The group must be specified
and names within AutoCAD before the DXF file is saved.
The group can be specified by group name or index number. The index of a group is
the zero-based position of its name in the vector returned by groupNames().
•
void groupShapeTree(
c_Int32 group,
ccGeneralShapeTree& tree) const;
Parameters
group
tree
The index number of a group in the vector of group names
returned by groupNames().
The shape tree where the group is to be added.
Throws
ccCADFile::FileNotOpen
If there is no open DXF file.
734
CVL Class Reference
ccCADFile
ccCADFile::BadIndex
If group is invalid.
•
void groupShapeTree(
const ccCvlString& grpName,
ccGeneralShapeTree& tree) const;
Parameters
grpName
tree
The group name to be added from the currently open DXF file.
The shape tree where the group is to be added.
Throws
ccCADFile::FileNotOpen
If there is no open DXF file.
ccCADFile::BadIndex
If grpName is invalid.
CVL Class Reference
735
ccCADFile
736
CVL Class Reference
ccCalib2ParamsExtrinsic
#include <ch_cvl/ccalib.h>
class ccCalib2ParamsExtrinsic;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class holds extrinsic camera calibration parameters (properties of the image
acquisition system that are external to the camera). These are:
•
Orientation of the physical coordinate system with respect to the camera coordinate
system, specified by three angles.
•
Translation of the origin of the 3-D physical coordinate system with respect to the
camera coordinate system.
The extrinsic parameters describe the rigid 3-D transform between the camera
coordinate system and the physical coordinates system. This transform maps a 3-D
vector v to R * v + t where t is the 3-D translation and R is the 3x3 matrix of rotations
through angles contained in the extrinsic parameters.
When you use multiple views for a calibration application (for example, to create a
cc2XformCalib2 object), each view has a unique set of extrinsic parameters.
Constructors/Destructors
ccCalib2ParamsExtrinsic
ccCalib2ParamsExtrinsic(
const cc3AngleVect& orientation,
const cc3Vect& translation);
ccCalib2ParamsExtrinsic();
•
ccCalib2ParamsExtrinsic(
const cc3AngleVect& orientation,
const cc3Vect& translation);
Constructs an object with the specified orientation and translation.
CVL Class Reference
737
ccCalib2ParamsExtrinsic
Parameters
orientation
translation
•
An object that holds the three rotation angles of the axes of a 3-D
coordinate system.
The 3-D origin translation between the physical coordinate
system and the image coordinate system.
ccCalib2ParamsExtrinsic();
Default constructor. Constructs an object initialized with all rotation angles = 0 and
translation = (0, 0, 1).
Public Member Functions
orientation
const cc3AngleVect& orientation() const;
void orientation(const cc3AngleVect& orientation);
•
const cc3AngleVect& orientation() const;
Returns the orientation parameter stored in this object.
•
void orientation(const cc3AngleVect& orientation);
Sets a new orientation parameter.
Parameters
orientation
translation
The new orientation parameter.
const cc3Vect& translation() const;
void translation(const cc3Vect& translation);
•
const cc3Vect& translation() const;
Returns the translation parameter stored in this object.
•
void translation(const cc3Vect& translation);
Sets a new translation parameter.
Parameters
translation
738
The new translation parameter.
CVL Class Reference
ccCalib2ParamsIntrinsic
#include <ch_cvl/ccalib.h>
class ccCalib2ParamsIntrinsic;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class holds intrinsic camera calibration parameters (properties in an image
acquisition system that are internal to the camera). The intrinsic parameters are:
•
The x- and y-scale (also called focal lengths)
•
Skew
•
The x- and y-translation
•
Coefficient of radial distortion
These parameters remain constant as long as the internal camera settings (camera
itself, lens used on the camera, focal length setting, aperture setting, and so on) remain
constant. Also, the intrinsic camera calibration parameters are expected to stay
constant even if external settings vary such as orientation of object plane with respect
to the camera, lighting conditions, and so on.
CVL Class Reference
739
ccCalib2ParamsIntrinsic
Constructors/Destructors
ccCalib2ParamsIntrinsic
ccCalib2ParamsIntrinsic(
const cc2Vect& scale,
double skew,
const cc2Vect& translation,
double k1);
ccCalib2ParamsIntrinsic();
•
ccCalib2ParamsIntrinsic(
const cc2Vect& scale,
double skew,
const cc2Vect& translation,
double k1);
Constructs an intrinsic calibration parameters object from x and y scales, skew, x and y
translation, and the radial distortion coefficient.
Parameters
scale
The x- and y-scale. For example, (.9, 1.1) for an x-scale factor of
.9 and a y-scale factor of 1.1.
skew
Equals -Sy(tanθ), where Sy is the y-scale (see above) and θ is the
shear angle as described in the cc2Matrix reference page.
translation
The x- and y-translation in client coordinates.
k1
Radial distortion coefficient. There are two types of radial
distortion:
1. Barrel distortion: This distortion bends the edges of a square
outward from its center. In this case, k1 < 0.
2. Pincushion distortion: This distortion bends the edges of a
square inward towards its center. In this case, k1 > 0.
740
CVL Class Reference
ccCalib2ParamsIntrinsic
When k1 = 0 there is no radial distortion. See the following
diagram.
Pincushion distortion
k1 > 0
Barrel distortion
k1 < 1
Throws
cc2XformCalibDefs::BadParams
If scale.x() <= 0 or scale.y() <= 0.
•
ccCalib2ParamsIntrinsic();
Constructs an object initialized to its default state with scale = (1,1), skew = 0,
translation = (0,0), and k1 = 0.
Public Member Functions
scale
cc2Vect scale() const;
void scale(const cc2Vect& scale);
•
cc2Vect scale() const;
Returns the x- and y-scales stored in this object.
•
void scale(const cc2Vect& scale);
Sets new x- and y-scales.
Parameters
scale
The new x- and y-scales.
Throws
cc2XformCalibDefs::BadParams
If scale.x() <= 0 or scale.y() <= 0.
CVL Class Reference
741
ccCalib2ParamsIntrinsic
skew
double skew() const;
void skew(double skew);
See skew description in the constructor.
•
double skew() const;
Returns the skew stored in this object.
•
void skew(double skew);
Sets a new skew value.
Parameters
skew
translation
The new skew.
cc2Vect translation() const;
void translation(const cc2Vect& trans);
The x- and y-translation in client coordinates.
•
cc2Vect translation() const;
Returns the x and y translation stored in this object.
•
void translation(const cc2Vect& trans);
Sets new x and y translation.
Parameters
trans
k1
The new x and y translation.
double k1() const;
void k1(double k1);
See k1 description in the constructor.
•
double k1() const;
Returns the radial distortion coefficient stored in this object.
742
CVL Class Reference
ccCalib2ParamsIntrinsic
•
void k1(double k1);
Sets a new radial distortion coefficient.
Parameters
k1
CVL Class Reference
The new radial distortion coefficient.
743
ccCalib2ParamsIntrinsic
744
CVL Class Reference
ccCalib2VertexFeatureDefs
#include <ch_cvl/calibftr.h>
class ccCalib2VertexFeatureDefs;
Name space for calibration feature extraction related enums.
CVL Class Reference
745
ccCalib2VertexFeatureDefs
Enumerations
CorrespondMethod
enum CorrespondMethod;
This enumeration defines the modes used to set the origin and coordinate axes of the
calibration plate physical coordinate system. The correspondence method is also
known as the label mode or label method. These enum modes are passed to
ccCalib2VertexFeatureParams::labelMode(mode).
If it is crucial to have the physical coordinate system stationary with respect to the
physical calibration plate (for example, in multiple view calibration), you should only use
the eUseFiducial mode.
746
CVL Class Reference
ccCalib2VertexFeatureDefs
Mode
Meaning
eNone = 0
The origin of the physical coordinate system is set at the vertex closest
to the center of the image. The physical x-axis is set on the row or
column of vertices that passes through the origin, and is most closely
aligned with the image space x-axis. The image space x-axis and the
physical x-axis, as viewed in the image, point in approximately the
same direction. See the following figure.
xi
Image space
yi
xp
yp
Keep in mind that the checkerboard in the image can be at any oblique
angle depending on the camera angle, and it can be distorted.
This is the default mode.
eUseOrigin
Specifies that the vertex closest to a designated location be used as
the origin of the physical coordinate system. The designated origin can
be set using ccCalibrationVertexFeatureParams::origin().
The direction of the axes is set exactly as in eNone mode above.
eUseFiducial
Specifies that the use of a Cognex-specific fiducial target be found in
the image and used to set the physical coordinate system. The origin
(0,0) and the axes (x and y) of the physical coordinate system are
chosen as shown in the following diagram of a calibration plate
containing a fiducial marker.
The Cognex part number for these calibration plates is 320-0015.
CVL Class Reference
747
ccCalib2VertexFeatureDefs
If you use your own calibration plate, it must conform to specifications contained in an
engineering drawing available from Cognex. This specification allows for any physical
size for checkers but once physical checker size is decided, the width, length of the
fiducial bars, polarities of checkers, and the fiducial must be according to specification.
Note that size of all checkers in acquired images of a physical calibration plate must be
at least 15x15 pixels.
The following is an example calibration plate with a fiducial mark.
Origin
(0 0)
x
y
enum
This enumeration defines default calibration plate parameters.
748
Value
Meaning
kDefaultGridPitch = 1
Default grid pitch in client units.
CVL Class Reference
ccCalib2VertexFeatureDefs
Algorithm
enum Algorithm;
This enumeration defines the algorithms used to extract and label features (tile vertices)
from the image.
Value
Meaning
eStandard = 0
Appropriate for clean images with minimal noise,
contrast variations, or image defects.
eExhaustive = 1
An exhaustive algorithm is used to locate and label
the tile vertices. This algorithm is significantly more
robust than eStandard, although it may take longer to
run.
Cognex recommends the use of eExhaustive in all
cases. Note, however, that the vertex locations
returned by eExhaustive may differ slightly from those
returned by eStandard.
kDefaultAlgorithm =
eStandard
CVL Class Reference
The default algorithm (to preserve backwards
compatibility.
749
ccCalib2VertexFeatureDefs
750
CVL Class Reference
ccCalib2VertexFeatureParams
#include <ch_cvl/calibftr.h>
class ccCalib2VertexFeatureParams;
Class Properties
Copyable
Yes
Derivable
Yes
Archiveable
Simple
This class encapsulates all the parameters required to configure feature extraction from
a checkerboard type calibration plate image.
Constructors/Destructors
ccCalib2VertexFeatureParams
ccCalib2VertexFeatureParams();
ccCalib2VertexFeatureParams(
const cc2Vect& gridPitch,
ccCalib2VertexFeatureDefs::CorrespondMethod mode =
ccCalib2VertexFeatureDefs::eNone);
•
ccCalib2VertexFeatureParams();
Default constructor. Default values are:
gridPitch = (1, 1)
mode = eNone
•
ccCalib2VertexFeatureParams(
const cc2Vect& gridPitch,
ccCalib2VertexFeatureDefs::CorrespondMethod mode =
ccCalib2VertexFeatureDefs::eNone);
Constructs a vertex feature parameters object using the given parameters.
Parameters
gridPitch
mode
CVL Class Reference
The calibration plate grid pitch.
The correspondence mode.
751
ccCalib2VertexFeatureParams
Public Member Functions
physicalGridPitch
void physicalGridPitch(const cc2Vect& gridPitch);
const cc2Vect& physicalGridPitch() const;
Specifies physical units along the x- and y-axes of the physical coordinate system. The
x-component of gridPitch is the distance between any two adjacent checker vertices
when the line joining them is parallel to the physical x-axis. The y-component of gridPitch
is the distance between any two adjacent checker vertices when the line joining them is
parallel to the physical y-axis.
The default physical grid pitch is (1, 1).
•
void physicalGridPitch(const cc2Vect& gridPitch);
Sets a new grid pitch.
Parameters
gridPitch
The new grid pitch.
Throws
ccCalib2VertexFeatureDefs::BadParam
If either component of gridPitch is negative.
•
const cc2Vect& physicalGridPitch() const;
Returns the current grid pitch.
origin
void origin(const cc2Vect& o);
const cc2Vect& origin() const;
An origin in client units to be used for labeling of returned feature points. The vertex
closest to this point will be used as the origin for point correspondence when operating
in ccCalib2VertexFeatureDefs::eUseOrigin mode. The default is (0, 0).
•
void origin(const cc2Vect& o);
Sets a new origin.
Parameters
o
752
The new origin.
CVL Class Reference
ccCalib2VertexFeatureParams
•
const cc2Vect& origin() const;
Returns the current origin.
labelMode
void labelMode(
ccCalib2VertexFeatureDefs::CorrespondMethod m);
ccCalib2VertexFeatureDefs::CorrespondMethod labelMode()
const;
The method used for labeling detected vertex points in the calibration plate image. The
default is ccCalib2VertexFeatureDefs::eNone.
•
void labelMode(
ccCalib2VertexFeatureDefs::CorrespondMethod m);
Sets a new label mode.
Parameters
m
The new label mode.
Throws
ccCalib2VertexFeatureDefs::BadParam
If m is not a valid entry from the
ccCalib2VertexFeatureDefs::CorrespondMethod enum
•
ccCalib2VertexFeatureDefs::CorrespondMethod labelMode()
const;
Returns the current label mode.
algorithm
void algorithm(
ccCalib2VertexFeatureDefs::Algorithm algorithm);
ccCalib2VertexFeatureDefs::Algorithm algorithm()const;
The algorithm to use when extracting and labeling vertices. The default is
ccCalib2VertexFeatureDefs::eStandard. Cognex recommends the use of
ccCalib2VertexFeatureDefs::eExhaustive, which is more robust, particularly in cases of
low or uneven contrast, image blur, reflections, or plate defects.
•
void algorithm(
ccCalib2VertexFeatureDefs::Algorithm algorithm);
Sets the algorithm.
CVL Class Reference
753
ccCalib2VertexFeatureParams
Parameters
m
•
The algorithm.
ccCalib2VertexFeatureDefs::Algorithm algorithm()const;
Returns the current algorithm.
Deprecated Members
The following constructor and functions are deprecated and are maintained here for
backward compatibility only.
ccCalib2VertexFeatureParams
ccCalib2VertexFeatureParams(
const cc2Vect& gridPitch,
const cc2Vect& tileSize =
cc2Vect(ccCalib2VertexFeatureDefs::kDefaultTileSize,
ccCalib2VertexFeatureDefs::kDefaultTileSize),
ccCalib2VertexFeatureDefs::CorrespondMethod mode =
ccCalib2VertexFeatureDefs::eNone);
nominalTileSize
void nominalTileSize(const cc2Vect& tileSize);
const cc2Vect& nominalTileSize();
754
CVL Class Reference
ccCalibDefs
#include <ch_cvl/calib.h>
class ccCalibDefs;
A name space that holds enumerations and constants used with the Calibration tool
classes.
Enumerations
CalibType
enum CalibType;
This enumeration defines the types of calibration supported by the Calibration tool.
Polarity
Value
Meaning
eGridLinear
Linear calibration using a grid of dots.
eGridPolynomialOrder3
Third-order polynomial calibration using
a grid of dots.
eGridPolynomialOrder5
Fifth-order polynomial calibration using a
grid of dots.
enum Polarity;
This enumeration defines the polarity of the calibration grid image used to perform the
calibration.
CVL Class Reference
Value
Meaning
eDarkOnLight
The image consists of dark dots on a
light background.
eLightOnDark
The image consists of light dots on a
dark background.
eAutoDetect
The Calibration tool automatically
determines the polarity of the image.
755
ccCalibDefs
756
CVL Class Reference
ccCaliperBaseResultSet
#include <ch_cvl/caliper.h>
class ccCaliperBaseResultSet: public virtual ccPersistent;
Class Properties
Copyable
No
Derivable
No
Archiveable
Complex
This base class contains some of the results returned by both correlation and edge
mode.
You should not attempt to instantiate this class directly.
Note
Constructors/Destructors
ccCaliperBaseResultSet
ccCaliperBaseResultSet();
Constructs ccCaliperBaseResultSet with no results.
Operators
operator==
bool operator== (const ccCaliperBaseResultSet& that) const;
Two ccCaliperBaseResultSet objects are equal if and only if the following items are all
the same: the vectors of ccResults; the vectors of ccCaliperResultEdges; the caliper
data; the user-specified origin in client coordinates; the unit vectors in the search
direction; the run mode; the result angles; and the clipping status.
Public Member Functions
results
const cmStd vector<ccCaliperOneResult>& results () const;
Returns a vector of ccCaliperOneResult. Every edge or edge pair for which a score was
computed is included in the vector returned by this function.
CVL Class Reference
757
ccCaliperBaseResultSet
mapPositionToPoint
cc2Vect mapPositionToPoint (double position) const;
Map the given position within the projection region to a point in the client coordinates of
the input image. If the projection image was constructed by the Caliper tool, the position
is specified relative to the center of the projection region and the returned point lies on
the center line of the projection region in the input image, as shown in the following
figure:
position
Input image:
Projection window
center
Projection
direction
Returned point
If you supplied the projection image to the Caliper tool, then this function returns the
two-dimensional point within the input image specified by the distance from the origin
that you supplied.
Parameters
position
The position of interest, relative to either the center of the
projection region or to the origin that you supplied with the
projection image.
Notes
This function can be used to convert positions to 2-D client coordinates.
projectTime
double projectTime () const;
Returns the amount of time, in seconds, required to create the projection image.
filterTime
double filterTime () const;
Returns the amount of time, in seconds, required to create the filtered image.
758
CVL Class Reference
ccCaliperBaseResultSet
scoreTime
double scoreTime () const;
Returns the amount of time, in seconds, required to compute the scores for the edges
in the input image.
projectedImage
ccPelBuffer_const<c_UInt32> projectedImage () const;
Returns the projection image. This image was created by projecting the pixels within the
caliper window.
The cc2Xform returned by calling projectedImage()::clientFromImageXform() maps
two-dimensional points within the projection image to the corresponding points within
the input image client coordinate system, as shown in the following figure:
Px
Po
Projection
direction
Input image:
Py
Projection image:
weightsImage
ccPelBuffer_const<c_UInt32> weightsImage () const;
Return the weights image. If clipping occurred, each pixel in this image contains the
number of pixels that where summed together to produce the corresponding pixel in the
projected image.
To determine if clipping occurred, call the clipped() member function.
The image returned by this function is only valid if clipping occurred and if auto-clipping
mode is enabled.
CVL Class Reference
759
ccCaliperBaseResultSet
filteredImage
ccPelBuffer_const<double> filteredImage () const;
Return the filtered projection image. The width of the image returned by this function is
smaller than that returned by projectedImage(), but the client coordinate system of the
returned image lets you convert points between the projection image and the filtered
image.
projectedXFromPosition
cc1Xform projectedXFromPosition() const;
Returns a cc1Xform that can be used to map back and forth between a
one-dimensional position and the corresponding x-coordinate in the projection image,
as shown in the following figure:
x-coordinate
Center
Projection image:
position
filteredXFromPosition
cc1Xform filteredXFromPosition() const;
Returns a cc1Xform that can be used to map back and forth between a
one-dimensional position and the corresponding x-coordinate in the filtered image, as
shown in the following figure:
x-coordinate
Center
Filtered image:
position
760
CVL Class Reference
ccCaliperBaseResultSet
resultAngle
ccRadian resultAngle() const;
Returns the angle at which the Caliper tool was applied to generate this
ccCaliperBaseResultSet.
clipped
bool clipped() const;
Returns true if the source image was clipped by the projection region, false if no clipping
occurred.
CVL Class Reference
761
ccCaliperBaseResultSet
762
CVL Class Reference
ccCaliperBaseRunParams
#include <ch_cvl/caliper.h>
class ccCaliperBaseRunParams: public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
The ccCaliperBaseRunParams class is a base class from which the following two
run-time parameter classes are derived:
•
ccCaliperRunParams, which includes run-time parameters for edge mode
•
ccCaliperCorrelationRunParams, which includes run-time parameters for
correlation mode
The ccCaliperBaseRunParams class includes run-time parameters which are common
to both edge and correlation mode.
Note
CVL Class Reference
You should not attempt to instantiate this class directly.
763
ccCaliperBaseRunParams
Enumerations
Timer
enum Timer;
This enumeration specifies the type of timer used to compute times in the result with the
caliper tool.
Value
Meaning
eElapsedTime
Use the elapsed clock time in seconds.
Produces accurate results on all machine types, but the
overhead of computing the elapsed time can be
noticeable (several microseconds) when using a large
number of small (fast) calipers.
eScaledProcessorCycles
Use the number of processor cycles (scaled to
seconds).
Does not always produce accurate results on
machines with a variable clock rate, but has a much
lower overhead. Some machines (especially laptops)
may use a variable clock rate to conserve power.
Public Member Functions
scanParams
const ccCaliperScanParams& scanParams() const;
void scanParams(ccRadian start, ccRadian end,
ccRadian increment, bool interpolate);
•
const ccCaliperScanParams& scanParams() const;
Returns the ccCaliperScanParams object associated with this
ccCaliperBaseRunParams.
•
void scanParams(ccRadian start, ccRadian end,
ccRadian increment, bool interpolate);
Sets the parameters of the ccCaliperScanParams object associated with this
ccCaliperBaseRunParams.
Parameters
start
764
The start of the range of angles to be scanned in radians. The
angle is from the client coordinate system x-axis to the projection
direction.
CVL Class Reference
ccCaliperBaseRunParams
scanEnable
end
The end of the range of angles to be scanned in radians. The
angle is from the client coordinate system x-axis to the projection
direction.
increment
The amount by which to increment the angle between scans.
interpolate
If true, intermediate angles are evaluated.
bool scanEnable() const;
void scanEnable(bool on);
•
bool scanEnable() const;
Returns true if scan mode is enabled, false if it is disabled.
•
void scanEnable(bool on);
Enables or disables scan mode. If scan mode is enabled, the caliper is successively
applied at the angles specified in the ccCaliperScanParams. The angle which yields
the highest average score for all results is used to compute the score for the tool.
Parameters
on
autoClip
If true, scan mode is enabled. If false, scan mode is disabled.
bool autoClip() const;
void autoClip(bool state);
•
bool autoClip() const;
Returns true if auto-clipping mode is enabled, false if it is disabled.
•
void autoClip(bool state);
Enables or disables auto-clipping mode. If auto-clipping mode is enabled, if the
projection region is clipped by the input image, the projection image is automatically
resized to include only the pixels which were not affected by clipping. If auto-clipping
mode is disabled, the tool throws an error if the projection region is clipped by the input
image.
Parameters
state
CVL Class Reference
If true, auto-clipping mode is enabled. If false, auto-clipping
mode is disabled.
765
ccCaliperBaseRunParams
Notes
Enabling auto-clipping mode will cause the cfCaliperRun() function to run as much
as 10 times more slowly than when auto-clipping mode is disabled.
computeIntermediateTimes
bool computeIntermediateTimes() const;
void computeIntermediateTimes(bool val);
bool computeIntermediateTimes() const;
•
Returns true if the caliper tool should compute intermediate times for projection, filtering,
scoring, and edge or peak detection, false otherwise. If false, the getters for these times
will return zero.
void computeIntermediateTimes(bool val);
•
Sets whether the caliper tool should compute intermediate times for projection, filtering,
scoring, and edge or peak detection. If false, the getters for these times will return zero.
Parameters
val
Note
timerType
Set to true if the tool should calculate intermediate results, false
otherwise. The default is true.
Querying the system timer with QueryPerformanceCounter costs, for
example, ~1.7 microseconds on a 650 MHz system. Computing
intermediate times can thus add nontrivial overhead for very small
calipers. To get the fastest performance, turn timers off.
Timer timerType() const;
void timerType(Timer t);
•
Timer timerType() const;
Retrieves the type of timer used to compute times in the result.
•
void timerType(Timer t);
Sets the type of timer used to compute times in the result.
766
CVL Class Reference
ccCaliperBaseRunParams
Parameters
t
The type of timer. Must be one of:
ccCaliperBaseRunParams::eElapsedTime
ccCaliperBaseRunParams::eScaledProcessorCycles (default)
Note
CVL Class Reference
For fastest execution of multiple calipers, set calipers once in the
application code.
767
ccCaliperBaseRunParams
768
CVL Class Reference
ccCaliperCircleFinderAutoRunParams
#include <ch_cvl/clpfind.h>
class ccCaliperCircleFinderAutoRunParams :
public ccCaliperFinderBaseAutoRunParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
Encapsulates the Circle Finder tool run-time parameters for running the tool in auto
mode.
Constructors/Destructors
ccCaliperCircleFinderAutoRunParams
ccCaliperCircleFinderAutoRunParams (
const ccCircle &expectedCircle = ccCircle(),
c_Int16 numCalipers = 0,
const ccDPair &caliperSize = ccDPair(0, 0),
const ccCaliperRunParams &caliperRunParams =
ccCaliperRunParams(),
const ccDPair &caliperSampling = ccDPair(1, 1),
const ccAngleRange &angleRange =
ccAngleRange::FullAngleRange(),
ccAffineSamplingParams::Interpolation
interpolationMethod =
ccAffineSamplingParams::eBilinear,
const ccCircleFitParams &circleFitParams =
ccCircleFitParams(),
bool centrifugal = true,
const cc2Xform& startPose = cc2Xform(),
bool decrementNumIgnore = true,
bool placeCalipersSymmetrically = true);
virtual ~ccCaliperCircleFinderAutoRunParams() {}
•
ccCaliperCircleFinderAutoRunParams (
const ccCircle &expectedCircle = ccCircle(),
c_Int16 numCalipers = 0,
const ccDPair &caliperSize = ccDPair(0, 0),
CVL Class Reference
769
ccCaliperCircleFinderAutoRunParams
const ccCaliperRunParams &caliperRunParams =
ccCaliperRunParams(),
const ccDPair &caliperSampling = ccDPair(1, 1),
const ccAngleRange &angleRange =
ccAngleRange::FullAngleRange(),
ccAffineSamplingParams::Interpolation
interpolationMethod =
ccAffineSamplingParams::eBilinear,
const ccCircleFitParams &circleFitParams =
ccCircleFitParams(),
bool centrifugal = true,
const cc2Xform& startPose = cc2Xform(),
bool decrementNumIgnore = true,
bool placeCalipersSymmetrically = true);
Constructs a Circle Finder tool run-time parameters object.
Notes
Default constructed objects do not contain valid run-time parameters.
Parameters
expectedCircle
The circle you expect the tool to find in images.
numCalipers
The number of calipers the tool should use to find the circle.
caliperSize
The caliper size, width and height in client coordinates. All
calipers are the same size.
caliperRunParams
The run-time parameters object to be used when the Caliper tool
is run.
caliperSampling The sampling rate in samples/pixel for x and y, to be used on the
calipers. For example, the following calculates the number of
caliper samples in the x direction:
If xSize is caliperSize.x() in image coordinates, then the effective
number of samples in the x direction will be c_Int16(xSize * caliperSampling.x() + 0.5)
angleRange
770
The beginning angle and the ending angle of the angle range
where calipers will be placed along the expected circle
perimeter. Angles are measured from the x-axis in the positive
direction. The default is the full angular range.
CVL Class Reference
ccCaliperCircleFinderAutoRunParams
interpolationMethod
The interpolation method used with the calipers. Must be one of
the ccAffineSamplingParams::Interpolation enums. The
default is eBilinear.
See the ccAffineSamplingParams reference page.
circleFitParams
The run-time parameters to use with the Fitting tool.
centrifugal
When set true, the caliper search direction is outward from the
circle center. When set false, the caliper search direction is
inward. The default is true.
startPose
A transform that maps the expected circle from circle space to its
expected pose in the run-time client space.
decrementNumIgnore
When true, ccCircleFitParams::numIgnore is decremented for
each caliper that fails to find an edge. When false, no decrement
occurs.
placeCalipersSymmetrically
True specifies that the calipers should be placed at the center of
each evenly spaced section of the angleRange. False specifies
that the calipers be placed at the start of each evenly spaced
section. The default is true.
Note: The default mode (true) is always the appropriate choice
for placing the calipers. This is flag only exists for backward
compatibility. Users who do not require backwards compatibility
should not change the state of this flag.
Throws
ccCaliperFinderBaseDefs::BadParams
If numCalipers is not zero and is less than minNumCalipers(),
or if caliperSize is less than (0, 0),
or if caliperSampling is less than or equal to (0, 0),
or if angleRange is empty,
or if startPose is singular.
•
virtual ~ccCaliperCircleFinderAutoRunParams() {}
Destructor.
CVL Class Reference
771
ccCaliperCircleFinderAutoRunParams
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseRunParams& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperCircleFinderAutoRunParams objects are considered equal if, and only
if, all their members and base classes are equal.
Parameters
that
The ccCaliperCircleFinderAutoRunParams object to compare
to this object.
Public Member Functions
expectedCircle
const ccCircle &expectedCircle() const;
void expectedCircle(const ccCircle &expectedCircle);
The circle you expect to find in images processed by the Circle Finder tool. The
expected circle should be close to actual circles in the images.
•
const ccCircle &expectedCircle() const;
Returns the expected circle.
•
void expectedCircle(const ccCircle &expectedCircle);
Sets the expected circle.
Parameters
expectedCircle
The new expected circle.
Throws
ccCaliperFinderBaseDefs::BadParams
If expectedCircle radius is 0.
772
CVL Class Reference
ccCaliperCircleFinderAutoRunParams
angleRange
const ccAngleRange &angleRange() const;
void angleRange(const ccAngleRange &angleRange);
The beginning angle and the ending angle of the angle range where calipers will be
placed along the expected circle perimeter. Angles are measured from the x-axis in the
positive direction. The default is the full angular range.
•
const ccAngleRange &angleRange() const;
Returns the angle range.
•
void angleRange(const ccAngleRange &angleRange);
Sets a new angle range.
Parameters
angleRange
The new angle range.
Throws
ccCaliperFinderBaseDefs::BadParams
If angleRange is empty.
circleFitParams
const ccCircleFitParams &circleFitParams() const;
void circleFitParams(
const ccCircleFitParams &circleFitParams);
•
const ccCircleFitParams &circleFitParams() const;
Returns the circle fit parameters.
•
void circleFitParams(
const ccCircleFitParams &circleFitParams);
Sets new circle fit parameters.
Parameters
circleFitParams
CVL Class Reference
The new circle fit parameters.
773
ccCaliperCircleFinderAutoRunParams
centrifugal
bool centrifugal() const;
void centrifugal(bool centrifugal);
When set true, the caliper search direction is outward from the circle center. When set
false, the caliper search direction is inward. The default is true.
•
bool centrifugal() const;
Returns the centrifugal setting, true or false.
•
void centrifugal(bool centrifugal);
Sets the caliper search direction.
Parameters
centrifugal
minNumCalipers
The new caliper search direction.
virtual c_Int16 minNumCalipers() const;
Returns the minimum number of calipers required (3).
placeCalipersSymmetrically
bool placeCalipersSymmetrically() const;
void placeCalipersSymmetrically(bool symmetrically);
True specifies that the calipers should be placed at the center of each evenly spaced
section of the angleRange. False specifies that the calipers be placed at the start of
each evenly spaced section. The default is true.
Notes
The default mode (true) is always the appropriate choice for placing the calipers.
This is flag only exists for backward compatibility. Users who do not require
backwards compatibility should not change the state of this flag.
•
bool placeCalipersSymmetrically() const;
Returns the current specification, true or false.
•
void placeCalipersSymmetrically(bool symmetrically);
Sets a new specification.
774
CVL Class Reference
ccCaliperCircleFinderAutoRunParams
Parameters
symmetrically
The new specification.
Protected Member Functions
computeAffineSamplingParams_
virtual void computeAffineSamplingParams_();
Computes the affine sampling parameters of the calipers to be run from the current auto
run parameters.
Throws
ccCaliperFinderBaseDefs::BadParams
If any members have invalid values.
CVL Class Reference
775
ccCaliperCircleFinderAutoRunParams
776
CVL Class Reference
ccCaliperCircleFinderManualRunParams
#include <ch_cvl/clpfind.h>
class ccCaliperCircleFinderManualRunParams :
public ccCaliperFinderBaseManualRunParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
Encapsulates the Circle Finder tool run-time parameters for running the tool in manual
mode.
Constructors/Destructors
ccCaliperCircleFinderManualRunParams
ccCaliperCircleFinderManualRunParams (
const ccCircle &expectedCircle = ccCircle(),
const cmStd vector<ccAffineSamplingParams>& affParams =
cmStd vector<ccAffineSamplingParams>(),
const cmStd vector<ccCaliperRunParams>& clpParams =
cmStd vector<ccCaliperRunParams>(),
const ccCircleFitParams &circleFitParams =
ccCircleFitParams(),
const cc2Xform &startPose = cc2Xform(),
bool decrementNumIgnore = true);
virtual ~ccCaliperCircleFinderManualRunParams() {}
•
ccCaliperCircleFinderManualRunParams (
const ccCircle &expectedCircle = ccCircle(),
const cmStd vector<ccAffineSamplingParams>& affParams =
cmStd vector<ccAffineSamplingParams>(),
const cmStd vector<ccCaliperRunParams>& clpParams =
cmStd vector<ccCaliperRunParams>(),
const ccCircleFitParams &circleFitParams =
ccCircleFitParams(),
const cc2Xform &startPose = cc2Xform(),
bool decrementNumIgnore = true);
Constructs a circle finder manual run-time parameters object.
CVL Class Reference
777
ccCaliperCircleFinderManualRunParams
Notes
Default constructed objects do not contain valid run-time parameters.
Parameters
expectedCircle
The circle you expect the tool to find in images.
affParams
A vector of affine rectangle sampling parameters, one parameter
set for each caliper.
clpParams
A vector of caliper run-time parameters, one parameter set for
each caliper.
circleFitParams
The run-time parameters to use with the Fitting tool.
startPose
A transform that maps the expected circle from circle space to its
expected pose in the run-time client space.
decrementNumIgnore
When true, ccCircleFitParams::numIgnore is decremented for
each caliper that fails to find an edge. When false, no decrement
occurs.
Throws
ccCaliperFinderBaseDefs::BadParams
If affParams.size() is not equal to clpParams.size(),
or if params sizes are not zero and less than minNumCalipers(),
or if startPose is singular.
•
virtual ~ccCaliperCircleFinderManualRunParams() {}
Destructor.
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseRunParams& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperCircleFinderManualRunParams objects are considered equal if, and
only if, all their members and base classes are equal.
Parameters
that
778
The ccCaliperCircleFinderManualRunParams object to
compare to this object.
CVL Class Reference
ccCaliperCircleFinderManualRunParams
Public Member Functions
expectedCircle
const ccCircle &expectedCircle() const;
void expectedCircle(const ccCircle &expectedCircle);
The circle you expect to find in images processed by the Circle Finder tool. The
expected circle should be close to actual circles in the images.
•
const ccCircle &expectedCircle() const;
Returns the expected circle.
•
void expectedCircle(const ccCircle &expectedCircle);
Sets the expected circle.
Parameters
expectedCircle
The new expected circle.
Throws
ccCaliperFinderBaseDefs::BadParams
If expectedCircle radius is 0.
circleFitParams
const ccCircleFitParams &circleFitParams() const;
void circleFitParams(
const ccCircleFitParams &circleFitParams);
•
const ccCircleFitParams &circleFitParams() const;
Returns the circle fitter run-time parameters.
•
void circleFitParams(
const ccCircleFitParams &circleFitParams);
Sets new circle fit run-time parameters.
Parameters
circleFitParams
CVL Class Reference
The new circle fit run-time parameters.
779
ccCaliperCircleFinderManualRunParams
minNumCalipers
virtual c_Int16 minNumCalipers() const;
Returns the minimum number of calipers required (3).
780
CVL Class Reference
ccCaliperCircleFinderResult
#include <ch_cvl/clpfind.h>
class ccCaliperCircleFinderResult :
public ccCaliperFinderBaseResult;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class encapsulates the results from the Circle Finder tool.
Constructors/Destructors
ccCaliperCircleFinderResult
ccCaliperCircleFinderResult() {}
virtual ~ccCaliperCircleFinderResult() {}
•
ccCaliperCircleFinderResult() {}
Default constructor. Creates a default constructed (unfound) circle result object.
•
virtual ~ccCaliperCircleFinderResult() {}
Destructor.
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseResult& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperCircleFinderResult objects are considered equal if, and only if, all their
members and base classes are equal.
CVL Class Reference
781
ccCaliperCircleFinderResult
Parameters
that
The ccCaliperCircleFinderResult object to compare to this
object.
Public Member Functions
found
virtual bool found() const;
Returns true if a circle was found. Returns false otherwise.
A circle is found if its computed error is less than the error threshold specified in the
Circle Fitting tool parameters. See ccCircleFitParams::threshold().
circleFit
const ccCircleFitResults &circleFit() const;
Returns the circle fitting result.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
circle
const ccCircle &circle() const;
Returns the computed circle.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
position
const cc2Vect &position() const;
Returns the position of the computed circle.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
radius
double radius() const;
Returns the radius of the computed circle.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
782
CVL Class Reference
ccCaliperCircleFinderResult
circleFitTime
double circleFitTime() const;
Returns the circle fitting time, in seconds.
CVL Class Reference
783
ccCaliperCircleFinderResult
784
CVL Class Reference
ccCaliperCorrelationResultSet
#include <ch_cvl/caliper.h>
class ccCaliperCorrelationResultSet :
public ccCaliperBaseResultSet;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class contains the results returned by a single application of the Caliper tool to an
input image in correlation mode. Results common to both modes can be found in
ccCaliperBaseResultSet.
Constructors/Destructors
ccCaliperCorrelationResultSet
ccCaliperCorrelationResultSet ();
Constructs a ccCaliperCorrelationResultSet with no results.
operator==
bool operator== (const ccCaliperCorrelationResultSet& that)
const;
Two ccCaliperCorrelationResultSet objects are equal if and only if the following items
are all the same: the vectors of ccResults; the caliper data; the user-specified origin in
client coordinates; the unit vectors in the search direction; the run mode; the result
angles; and the clipping status.
Public Member Functions
peakDetectTime
double peakDetectTime () const;
Returns the amount of time, in seconds, required to perform peak detection.
CVL Class Reference
785
ccCaliperCorrelationResultSet
runMode
ccCaliperDefs::RunMode runMode();
Returns the mode in which the caliper was run to generate this
ccCaliperCorrelationResultSet. The returned value is one of the following values:
ccCaliperDefs::eEdge
ccCaliperDefs::eNormalizedCorrelation
ccCaliperDefs::eRelativeCorrelation
draw
void draw(
ccGraphicList& graphList,
c_UInt32 drawMode = ccCaliperDefs::eDrawStandard,
double plotHeight = ccCaliperDefs::kDefaultPlotHeight)
const;
Appends result graphics for all the results in this ccCaliperCorrelationResultSet to the
supplied ccGraphicList.
Parameters
graphList
drawMode
The graphics list to append the graphics to.
The drawing mode to use. drawMode must be composed by
ORing together one or more of the following values:
ccCaliperDefs::eDrawEdgeLine
ccCaliperDefs::eDrawLabel
ccCaliperDefs::eDrawProjFilter
ccCaliperDefs::eDrawProjectionRegion
ccCaliperDefs::eDrawStandard
ccCaliperDefs::eDrawRawEdges
plotHeight
786
The height of the projection and filter plots, in client coordinates.
CVL Class Reference
ccCaliperCorrelationRunParams
#include <ch_cvl/caliper.h>
class ccCaliperCorrelationRunParams:
public ccCaliperBaseRunParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Complex
This class contains the run-time parameters for the Caliper tool used in correlation
mode, including the reference image.
Constructors/Destructors
ccCaliperCorrelationRunParams
ccCaliperCorrelationRunParams();
ccCaliperCorrelationRunParams(
const ccPelBuffer_const<c_UInt8>& refSrc,
ccCaliperDefs::RunMode mode =
ccCaliperDefs::eNormalizedCorrelation,
const cc2Vect& origin = cc2Vect(0,0));
ccCaliperCorrelationRunParams(
const ccPelBuffer_const<c_UInt8>& src,
ccAffineSamplingParams affSamp,
ccCaliperDefs::RunMode mode =
ccCaliperDefs::eNormalizedCorrelation,
const cc2Vect& origin = cc2Vect(0,0));
ccCaliperCorrelationRunParams(
const ccPelBuffer_const<c_UInt32>& refSrc,
int nPelsPerBin,
CVL Class Reference
787
ccCaliperCorrelationRunParams
ccCaliperDefs::RunMode mode =
ccCaliperDefs::eNormalizedCorrelation,
const cc2Vect& origin = cc2Vect(0,0));
•
ccCaliperCorrelationRunParams();
Constructs a ccCaliperCorrelationRunParams with no reference image. This
ccCaliperCorrelationRunParams will not be usable until you supply a reference
image.
•
ccCaliperCorrelationRunParams(
const ccPelBuffer_const<c_UInt8>& refSrc,
ccCaliperDefs::RunMode mode =
ccCaliperDefs::eNormalizedCorrelation,
const cc2Vect& origin = cc2Vect(0,0));
Constructs a ccCaliperCorrelationRunParams using the supplied one-dimensional
image as the reference image. You must specify the location of the origin in client
coordinates.
Parameters
refSrc
mode
The image to use. refSrc must have an y-dimension equal to 1
pixel.
The correlation mode to use. mode must be one of the following
values:
ccCaliperDefs::eNormalizedCorrelation
ccCaliperDefs::eRelativeCorrelation
origin
The origin of the reference image. Correlation peaks will be
reported with respect to this origin. origin must be specified in
refSrc’s client coordinate system. The y-coordinate of origin is
ignored.
Notes
The default value of the peak separation threshold is set to the width of the refSrc.
Throws
ccCaliperDefs::BadParams
mode is not ccCaliperDefs::eNormalizedCorrelation or
ccCaliperDefs::eRelativeCorrelation or refSrc.height() is not 1.
•
788
ccCaliperCorrelationRunParams(
const ccPelBuffer_const<c_UInt8>& src,
ccAffineSamplingParams affSamp,
CVL Class Reference
ccCaliperCorrelationRunParams
ccCaliperDefs::RunMode mode =
ccCaliperDefs::eNormalizedCorrelation,
const cc2Vect& origin = cc2Vect(0,0));
Constructs a ccCaliperCorrelationRunParams. The reference image is constructed by
applying the supplied affine sampling parameters to the supplied two-dimensional
image. You must specify the location of the origin in client coordinates.
Parameters
src
The image to use to generate the reference image.
affSamp
The affine sampling parameters with which to sample src.
mode
The correlation mode to use. mode must be one of the following
values:
ccCaliperDefs::eNormalizedCorrelation
ccCaliperDefs::eRelativeCorrelation
origin
The origin of the reference image. Correlation peaks will be
reported with respect to this origin. origin must be specified in
src’s client coordinate system. The origin is transformed to the
projection image produced by applying affSamp to src.
Notes
The default value of the peak separation threshold is set to the width of the image
produced by applying affSamp to src.
Throws
ccCaliperDefs::BadParams
mode is not ccCaliperDefs::eNormalizedCorrelation or
ccCaliperDefs::eRelativeCorrelation.
•
ccCaliperCorrelationRunParams(
const ccPelBuffer_const<c_UInt32>& refSrc,
int nPelsPerBin,
ccCaliperDefs::RunMode mode =
ccCaliperDefs::eNormalizedCorrelation,
const cc2Vect& origin = cc2Vect(0,0));
Constructs a ccCaliperCorrelationRunParams using the supplied one-dimensional
image as the reference image after normalizing each pixel of the image using the
supplied normalization value. You must specify the location of the origin in client
coordinates.
CVL Class Reference
789
ccCaliperCorrelationRunParams
Parameters
refSrc
The image to use. refSrc must have a y-dimension equal to 1
pixel.
nPelsPerBin
The number of pixels that were summed to produce each value
in refSrc. Each pixel value in refSrc is divided by nPelsPerBin.
mode
The correlation mode to use. mode must be one of the following
values:
ccCaliperDefs::eNormalizedCorrelation
ccCaliperDefs::eRelativeCorrelation
origin
The origin of the reference image. Correlation peaks will be
reported with respect to this origin. origin must be specified in
refSrc’s client coordinate system. The y-coordinate of origin is
ignored.
Throws
ccCaliperDefs::BadParams
mode is not ccCaliperDefs::eNormalizedCorrelation or
ccCaliperDefs::eRelativeCorrelation; refSrc.height() is not 1; or
nPelsPerBin is less than 1.
Public Member Functions
ref1DCorrelation
void ref1DCorrelation(
const ccPelBuffer_const<c_UInt8>& ref1D,
const cc2Vect& origin= cc2Vect(0,0));
void ref1DCorrelation(cmStd vector<ccIPair> refValues,
int smooth=0, double origin = 0.0);
void ref1DCorrelation(cmStd vector<c_UInt8> refValues,
double origin= 0.0);
void ref1DCorrelation(
ccCaliperDefs::PreDefined1DSignal refSignal,
c_UInt32 width, c_UInt8 max, c_UInt8 min, int smooth=0,
double origin = 0.0);
•
void ref1DCorrelation(
const ccPelBuffer_const<c_UInt8>& ref1D,
const cc2Vect& origin= cc2Vect(0,0));
Sets this ccCaliperCorrelationRunParams’s reference image to be the supplied
one-dimensional image. You must specify the location of the origin in client coordinates.
790
CVL Class Reference
ccCaliperCorrelationRunParams
Parameters
ref1D
origin
The image to use. ref1D must have a y-dimension equal to 1
pixel.
The origin of the reference image. Correlation peaks will be
reported with respect to this origin. origin must be specified in
refSrc’s client coordinate system. The y-coordinate of origin is
ignored.
Notes
The default value of the peak separation threshold is set to the width of the refSrc.
Throws
ccFiltErr::BadImageSize
ref1D.height() is not 1 or ref1D.width() is less than 1.
•
void ref1DCorrelation(cmStd vector<ccIPair> refValues,
int smooth=0, double origin = 0.0);
Sets this ccCaliperCorrelationRunParams’s reference image to be the supplied vector
of run-length codes. Any specified smoothing value is used as input to the Gaussian
Sampling tool to smooth the image produced from the list of run-length codes. The origin
is specified in the image coordinate system of the image produced from the list of
run-length codes.
Parameters
refValues
A vector of run-length codes. Each element of refValues is
interpreted as follows: refValues.x() is the number of pixels in the
run and refValues.y() is the pixel value of the run.
smooth
The smoothing value.
origin
The reference image origin, specified in image coordinates of the
image produced from refValues.
Notes
The default value of the peak separation threshold is set to the width of the refSrc.
Throws
ccFiltErr::BadImageSize
refValues contains less than 1 element.
ccCaliperDefs::BadParams
smooth is less than 0.
CVL Class Reference
791
ccCaliperCorrelationRunParams
•
void ref1DCorrelation(cmStd vector<c_UInt8> refValues,
double origin= 0.0);
Sets this ccCaliperCorrelationRunParams’s reference image to be the supplied vector
of values. The origin is specified in the image coordinate system of the image produced
from the list of values.
Parameters
refValues
origin
A vector of 8-bit pixel values.
The reference image origin, specified in image coordinates of the
image produced from refValues.
Notes
The default value of the peak separation threshold is set to the width of the refSrc.
Throws
ccFiltErr::BadImageSize
refValues contains less than 1 element.
•
void ref1DCorrelation(
ccCaliperDefs::PreDefined1DSignal refSignal,
c_UInt32 width, c_UInt8 max, c_UInt8 min, int smooth=0,
double origin = 0.0);
Sets this ccCaliperCorrelationRunParams’s reference image to be the specified
pre-defined reference image. The origin is specified in the image coordinate system of
the image.
If you specify ccCaliperDefs::ePosGauss or ccCaliperDefs::eNegGauss, this function
applies a Gaussian kernel with a sigma equal to one fourth of the width of the image.
You can override this kernel size.
Parameters
refSignal
The pre-defined reference image. refSignal must be one of the
following values:
ccCaliperDefs::ePosPulse
ccCaliperDefs::eNegPulse
ccCaliperDefs::ePosGauss
ccCaliperDefs::eNegGauss
792
width
The width of the reference signal. The overall width of the
resulting image is equal to width+2.
max
The maximum value of the image. For ccCaliperDefs::ePosPulse
and ccCaliperDefs::ePosGauss, max is the value of the peak.
CVL Class Reference
ccCaliperCorrelationRunParams
max
The minimum value of the image. For ccCaliperDefs::eNegPulse
and ccCaliperDefs::eNegGauss, max is the value of the peak.
smooth
The smoothing value to apply to produce a Gaussian reference
image. Set smooth to a positive value to override the default
smoothing value. The resulting sigma will be approximately 1.5
times smooth.
Throws
ccFiltErr::BadImageSize
width is less than 1.
ccCaliperDefs::BadParams
max is less than min or smooth is less than 0.
ccFiltErr::BadImageSize
width is less than 1.
acceptThreshold
double acceptThreshold() const;
void acceptThreshold(double thresh);
•
double acceptThreshold() const;
Returns the accept threshold for this ccCaliperCorrelationRunParams. Only
correlation peaks with correlation scores greater than this threshold are scored.
•
void acceptThreshold(double thresh);
Sets the accept threshold for this ccCaliperCorrelationRunParams. Only correlation
peaks with correlation scores greater than this threshold are scored.
The default accept threshold is 0.
Parameters
thresh
The accept threshold. thresh must be in the range 0 to 1000.
Throws
ccCaliperDefs::BadParams
thresh is less than 0 or greater than 1000.
CVL Class Reference
793
ccCaliperCorrelationRunParams
Notes
Keep in mind that correlation scores differ depending on the type of correlation. For
normalized correlation, scores range between 0 and 1000. For relative correlation,
scores range between 0 and the maximum value that can be stored by a pixel in
the input image (255 for 8-bit images).
runMode
ccCaliperDefs::RunMode runMode() const;
void runMode(ccCaliperDefs::RunMode mode, double thresh);
•
ccCaliperDefs::RunMode runMode() const;
Returns the type of correlation for this ccCaliperCorrelationRunParams.
•
void runMode(ccCaliperDefs::RunMode mode, double thresh);
Sets the type of correlation for this ccCaliperCorrelationRunParams.
Parameters
mode
The correlation mode. mode must be one of the following values:
ccCaliperDefs::eNormalizedCorrelation
ccCaliperDefs::eRelativeCorrelation
thresh
The accept threshold for this ccCaliperCorrelationRunParams.
See acceptThreshold() on page 793 for information on the
accept threshold.
Throws
ccCaliperDefs::BadParams
mode is not ccCaliperDefs::eNormalizedCorrelation or
ccCaliperDefs::eRelativeCorrelation.
maxNumResults
c_Int16 maxNumResults () const;
void maxNumResults (c_Int16 num);
•
c_Int16 maxNumResults () const;
Returns the maximum number of results that this ccCaliperCorrelationRunParams is
configured to return.
void maxNumResults (c_Int16 num);
Sets the maximum number of results that this ccCaliperCorrelationRunParams is
configured to return.
794
CVL Class Reference
ccCaliperCorrelationRunParams
Parameters
num
The maximum number of results to return. If you specify 0 for
num, the tool will perform the projection, filtering, and peak
detection steps, but it will not produce any scored results.
Throws
ccCaliperDefs::BadParams
num is less than 0.
scoringMethods
const cmStd vector<ccCaliperScore*> scoringMethods() const;
void scoringMethods (
const cmStd vector<ccCaliperScore*>& methods);
•
const cmStd vector<ccCaliperScore*> scoringMethods() const;
Returns a vector of ccCaliperScore objects that define how correlation peaks are
scored.
•
void scoringMethods (
const cmStd vector<ccCaliperScore*>& methods);
Sets the list of ccCaliperScore objects that determine how correlation peaks are
scored. Any existing list of ccCaliperScore objects is discarded.
The only legal type of scoring object for correlation mode is ccScoreContrast.
Parameters
methods
The scoring methods to set.
Notes
If methods contains no objects (has a length of 0), then any attempt to run the
Caliper tool with a value for the maximum number of results other than 0 will throw
an error.
A default-constructed ccCaliperCorrelationRunParams object contains a single
ccScoreContrast scoring method.
Throws
ccCaliperDefs::BadParams
An element of method is not of type ccScoreContrast.
CVL Class Reference
795
ccCaliperCorrelationRunParams
peakSeparationThreshold
double peakSeparationThreshold() const;
void peakSeparationThreshold(double peakSep);
•
double peakSeparationThreshold() const;
Returns the peak separation threshold configured for this
ccCaliperCorrelationRunParams.
•
void peakSeparationThreshold(double peakSep);
Sets the peak separation threshold configured for this
ccCaliperCorrelationRunParams.
The peak separation threshold is the minimum distance, in client coordinate system
units, between separate peaks. Peaks that are closer together than the threshold are
treated as a single peak; the peak with the lower score is discarded.
Parameters
peakSep
796
The peak separation threshold.
CVL Class Reference
ccCaliperDefs
#include <ch_cvl/caliper.h>
class ccCaliperDefs;
A name space class for the Caliper tool.
Enumerations
Interpolation
enum Interpolation;
This enumeration defines the sampling types supported by the Caliper tool.
RunMode
Value
Meaning
eNone
Nearest neighbor sampling is used to
construct the projection image.
eBilinear
Bilinear interpolation is used to construct
the projection image.
kDefaultInterpolation
The default sampling method, as defined
in caliper.h.
enum RunMode;
This enumeration defines the modes supported by the Caliper tool.
CVL Class Reference
Value
Meaning
eEdge
Features are located by detecting and
scoring of edge peaks and edge pair
peaks.
eNormalizedCorrelation
Features are located be detecting and
scoring normalized correlation peaks
between run-time and reference images.
eRelativeCorrelation
Features are located be detecting and
scoring relative correlation peaks
between run-time and reference images.
kDefaultRunMode
The default mode, as defined in
caliper.h.
797
ccCaliperDefs
PreDefined1DSignal
enum PreDefined1DSignal;
This enumeration defines the pre-defined reference signals available for correlation
mode.
DrawMode
Value
Meaning
ePosPulse
A boxcar signal going from low to high to
low.
eNegPulse
A boxcar signal going from high to low to
high.
ePosGauss
A boxcar signal going from low to high to
low which has been smoothed using a
Gaussian filter.
eNegGauss
A boxcar signal going from high to low to
high which has been smoothed using a
Gaussian filter.
enum DrawMode;
This enumeration defines the types of result graphics you can draw for Caliper tool
results.
798
Value
Meaning
eDrawEdgeLine
Draws a line at the location of each
detected edge.
eDrawLabel
Draws a text label at each detected
edge.
eDrawProjFilter
Draws a graphical representation of the
filtered projection image and projection
image at the top and bottom
(respectively) of the bounding box for
the result.
eDrawProjectionRegion
Draws a box describing the projection
region.
eDrawStandard
Draws a labeled line for each detected
edge, and draws a box around the
projection region.
CVL Class Reference
ccCaliperDefs
Notes
Edges and labels are drawn in ccColor::greenColor(), projected and filtered
images are drawn in ccColor::cyanColor(), bounding boxes are drawn in
ccColor::magentaColor(), and projection region is drawn in
ccColor::blueColor().
ResultSetDrawMode
enum ResultSetDrawMode;
This enumeration defines the types of result graphics you can draw for Caliper tool
results.
Value
Meaning
eDrawRawEdges
Draws a ccColor::redColor() line at
each edge detected in the projection
image.
enum { kDefaultPlotHeight = 30 };
CVL Class Reference
799
ccCaliperDefs
800
CVL Class Reference
ccCaliperDesiredEdge
#include <ch_cvl/caliper.h>
class ccCaliperDesiredEdge;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class describes a single edge. This class is constructed automatically by the
Caliper tool. You specify the location and polarity of the model edge or edges when you
construct a ccCaliperRunParams.
You should not construct a ccCaliperDesiredEdge directly.
Note
Constructors/Destructors
ccCaliperDesiredEdge
ccCaliperDesiredEdge (double position = 0.0,
ceEdgePolarity polarity = ceDontCare);
Construct this edge using the specified parameters.
Parameters
position
polarity
The expected position of this edge with respect to the edge
model origin in input image client coordinate system units.
The expected polarity of the edge. polarity must be one of the
following values:
ceDarkToLight
ceLightToDark
ceDontCare
A value of ceDontCare means the edge has either polarity.
CVL Class Reference
801
ccCaliperDesiredEdge
Public Member Functions
position
double position () const;
void position (double pos);
•
double position () const;
Return the position of this edge with respect to the model origin. The position is a signed
value in client coordinate system units.
•
void position (double pos);
Sets the position of this edge with respect to the model origin. The position is a signed
value in client coordinate units.
Parameters
pos
The position to set.
Notes
The positions returned by the Caliper tool’s cfCaliperRun() function indicate the
distance between the model origin and the center of the caliper window (or another,
user-supplied origin)
polarity
ceEdgePolarity polarity () const;
void polarity (ceEdgePolarity pol);
•
ceEdgePolarity polarity () const;
Returns the polarity of this edge. The polarity is defined as being measured in the
ascending x-axis direction of the projection image. The value returned by this function
is one of the following:
ceDarkToLight
ceLightToDark
ceDontCare
•
void polarity (ceEdgePolarity pol);
Sets the polarity of this edge. The polarity is defined as being measured in the
ascending x-axis direction of the projection image.
Parameters
pol
802
The polarity to set. pol must be one of the following values:
CVL Class Reference
ccCaliperDesiredEdge
ceDarkToLight
ceLightToDark
ceDontCare
CVL Class Reference
803
ccCaliperDesiredEdge
804
CVL Class Reference
ccCaliperEllipseFinderAutoRunParams
#include <ch_cvl/clpfind.h>
class ccCaliperEllipseFinderAutoRunParams :
public ccCaliperFinderBaseAutoRunParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
Encapsulates the Ellipse Finder tool run-time parameters for running the tool in auto
mode.
Constructors/Destructors
ccCaliperEllipseFinderAutoRunParams
ccCaliperEllipseFinderAutoRunParams();
ccCaliperEllipseFinderAutoRunParams (
const ccEllipse2 &expectedEllipse,
c_Int16 numCalipers = 0,
const ccDPair &caliperSize = ccDPair(0, 0),
const ccCaliperRunParams &caliperRunParams =
ccCaliperRunParams(),
const ccDPair &caliperSampling = ccDPair(1, 1),
const ccAngleRange &angleRange =
ccAngleRange::FullAngleRange(),
ccAffineSamplingParams::Interpolation
interpolationMethod =
ccAffineSamplingParams::eBilinear,
const ccEllipseFitParams &ellipseFitParams =
ccEllipseFitParams(),
bool centrifugal = true,
const cc2Xform& startPose = cc2Xform(),
bool decrementNumIgnore = true);
virtual ~ccCaliperEllipseFinderAutoRunParams() {}
•
ccCaliperEllipseFinderAutoRunParams();
Default constructor.
CVL Class Reference
805
ccCaliperEllipseFinderAutoRunParams
Notes
A default constructed object is not valid for running.
•
ccCaliperEllipseFinderAutoRunParams (
const ccEllipse2 &expectedEllipse,
c_Int16 numCalipers = 0,
const ccDPair &caliperSize = ccDPair(0, 0),
const ccCaliperRunParams &caliperRunParams =
ccCaliperRunParams(),
const ccDPair &caliperSampling = ccDPair(1, 1),
const ccAngleRange &angleRange =
ccAngleRange::FullAngleRange(),
ccAffineSamplingParams::Interpolation
interpolationMethod =
ccAffineSamplingParams::eBilinear,
const ccEllipseFitParams &ellipseFitParams =
ccEllipseFitParams(),
bool centrifugal = true,
const cc2Xform& startPose = cc2Xform(),
bool decrementNumIgnore = true);
Constructs a ellipse finder run-time parameters object.
Parameters
expectedEllipse The ellipse you expect the tool to find in images.
numCalipers
The number of calipers the tool should use to find the ellipse.
caliperSize
The caliper size, width and height in client coordinates. All
calipers are the same size.
caliperRunParams
The run-time parameters object to be used when the Caliper tool
is run.
caliperSampling The sampling rate in samples/pixel for x and y, to be used on the
calipers. For example, the following calculates the number of
caliper samples in the x direction:
If xSize is caliperSize.x() in image coordinates, then the effective
number of samples in the x direction will be c_Int16(xSize * caliperSampling.x() + 0.5)
angleRange
806
The beginning angle and the ending angle of the angle range
where calipers will be placed along the expected ellipse
perimeter. Angles are measured from the x-axis in the positive
direction around a unit circle centered inside the ellipse. The
CVL Class Reference
ccCaliperEllipseFinderAutoRunParams
angle range along the unit circle perimeter is projected outward
onto the ellipse perimeter. See the Shape Finder Tool chapter of
the Vision Tools Guide for details.
The default is the full angular range.
interpolationMethod
The interpolation method used with the calipers. Must be one of
the ccAffineSamplingParams::Interpolation enums. The
default is eBilinear.
See the ccAffineSamplingParams reference page.
ellipseFitParams The run-time parameters to use with the Fitting tool.
centrifugal
When set true, the caliper search direction is outward from the
ellipse center. When set false, the caliper search direction is
inward. The default is true.
startPose
A transform that maps the expected ellipse from ellipse space to
its expected pose in the run-time client space.
decrementNumIgnore
When true, ccEllipseFitParams::numIgnore is decremented for
each caliper that fails to find an edge. When false, no decrement
occurs.
Throws
ccCaliperFinderBaseDefs::BadParams
If numCalipers is not zero and is less than minNumCalipers(),
or if caliperSize is less than (0, 0),
or if caliperSampling is less than or equal to (0, 0),
or if angleRange is empty,
or if startPose is singular.
•
virtual ~ccCaliperEllipseFinderAutoRunParams() {}
Destructor.
CVL Class Reference
807
ccCaliperEllipseFinderAutoRunParams
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseRunParams& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperEllipseFinderAutoRunParams objects are considered equal if, and
only if, all their members and base classes are equal.
Parameters
that
The ccCaliperEllipseFinderAutoRunParams object to
compare to this object.
Public Member Functions
expectedEllipse
ccEllipse2 &expectedEllipse2() const;
void expectedEllipse2(const ccEllipse2 &expectedEllipse);
The ellipse you expect to find in images processed by the Ellipse Finder tool. The
expected ellipse should be close to actual ellipses in the images.
•
ccEllipse2 &expectedEllipse2() const;
Returns the expected ellipse.
•
void expectedEllipse2(const ccEllipse2 &expectedEllipse);
Sets a new expected ellipse.
Parameters
expectedEllipse The new expected ellipse.
Throws
ccCaliperFinderBaseDefs::BadParams
If an expectedEllipse radius is 0.
808
CVL Class Reference
ccCaliperEllipseFinderAutoRunParams
angleRange
const ccAngleRange &angleRange() const;
void angleRange(const ccAngleRange &angleRange);
The beginning angle and the ending angle of the angle range where calipers will be
placed along the expected ellipse perimeter. Angles are measured from the x-axis in the
positive direction around a unit circle centered inside the ellipse. The angle range along
the unit circle perimeter is projected outward onto the ellipse perimeter. See the Shape
Finder Tool chapter of the Vision Tools Guide for details.
The default is the full angular range.
Notes
This angle range is not in client coordinates. It is in the intrinsic coordinates of the ellipse
to be consistent with the ccEllipseArc and ccEllipseAnnulusSection classes.
Therefore, be careful when the ellipse’s aspect ratio changes because of a transform
since the angle range will mean something very different. For more information, see the
ccEllipse, ccEllipseArc, and ccEllipseAnnulusSection reference pages.
•
const ccAngleRange &angleRange() const;
Returns the angle range.
•
void angleRange(const ccAngleRange &angleRange);
Sets a new angle range.
Parameters
angleRange
The new angle range.
Throws
ccCaliperFinderBaseDefs::BadParams
If angleRange is empty.
ellipseFitParams
const ccEllipseFitParams &ellipseFitParams() const;
void ellipseFitParams(
const ccEllipseFitParams &ellipseFitParams);
•
const ccEllipseFitParams &ellipseFitParams() const;
Returns the ellipse fit parameters.
CVL Class Reference
809
ccCaliperEllipseFinderAutoRunParams
•
void ellipseFitParams(
const ccEllipseFitParams &ellipseFitParams);
Sets new ellipse fit parameters.
Parameters
ellipseFitParams The new ellipse fit parameters.
centrifugal
bool centrifugal() const;
void centrifugal(bool centrifugal);
When set true, the caliper search direction is outward from the ellipse center. When set
false, the caliper search direction is inward. The default is true.
•
bool centrifugal() const;
Returns the centrifugal setting, true or false.
•
void centrifugal(bool centrifugal);
Sets the caliper search direction.
Parameters
centrifugal
minNumCalipers
The new caliper search direction.
virtual c_Int16 minNumCalipers() const;
Returns the minimum number of calipers required (5).
Deprecated Members
The following have been deprecated and are provided here for backward compatibility
only.
expectedEllipse
const ccEllipse &expectedEllipse() const;
void expectedEllipse(const ccEllipse &expectedEllipse);
The ellipse you expect to find in images processed by the Ellipse Finder tool. The
expected ellipse should be close to actual ellipses in the images.
810
CVL Class Reference
ccCaliperEllipseFinderAutoRunParams
ccCaliperEllipseFinderAutoRunParams
ccCaliperEllipseFinderAutoRunParams (
const ccEllipse &expectedEllipse,
c_Int16 numCalipers = 0,
const ccDPair &caliperSize = ccDPair(0, 0),
const ccCaliperRunParams &caliperRunParams =
ccCaliperRunParams(),
const ccDPair &caliperSampling = ccDPair(1, 1),
const ccAngleRange &angleRange =
ccAngleRange::FullAngleRange(),
ccAffineSamplingParams::Interpolation
interpolationMethod =
ccAffineSamplingParams::eBilinear,
const ccEllipseFitParams &ellipseFitParams =
ccEllipseFitParams(),
bool centrifugal = true,
const cc2Xform& startPose = cc2Xform(),
bool decrementNumIgnore = true);
Constructor.
CVL Class Reference
811
ccCaliperEllipseFinderAutoRunParams
812
CVL Class Reference
ccCaliperEllipseFinderManualRunParams
#include <ch_cvl/clpfind.h>
class ccCaliperEllipseFinderManualRunParams :
public ccCaliperFinderBaseManualRunParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
Encapsulates the Ellipse Finder tool run-time parameters for running the tool in manual
mode.
Constructors/Destructors
ccCaliperEllipseFinderManualRunParams
ccCaliperEllipseFinderManualRunParams() :
ccCaliperFinderBaseManualRunParams(cc2Xform(), true) {}
ccCaliperEllipseFinderManualRunParams (
const ccEllipse2 &expectedEllipse,
const cmStd vector<ccAffineSamplingParams>& affParams =
cmStd vector<ccAffineSamplingParams>(),
const cmStd vector<ccCaliperRunParams>& clpParams =
cmStd vector<ccCaliperRunParams>(),
const ccEllipseFitParams &ellipseFitParams =
ccEllipseFitParams(),
const cc2Xform &startPose = cc2Xform(),
bool decrementNumIgnore = true);
virtual ~ccCaliperEllipseFinderManualRunParams() {}
•
ccCaliperEllipseFinderManualRunParams() :
ccCaliperFinderBaseManualRunParams(cc2Xform(), true) {}
Default constructor.
Notes
A default constructed object is not valid for running.
CVL Class Reference
813
ccCaliperEllipseFinderManualRunParams
•
ccCaliperEllipseFinderManualRunParams (
const ccEllipse2 &expectedEllipse,
const cmStd vector<ccAffineSamplingParams>& affParams =
cmStd vector<ccAffineSamplingParams>(),
const cmStd vector<ccCaliperRunParams>& clpParams =
cmStd vector<ccCaliperRunParams>(),
const ccEllipseFitParams &ellipseFitParams =
ccEllipseFitParams(),
const cc2Xform &startPose = cc2Xform(),
bool decrementNumIgnore = true);
Constructs a ellipse finder manual run-time parameters object.
Parameters
expectedEllipse The ellipse you expect the tool to find in images.
affParams
A vector of affine rectangle sampling parameters, one parameter
set for each caliper.
clpParams
A vector of caliper run-time parameters, one parameter set for
each caliper.
ellipseFitParams The run-time parameters to use with the Fitting tool.
startPose
A transform that maps the expected ellipse from ellipse space to
its expected pose in the run-time client space.
decrementNumIgnore
When true, ccEllipseFitParams::numIgnore is decremented for
each caliper that fails to find an edge. When false, no decrement
occurs.
Throws
ccCaliperFinderBaseDefs::BadParams
If affParams.size() is not equal to clpParams.size(),
or if params sizes are not zero and less than minNumCalipers(),
or if startPose is singular.
•
virtual ~ccCaliperEllipseFinderManualRunParams() {}
Destructor.
814
CVL Class Reference
ccCaliperEllipseFinderManualRunParams
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseRunParams& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperEllipseFinderManualRunParams objects are considered equal if, and
only if, all their members and base classes are equal.
Parameters
that
The ccCaliperEllipseFinderManualRunParams object to
compare to this object.
Public Member Functions
expectedEllipse2
ccEllipse2 expectedEllipse() const;
void expectedEllipse2(const ccEllipse2 &expectedEllipse);
The ellipse you expect to find in images processed by the Ellipse Finder tool. The
expected ellipse should be close to actual ellipses in the images.
•
ccEllipse2 expectedEllipse() const;
Returns the expected ellipse.
•
void expectedEllipse2(const ccEllipse2 &expectedEllipse);}
Sets a new expected ellipse.
Parameters
expectedEllipse The new expected ellipse.
Throws
ccCaliperFinderBaseDefs::BadParams
If an expectedEllipse radius is 0.
CVL Class Reference
815
ccCaliperEllipseFinderManualRunParams
ellipseFitParams
const ccEllipseFitParams &ellipseFitParams() const;
void ellipseFitParams(
const ccEllipseFitParams &ellipseFitParams);
•
const ccEllipseFitParams &ellipseFitParams() const;
Returns the ellipse fitter run-time parameters.
•
void ellipseFitParams(
const ccEllipseFitParams &ellipseFitParams);
Sets new ellipse fitter run-time parameters.
Parameters
ellipseFitParams The new parameters.
minNumCalipers
virtual c_Int16 minNumCalipers() const;
Returns the minimum number of calipers required (5).
Deprecated Members
The following have been deprecated and are provided here only for backward
compatibility.
expectedEllipse
const ccEllipse &expectedEllipse() const;
void expectedEllipse(const ccEllipse &expectedEllipse);
The ellipse you expect to find in images processed by the Ellipse Finder tool. The
expected ellipse should be close to actual ellipses in the images.
ccCaliperEllipseFinderManualRunParams
ccCaliperEllipseFinderManualRunParams (
const ccEllipse &expectedEllipse,
const cmStd vector<ccAffineSamplingParams>& affParams =
cmStd vector<ccAffineSamplingParams>(),
const cmStd vector<ccCaliperRunParams>& clpParams =
cmStd vector<ccCaliperRunParams>(),
const ccEllipseFitParams &ellipseFitParams =
ccEllipseFitParams(),
const cc2Xform &startPose = cc2Xform(),
bool decrementNumIgnore = true);
Constructor.
816
CVL Class Reference
ccCaliperEllipseFinderResult
#include <ch_cvl/clpfind.h>
class ccCaliperEllipseFinderResult :
public ccCaliperFinderBaseResult;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class encapsulates the results from the Ellipse Finder tool.
Constructors/Destructors
ccCaliperEllipseFinderResult
ccCaliperEllipseFinderResult() {};
virtual ~ccCaliperEllipseFinderResult() {}
•
ccCaliperEllipseFinderResult() {};
Default constructor. Creates a default constructed (unfound) ellipse result object.
•
virtual ~ccCaliperEllipseFinderResult() {}
Destructor.
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseResult& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperEllipseFinderResult objects are considered equal if, and only if, all their
members and base classes are equal.
CVL Class Reference
817
ccCaliperEllipseFinderResult
Parameters
that
The ccCaliperEllipseFinderResult object to compare to this
object.
Public Member Functions
found
virtual bool found() const;
Returns true if an ellipse was found. Returns false otherwise.
An ellipse is found if its computed error is less than the error threshold specified in the
Ellipse Fitting tool parameters. See ccEllipseFitParams::threshold().
ellipseFit
const ccEllipseFitResults &ellipseFit() const;
Returns the ellipse fitting result.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
ellipse2
const ccEllipse2 &ellipse2() const;
Returns the found ellipse if found() is true.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
position
const cc2Vect &position() const;
Returns the position of the computed ellipse.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
ellipseFitTime
double ellipseFitTime() const;
Returns the circle fitting time, in seconds.
818
CVL Class Reference
ccCaliperEllipseFinderResult
Deprecated Members
ellipse
const ccEllipse &ellipse() const;
Returns the found ellipse if found() is true.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
CVL Class Reference
819
ccCaliperEllipseFinderResult
820
CVL Class Reference
ccCaliperFinderBaseAutoRunParams
#include <ch_cvl/clpfind.h>
class ccCaliperFinderBaseAutoRunParams :
public ccCaliperFinderBaseRunParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This is an abstract base class for the Shape Finder tool run-time parameters. See the
following class hierarchy diagram.
Abstract
base classes
ccCaliperFinderBaseRunParams
ccCaliperFinderBaseManualRunParams
ccCaliperFinderBaseAutoRunParams
ccCaliperLineFinderManualRunParams
ccCaliperLineFinderAutoRunParams
ccCaliperCircleFinderManualRunParams
ccCaliperCircleFinderAutoRunParams
ccCaliperEllipseFinderManualRunParams
ccCaliperEllipseFinderAutoRunParams
Manual mode
Auto mode
Constructors/Destructors
ccCaliperFinderBaseAutoRunParams
ccCaliperFinderBaseAutoRunParams (
c_Int16 numCalipers,
const ccDPair &caliperSize,
const ccCaliperRunParams &caliperRunParams,
const ccDPair &caliperSampling,
ccAffineSamplingParams::Interpolation
CVL Class Reference
821
ccCaliperFinderBaseAutoRunParams
interpolationMethod,
const cc2Xform &startPose,
bool decrementNumIgnore);
ccCaliperFinderBaseAutoRunParams(
const ccCaliperFinderBaseAutoRunParams&);
virtual ~ccCaliperFinderBaseAutoRunParams() = 0;
•
ccCaliperFinderBaseAutoRunParams (
c_Int16 numCalipers,
const ccDPair &caliperSize,
const ccCaliperRunParams &caliperRunParams,
const ccDPair &caliperSampling,
ccAffineSamplingParams::Interpolation
interpolationMethod,
const cc2Xform &startPose,
bool decrementNumIgnore);
Protected; constructs a finder base auto run-time parameters object.
Parameters
numCalipers
caliperSize
The number of calipers the tool should use to find the shape.
The caliper size, width and height in client coordinates. All
calipers are the same size. Caliper width is also called the search
length and caliper height is also called the projection length.
caliperRunParams
The run-time parameters object to be used when the Caliper tool
is run.
caliperSampling The sampling rate in samples/pixel for x and y, to be used on the
calipers. For example, the following calculates the number of
caliper samples in the x direction:
If xSize is caliperSize.x() in image coordinates, then the effective
number of samples in the x direction will be c_Int16(xSize * caliperSampling.x() + 0.5)
interpolationMethod
The interpolation method used with the calipers. Must be one of
the ccAffineSamplingParams::Interpolation enums.
See the ccAffineSamplingParams reference page.
822
CVL Class Reference
ccCaliperFinderBaseAutoRunParams
startPose
A transform that maps the expected shape from shape space to
its expected pose in the run-time client space.
decrementNumIgnore
When true, numIgnore in the shape fit parameters is
decremented for each caliper that fails to find an edge. When
false, no decrement occurs. The default is true.
Throws
ccCaliperFinderBaseDefs::BadParams
If numCalipers is less than 0,
or if caliperSize is less than (0, 0),
or if caliperSampling is less than or equal to (0, 0),
or if startPose is singular.
•
ccCaliperFinderBaseAutoRunParams(
const ccCaliperFinderBaseAutoRunParams&);
Protected copy constructor.
•
virtual ~ccCaliperFinderBaseAutoRunParams() = 0;
Destructor.
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseRunParams& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperFinderBaseRunParams objects are considered equal if, and only if, all
their members and base classes are equal.
Parameters
that
operator=
The object to compare to this object.
ccCaliperFinderBaseAutoRunParams& operator= (
const ccCaliperFinderBaseAutoRunParams& newObj);
Protected assignment operator. Prohibits copying and assignment by base pointers.
Parameters
newObj
CVL Class Reference
The new object that is a copy of this object.
823
ccCaliperFinderBaseAutoRunParams
Public Member Functions
numCalipers
c_Int16 numCalipers() const;
void numCalipers(c_Int16 numCalipers);
The number of calipers the tool should use to find the shape. The default is zero which
is not valid for running the tool.
•
c_Int16 numCalipers() const;
Returns the number of calipers to use.
•
void numCalipers(c_Int16 numCalipers);
Sets a new number of calipers.
Parameters
numCalipers
The new number of calipers.
Throws
ccCaliperFinderBaseDefs::BadParams
If numCalipers < minNumCalipers().
caliperWidth
double caliperWidth() const;
void caliperWidth(double caliperWidth);
The caliper width in pixels.
•
double caliperWidth() const;
Returns the caliper width.
•
void caliperWidth(double caliperWidth);
Sets a new caliper width.
Parameters
caliperWidth
824
The new caliper width.
CVL Class Reference
ccCaliperFinderBaseAutoRunParams
caliperHeight
double caliperHeight() const;
void caliperHeight(double caliperHeight);
The caliper height in pixels.
•
double caliperHeight() const;
Returns the caliper height.
•
void caliperHeight(double caliperHeight);
Sets a new caliper height.
Parameters
caliperHeight
caliperSize
The new caliper height.
const ccDPair &caliperSize() const;
void caliperSize(const ccDPair &caliperSize);
The caliper size, width and height in client coordinates. All calipers are the same size.
The default is (0, 0) which is not valid for running a tool.
•
const ccDPair &caliperSize() const;
Returns the caliper size.
•
void caliperSize(const ccDPair &caliperSize);
Sets a new caliper size.
Parameters
caliperSize
The new caliper size.
Throws
ccCaliperFinderBaseDefs::BadParams
If caliperSize is equal to or less than (0., 0.).
CVL Class Reference
825
ccCaliperFinderBaseAutoRunParams
caliperRunParams
ccCaliperRunParams caliperRunParams() const;
void caliperRunParams(
const ccCaliperRunParams &caliperRunParams);
The run-time parameters object to use when the Caliper tool is run.
•
ccCaliperRunParams caliperRunParams() const;
Returns the current run-time parameters.
•
void caliperRunParams(
const ccCaliperRunParams &caliperRunParams);
Sets a new run-time parameters object.
Parameters
caliperRunParams
The new run-time parameters.
caliperSampling
const ccDPair &caliperSampling() const;
void caliperSampling(const ccDPair &caliperSampling);
The sampling rate in samples/pixel for x and y (width and height), to be used on the
calipers. See caliperSampling in the ctor.
The default is (1, 1).
•
const ccDPair &caliperSampling() const;
Returns the caliper sampling values.
•
void caliperSampling(const ccDPair &caliperSampling);
Sets new caliper sampling values.
Parameters
caliperSampling The new caliper sampling.
Throws
ccCaliperFinderBaseDefs::BadParams
If caliperSampling is equal to or less than (0., 0.).
826
CVL Class Reference
ccCaliperFinderBaseAutoRunParams
interpolationMethod
ccAffineSamplingParams::Interpolation
interpolationMethod() const;
void interpolationMethod(
ccAffineSamplingParams::Interpolation method);
The interpolation method used with the calipers. Must be one of the
ccAffineSamplingParams::Interpolation enums. See the ccAffineSamplingParams
reference page.
The default is bilinear interpolation.
•
ccAffineSamplingParams::Interpolation
interpolationMethod() const;
Returns the current interpolation method.
•
void interpolationMethod(
ccAffineSamplingParams::Interpolation method);
Sets a new interpolation method.
Parameters
method
The new interpolation method.
affineSamplingParamsList
virtual const cmStd
vector<ccAffineSamplingParams> affineSamplingParamsList(
const cc2XformBase &clientFromImage =
cc2XformLinear()) const;
Returns the affine sampling parameters. The parameters are computed if necessary.
Parameters
clientFromImage
The client space to image space transform.
Throws
ccCaliperFinderBaseDefs::BadParams
If any run parameter is invalid,
or if the sampling rate causes an overflow,
or if the resulting number of samples is less than (1, 1).
Notes
These parameters do not reflect the start pose.
CVL Class Reference
827
ccCaliperFinderBaseAutoRunParams
Protected Member Functions
dirty
void dirty();
Sets the dirty flag to true so that affine sampling parameters are recomputed when the
tool is run.
computeAffineSamplingParams
void computeAffineSamplingParams(
const cc2XformBase &imageFromClient);
This function is for Cognex internal use only.
Throws
ccCaliperFinderBaseDefs::BadParams
If any run parameter is invalid,
or if the sampling rate causes an overflow,
or if the resulting number of samples is less than (1, 1).
computeAffineSamplingParams_
virtual void computeAffineSamplingParams_();
This function is for Cognex internal use only.
Throws
ccCaliperFinderBaseDefs::BadParams
If any run parameter is invalid,
or if the sampling rate causes an overflow,
or if the resulting number of samples is less than (1, 1).
828
CVL Class Reference
ccCaliperFinderBaseManualRunParams
#include <ch_cvl/clpfind.h>
class ccCaliperFinderBaseManualRunParams :
public ccCaliperFinderBaseRunParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This is an abstract base class for the Shape Finder tool run-time parameters. See the
following class hierarchy diagram.
Abstract
base classes
ccCaliperFinderBaseRunParams
ccCaliperFinderBaseManualRunParams
ccCaliperLineFinderManualRunParams
ccCaliperFinderBaseAutoRunParams
ccCaliperLineFinderAutoRunParams
ccCaliperCircleFinderManualRunParams
ccCaliperCircleFinderAutoRunParams
ccCaliperEllipseFinderManualRunParams
ccCaliperEllipseFinderAutoRunParams
Manual mode
CVL Class Reference
Auto mode
829
ccCaliperFinderBaseManualRunParams
Constructors/Destructors
ccCaliperFinderBaseManualRunParams
ccCaliperFinderBaseManualRunParams (
const cc2Xform &startPose,
bool decrementNumIgnore);
ccCaliperFinderBaseManualRunParams (
const ccCaliperFinderBaseManualRunParams&);
virtual ~ccCaliperFinderBaseManualRunParams() = 0;
•
ccCaliperFinderBaseManualRunParams (
const cc2Xform &startPose,
bool decrementNumIgnore);
Protected; constructs a finder base manual run-time parameters object.
Parameters
startPose
A transform that maps the expected shape from shape space to
its expected pose in the run-time client space. It also maps the
caliper affine rectangles into client space.
decrementNumIgnore
When true, numIgnore in the shape fit parameters is
decremented for each caliper that fails to find an edge. When
false, no decrement occurs. The default is true.
Throws
ccCaliperFinderBaseDefs::BadParams
If startPose is singular.
•
ccCaliperFinderBaseManualRunParams (
const ccCaliperFinderBaseManualRunParams&);
Protected copy constructor.
•
virtual ~ccCaliperFinderBaseManualRunParams() = 0;
Destructor.
830
CVL Class Reference
ccCaliperFinderBaseManualRunParams
Operators
operator=
ccCaliperFinderBaseRunParams& operator=(
const ccCaliperFinderBaseRunParams& newObj);
Protected assignment operator. Prohibits copying and assignment by base pointers.
Parameters
newObj
The new object that is a copy of this object.
Public Member Functions
setAffineSamplingAndCaliperRunParams
void setAffineSamplingAndCaliperRunParams (
const cmStd vector<ccAffineSamplingParams>& affParams,
const cmStd vector<ccCaliperRunParams>& clpParams);
Sets the affine sampling and caliper run-time parameters. These lists are used in manual
mode where each affine parameter list item corresponds to the affine sampling
parameters for one caliper and each caliper parameter list item corresponds to the
run-time parameters for one caliper.
The defaults are empty vectors which are not valid for running a tool.
Parameters
affParams
The affine sampling parameters list.
clpParams
The caliper run-time parameters list.
Throws
ccCaliperFinderBaseDefs::BadParams
If affParams.size() is not equal to clpParams.size(),
or if affParams.size() < minNumCalipers(),
or if clpParams.size() < minNumCalipers().
CVL Class Reference
831
ccCaliperFinderBaseManualRunParams
832
CVL Class Reference
ccCaliperFinderBaseResult
#include <ch_cvl/clpfind.h>
class ccCaliperFinderBaseResult : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This is an abstract base class for the Shape Finder tool results.
Constructors/Destructors
ccCaliperFinderBaseResult
ccCaliperFinderBaseResult();
ccCaliperFinderBaseResult(
const ccCaliperFinderBaseResult&);
virtual ~ccCaliperFinderBaseResult();
•
ccCaliperFinderBaseResult();
Protected default constructor. fitterResultsValid() is set to false.
•
ccCaliperFinderBaseResult(
const ccCaliperFinderBaseResult&);
Protected copy constructor.
•
virtual ~ccCaliperFinderBaseResult();
Destructor.
CVL Class Reference
833
ccCaliperFinderBaseResult
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseResult& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperFinderBaseResult objects are considered equal if and only if their
fitterResultsValid, pose, caliper results, and edge positions are equal.
Parameters
that
operator=
The object to compare to this object.
ccCaliperFinderBaseResult& operator=(
const ccCaliperFinderBaseResult& newObj);
Protected assignment operator. Prohibits copying and assignment by base pointers.
Parameters
newObj
The new object that is a copy of this object.
Public Member Functions
found
virtual bool found() const;
Returns true for a found shape with a valid result. Otherwise returns false.
fitterResultsValid
bool fitterResultsValid() const;
Returns true if the fitter results are valid. Otherwise returns false.
pose
const cc2Xform& pose() const;
Returns the pose that maps the expected shape to the found shape.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the fitter results are invalid.
caliperResults
const cmStd vector<ccCaliperResultSet> &caliperResults();
Returns the caliper results.
834
CVL Class Reference
ccCaliperFinderBaseResult
edgePositions
const cmStd vector<cc2Vect> &edgePositions() const;
Returns the found edge positions.
caliperTime
double caliperTime() cons;
Returns the time (in seconds) spent running calipers.
totalTime
double totalTime() const;
Returns the total time (in seconds) to find the shape.
Protected Member Functions
checkFitterResults
void checkFitterResults() const;
Checks whether or not the fitter results are valid. If the results are valid, the function
returns. If the results are not valid it throws the error below.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the fitter results are invalid because they were not computed.
CVL Class Reference
835
ccCaliperFinderBaseResult
836
CVL Class Reference
ccCaliperFinderBaseRunParams
#include <ch_cvl/clpfind.h>
class ccCaliperFinderBaseRunParams : public virtual ccPersistent;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This is an abstract base class for the Shape Finder tool run-time parameters. See the
following class hierarchy diagram.
Abstract
base classes
ccCaliperFinderBaseRunParams
ccCaliperFinderBaseManualRunParams
ccCaliperLineFinderManualRunParams
ccCaliperFinderBaseAutoRunParams
ccCaliperLineFinderAutoRunParams
ccCaliperCircleFinderManualRunParams
ccCaliperCircleFinderAutoRunParams
ccCaliperEllipseFinderManualRunParams
ccCaliperEllipseFinderAutoRunParams
Manual mode
CVL Class Reference
Auto mode
837
ccCaliperFinderBaseRunParams
Constructors/Destructors
ccCaliperFinderBaseRunParams
ccCaliperFinderBaseRunParams(
const cc2Xform& startPose,
bool decrementNumIgnore);
ccCaliperFinderBaseRunParams(
const ccCaliperFinderBaseRunParams&);
virtual ~ccCaliperFinderBaseRunParams() = 0;
•
ccCaliperFinderBaseRunParams(
const cc2Xform& startPose,
bool decrementNumIgnore);
Protected; constructs a finder base run-time parameters object.
Parameters
startPose
A transform that maps the expected shape from shape space to
its expected pose in the run-time client space. It also maps the
caliper affine rectangles into client space.
decrementNumIgnore
When true, numIgnore in the shape fit parameters is
decremented for each caliper that fails to find an edge. When
false, no decrement occurs. The default is true.
Throws
ccCaliperFinderBaseDefs::BadParams
If startPose is singular.
•
ccCaliperFinderBaseRunParams(
const ccCaliperFinderBaseRunParams&);
Protected copy constructor.
•
virtual ~ccCaliperFinderBaseRunParams() = 0;
Destructor.
838
CVL Class Reference
ccCaliperFinderBaseRunParams
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseRunParams& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperFinderBaseRunParams objects are considered equal if, and only if, all
their members are equal.
Parameters
that
operator=
The object to compare to this object.
ccCaliperFinderBaseRunParams& operator=(
const ccCaliperFinderBaseRunParams& newObj);
Protected assignment operator. Prohibits copying and assignment by base pointers.
Parameters
newObj
The new object that is a copy of this object.
Public Member Functions
startPose
const cc2Xform& startPose() const;
void startPose(const cc2Xform& startPose);
A transform that maps the expected shape from shape space to its expected pose in
the run-time client space. It also maps the caliper affine rectangles into client space.
The default is the identity transform.
•
const cc2Xform& startPose() const;
Returns the current start pose.
•
void startPose(const cc2Xform& startPose);
Sets a new start pose.
Parameters
startPose
CVL Class Reference
The new start pose.
839
ccCaliperFinderBaseRunParams
Throws
ccCaliperFinderBaseDefs::BadParams
If startPose is singular.
decrementNumIgnore
bool decrementNumIgnore() const;
void decrementNumIgnore(bool ignore);
When true, numIgnore in the shape fit parameters is decremented for each caliper that
fails to find an edge. When false, no decrement occurs. The default is true.
Notes
An internal copy is decremented not the actual fitter parameters given by the user.
•
bool decrementNumIgnore() const;
Returns the current setting, true or false.
•
void decrementNumIgnore(bool ignore);
Sets the ignore flag.
Parameters
ignore
The new flag, true or false.
affineSamplingParamsList
virtual const cmStd
vector<ccAffineSamplingParams> affineSamplingParamsList(
const cc2XformBase &clientFromImage =
cc2XformLinear()) const;
Parameters
clientFromImage
The client space to image space transform.
Returns the affine sampling parameters list. This list is used in manual mode where each
list item corresponds to the affine sampling parameters for one caliper.
Notes
These sampling parameters do not reflect the start pose.
If you call this function on a default constructed object, it returns an empty vector
which is not valid for running a tool. You must first set valid values for caliper size,
number of calipers, and caliper sampling.
840
CVL Class Reference
ccCaliperFinderBaseRunParams
caliperRunParamsList
const cmStd vector<ccCaliperRunParams>
&caliperRunParamsList() const;
Returns the caliper run-time parameters list. This list is used in manual mode where each
list item corresponds to the run-time parameters for one caliper.
Notes
The default is an empty vector which is not valid for running a tool.
minNumCalipers
virtual c_Int16 minNumCalipers() const = 0;
Returns the minimum number of calipers required.
Protected Member Functions
affineSamplingParamsList
void affineSamplingParamsList (
const cmStd vector<ccAffineSamplingParams>&
affineSamplingParamsList);
Sets the affine sampling parameters list. This list is used in manual mode where each list
item corresponds to the affine sampling parameters for one caliper.
Parameters
affineSamplingParamsList
The new list.
caliperRunParamsList
void caliperRunParamsList (
const cmStd vector<ccCaliperRunParams>&
caliperRunParamsList);
Sets the caliper run-time parameters list. This list is used in manual mode where each
list item corresponds to the run-time parameters for one caliper.
Parameters
caliperRunParamsList
The new list.
CVL Class Reference
841
ccCaliperFinderBaseRunParams
842
CVL Class Reference
ccCaliperLineFinderAutoRunParams
#include <ch_cvl/clpfind.h>
class ccCaliperLineFinderAutoRunParams :
public ccCaliperFinderBaseAutoRunParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
Encapsulates the Line Finder tool run-time parameters for running the tool in auto mode.
Constructors/Destructors
Notes
Default constructed objects do not contain valid run-time parameters.
ccCaliperLineFinderAutoRunParams
ccCaliperLineFinderAutoRunParams (
const ccLineSeg& expectedLine = ccLineSeg(),
c_Int16 numCalipers = 0,
const ccDPair& caliperSize = ccDPair(0, 0),
const ccCaliperRunParams& caliperRunParams =
ccCaliperRunParams(),
const ccDPair& caliperSampling = ccDPair(1, 1),
const ccRadian& skew = ccRadian(0),
ccAffineSamplingParams::Interpolation
interpolationMethod =
ccAffineSamplingParams::eBilinear,
const ccLineFitParams& lineFitParams = ccLineFitParams(),
const cc2Xform& startPose = cc2Xform(),
bool decrementNumIgnore = true);
ccCaliperLineFinderAutoRunParams (
const ccAffineRectangle &affineRectangle,
c_Int16 numCalipers = 0,
double caliperHeight = 0,
const ccCaliperRunParams &caliperRunParams =
ccCaliperRunParams(),
const ccDPair &caliperSampling = ccDPair(1, 1),
ccAffineSamplingParams::Interpolation
interpolationMethod =
CVL Class Reference
843
ccCaliperLineFinderAutoRunParams
ccAffineSamplingParams::eBilinear,
const ccLineFitParams& lineFitParams = ccLineFitParams(),
const cc2Xform& startPose = cc2Xform(),
bool decrementNumIgnore = true);
virtual ~ccCaliperLineFinderAutoRunParams() {}
•
ccCaliperLineFinderAutoRunParams (
const ccLineSeg& expectedLine = ccLineSeg(),
c_Int16 numCalipers = 0,
const ccDPair& caliperSize = ccDPair(0, 0),
const ccCaliperRunParams& caliperRunParams =
ccCaliperRunParams(),
const ccDPair& caliperSampling = ccDPair(1, 1),
const ccRadian& skew = ccRadian(0),
ccAffineSamplingParams::Interpolation
interpolationMethod =
ccAffineSamplingParams::eBilinear,
const ccLineFitParams& lineFitParams = ccLineFitParams(),
const cc2Xform& startPose = cc2Xform(),
bool decrementNumIgnore = true);
Constructs a line finder auto run parameters object where the expected line is defined
by a ccLineSeg object.
Parameters
expectedLine
The line you expect the tool to find in images.
numCalipers
The number of calipers the tool should use to find the line.
caliperSize
The caliper size, width and height in client coordinates. All
calipers are the same size.
caliperRunParams
The run-time parameters object to be used when the Caliper tool
is run.
caliperSampling The sampling rate in samples/pixel for x and y, to be used on the
calipers. For example, the following calculates the number of
caliper samples in the x direction:
If xSize is caliperSize.x() in image coordinates, then the effective
number of samples in the x direction will be c_Int16(xSize * caliperSampling.x() + 0.5)
844
CVL Class Reference
ccCaliperLineFinderAutoRunParams
skew
A skew angle. Normally calipers are perpendicular to the
expected line. You may wish to skew the calipers to avoid
features in the image that could be confused with the line. See
skew on page 848.
interpolationMethod
The interpolation method used with the calipers. Must be one of
the ccAffineSamplingParams::Interpolation enums. The
default is eBilinear.
See the ccAffineSamplingParams reference page.
lineFitParams
The run-time parameters to use with the Fitting tool.
startPose
A transform that maps the expected line from line space to its
expected pose in the run-time client space.
decrementNumIgnore
When true, ccLineFitParams::numIgnore is decremented for
each caliper that fails to find an edge. When false, no decrement
occurs.
Throws
ccCaliperFinderBaseDefs::BadParams
If numCalipers is not zero and is less than minNumCalipers(),
or if caliperSize is less than (0, 0),
or if caliperSampling is less than or equal to (0, 0),
or if skew is +90° or -90°,
or if startPose is singular.
•
ccCaliperLineFinderAutoRunParams (
const ccAffineRectangle &affineRectangle,
c_Int16 numCalipers = 0,
double caliperHeight = 0,
const ccCaliperRunParams &caliperRunParams =
ccCaliperRunParams(),
const ccDPair &caliperSampling = ccDPair(1, 1),
ccAffineSamplingParams::Interpolation
interpolationMethod =
ccAffineSamplingParams::eBilinear,
const ccLineFitParams& lineFitParams = ccLineFitParams(),
const cc2Xform& startPose = cc2Xform(),
bool decrementNumIgnore = true);
Constructs a line finder auto run parameters object where the expected line is defined
by an affine rectangle. Specifying the affine rectangle also sets caliperWidth and the
skew.
CVL Class Reference
845
ccCaliperLineFinderAutoRunParams
Parameters
affineRectangle
A rectangle that defines the expected line segment.
numCalipers
The number of calipers the tool should use to find the line.
caliperHeight
The caliper height in pixels. The caliper width is defined by the
affineRectangle width. All calipers are the same size.
caliperRunParams
The run-time parameters object to be used when the Caliper tool
is run.
caliperSampling The sampling rate in samples/pixel for x and y, to be used on the
calipers. For example, the following calculates the number of
caliper samples in the x direction:
If xSize is caliperSize.x() in image coordinates, then the effective
number of samples in the x direction will be c_Int16(xSize * caliperSampling.x() + 0.5)
interpolationMethod
The interpolation method used with the calipers. Must be one of
the ccAffineSamplingParams::Interpolation enums. The
default is eBilinear.
See the ccAffineSamplingParams reference page.
lineFitParams
The run-time parameters to use with the Fitting tool.
startPose
A transform that maps the expected line from line space to its
expected pose in the run-time client space.
decrementNumIgnore
When true, ccLineFitParams::numIgnore is decremented for
each caliper that fails to find an edge. When false, no decrement
occurs.
Throws
ccCaliperFinderBaseDefs::BadParams
If numCalipers is not zero and is less than minNumCalipers(),
or if affineRectangle.degen() is true,
or if caliperHeight is less than 0,
or if caliperSampling is less than or equal to (0, 0),
or if startPose is singular.
846
CVL Class Reference
ccCaliperLineFinderAutoRunParams
•
virtual ~ccCaliperLineFinderAutoRunParams() {}
Destructor.
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseRunParams& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperLineFinderAutoRunParams objects are considered equal if, and only if,
all their members and base classes are equal.
Parameters
that
The ccCaliperLineFinderAutoRunParams object to compare to
this object.
Public Member Functions
expectedLine
const ccLineSeg &expectedLine() const;
void expectedLine(const ccLineSeg &expectedLine);
•
const ccLineSeg &expectedLine() const;
Returns the expected line segment.
•
void expectedLine(const ccLineSeg &expectedLine);
Sets the expected line segment.
Throws
ccCaliperFinderBaseDefs::BadParams
If expectedLine.p1() == expectedLine.p2().
CVL Class Reference
847
ccCaliperLineFinderAutoRunParams
skew
const ccRadian &skew() const;
void skew(const ccRadian &skew);
When skew is 0°, calipers are perpendicular to the expected line. You may wish to skew
the calipers to avoid features in the image that could be confused with the line. See the
following example.
x
Skew angle
θ
y
•
Expected
line
const ccRadian &skew() const;
Returns the current skew angle. The default is 0°.
•
void skew(const ccRadian &skew);
Sets a new skew angle.
Parameters
skew
The new skew angle.
Throws
ccCaliperFinderBaseDefs::BadParams
If f skew is +90° or -90°.
848
CVL Class Reference
ccCaliperLineFinderAutoRunParams
affineRectangle
void affineRectangle(
const ccAffineRectangle &affineRectangle);
ccAffineRectangle affineRectangle() const;
You can use an affine rectangle to define the expected line, caliper width, and skew. See
the example below.
Caliper height
x
Skew angle
θ
P0
Py
P0
Px
y
Expected line
Caliper width
Px
Py
Affine
rectangle
Calipers
The expected line bisects the rectangle as shown, and the calipers are evenly
distributed along the expected line.
•
ccAffineRectangle affineRectangle() const;
Returns the current affine rectangle.
•
void affineRectangle(
const ccAffineRectangle &affineRectangle);
Sets a new affine rectangle.
Parameters
affineRectangle
The new affine rectangle.
Throws
ccCaliperFinderBaseDefs::BadParams
If affineRectangle.degen() is true.
ccCaliperFinderBaseDefs::BadParams if affineRectangle.degen().
CVL Class Reference
849
ccCaliperLineFinderAutoRunParams
lineFitParams
const ccLineFitParams &lineFitParams() const;
void lineFitParams(const ccLineFitParams &lineFitParams);
•
const ccLineFitParams &lineFitParams() const;
Returns the line fit parameters.
•
void lineFitParams(const ccLineFitParams &lineFitParams);
Sets new line fit parameters.
Parameters
lineFitParams
minNumCalipers
The new parameters.
virtual c_Int16 minNumCalipers() const;
Returns the minimum number of calipers required (2).
850
CVL Class Reference
ccCaliperLineFinderManualRunParams
#include <ch_cvl/clpfind.h>
class ccCaliperLineFinderManualRunParams :
public ccCaliperFinderBaseManualRunParams;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
Encapsulates the Line Finder tool run-time parameters for running the tool in manual
mode.
Constructors/Destructors
ccCaliperLineFinderManualRunParams
ccCaliperLineFinderManualRunParams (
const ccLineSeg& expectedLine = ccLineSeg(),
const cmStd vector<ccAffineSamplingParams>& affParams =
cmStd vector<ccAffineSamplingParams>(),
const cmStd vector<ccCaliperRunParams>& clpParams =
cmStd vector<ccCaliperRunParams>(),
const ccLineFitParams& lineFitParams = ccLineFitParams(),
const cc2Xform &startPose = cc2Xform(),
bool decrementNumIgnore = true);
virtual ~ccCaliperLineFinderManualRunParams() {}
•
ccCaliperLineFinderManualRunParams (
const ccLineSeg& expectedLine = ccLineSeg(),
const cmStd vector<ccAffineSamplingParams>& affParams =
cmStd vector<ccAffineSamplingParams>(),
const cmStd vector<ccCaliperRunParams>& clpParams =
cmStd vector<ccCaliperRunParams>(),
const ccLineFitParams& lineFitParams = ccLineFitParams(),
const cc2Xform &startPose = cc2Xform(),
bool decrementNumIgnore = true);
Constructs a line finder manual run-time parameters object.
CVL Class Reference
851
ccCaliperLineFinderManualRunParams
Notes
Default constructed objects do not contain valid run-time parameters.
Parameters
expectedLine
The line you expect the tool to find in images.
affParams
A vector of affine rectangle sampling parameters, one parameter
set for each caliper.
clpParams
A vector of caliper run-time parameters, one parameter set for
each caliper.
lineFitParams
The run-time parameters to use with the Fitting tool.
startPose
A transform that maps the expected line from line space to its
expected pose in the run-time client space.
decrementNumIgnore
When true, ccLineFitParams::numIgnore is decremented for
each caliper that fails to find an edge. When false, no decrement
occurs.
Throws
ccCaliperFinderBaseDefs::BadParams
If affParams.size() is not equal to clpParams.size(),
or if params sizes are not zero and less than minNumCalipers(),
or if startPose is singular.
•
virtual ~ccCaliperLineFinderManualRunParams() {}
Destructor.
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseRunParams& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperLineFinderManualRunParams objects are considered equal if, and
only if, all their members and base classes are equal.
Parameters
that
852
The ccCaliperLineFinderManualRunParams object to
compare to this object.
CVL Class Reference
ccCaliperLineFinderManualRunParams
Public Member Functions
expectedLine
const ccLineSeg &expectedLine() const;
void expectedLine(const ccLineSeg &expectedLine);
The line segment you expect to find in images processed by the Line Finder tool. The
expected line should be close to actual lines in the images.
•
const ccLineSeg &expectedLine() const;
Returns the expected line segment.
•
void expectedLine(const ccLineSeg &expectedLine);
Sets the expected line segment.
Throws
ccCaliperFinderBaseDefs::BadParams
If expectedLine.p1() == expectedLine.p2().
lineFitParams
const ccLineFitParams &lineFitParams() const;
void lineFitParams(const ccLineFitParams &lineFitParams);
•
const ccLineFitParams &lineFitParams() const;
Returns the line fitter run-time parameters.
•
void lineFitParams(const ccLineFitParams &lineFitParams);
Sets new line fitter run-time parameters.
Parameters
lineFitParams
The new parameters.
minNumCalipers
virtual c_Int16 minNumCalipers() const;
Returns the minimum number of calipers required (2).
CVL Class Reference
853
ccCaliperLineFinderManualRunParams
854
CVL Class Reference
ccCaliperLineFinderResult
#include <ch_cvl/clpfind.h>
class ccCaliperLineFinderResult :
public ccCaliperFinderBaseResult;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class encapsulates the results from the Line Finder tool.
Constructors/Destructors
ccCaliperLineFinderResult
ccCaliperLineFinderResult() {};
virtual ~ccCaliperLineFinderResult() {}
•
ccCaliperLineFinderResult() {};
Default constructor. Creates a default constructed (unfound) line result object.
•
virtual ~ccCaliperLineFinderResult() {}
Destructor.
Operators
operator==
virtual bool operator==(
const ccCaliperFinderBaseResult& that) const;
Compares this object to another object of the same type. Returns true if this object
equals that. Returns false otherwise.
Two ccCaliperLineFinderResult objects are considered equal if, and only if, all their
members and base classes are equal.
CVL Class Reference
855
ccCaliperLineFinderResult
Parameters
that
The ccCaliperLineFinderResult object to compare to this
object.
Public Member Functions
found
virtual bool found() const;
Returns true if a line was found. Returns false otherwise.
A line is found if its computed error is less than the error threshold specified in the Line
Fitting tool parameters. See ccLineFitParams::threshold().
lineFit
const ccLineFitResults &lineFit() const;
Returns the line fitting result.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
line
const ccFLine &line() const;
Returns the computed line.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
lineSeg
const ccLineSeg &lineSeg() const;
Returns the best-fit line segment of the found line (the found line is an infinite length line).
The best-fit line segment center is aligned with the expected line center and is the same
length as the expected line.
Throws
ccCaliperFinderBaseDefs::NotComputed
If the Fitting tool results are invalid.
lineFitTime
double lineFitTime() const;
Returns the line fitting time, in seconds.
856
CVL Class Reference
ccCaliperOneResult
#include <ch_cvl/caliper.h>
class ccCaliperOneResult;
Class Properties
Copyable
Yes
Derivable
No
Archiveable
Simple
This class contains a single edge or edge pair re