pybullet

• 

0. pb.computeViewMatrix

• 카메라의 뷰 매트릭스(view matrix)를 계산하기 위해 사용
• 뷰 매트릭스는 3D 씬을 2D 이미지로 투영할 때 카메라의 위치와 방향을 정의하는 데 사용됩니다.

0.1. 뷰 매트릭스(View Matrix)

• extrinsic (4 by 4)
• 

0.2. 파라미터(Parameters)

• cameraEyePosition:
  • 카메라의 위치를 나타내는 3차원 좌표
  • 형식은 (x, y, z)의 튜플
• cameraTargetPosition:
  • 카메라가 바라보는 타겟의 위치를 나타내는 3차원 좌표
  • 형식은 (x, y, z)의 튜플
• cameraUpVector:
  • 카메라의 업 벡터를 나타내는 3차원 좌표
  • 이 벡터는 카메라가 '위'라고 인식하는 방향을 정의
  • 형식은 (x, y, z)의 튜플입니다.

0.3. 반환 값(Return Value)

• computeViewMatrix 함수는 계산된 뷰 매트릭스를 나타내는 16개의 실수(float) 값으로 구성된 플랫(flatten)된 리스트를 반환
• 이 리스트는 4x4 매트릭스를 일렬로 나열한 것으로, OpenGL이나 다른 그래픽스 라이브러리에서 사용하기에 적합한 형태입니다.

반환 타입: List[float] (길이가 16인 리스트)

0.4. 사용 예시

import pybullet as pb

# 카메라의 위치, 타겟 위치, 업 벡터 정의
cameraEyePosition = (1, 1, 1)
cameraTargetPosition = (0, 0, 0)
cameraUpVector = (0, 0, 1)

# 뷰 매트릭스 계산
viewMatrix = pb.computeViewMatrix(cameraEyePosition, cameraTargetPosition, cameraUpVector)

print("뷰 매트릭스:", viewMatrix)

• 이 예시에서는 카메라가 (1, 1, 1) 위치에 있고, (0, 0, 0)을 바라보며, 카메라의 '위' 방향이 z축 방향인 상황에서 뷰 매트릭스를 계산합니다. 반환된 뷰 매트릭스는 3D 씬을 2D 이미지로 투영하는 데 사용할 수 있습니다.

---

1. computeViewMatrixFromYawPitchRoll

• PyBullet에서 카메라의 뷰 매트릭스를 계산하는 데 사용
• 이 메서드는 주어진 요(yaw), 피치(pitch), 롤(roll) 각도와 카메라의 대상 위치, 거리 등을 기반으로 뷰 매트릭스를 생성
• 뷰 매트릭스: 3D 세계에서의 객체를 카메라 관점으로 변환하는 데 사용

뷰 매트릭스(View Matrix)

• extrinsic (4 by 4)
• 

인자:

• cameraTargetPosition (tuple(float, float, float)):
  • 카메라가 바라보고 있는 대상 위치
  • 일반적으로 이는 카메라가 중심을 맞추고 있는 지점의 월드 좌표
• distance (float):
  • 카메라와 대상 위치 간의 거리
• yaw (float):
  • 카메라의 요(yaw) 각도
  • 이는 수평 회전을 나타내며, 각도는 도(degree) 단위로 측정
• pitch (float): 카메라의 피치(pitch) 각도입니다. 이는 수직 회전을 나타냄
• roll (float): 카메라의 롤(roll) 각도입니다. 이는 카메라가 자신의 축을 중심으로 회전하는 것을 나타냄
• upAxisIndex (int):
  카메라의 "위" 방향을 결정하는 축의 인덱스입니다.
  일반적으로 1은 Y축이 위쪽을 가리키고, 2는 Z축이 위쪽을 가리키는 설정에 사용됩니다.

반환 값:

계산된 뷰 매트릭스를 나타내는 16개의 값을 포함하는 리스트를 반환
이 뷰 매트릭스는 OpenGL 스타일로 구성되어 있으며,
이를 통해 3D 월드 -> 카메라 관점 (Extrinsic)

---

2. computeProjectionMatrixFOV

