Region · Calibration Types

기준: OverAnim 0.1.0 Beta · Unreal Engine 5.8
헤더: OverAnimation/Runtime/OverAnimProportionCalibration.h, OverAnimation/Types/OverAnimRegionTypes.h

이 페이지는 Region 거리와 motion feature를 캐릭터 크기에 맞춰 해석하는 공개 타입을 다룹니다. Region mask 자체는 Bone Group · Region을 참조합니다.

Region mask · LOD C++ contracts

OverAnimRegionTypes.h의 Region mask, LOD, composition 타입은 Bone Group의 Region 설정에 사용됩니다. Details 필드의 전체 표는 Bone Group · Region에서 확인합니다.

Enum 또는 C++ 선언	값 · 반환	계약
`EOverAnimRegionFalloffMode`	`Linear`, `SmoothStep`, `Power`	`FOverAnimRegionMaskPolicy::FalloffMode`가 vertex mask의 0과 full 사이 curve를 선택합니다. `Power`만 `FalloffExponent`를 읽습니다.
`EOverAnimRegionLodPolicy`	`AllowInactive`, `WarnIfInactive`, `RequireCoverage`	해당 LOD의 Region coverage 부족을 허용, 경고, 필수 조건으로 각각 처리합니다.
`EOverAnimRegionCompositionPolicy`	`AdditiveClamped` (`Additive Delta`), `StrongestDelta` (`Strongest Delta`)	겹치는 Region delta를 clamp한 합으로 합성하거나, 가장 강한 delta 하나로 합성합니다.
`bool OverAnimRegionLod::RequiresCoverage(EOverAnimRegionLodPolicy Policy, bool bIsAttachmentDependency)`	coverage가 필수면 `true`	`bIsAttachmentDependency`가 true이면 policy와 무관하게 `true`입니다. 그렇지 않으면 `RequireCoverage`일 때만 `true`입니다. Blueprint 노드가 아닙니다.

`FOverAnimRegionMaskPolicy` 필드	기본값 · 범위	효과 · 조건
`FalloffMode`	`SmoothStep`	위 falloff curve를 선택합니다.
`ZeroWeight`	`0`, `0..1`	이 skin weight 이하에서 Region mask는 0입니다.
`FullWeight`	`1`, `0..1`	이 skin weight 이상에서 Region mask는 1입니다. `ZeroWeight`보다 커야 유효한 전이 구간을 만듭니다.
`FalloffExponent`	`1`, `0.01+`	`Power` mode의 곡률입니다. 다른 mode에서는 값이 남아 있어도 결과에 쓰이지 않습니다.

Calibration Enum

Enum	값	의미
`EOverAnimSpatialCalibrationMode`	`CharacterRelative`	authored linear distance에 character scale을 곱합니다.
	`RegionRelative`	Region reference size와 ratio가 유효하면 그 값을 사용하고, 아니면 character-relative로 fallback합니다.
	`Absolute`	authored distance를 그대로 사용합니다.
`EOverAnimMotionMeasurementBasis`	`Auto`	actor motion은 locomotion height, Region motion은 chain/span/bounds/average bone 순으로 선택합니다.
	`CharacterHeight`, `LocomotionHeight`	전 캐릭터 기준의 scale을 사용합니다.
	`RegionSpan`, `RegionBoundsRadius`, `RegionChainLength`, `AverageBoneLength`	Region measurement가 있을 때만 해당 scale을 사용합니다. 없으면 해석 실패입니다.
	`Absolute`	scale `1`을 사용합니다.

FOverAnimProportionCalibrationSettings

OverAnimProportion namespace는 긴 구조체 이름을 사용하는 C++ 통합을 위해 다음 alias를 제공합니다.

Alias	원래 타입
`OverAnimProportion::FCalibration`	`FOverAnimProportionCalibrationSettings`
`OverAnimProportion::FCharacter`	`FOverAnimResolvedCharacterProportions`
`OverAnimProportion::FRegion`	`FOverAnimResolvedRegionProportions`
`OverAnimProportion::FMotionScales`	`FOverAnimMotionMeasurementScales`

