PositionAxesMap

위치 변수와 모션 축 간의 매핑을 관리하여 위치 기반 모션 제어를 가능하게 합니다.

네임스페이스: ControlBee.Models

구현: IPositionAxesMap

개요

PositionAxesMap은 위치 변수(예: Position1D, Position3D)를 물리적 모션 축에 연결합니다. 이 매핑은 다음을 가능하게 합니다:

위치 티칭 - 현재 축 위치를 위치 변수로 읽기
위치 모션 - 여러 축을 저장된 위치로 이동
UI 생성 - 위치와 연결된 축 표시
유효성 검사 - 모션 전에 축이 사용 가능한지 확인

각 액터는 Actor.PositionAxesMap 속성을 통해 액세스할 수 있는 자체 PositionAxesMap 인스턴스를 가집니다.

내부 저장소

private readonly Dictionary<string, IAxis[]> _map;
private readonly Dictionary<IVariable, IAxis[]> _variableMap;

클래스는 두 개의 딕셔너리를 유지합니다:

_variableMap - 액터 생성 중 임시 저장소
_map - 변수 항목 경로로 키가 지정된 최종 매핑

매핑은 프레임워크에서 UpdateMap()이 호출될 때 완료됩니다.

메서드

Add

public void Add(IVariable variable, IAxis[] axes)

위치 변수와 축 배열 간의 매핑을 추가합니다.

매개변수:

variable — 위치 변수(Position1D, Position2D, Position3D 등)
axes — 이 위치에 해당하는 축 배열

사용 예시:

public class StageActor : Actor
{
    public Variable<Position1D> LoadPosX = new(VariableScope.Local);
    public Variable<Position3D> PickPos = new(VariableScope.Local);

    public IAxis X, Y, Z;

    public StageActor(ActorConfig config) : base(config)
    {
        X = config.AxisFactory.Create();
        Y = config.AxisFactory.Create();
        Z = config.AxisFactory.Create();

        // 위치 변수를 축에 매핑
        PositionAxesMap.Add(LoadPosX, [X]);           // 1D 위치는 X 축에 매핑
        PositionAxesMap.Add(PickPos, [X, Y, Z]);     // 3D 위치는 X, Y, Z 축에 매핑
    }
}

Get

public IAxis[] Get(string itemPath)

항목 경로로 위치 변수와 연결된 축을 검색합니다.

매개변수:

itemPath — 위치 변수의 항목 경로

반환값: 이 위치에 매핑된 축 배열

예외: 항목 경로가 맵에서 발견되지 않으면 PlatformException

사용 예시:

// 위치에 대한 축 가져오기
var axes = PositionAxesMap.Get("PickPos");
foreach (var axis in axes)
{
    Console.WriteLine($"Axis position: {axis.ActualPosition}");
}

참고: 이 메서드는 일반적으로 프레임워크에서 내부적으로 사용됩니다. 사용자 코드는 일반적으로 직접 호출하지 않습니다.

UpdateMap

public void UpdateMap()

_variableMap에서 _map으로 항목을 전송하여 매핑을 완료합니다. 액터 생성 후 프레임워크에서 호출됩니다.

참고: 프레임워크에서 자동으로 호출됩니다. 사용자 코드는 이 메서드를 호출해서는 안 됩니다.

사용 패턴

1. 단일 축 위치

public class LinearStageActor : Actor
{
    public Variable<Position1D> LoadPos = new(VariableScope.Local);
    public Variable<Position1D> UnloadPos = new(VariableScope.Local);

    public IAxis X;

    public LinearStageActor(ActorConfig config) : base(config)
    {
        X = config.AxisFactory.Create();

        // 두 위치를 동일한 X 축에 매핑
        PositionAxesMap.Add(LoadPos, [X]);
        PositionAxesMap.Add(UnloadPos, [X]);
    }

    [Function]
    public void MoveToLoad()
    {
        LoadPos.Value.MoveAndWait();  // X 축을 LoadPos 위치로 이동
    }

    [Function]
    public void TeachLoadPos()
    {
        LoadPos.Value.TeachCurrent();  // X 축 위치를 LoadPos로 읽기
    }
}

2. 다축 위치

public class PickerActor : Actor
{
    public Variable<Position3D> PickPos = new(VariableScope.Local);
    public Variable<Position3D> PlacePos = new(VariableScope.Local);

    public IAxis X, Y, Z;

    public PickerActor(ActorConfig config) : base(config)
    {
        X = config.AxisFactory.Create();
        Y = config.AxisFactory.Create();
        Z = config.AxisFactory.Create();

        // 3D 위치를 세 축 모두에 매핑
        PositionAxesMap.Add(PickPos, [X, Y, Z]);
        PositionAxesMap.Add(PlacePos, [X, Y, Z]);
    }

    [Function]
    public void MoveToPick()
    {
        // X, Y, Z 축을 PickPos로 동시에 이동
        PickPos.Value.MoveAndWait();
    }

    [Function]
    public void TeachPickPos()
    {
        // X, Y, Z 위치를 PickPos로 읽기
        PickPos.Value.TeachCurrent();
    }
}

3. 혼합 차원

public class ComplexStageActor : Actor
{
    public Variable<Position1D> LoadPosX = new(VariableScope.Local);
    public Variable<Position2D> ScanPosXY = new(VariableScope.Local);
    public Variable<Position3D> PickPosXYZ = new(VariableScope.Local);

    public IAxis X, Y, Z;

    public ComplexStageActor(ActorConfig config) : base(config)
    {
        X = config.AxisFactory.Create();
        Y = config.AxisFactory.Create();
        Z = config.AxisFactory.Create();

        // 다양한 차원의 위치
        PositionAxesMap.Add(LoadPosX, [X]);           // 1D - X만
        PositionAxesMap.Add(ScanPosXY, [X, Y]);      // 2D - X와 Y
        PositionAxesMap.Add(PickPosXYZ, [X, Y, Z]);  // 3D - X, Y, Z
    }
}