• PyBullet에서 카메라의 프로젝션 매트릭스를 계산
• 프로젝션 매트릭스는 3D 세계의 객체를 2D 이미지로 투영하는 데 사용

prjection matrix

• 이 매트릭스는 3D 장면을 카메라의 시점에서 보는 방식을 정의하며, 주로 원근 투영(Perspective Projection)과 직교 투영(Orthographic Projection) 두 가지 유형이 있습니다.

Perspective Projection Matrix

• 원근 투영은 3D 공간의 점들을 2D 평면에 투영할 때 깊이(Z 값)에 따라 객체의 크기가 달라지게 하는 효과
• 이는 실제 인간의 시각과 유사한 효과를 생성하며, 멀리 있는 객체가 가까이 있는 객체보다 작게 보이는 원근감을 제공
• 원근 투영 매트릭스는 다음과 같은 수식으로 나타낼 수 있습니다:
• 
• 

Orthographic Projection Matrix

• 직교 투영은 깊이에 관계없이 모든 객체의 크기를 동일하게 유지하는 투영 방법입니다.
• 이는 주로 엔지니어링 도면이나 건축 렌더링에 사용되어 객체 간의 정확한 비율을 유지해야 할 때 적합합니다.
• 

인자:

• fov (float): 카메라의 시야각(Field of View)입니다. 이는 카메라가 한 번에 볼 수 있는 범위를 결정하며, 각도는 도(degree) 단위로 측정
• aspect (float): 카메라의 종횡비(aspect ratio)입니다. 이는 이미지의 가로 세로 비율을 나타내며, 일반적으로 화면의 가로 길이를 세로 길이로 나눈 값
• nearPlane (float): 근접 평면(near plane)의 거리입니다. 이는 카메라로부터 얼마나 가까운 지점부터 장면을 렌더링할지 결정합니다. 이 값은 양수
• farPlane (float): 원거리 평면(far plane)의 거리입니다. 이는 카메라로부터 얼마나 먼 지점까지 장면을 렌더링할지 결정합니다. 근접 평면보다 커야 하며, 이 값에 따라 렌더링할 수 있는 장면의 최대 깊이가 결정

반환 값:

• 이 메서드는 계산된 프로젝션 매트릭스를 나타내는 16개의 값을 포함하는 리스트를 반환
• 이 프로젝션 매트릭스는 OpenGL 스타일로 구성되어 있음

---

3. getCameraImage

• getCameraImage 메서드는 PyBullet에서 시뮬레이션된 3D 환경의 이미지를 캡처하는 데 사용
• 이 메서드는 미리 정의된 카메라의 뷰 매트릭스와 프로젝션 매트릭스를 기반으로 2D 이미지를 생성

인자:

• width (int): 이미지의 너비(픽셀 단위).
• height (int): 이미지의 높이(픽셀 단위).
• viewMatrix ([float]): 카메라의 뷰 매트릭스. 이 매트릭스는 카메라의 위치와 방향을 결정합니다. computeViewMatrixFromYawPitchRoll 함수를 사용하여 생성할 수 있습니다.
• projectionMatrix ([float]): 카메라의 프로젝션 매트릭스. 이 매트릭스는 3D 장면을 2D 이미지로 투영하는 방법을 결정합니다. computeProjectionMatrixFOV 함수를 사용하여 생성할 수 있습니다.
• lightDirection ([float], optional): 조명의 방향을 결정하는 3개의 값으로 구성된 리스트. 기본값은 [0, 0, 1]입니다.
• lightColor ([float], optional): 조명의 색상과 강도를 결정하는 3개의 값으로 구성된 리스트. 기본값은 [1, 1, 1]으로 백색 조명입니다.
• shadow (bool, optional): 그림자 효과를 활성화할지 여부를 결정합니다. 기본값은 False입니다.
• renderer (int, optional): 사용할 렌더러를 지정합니다. p.ER_TINY_RENDERER (기본값) 또는 p.ER_BULLET_HARDWARE_OPENGL 중 선택할 수 있습니다.

반환 값:

getCameraImage 메서드는 다음을 포함하는 튜플을 반환합니다:

