1. 핵심 비전 도구 소개

Cognex VisionPro는 산업용 머신 비전 시스템 개발을 위한 포괄적인 소프트웨어 플랫폼입니다. 이 플랫폼은 다양한 비전 애플리케이션에 적용할 수 있는 강력한 도구와 알고리즘을 포함하고 있습니다. 다음은 VisionPro의 주요 도구와 그 역할에 대한 설명입니다.

기능 명칭	주요 역할
VisionPro	Cognex 사의 머신 비전 개발 환경으로, 다양한 비전 알고리즘과 도구를 제공합니다.
ToolBlock	VisionPro 내에서 여러 비전 처리 도구들을 체계적으로 구성하고 순차적으로 실행할 수 있게 하는 블록 단위 컨테이너입니다.
CogPMAlignTool	패턴 인식 및 정렬 도구로, 이미지 내에서 특정 템플릿 패턴의 위치와 각도를 찾아냅니다.
CogBlobTool	이미지에서 연결된 픽셀 영역(Blob)을 검출하고 분석하여 크기, 위치, 모양 등의 정보를 추출합니다.
CogIDTool	1D/2D 바코드, OCR 등 다양한 형태의 식별 코드를 판독하는 도구입니다.
CogColorTool	이미지 내 색상 정보를 분석하여 특정 색상 영역을 검출하거나 색상 일치 여부를 판별합니다.
CogCaliperTool	정밀한 에지(모서리)를 검출하고 이를 기반으로 거리, 폭, 각도 등 기하학적 측정을 수행합니다.
CogCompareTool	두 이미지 간의 유사성을 비교하거나 차이점을 분석하여 결함을 검출하는 데 사용됩니다.
CogHistogramTool	이미지의 픽셀 강도 분포를 분석하여 밝기, 대비 등의 통계 정보를 제공합니다.
CogImageConvertTool	이미지의 색 공간(예: RGB를 그레이스케일로)을 변환하거나 이미지 형식을 변경합니다.
CogPolarUnwrapTool	원형 영역의 이미지를 직사각형 형태로 펼쳐서(극좌표 변환) 분석하기 쉽게 만듭니다.
CogFixtureTool	특정 객체를 기준으로 이미지의 좌표계를 재정의하여 후속 비전 도구들이 고정된 좌표계에서 작동하도록 돕습니다.
CogGraphicLabel	이미지 위에 텍스트 정보를 표시하는 데 사용되는 그래픽 요소입니다.
CogGraphicCollection	여러 그래픽 객체들을 하나로 묶어 관리하는 컨테이너입니다.

2. VisionPro 도구 프로그래밍 실무

1. 개발 환경 설정 및 네임스페이스

VisionPro SDK 설치 후 Visual Studio 프로젝트에서 필요한 참조를 추가해야 합니다. C# 코드를 통해 VisionPro 도구를 활용하기 위해 일반적으로 사용되는 네임스페이스는 다음과 같습니다.

// VisionPro SDK 설치 후 Visual Studio 프로젝트에서 참조를 추가해야 합니다.
// 주로 사용되는 Cognex VisionPro 네임스페이스 목록:
using Cognex.VisionPro;                // 핵심 인터페이스 (ICogImage), 디스플레이 (CogDisplay), 직렬화 (CogSerializer) 등
using Cognex.VisionPro.ToolBlock;      // ToolBlock 내 스크립트 작성 시
using Cognex.VisionPro.PMAlign;        // 패턴 정합 및 정렬 기능
using Cognex.VisionPro.CalibFix;       // 좌표계 변환 및 보정 (캘리브레이션)
using Cognex.VisionPro.Caliper;        // 정밀 에지 검출 및 거리 측정
using Cognex.VisionPro.Blob;           // 연결된 영역(Blob) 분석
using Cognex.VisionPro.ImageProcessing; // 이미지 전처리 (극좌표 변환, 모폴로지 연산 등)

2. 패턴 정합 도구 활용 (CogPMAlignTool)

CogPMAlignTool은 이미지 내에서 특정 패턴의 위치, 회전, 스케일을 찾아내는 데 사용됩니다. 주로 부품 정렬, 위치 검출 등에 활용됩니다.

// 패턴 정합(PMAlign) 도구 인스턴스 생성
CogPMAlignTool patternMatcher = new CogPMAlignTool();

// 템플릿 학습용 이미지 설정 (ICogImage 타입의 sourceImage 변수)
patternMatcher.Pattern.TrainImage = sourceImage;