Details UI 이름	C++ 속성명	기본값 · 범위	영향
Enable Automatic Calibration	`bEnableAutomaticCalibration`	`true`	linear distance, speed, acceleration을 측정된 비율로 보정합니다. angular/time 값은 바꾸지 않습니다.
Reference Character Height	`ReferenceCharacterHeight`	`180 cm`, `1+`	character scale이 1이 되는 기준 높이입니다.
Locomotion Root Bone	`LocomotionRootBone`	`None`	locomotion height를 바닥에서 재는 reference-pose bone입니다. `None`이면 body root를 자동 선택합니다.
Reference Locomotion Height	`ReferenceLocomotionHeight`	`90 cm`, `1+`	actor speed/acceleration authored 기준 높이입니다.
Reference Ground Probe Radius	`ReferenceGroundProbeRadius`	`42 cm`, `1+`	ground probe distance의 scale 기준입니다.
Reference Region Span Length	`ReferenceRegionSpanLength`	`60 cm`, `1+`	Region endpoint span의 scale 기준입니다.
Reference Region Bounds Radius	`ReferenceRegionBoundsRadius`	`20 cm`, `1+`	Region bounds radius의 scale 기준입니다.
Reference Region Chain Length	`ReferenceRegionChainLength`	`60 cm`, `1+`	Region chain length의 scale 기준입니다.
Reference Average Bone Length	`ReferenceAverageBoneLength`	`15 cm`, `1+`	Region average bone length의 scale 기준입니다.
Minimum Character Scale	`MinimumCharacterScale`	`0.25`, `0.01..1`	자동 계산 scale의 하한입니다.
Maximum Character Scale	`MaximumCharacterScale`	`4`, `1..10`	자동 계산 scale의 상한입니다. 내부 해석은 최소값보다 작지 않게 정리합니다.

ResolveMeasurementScale은 automatic calibration이 꺼졌거나 measurement/reference가 유효하지 않으면 1을 반환합니다. measurement/reference가 유효하면 Measured / Reference를 minimum/maximum scale 범위로 clamp합니다.

Calibration C++ resolver contracts

C++ 선언	반환	입력 · 경계 계약
`float ResolveMeasurementScale(float MeasuredValue, float ReferenceValue) const`	character-scale 범위의 scale	automatic calibration이 꺼졌거나 measurement/reference가 non-finite 또는 0 이하이면 `1`입니다. 그 외에는 `MeasuredValue / ReferenceValue`를 `max(MinimumCharacterScale, 0.01)`부터 `max(MaximumCharacterScale, minimum)`까지 clamp합니다.
`float ResolveCharacterScale(float CharacterHeight) const`	character-height scale	`ResolveMeasurementScale(CharacterHeight, ReferenceCharacterHeight)`의 결과입니다.
`float ResolveOptionalMeasurementScale(float MeasuredValue, float ReferenceValue) const`	optional Region measurement scale	measurement가 non-finite 또는 0 이하이면 `0`입니다. 그 외에는 `ResolveMeasurementScale` 결과입니다. `0`은 Region measurement 부재를 나타내며 character scale fallback이 아닙니다.

FOverAnimMotionMeasurementScales

이 구조체는 runtime read-only snapshot입니다. FOverAnimSignal::MotionFeatures.MeasurementScales에서 읽습니다.

C++ 속성명	기본값	의미
`CharacterHeightScale`	`1`	character height의 calibrated scale
`LocomotionHeightScale`	`1`	locomotion height의 calibrated scale
`GroundProbeRadiusScale`	`1`	ground probe radius의 calibrated scale
`RegionSpanScale`, `RegionBoundsRadiusScale`, `RegionChainLengthScale`, `AverageBoneLengthScale`	`0`	Region measurements가 없으면 0입니다.
`bIsRegionMotion`	`false`	현재 signal이 Region motion인지 나타냅니다.
`bHasRegionMeasurements`	`false`	하나 이상의 Region scale이 유효함을 나타냅니다.