• width (int): 이미지의 너비.
• height (int): 이미지의 높이.
• rgbPixels ([int]): RGB 컬러 이미지 데이터를 포함하는 배열. 배열의 크기는 [높이, 너비, 4]이며, 마지막 차원은 RGBA 값입니다.
• depthPixels ([float]): 깊이 이미지 데이터를 포함하는 배열. 각 픽셀 값은 카메라로부터의 상대적 거리를 나타냅니다. 배열의 크기는 [높이, 너비]입니다.
• segmentationMaskBuffer ([int]): 각 픽셀의 세그멘테이션 마스크 데이터를 포함하는 배열. 이 값은 해당 픽셀에서 보이는 객체의 고유 ID를 나타냅니다. 배열의 크기는 [높이, 너비]입니다.

이 메서드를 사용하면 시뮬레이션 환경 내의 다양한 시점에서 캡처한 컬러, 깊이, 그리고 세그멘테이션 이미지를 얻을 수 있으며, 이를 통해 시뮬레이션된 환경의 시각적 분석이나 로봇 비전 시스템의 개발에 활용할 수 있습니다.

---

4. pb.loadURDF

• loadURDF 메서드는 PyBullet 시뮬레이션에 Unified Robot Description Format (URDF) 파일을 이용하여 로봇이나 다른 객체를 로드하는 데 사용
• URDF 파일은 로봇의 물리적, 시각적 특성과 관절, 센서 등을 정의

인자:

• fileName (str): 로드할 URDF 파일의 경로입니다. 이 파일은
• basePosition ([float, float, float], optional): 객체의 월드 공간에서의 초기 위치입니다. 기본값은 [0, 0, 0]입니다.
• baseOrientation ([float, float, float, float], optional): 객체의 월드 공간에서의 초기 방향(쿼터니언)입니다. 기본값은 [0, 0, 0, 1]이며, 이는 회전 없음을 의미합니다.
• useFixedBase (bool, optional): 객체가 움직이지 않고 고정되어 있어야 하는 경우 True로 설정합니다. 기본값은 False입니다. 예를 들어, 환경에 고정된 구조물을 나타낼 때 유용합니다.
• globalScaling (float, optional): 객체의 전체 크기를 조정하는 스케일 인자입니다. 기본값은 1.0이며, 이는 원본 크기를 의미합니다.
• physicsClientId (int, optional): 여러 PyBullet 인스턴스를 사용하는 경우, 특정 시뮬레이션 인스턴스를 지정하는 데 사용됩니다. 기본값은 0입니다.
• 기타 인자: URDF를 로드할 때 추가적인 설정을 위한 다양한 인자가 있을 수 있습니다. 이러한 인자들은 PyBullet의 버전에 따라 달라질 수 있으며, 공식 문서를 참조하는 것이 좋습니다.

반환 값:

• 이 메서드는 로드된 객체의 고유 ID를 반환
• 이 ID는 나중에 객체에 대한 참조로 사용되며, PyBullet의 다른 메서드에서 해당 객체를 조작할 때 필요

---

5. pb.resetDebugVisualizerCamera

• 디버그 시각화 카메라의 위치와 방향을 설정하는 데 사용
• 이 메서드를 통해 시뮬레이션 내에서 카메라의 시점을 조절할 수 있으며, 특정 객체를 관찰하거나 시뮬레이션 환경을 다양한 각도에서 바라보고자 할 때 유용

파라미터

• cameraDistance (float):
  • 관측 대상으로부터 카메라까지의 거리
• cameraYaw (float):
  • 수평축(yaw axis)을 중심으로 한 카메라의 회전 각도
  • 단위는 도(degree)
• cameraPitch (float):
  • 수직축(pitch axis)을 중심으로 한 카메라의 회전 각도
  • 단위는 도(degree)입니다.
• cameraTargetPosition ([float, float, float]):
  • 카메라가 바라보는 목표 지점의 세계 좌표
  • 리스트나 튜플 형태로 [x, y, z] 좌표를 제공해야 합니다.

반환 값

resetDebugVisualizerCamera 메서드는 특별한 반환 값이 없습니다(None을 반환)

예제 사용법

import pybullet as p