// 템플릿 학습 영역 지정 (예: CogRectangle1D 또는 CogRectangle 등의 영역 변수)
patternMatcher.Pattern.TrainRegion = trainRegion;

// 템플릿 학습 실행
patternMatcher.Pattern.Train();

// 패턴 정합 도구 실행
patternMatcher.Run();

// 정합 결과 분석
// 결과는 매칭 점수 기준으로 정렬되며, [0]이 가장 높은 점수의 결과입니다.
if (patternMatcher.Results != null && patternMatcher.Results.Count > 0)
{
    CogPMAlignResult bestMatch = patternMatcher.Results[0];
    double locX     = bestMatch.GetPose().TranslationX; // 매칭된 패턴의 중심 X 좌표 (픽셀)
    double locY     = bestMatch.GetPose().TranslationY; // 매칭된 패턴의 중심 Y 좌표 (픽셀)
    double rotation = bestMatch.GetPose().Rotation;     // 회전 각도 (라디안)
    double score    = bestMatch.Score;                  // 매칭 점수 (0~1, 일반적으로 0.5 이상 사용)
}

3. 캘리퍼 도구 사용법 (CogCaliperTool)

CogCaliperTool은 이미지에서 정밀한 에지(모서리)를 검출하고, 이를 기반으로 다양한 측정을 수행하는 도구입니다. 길이, 폭, 간격 등을 측정할 때 유용합니다.

// 캘리퍼 도구 객체 생성
CogCaliperTool edgeCaliper = new CogCaliperTool();

// 에지 검색 영역 설정 (예: CogRectangle 타입의 searchArea 변수)
edgeCaliper.Region = searchArea;

// 캘리퍼 실행 파라미터 설정
// EdgeMode: SingleEdge (단일 에지), PairEdge (두 쌍의 에지 - 폭 측정용)
edgeCaliper.RunParams.EdgeMode = CogCaliperEdgeModeConstants.SingleEdge;
// EdgePolarity: DarkToLight (어두운 곳에서 밝은 곳으로), LightToDark (밝은 곳에서 어두운 곳으로), DontCare (방향 무관)
edgeCaliper.RunParams.EdgePolarity = CogCaliperEdgePolarityConstants.DarkToLight;

// 캘리퍼 도구 실행
edgeCaliper.Run();

// 에지 검출 결과 확인
if (edgeCaliper.Results != null && edgeCaliper.Results.Count > 0)
{
    CogCaliperResult firstEdge = edgeCaliper.Results[0];
    double edgePosX     = firstEdge.EdgeX;    // 검출된 에지의 X 좌표
    double edgePosY     = firstEdge.EdgeY;    // 검출된 에지의 Y 좌표
    double edgeStrength = firstEdge.EdgeScore; // 에지의 강도 점수 (높을수록 명확한 에지)
}

4. Blob 분석 도구 (CogBlobTool)

CogBlobTool은 이미지에서 연결된 픽셀 영역(Blob)을 찾아 그 크기, 위치, 모양 등 다양한 기하학적 특성을 분석하는 도구입니다. 주로 이물 검사, 부품 존재 유무, 면적 측정 등에 사용됩니다.

// Blob 분석 도구 인스턴스 생성
CogBlobTool blobAnalyzer = new CogBlobTool();

// 분석 대상 이미지 지정 (ICogImage 타입의 inputImg 변수)
blobAnalyzer.InputImage = inputImg;

// 이미지 분할(Segmentation) 파라미터 설정
// Mode: HardFixedThreshold (고정 임계값 분할), 특정 임계값을 기준으로 픽셀을 분리
blobAnalyzer.RunParams.SegmentationParams.Mode = CogBlobSegmentationModeConstants.HardFixedThreshold;
blobAnalyzer.RunParams.SegmentationParams.HardFixedThreshold = 128; // 0~255 범위, 128은 중간값

// 결과 필터링 설정 (노이즈 Blob 및 과도하게 큰 배경 Blob 제거)
blobAnalyzer.RunParams.FilterResults = true;
blobAnalyzer.RunParams.FilterResultParams.MaxArea = 1000; // 최대 Blob 면적 (픽셀 제곱), 배경 제외용
blobAnalyzer.RunParams.FilterResultParams.MinArea = 100;  // 최소 Blob 면적 (픽셀 제곱), 노이즈 제거용