TryResolveScale(Basis, OutScale)은 Region* basis를 선택했는데 Region measurement가 없거나 0이면 false입니다. Auto는 Region motion일 때 chain → span → bounds → average bone 순으로 fallback하고, actor motion일 때 locomotion height를 사용합니다.

C++ 선언	반환 · out	계약
`bool IsValid() const`	scale snapshot 유효 여부	`CharacterHeightScale`, `LocomotionHeightScale`, `GroundProbeRadiusScale`가 모두 finite한 양수여야 합니다. Region scale의 유무는 이 검사에 포함되지 않습니다.
`bool TryResolveScale(EOverAnimMotionMeasurementBasis Basis, float& OutScale) const`	scale을 찾으면 `true` 및 `OutScale`	호출 시작 시 `OutScale`은 `0`입니다. `Absolute`는 `1`; character/locomotion은 해당 scale을 사용합니다. `Region*`은 `bHasRegionMeasurements`가 true일 때만 해당 scale을 사용합니다. `Auto`의 Region fallback 순서는 chain → span → bounds → average bone입니다. 최종 scale이 finite한 양수여야 `true`입니다.

Resolved measurement structs

FOverAnimResolvedCharacterProportions와 FOverAnimResolvedRegionProportions는 외부 설정 입력이 아니라 runtime에서 계산되는 C++ 공개 값입니다.

구조체	읽기 값	의미
`FOverAnimResolvedCharacterProportions`	`CharacterHeightCS/WS`, `CharacterScaleCS/WS`	component/world space의 character height와 scale
	`LocomotionHeightCS/WS`, `LocomotionScaleCS/WS`	locomotion 기준 높이와 scale
	`GroundProbeRadiusCS/WS`, `GroundProbeScaleCS/WS`	ground probe 기준과 scale
`FOverAnimResolvedRegionProportions`	`SpanLength`, `BoundsRadius`, `ChainLength`, `AverageBoneLength`	Region의 측정 길이
	`GetOffsetReferenceLength()`	chain → span → bounds diameter → average bone 순으로 offset reference를 반환합니다.
	`GetFocalReferenceRadius()`	bounds radius → span half → average bone 순으로 focal reference를 반환합니다.

선형 단위만 보정

Proportion Calibration은 cm, cm/s, cm/s² 같은 선형 값을 다룹니다. degree, radian, seconds 값은 character size에 따라 바뀌지 않습니다.

Resolved proportion · namespace helper contracts

C++ 선언	반환	계약
`float FOverAnimResolvedRegionProportions::GetOffsetReferenceLength() const`	offset reference length	`ChainLength` → `SpanLength` → `BoundsRadius × 2` → `max(AverageBoneLength, 0)` 순으로 첫 양수를 반환합니다.
`float FOverAnimResolvedRegionProportions::GetFocalReferenceRadius() const`	focal reference radius	`BoundsRadius` → `SpanLength × 0.5` → `max(AverageBoneLength, 0)` 순으로 첫 양수를 반환합니다.
`FOverAnimMotionMeasurementScales OverAnimProportion::BuildMeasurementScales(const FOverAnimProportionCalibrationSettings& Calibration, const FOverAnimResolvedCharacterProportions& Character, const FOverAnimResolvedRegionProportions* Region, bool bWorldSpace)`	measurement scale snapshot	`bWorldSpace`에 따라 Character의 CS 또는 WS scale을 복사합니다. `Region`이 있으면 Region motion으로 표시하고 네 optional Region scale을 계산하며, 하나라도 양수이면 `bHasRegionMeasurements`를 true로 둡니다. `Region == nullptr`이면 Region 관련 값은 기본 0/false입니다.
`float OverAnimProportion::ResolveSpatialDistance(EOverAnimSpatialCalibrationMode Mode, float AuthoredDistance, float RegionRatio, float CharacterScale, float RegionReferenceSize)`	해석된 거리	authored distance는 최소 `0`, character scale은 finite한 최소 `0.01` 또는 fallback `1`입니다. `Absolute`는 distance 그대로, `RegionRelative`는 양의 region size와 ratio가 모두 있을 때 그 곱, 그 외와 `CharacterRelative`는 distance × character scale입니다.