# PyBullet 연결을 시작합니다.
physicsClient = p.connect(p.GUI)

# 카메라를 초기화하고, 특정 지점을 바라보도록 설정합니다.
# 여기서, 카메라는 (0, 0, 0)을 바라보며, 거리는 10, Yaw는 45도, Pitch는 -30도로 설정됩니다.
p.resetDebugVisualizerCamera(cameraDistance=10, cameraYaw=45, cameraPitch=-30, cameraTargetPosition=[0, 0, 0])

---

6. pb.configureDebugVisualizer

• 디버그 시각화 설정을 구성하는 데 사용되는 함수
• 이 함수는 다양한 시각적 속성을 변경할 수 있게 해주어 시뮬레이션 중에 정보를 더 잘 이해하고 분석할 수 있게 돕습니다.

6.1. 사용법

import pybullet as pb

pb.connect(pb.GUI)  # 시뮬레이션을 시작하고 GUI 모드로 연결

# configureDebugVisualizer를 사용하여 디버그 시각화 설정을 구성
pb.configureDebugVisualizer(flag=pb.COV_ENABLE_GUI, value=0)  # 예: GUI 를 비활성화

주요 인자

• flag: 설정하려는 시각화 구성의 유형을 지정합니다. 예를 들어, COV_ENABLE_SHADOWS는 그림자 활성화/비활성화를, COV_ENABLE_GUI는 GUI 활성화/비활성화를 제어합니다.
• value: 지정된 flag에 대한 값입니다.
  • 대부분의 경우, 이 값은 0 (비활성화) 또는 1 (활성화)

주요 Flag

• COV_ENABLE_SHADOWS: 그림자
• COV_ENABLE_WIREFRAME: 와이어프레임 모드
• COV_ENABLE_GUI: 내장된 GUI 모드
  • 버튼이나 슬라이더와 같은 GUI 요소의 표시를 제어
• COV_ENABLE_TINY_RENDERER: Tiny Renderer를 사용하는 시각화
• COV_ENABLE_RGB_BUFFER_PREVIEW: RGB 버퍼 미리보기
• COV_ENABLE_DEPTH_BUFFER_PREVIEW: 깊이 버퍼 미리보기
• COV_ENABLE_SEGMENTATION_MARK_PREVIEW: segmentation mask 미리보기
• COV_ENABLE_MOUSE_PICKING: 사용자는 마우스로 객체를 선택하고 조작할 수 있음.
• COV_ENABLE_KEYBOARD_SHORTCUTS: 디버그 시각화에서 제공하는 키보드 단축키 기능
• COV_ENABLE_RENDERING:
  • 렌더링 프로세스를 활성화하거나 비활성화하는 데 사용
  • 이 플래그를 사용하면, 시뮬레이션 중에 객체의 추가, 제거, 또는 변형과 같은 연산을 수행할 때 시각적 렌더링을 일시적으로 중지할 수 있음
  • 이렇게 함으로써, 여러 변경 사항을 한 번에 적용한 후에만 렌더링을 다시 활성화하여 시각적 업데이트를 수행할 수 있으므로, 이러한 연산들이 시각적으로 표현되는 과정을 더 효율적으로 관리할 수 있음

반환 값

• 없음

사용 예시

• 이 함수의 사용은 시뮬레이션의 성능에 영향을 줄 수 있으므로, 시각적 요소가 중요하지 않은 배치 실행이나 성능 최적화가 필요한 경우에는 불필요한 시각적 기능을 비활성화하는 것이 좋습니다.

---

7. pb.setAdditionalSearchPath(pybullet_data.getDataPath())

• PyBullet 시뮬레이션에 사용될 추가적인 데이터 파일(예: 모델, 환경 텍스처 등)을 찾기 위한 검색 경로를 설정

---

8. pb.rayTestBatch

• 여러 개의 광선(ray)을 동시에 시뮬레이션 환경에 쏘아서, 각 광선이 물체와 충돌하는지 여부를 테스트하는 데 사용
• 이 함수는 특히 물리 기반 시뮬레이션에서 객체 간의 상호작용이나 시야 판정, 거리 측정 등에 유용하게 쓰일 수 있음

8.1. 파라미터(Parameter)