// Blob 분석 도구 실행
blobAnalyzer.Run();

// 분석 결과 획득 (Blob들은 면적 기준으로 내림차순 정렬)
int detectedBlobCount = blobAnalyzer.Results.GetBlobs().Count;
if (detectedBlobCount > 0)
{
    CogBlobResult mainBlob = blobAnalyzer.Results.GetBlobs()[0]; // 가장 큰 Blob
    double blobArea     = mainBlob.Area;        // Blob의 면적 (픽셀 제곱)
    double centerMassX  = mainBlob.CenterOfMassX; // Blob의 질량 중심 X 좌표
    double centerMassY  = mainBlob.CenterOfMassY; // Blob의 질량 중심 Y 좌표
}

5. 기하학적 형상 검출 (예: CogFindCircleTool)

VisionPro는 원, 선, 타원 등 특정 기하학적 형상을 이미지에서 찾아내는 도구를 제공합니다. 여기서는 CogFindCircleTool을 사용하여 원을 검출하는 예시를 보여줍니다.

// 원형 객체 검출 도구 (CogFindCircleTool) 생성
CogFindCircleTool circleFinder = new CogFindCircleTool();

// 검사할 이미지 입력 (ICogImage 타입의 targetImage 변수; 독립 실행 시 필수, ToolBlock에서는 파이프라인으로 연결됨)
circleFinder.InputImage = targetImage;

// 검색할 원형의 예상 조건 설정 (검색 속도 향상 및 정확도 증대)
circleFinder.RunParams.ExpectedCircularArc.CenterX = 100; // 예상 원의 중심 X
circleFinder.RunParams.ExpectedCircularArc.CenterY = 100; // 예상 원의 중심 Y
circleFinder.RunParams.ExpectedCircularArc.Radius  = 50;  // 예상 원의 반경 (픽셀)

// 원형 검출 도구 실행
circleFinder.Run();

// 검출된 원의 결과 획득
CogCircle detectedCircle = circleFinder.Results.GetCircle();
if (detectedCircle != null)
{
    double foundRadius = detectedCircle.Radius;   // 검출된 원의 반경
    double circleX     = detectedCircle.CenterX;  // 검출된 원의 중심 X
    double circleY     = detectedCircle.CenterY;  // 검출된 원의 중심 Y
}

6. 색상 분석 도구 (CogColorTool)

CogColorTool은 이미지의 색상 정보를 분석하여 특정 색상 영역을 검출하거나 색상 일치 여부를 판단합니다. 주로 제품의 색상 검사, 라벨 색상 확인 등에 활용됩니다.

// 색상 분석 도구 인스턴스 생성
CogColorTool colorAnalyzer = new CogColorTool();

// 분석 대상 이미지 지정 (반드시 컬러 이미지 ICogImage여야 함. coloredImage 변수)
colorAnalyzer.InputImage = coloredImage;

// 색상 분석 영역 설정 (선택 사항, 예: CogRectangle 타입의 analysisRegion 변수)
colorAnalyzer.Region = analysisRegion;

// 색상 분석 도구 실행
colorAnalyzer.Run();

// 분석 결과 확인 (각 Result는 하나의 색상 세그먼트에 대한 통계를 포함)
if (colorAnalyzer.Results != null && colorAnalyzer.Results.Count > 0)
{
    CogColorToolResult colorResult = colorAnalyzer.Results[0];
    double matchScore    = colorResult.Score;       // 색상 일치 점수 (0~1)
    double matchedPixels = colorResult.Count;     // 특정 색상 조건에 맞는 픽셀 수
}

// 참고: 색상 범위(Hue/Saturation/Intensity) 설정은 주로 QuickBuild에서 시각적으로 구성됩니다.

7. 이미지 전처리 도구

비전 시스템에서는 원본 이미지를 분석하기 전에 특정 목적에 맞게 변환하거나 개선하는 전처리 과정이 필요합니다. VisionPro는 이러한 전처리를 위한 다양한 도구를 제공합니다.

이미지 변환 (CogImageConvertTool)

// 이미지 형식/색 공간 변환 도구 (CogImageConvertTool)
CogImageConvertTool imageConverter = new CogImageConvertTool();
imageConverter.InputImage = originalImage; // 원본 이미지 (ICogImage 타입의 originalImage 변수)
imageConverter.RunParams.RunMode = CogImageConvertRunModeConstants.RGBToGrey; // RGB를 그레이스케일로 변환
imageConverter.Run();
// 변환된 이미지는 imageConverter.OutputImage 속성으로 접근 가능