4. 축 재사용

public class DualArmActor : Actor
{
    // 왼쪽 팔 위치
    public Variable<Position3D> LeftPickPos = new(VariableScope.Local);
    public Variable<Position3D> LeftPlacePos = new(VariableScope.Local);

    // 오른쪽 팔 위치
    public Variable<Position3D> RightPickPos = new(VariableScope.Local);
    public Variable<Position3D> RightPlacePos = new(VariableScope.Local);

    public IAxis LeftX, LeftY, LeftZ;
    public IAxis RightX, RightY, RightZ;

    public DualArmActor(ActorConfig config) : base(config)
    {
        // 두 팔에 대한 축 생성
        LeftX = config.AxisFactory.Create();
        LeftY = config.AxisFactory.Create();
        LeftZ = config.AxisFactory.Create();

        RightX = config.AxisFactory.Create();
        RightY = config.AxisFactory.Create();
        RightZ = config.AxisFactory.Create();

        // 왼쪽 팔 위치를 왼쪽 축에 매핑
        PositionAxesMap.Add(LeftPickPos, [LeftX, LeftY, LeftZ]);
        PositionAxesMap.Add(LeftPlacePos, [LeftX, LeftY, LeftZ]);

        // 오른쪽 팔 위치를 오른쪽 축에 매핑
        PositionAxesMap.Add(RightPickPos, [RightX, RightY, RightZ]);
        PositionAxesMap.Add(RightPlacePos, [RightX, RightY, RightZ]);
    }
}

오류 처리

매핑 누락

try
{
    var axes = PositionAxesMap.Get("UnmappedPosition");
}
catch (PlatformException ex)
{
    Console.WriteLine($"Position not mapped: {ex.Message}");
}

일반적인 원인:

생성자에서 PositionAxesMap.Add() 호출을 잊음
항목 경로의 오타
변수가 제대로 초기화되지 않음

해결책:

public MyActor(ActorConfig config) : base(config)
{
    X = config.AxisFactory.Create();

    // 매핑 추가를 잊지 마세요!
    PositionAxesMap.Add(MyPosition, [X]);
}

모범 사례

1. 생성자에서 매핑 추가

// ✅ 좋음 - 생성자에서 매핑 추가
public MyActor(ActorConfig config) : base(config)
{
    X = config.AxisFactory.Create();
    PositionAxesMap.Add(LoadPos, [X]);
}

// ❌ 나쁨 - 나중에 매핑 추가(작동하지 않음)
public MyActor(ActorConfig config) : base(config)
{
    X = config.AxisFactory.Create();
}

public override void Start()
{
    base.Start();
    PositionAxesMap.Add(LoadPos, [X]);  // 너무 늦음!
}

2. 모든 위치 변수 매핑

// ✅ 좋음 - 모든 위치 매핑됨
public MyActor(ActorConfig config) : base(config)
{
    X = config.AxisFactory.Create();

    PositionAxesMap.Add(LoadPos, [X]);
    PositionAxesMap.Add(UnloadPos, [X]);
    PositionAxesMap.Add(ProcessPos, [X]);
}

// ❌ 나쁨 - 매핑 누락
public MyActor(ActorConfig config) : base(config)
{
    X = config.AxisFactory.Create();

    PositionAxesMap.Add(LoadPos, [X]);
    // UnloadPos가 매핑되지 않음 - 사용할 때 예외가 발생합니다!
}

3. 올바른 축 순서

// ✅ 좋음 - 올바른 축 순서(X, Y, Z)
PositionAxesMap.Add(PickPos, [X, Y, Z]);

// ❌ 나쁨 - 잘못된 축 순서
PositionAxesMap.Add(PickPos, [Z, Y, X]);  // 잘못된 위치로 이동합니다!

4. 차원 일치

// ✅ 좋음 - 3개 축이 있는 3D 위치
Variable<Position3D> Pos = new(VariableScope.Local);
PositionAxesMap.Add(Pos, [X, Y, Z]);

// ❌ 나쁨 - 차원 불일치
Variable<Position3D> Pos = new(VariableScope.Local);
PositionAxesMap.Add(Pos, [X, Y]);  // Z 축 누락!

위치 변수와의 통합

위치 변수는 내부적으로 PositionAxesMap을 사용합니다:

// 위치를 티칭할 때
LoadPos.Value.TeachCurrent();
// 내부적으로:
// 1. PositionAxesMap에서 축 가져오기
// 2. 각 축의 ActualPosition 읽기
// 3. 위치 변수에 저장

// 위치로 이동할 때
LoadPos.Value.MoveAndWait();
// 내부적으로:
// 1. PositionAxesMap에서 축 가져오기
// 2. 각 축이 이동하도록 명령
// 3. 모든 축이 완료될 때까지 대기

참고

IPositionAxesMap 인터페이스 - 인터페이스 정의
변수 시스템 가이드 - 위치-축 매핑
Position 타입 - Position1D/2D/3D/4D 문서
IAxis 인터페이스 - 모션 축 인터페이스

개요​

내부 저장소​

메서드​

Add​

Get​

UpdateMap​

사용 패턴​

1. 단일 축 위치​

2. 다축 위치​

3. 혼합 차원​

4. 축 재사용​

오류 처리​

매핑 누락​

모범 사례​

1. 생성자에서 매핑 추가​

2. 모든 위치 변수 매핑​

3. 올바른 축 순서​

4. 차원 일치​

위치 변수와의 통합​

참고​

개요