• rayFromPositions:
  • 광선이 시작하는 위치의 리스트. 각 위치는 (x, y, z) 형태의 3차원 벡터로 표현됩니다.
• rayToPositions:
  • 광선이 도달하는 목표 위치의 리스트.
  • rayFromPositions과 마찬가지로, 각 목표 위치는 (x, y, z) 형태의 3차원 벡터입니다.
• numThreads:
  • 선택적인 파라미터로, 광선 테스트를 수행할 때 사용할 스레드의 수입니다.
  • 기본값은 1이며, 멀티스레딩을 사용하여 성능을 향상시킬 수 있습니다.
• parentObjectUniqueId:
  • 선택적인 파라미터로, 특정 객체를 광선 테스트에서 제외하고자 할 때 사용
  • 이 객체의 고유 ID를 지정하면, 해당 객체는 광선 테스트 대상에서 제외
• parentLinkIndex:
  • 선택적인 파라미터로, parentObjectUniqueId로 지정된 객체의 특정 링크를 광선 테스트에서 제외하고자 할 때 사용

8.2. 반환 값(Return Value)

• rayTestBatch 함수는 충돌 테스트의 결과를 나타내는 튜플의 리스트를 반환:

RayTestResult = Tuple[
	int, 
    int, 
    float, 
    Tuple[float, float, float], 
    Tuple[float, float, float]
    ]
RayTestBatchResults = List[RayTestResult]

• 각 튜플은 다음과 같은 정보를 포함합니다:

  • objectUniqueId:
    • 광선이 충돌한 객체의 고유 ID
    • 만약 광선이 어떤 객체와도 충돌하지 않았다면, 이 값은 -1
  • linkIndex:
    • 광선이 충돌한 객체의 링크 인덱스입니다.
    • 만약 광선이 객체의 기본 부분과 충돌했다면, 이 값은 -1입니다.
  • hitFraction:
    • 광선이 출발점에서 목표점까지 가는 도중에 충돌한 위치의 비율입니다.
    • 예를 들어, 0은 출발점 바로, 1은 목표점 바로 직전의 충돌을 나타냅니다.
  • hitPosition: 광선이 충돌한 위치의 좌표입니다.
  • hitNormal: 충돌 지점에서의 표면의 노멀 벡터입니다.

• 이 함수를 사용하여 복잡한 시뮬레이션 환경에서 여러 광선을 효율적으로 처리할 수 있으며, 다양한 물리적 상호작용의 검사나 분석에 활용될 수 있습니다.

---

9. pb.multiplyTransforms

• 두 변환(transform)을 곱하는데 사용
• 이 함수는 주로 두 객체 간의 상대적인 위치와 방향을 계산할 때 사용

9.1. 파라미터(Parameters)

• positionA, orientationA:
  • 첫 번째 변환을 나타내며, positionA는 위치(3차원 벡터), orientationA는 회전(쿼터니언)
• positionB, orientationB:
  • 두 번째 변환을 나타내며, positionB도 위치(3차원 벡터), orientationB도 회전(쿼터니언)

9.2. 반환 값(Return Values)

• 두 변환의 곱셈 결과로 얻어진 최종 위치와 회전을 반환

• 반환 값은 다음과 같은 두 부분으로 구성

• 최종 위치(Tuple[float, float, float]):

  • 3차원 공간에서의 위치를 나타내는 3개의 실수 값으로 구성된 튜플

• 최종 회전(Tuple[float, float, float, float]):

  • 회전을 나타내는 4개의 실수 값(쿼터니언)으로 구성된 튜플

사용 예시

import pybullet as pb

# 첫 번째 변환 (예: 객체 A)
positionA = (1, 0, 0)
orientationA = pb.getQuaternionFromEuler([0, 0, 0])

# 두 번째 변환 (예: 객체 B)
positionB = (0, 1, 0)
orientationB = pb.getQuaternionFromEuler([0, 0, 90])

# 두 변환 곱하기
finalPosition, finalOrientation = pb.multiplyTransforms(positionA, orientationA, positionB, orientationB)

print("최종 위치:", finalPosition)
print("최종 회전:", finalOrientation)