극좌표 변환 (CogPolarUnwrapTool)

// 극좌표 변환 도구 (CogPolarUnwrapTool) - 원형 영역을 직사각형으로 펼침 (예: 병뚜껑 에지 분석)
CogPolarUnwrapTool polarTransformer = new CogPolarUnwrapTool();
polarTransformer.InputImage = sourceImg; // 원본 이미지 (ICogImage 타입의 sourceImg 변수)
polarTransformer.RunParams.CenterX     = 100; // 변환 중심 X (일반적으로 원형 객체의 중심)
polarTransformer.RunParams.CenterY     = 100; // 변환 중심 Y
polarTransformer.RunParams.OuterRadius = 80;  // 바깥쪽 반경 (펼칠 영역의 외부 경계)
polarTransformer.RunParams.InnerRadius = 20;  // 안쪽 반경 (펼칠 영역의 내부 경계, 0보다 크면 중앙 영역 제외)
polarTransformer.Run();
// 변환된 출력 이미지의 너비와 높이는 설정된 반경 값에 따라 결정됩니다.
// (예: 너비 = 2π * (OuterRadius+InnerRadius)/2, 높이 = OuterRadius - InnerRadius)

// 참고: 모폴로지 연산(팽창, 침식 등)은 주로 QuickBuild UI의 ToolBlock 내에서 파라미터가 설정됩니다.

8. Fixture 도구 (CogFixtureTool)를 이용한 좌표계 정렬

CogFixtureTool은 검출된 객체의 위치와 자세에 따라 이미지의 좌표계를 동적으로 정렬하여, 후속 도구들이 일관된 기준 좌표계에서 작동하도록 돕습니다. 이는 특히 부품의 위치 변동이 심한 애플리케이션에서 유용합니다.

// CogFixtureTool은 검출된 객체를 기준으로 이미지의 좌표계를 정렬하는 데 사용됩니다.
// 주로 패턴 정합(PMAlign) 도구와 함께 사용되어, 객체 위치에 따라 후속 도구의 좌표를 조정합니다.
CogFixtureTool coordinateAligner = new CogFixtureTool();
coordinateAligner.InputImage = rawImage; // 원본 이미지 (ICogImage 타입의 rawImage 변수)

// PMAlign 결과에서 얻은 자세(Pose) 정보를 Fixture 변환으로 설정합니다.
// 이를 통해 후속 도구들은 객체의 고유한 좌표계 내에서 작동하게 됩니다.
// patternMatcher는 앞서 정의된 CogPMAlignTool 인스턴스라고 가정합니다.
coordinateAligner.RunParams.FixturedFromFixture = patternMatcher.Results[0].GetPose();
coordinateAligner.Run();

// 정렬된 출력 이미지를 가져옵니다. 이후의 캘리퍼나 Blob 도구 등은 이 이미지 위에서 실행됩니다.
ICogImage alignedImage = coordinateAligner.OutputImage;

9. ToolBlock 스크립트 활용

ToolBlock 스크립트는 VisionPro ToolBlock 내에서 C# 코드를 사용하여 비전 처리 로직을 제어하고, 도구 간의 복잡한 상호작용이나 커스텀 로직을 구현할 수 있게 합니다. 이는 유연하고 강력한 비전 시스템 구축을 가능하게 합니다.

// ToolBlock 스크립트의 기본 클래스
public class CustomToolBlockScript : CogToolBlockAdvancedScriptBase
{
    private CogToolBlock _toolBlockInstance;

    // ToolBlock의 주요 실행 함수: 이 함수에서 ToolBlock 내의 도구 실행 순서와 로직을 제어합니다.
    public override bool GroupRun(ref string message, ref CogToolResultConstants result)
    {
        // ToolBlock 내의 특정 도구에 접근
        // "CogBlobTool1"은 ToolBlock 내에 정의된 CogBlobTool의 이름이라고 가정합니다.
        CogBlobTool targetBlobTool = _toolBlockInstance.Tools["CogBlobTool1"] as CogBlobTool;
        
        // ToolBlock 내 모든 도구를 순서대로 실행 (스크립트에서 제어)
        foreach (ICogTool tool in _toolBlockInstance.Tools)
        {
            // 개별 도구 실행 중 오류 발생 시 예외 처리
            try
            {
                _toolBlockInstance.RunTool(tool, ref message, ref result);
            }
            catch (CogException ex)
            {
                message = $"도구 '{tool.Name}' 실행 중 오류: {ex.Message}";
                result = CogToolResultConstants.Error;
                return false; // 오류 발생 시 스크립트 중단
            }
        }
        
        // Blob 도구 결과 확인 및 스크립트 로직 수행
        int blobCount = 0;
        if (targetBlobTool != null && targetBlobTool.Results != null)
        {
            blobCount = targetBlobTool.Results.GetBlobs().Count;
        }
        
        // ToolBlock 상태바에 표시될 메시지 설정
        message = $"검출된 Blob 개수: {blobCount}";
        
        // false 반환: 스크립트가 도구 실행을 직접 처리했음을 ToolBlock에 알립니다.
        // ToolBlock은 더 이상 도구들을 자동으로 재실행하지 않습니다.
        return false;
    }

    // 스크립트 초기화 시 호출: ToolBlock 인스턴스를 저장하여 스크립트 내에서 접근할 수 있게 합니다.
    public override void Initialize(CogToolGroup host)
    {
        base.Initialize(host);
        _toolBlockInstance = host as CogToolBlock;
    }

    // 마지막 실행 기록 수정: CogRecordDisplay에 표시될 그래픽이나 텍스트를 추가할 수 있습니다.
    public override void ModifyLastRunRecord(ICogRecord lastRecord)
    {
        // 실행 기록에 텍스트 라벨 그래픽을 추가하여 CogRecordDisplay에 표시
        CogGraphicLabel resultLabel = new CogGraphicLabel();
        resultLabel.SetXYText(100, 100, "스크립트 결과");
        // 인자: 그래픽 객체, 기록 객체, 오버레이할 타겟 이미지의 기록 경로, 레이어 이름
        _toolBlockInstance.AddGraphicToRunRecord(resultLabel, lastRecord, "CogBlobTool1.InputImage", "scriptOverlay");
    }
}

3. 일반적인 문제 해결

오류 1: CogNotConnectedException (연결 끊김)

• 현상: 비전 도구 실행 시 "연결되지 않음" 오류 발생.
• 원인: 카메라 또는 이미지 소스의 연결 문제.
• 해결:
  1. 카메라 물리적 연결 상태 확인 (케이블, 전원).
  2. CogAcqFifoTool 설정 및 활성화 상태 점검.
  3. 이미지 취득(Acquisition)이 성공적으로 이루어지는지 확인.

오류 2: CogPMAlignNoMatchException (패턴 불일치)

• 현상: 패턴 정합 도구가 결과(Match)를 찾지 못함.
• 원인: 템플릿 학습 부족 또는 이미지 품질 저하.
• 해결:
  1. 명확한 특징을 포함하도록 템플릿 재학습.
  2. 매칭 임계값(Score), 검색 범위 등 파라미터 조정.
  3. 이미지의 조명 및 대비 상태 확인.

오류 3: CogCalibNPointToNPointCalibrationFailedException (교정 실패)

• 현상: 좌표계 교정(Calibration) 과정에서 오류 발생.
• 원인: 교정점 개수 부족 또는 비정상적인 분포.
• 해결:
  1. 교정점 개수 증가 (최소 4개 권장).
  2. 교정점이 전체 영역에 고르게 분포되도록 조정.
  3. 좌표 쌍(Points)의 정확성 검토.

오류 4: 스크립트 실행 문제

• 현상: ToolBlock 스크립트 실행 중 예기치 않은 오류 발생.
• 원인: 스크립트에서 존재하지 않는 도구 또는 파라미터 접근.
• 해결:
  1. ToolBlock 내 도구 이름과 스크립트에서 참조하는 이름 일치 여부 확인.
  2. 예외 처리를 위한 try-catch 블록 사용.
  3. 모든 필요한 도구가 ToolBlock에 올바르게 추가되었는지 확인.

오류 5: 이미지 디스플레이 문제

• 현상: CogDisplay 컨트롤에 이미지가 표시되지 않음.
• 원인: 이미지 할당 누락 또는 디스플레이 설정 오류.
• 해결:
  1. CogDisplay.Image 속성에 이미지가 할당되었는지 확인.
  2. cogDisplay.Fit() 호출로 이미지 자동 맞춤.
  3. 사용 중인 이미지 형식 지원 여부 확인.