Extend ModuleDockingNode with options for rotational alignment / increments

[sumghai]

Premise

At present, docking ports in KSP allow two vessels to connect together at any relative angle about their combined docking axes, in contrast to real life docking ports where rotational alignment is limited to some specific values (e.g. 120° for APAS, 90° for CBM).

While this may be relatively benign for very small stations or visiting space craft, cumulative rotational errors may result in difficulty in constructing larger or more complex designs, such as rings, closed loops or parallel-docked sections.

Analysis of current solutions

[TABLE=class: grid, width: 1200]

[TR]

[TD=align: center]Method

[/TD]

[TD=align: center]Advantages

[/TD]

[TD=align: center]Disadvantages

[/TD]

[/TR]

[TR]

[TD]Using bi/tri/quad adapters and multiple docking ports[/TD]

[TD]

• Magnetic force from adjacent ports (usually) helps to automatically "snap" rotational alignment afterrough rotational alignment via user input
  
• Able to restrict rotational alignments in angular increments of 180° (bi), 120° (tri) and 90° (quad)
  
• Rotational errors do not accumulate
  

[/TD]

[TD]

• Increased part count for each docking location
  
• Due to KSP's tree structure for vessels, only one docking connection is sufficient for current ModuleDockingNode system to conclude latching, possibly leaving other docking ports "floating"
  
• Visually unrealistic, especially in terms of crew transfer - the adapters are rather flat and with the offset between ports, it is rather difficult to imagine Kerbals squeezing through them
  

[/TD]

[/TR]

[TR]

[TD]Using additional parts on both vessels as

crosshairs / alignment markers (visual only)[/TD]

[TD]

• Few(er) additional parts required
  
• Stock Communotron 16 whiplash antenna is a favourite due to its small size and thin profile
  

[/TD]

[TD]

• Increased part count for each docking location
  
• Feedback is visual only - no physical "snapping"
  
• Manual control required for actual alignment
  
• Accuracy dependent on placement of these guides - minute angular errors may accumulate as more segments are docked along the same axis
  

[/TD]

[/TR]

[TR]

[TD]Using additional parts on both vessels as mechanical alignment guides (part collisions)[/TD]

[TD]

• Few(er) additional parts required
  
• Physical collision forces helps to automatically "snap" rotational alignment after rough rotational alignment via user input
  
• Depending on user design, able to restrict rotational alignments to arbitary angles or increments
  

[/TD]

[TD]

• Increased part count for each docking location
  
• Certain designs may not have room for these mechanical guides
  
• Accuracy dependent on placement of these guides - minute angular errors may accumulate as more segments are docked along the same axis
  

[/TD]

[/TR]

[TR]

[TD]Romfarer's Lazor Docking Cam[/TD]

[TD]

• No additional parts required - plugin only
  
• First-person POV from docking port camera
  
• Rotational error given as numerical reading
  

[/TD]

[TD]

• Feedback is visual only - no physical "snapping"
  
• Manual control required for actual alignment
  
• Accuracy dependent on readout - minute angular errors may accumulate as more segments are docked along the same axis
  

[/TD]

[/TR]

[TR]

[TD]NavyFish's Docking Alignment Indicator[/TD]

[TD]

• No additional parts required - plugin only
  
• Rotational error indicated graphically
  

[/TD]

[TD]

• Feedback is visual only - no physical "snapping"
  
• Manual control required for actual alignment
  
• Accuracy dependent on readout - minute angular errors may accumulate as more segments are docked along the same axis
  

[/TD]

[/TR]

[TR]

[TD]Docking ports with built-in guidance collider fins

(e.g. Semni's JARFR THSS Tri-Hex Docking Ports)[/TD]

[TD]

• No additional parts required
  

[/TD]

[TD]

• Unreliable - once ports are in range of magnetic latching, the alignment colliders are ignored
  

[/TD]

[/TR]

[TR]

[TD]Docking ports with multiple ModuleDockingNodes defined (e.g. Alskari's HSH Docking Ports)[/TD]

[TD]

• No additional parts required
  

[/TD]

[TD]

• Non-intuitive - multiple "Control from here" and "Set as Target" entries appear on controlled and target ports respectively, potentially leading to a guessing game to match combinations
  
• Unreliable - as soon as one node is in range of magnetic latching, the other alignment nodes are ignored
  

[/TD]

[/TR]

[TR]

[TD]sarbian's MechJeb 2 DLL fork with

Rotational Alignment to Target option[/TD]

[TD]

• No additional parts required - plugin only
  
• Allows user to set any arbitrary angular value for rotational alignment, which the craft will automatically maintain to a high degree of accuracy
  
• Very low probability of accumulated angular errors
  
• Available for both automated and manual docking (latter case involves using Smart A.S.S. to aim at target docking port)
  

[/TD]

[TD]

• MechJeb is generally considered controversial
  (I personally swear by it, but not everyone does or will)
  

[/TD]

[/TR]

[/TABLE]

Proposed Solution

I would like to suggest extending the ModuleDockingNode Part Module with optional variables for enforcing roll alignment and permissible angular increments:

MODULE
{
    name = ModuleDockingNode
    referenceAttachNode = top
    nodeType = size1


    [B]// Relative roll alignment for docking in degrees (0~359)
     // If specified, the controlled vessel will align and maintain its docking port to this rotational offset
     // If not specified, defaults to false, which allows docking without forcing any alignment (as is currently the case[/B])
[B]    rollAlignAngle = false

[/B]    [B]// Valid roll alignment increments for docking in degrees (0~180)
     // If specified, this adds additional valid angles to the target docking ports by this increment
     // If not specified, defaults to 0, which [/B][B]means only the value specified in [/B][B]rollAlignAngle[/B][B] is considered a valid docking angle
    rollAlignIncrementAngle = 0[/B]
}

If SAS is enabled, then the vessel will attempt to orient its docking port to the closest roll alignment angle available. This can be overridden and forced to snap at other defined angles if given a strong enough user input (e.g. via RCS).

Additionally, this roll alignment capability may be toggled on/off individually for each docking port via a new context menu GUI, "Enable Angle Snap / Disable Angle Snap".

Examples

1) Stock Clamp-o-tron docking ports

MODULE
{
    name = ModuleDockingNode
    referenceAttachNode = top
    nodeType = size1
}

Since neither of the additional parameters were specified, the Clamp-o-trons will dock freely at any angle about their common docking axis.

2) Non-stock docking port where only one orientation is permitted

MODULE
{
    name = ModuleDockingNode
    referenceAttachNode = top
    nodeType = size1
[B]   rollAlignAngle = 12.5[/B][B]
    rollAlignIncrementAngle = 0[/B]
}

In this case, the only valid roll orientation for docking is at 12.5°. Docking vessels will attempt to maintain this alignment by countering any user input in the rotation axis.

3) Non-stock docking port where a cardinal number of orientations are permitted

MODULE
{
    name = ModuleDockingNode
    referenceAttachNode = top
    nodeType = size1
[B]   rollAlignAngle = 0[/B][B]
    rollAlignIncrementAngle = 90[/B]
}

In this case, the only valid roll orientations for docking are at 0°, 90°, 180° and 270°. Docking vessels will attempt to snap to the alignment closest to the current roll orientation of the craft, and with sufficient roll input from the user, the port can be snapped to any of these four values.

4) Non-stock docking port where a cardinal number of orientations are permitted, plus an offset

MODULE
{
    name = ModuleDockingNode
    referenceAttachNode = top
    nodeType = size1
[B]   rollAlignAngle = 45[/B][B]
    rollAlignIncrementAngle = 90[/B]
}

In this case, the only valid roll orientations for docking are at 45°, 135°, 225° and 315°. Docking vessels will attempt to snap to the alignment closest to the current roll orientation of the craft, and with sufficient roll input from the user, the port can be snapped to any of these four values.

Thoughts?

Edited August 17, 2013 by sumghai
Spelling errors

[Greys]

I support this. Currently ModuleDockingNode is the bare minimum of working and as creative as we have been, docking ports only work well for flat circular matings. I don't think we need to involve SAS/ASAS in this, so long as the port is prohibited from resolving when it's outside of alignment.

[sumghai]

I don't think we need to involve SAS/ASAS in this, so long as the port is prohibited from resolving when it's outside of alignment.

Yeah, I guess that was rather a poor choice of words on my part. But yes, the inclusion of the optional parameters should prevent resolving of the docking sequence when outside of the specified values, or at least actively nudge vessel rotation to ensure the correct final orientation of the docking port.

[Fox62]

This would be more than useful for orbital docking construction.

[King Arthur]

Well, that's interesting - surely there are other folks who would like to see self-aligning docking ports?

Perhaps it's something that's so much in demand there's no pressing need for more debate?

Either way, I would love to see this realized so my docking-OCD will be slain once and for all.

[boomerdog2000]

Supported. I couldn't build my interplanetary ship because the drive pods docked slightly sideways, even with 2 docking ports for alignment.

[Prime flux]

+1 indeed. perhaps the dockingport should be more like the APAS and the new international docking standard, with a soft catching and a hard catch. Meaning that it first gets a soft catch with an extended docking part. When the soft docking is done the part retract to a "hard catch"

My understanding is that when the docking port is "active" the part is extended and can be steered in both position and rotation to compensate for small miss alignment during the docking. When the system retracts to a "hard catch" the 2 docked craft is perfectly aligned and positioned.

[Rascal Nag]

I'm all for a realistic limit to alignment errors, but I don't think the alignment should be automated (outside of trained crewmen docking as a part of the eventual crew tasks feature). Instead, a true docking camera and docking MFD would be my wish. The camera would help for obvious reasons, and the MFD could provide simple visuals of certain properties such as alignment, distance, closing speed, etc.

Here's the Orbiter 2010 docking MFD, for example:

Looks complicated, right? Nope! DST obviously means distance. It gives a numerical value in 10^x meters at the top and a bar representation of the same value below it, starting at 10^3 meters (1km) and going down to 10^-1 meters (1 tenth of a meter, or 10 centimeters). CVEL means Closing velocity in 10^x meters per second. It also has the numerical value and associated bar, which also runs from 10^3 down to 10^-1 m/s.

Now, about that circle. First, the center of the circle is where you're headed. The green cross is where the target is relative to this. It goes hand in hand with the yellow arrow and TVEL (top left). The yellow arrow gives you your vector in the plane perpendicular to approach plane. But from a purely visual point of view, the direction in which the yellow arrow points is the direction in which the center of the circle will move relative to the green cross (so in this case, we would continue moving the center of the circle up and to the left, or away from the target. This means we would shoot past the target to the top right if we did not make any corrections). The TVEL reading, or tangential velocity, simply gives you the magnitude of that vector (the velocity which the arrow represents). You should modify your TVEL so that the arrow points towards the green cross until it is centered, and then bring your TVEL down to zero so it stays there. Also provided is another scale along the concentric circles to give you a general idea of the speed a certain length of the arrow represents (Yellow numbers in bottom half of the circle. innermost circle is 10^-1 m/s, goes out to the outermost being 10^2 m/s). A similar scale is present in green; this represents your distance. It goes with the green circle, which gets smaller as you close in on the target. Each concentric circle has an associated distance which it represents on a logarithmic scale (10^x m). If your green cross is outside of this circle, you are outside of your "approach cone" and the TOFS (tangential offset - in the top left) will show a reading higher than 1. The circle will also become red. To visualize this better, think of the circle as not only a circle but as a hollow cone looked at from the bottom, with the green circle representing your current level in the cone. As you descend into the cone (get closer to the target), the circle will shrink since the cone shrinks as you approach the point. If the green cross is not centered, then as you get closer, it will eventually fall out of cone, meaning your target fell out of the cone. TOFS value is a numerical value that represents whether your target is in the cone or not. Values less than 1 tell you it is inside the cone.

Next, the red cross is where you're docking port is pointing relative to where you're headed. After you align the green cross to the center, you should start aligning the red cross to the center by rotating your ship accordingly. There are degree readings (10 degrees and 20 degrees here) to describe at what angle your docking port is out of alignment with your approach path. If you are well aligned, the cross turns white (beware - as you get closer, any small misalignment becomes magnified, so adjust the whole way in).

Finally, the red arrow indicates rotational alignment with the two docking ports. We would use Q and E to try and rotate this to the top of the circle.

After you've successfully lined up these crosses and brought the red arrow to the top of the circle, you can go back to the easy-peasy DST and CVEL readings to make sure you approach at safe speeds.

See? Not so bad. And anything in KSP would probably be simpler. I think a version without the logarithmic scales and a purely numerical DST and CVEL reading would be perfect.

[sumghai]

+1 indeed. perhaps the dockingport should be more like the APAS and the new international docking standard, with a soft catching and a hard catch. Meaning that it first gets a soft catch with an extended docking part. When the soft docking is done the part retract to a "hard catch"

-snip-

My understanding is that when the docking port is "active" the part is extended and can be steered in both position and rotation to compensate for small miss alignment during the docking. When the system retracts to a "hard catch" the 2 docked craft is perfectly aligned and positioned.

Interesting. That would probably require an additional parameter for specifying the animation between the extended active and retracted passive position, though.

I'm all for a realistic limit to alignment errors, but I don't think the alignment should be automated (outside of trained crewmen docking as a part of the eventual crew tasks feature). Instead, a true docking camera and docking MFD would be my wish. The camera would help for obvious reasons, and the MFD could provide simple visuals of certain properties such as alignment, distance, closing speed, etc.

-snip-

Bear in mind that my original request was for a docking port that mechanically limits allowable docking orientations, rather than visual-only alignment indicators like those already available in various mods.

[Rascal Nag]

Bear in mind that my original request was for a docking port that mechanically limits allowable docking orientations, rather than visual-only alignment indicators like those already available in various mods.

I know. I was just saying that I was against the solutions in the chart that employed automation (I'm personally against mechjeb), so suggested we get a robust MFD instead, and alignment would be manual. If it isn't aligned right it simply will not dock; if it is within a margin of error, it snaps into zero-misalignment position.

[Prime flux]

If you want to read more about the new international dockingstandard check out this document http://www.internationaldockingstandard.com/download/IDSS_IDD_RevA_Final_051311.pdf

Initial Contact Conditions

Lateral (radial) misalignment 0.11m

Pitch/Yaw misalignment 5.0 deg (vector sum of pitch/yaw)

Which is not much movement tbh, I would say it is similar to the current "magnetic" docking thingy.

Also this clip of the shuttle docking with ISS using APAS-95 can be of interested

Edited August 22, 2013 by Prime flux

[Prime flux]

The Docking Port alignment indicator have most of this functionality

I'm all for a realistic limit to alignment errors, but I don't think the alignment should be automated (outside of trained crewmen docking as a part of the eventual crew tasks feature). Instead, a true docking camera and docking MFD would be my wish. The camera would help for obvious reasons, and the MFD could provide simple visuals of certain properties such as alignment, distance, closing speed, etc.

Here's the Orbiter 2010 docking MFD, for example:

Looks complicated, right? Nope! DST obviously means distance. It gives a numerical value in 10^x meters at the top and a bar representation of the same value below it, starting at 10^3 meters (1km) and going down to 10^-1 meters (1 tenth of a meter, or 10 centimeters). CVEL means Closing velocity in 10^x meters per second. It also has the numerical value and associated bar, which also runs from 10^3 down to 10^-1 m/s.

Now, about that circle. First, the center of the circle is where you're headed. The green cross is where the target is relative to this. It goes hand in hand with the yellow arrow and TVEL (top left). The yellow arrow gives you your vector in the plane perpendicular to approach plane. But from a purely visual point of view, the direction in which the yellow arrow points is the direction in which the center of the circle will move relative to the green cross (so in this case, we would continue moving the center of the circle up and to the left, or away from the target. This means we would shoot past the target to the top right if we did not make any corrections). The TVEL reading, or tangential velocity, simply gives you the magnitude of that vector (the velocity which the arrow represents). You should modify your TVEL so that the arrow points towards the green cross until it is centered, and then bring your TVEL down to zero so it stays there. Also provided is another scale along the concentric circles to give you a general idea of the speed a certain length of the arrow represents (Yellow numbers in bottom half of the circle. innermost circle is 10^-1 m/s, goes out to the outermost being 10^2 m/s). A similar scale is present in green; this represents your distance. It goes with the green circle, which gets smaller as you close in on the target. Each concentric circle has an associated distance which it represents on a logarithmic scale (10^x m). If your green cross is outside of this circle, you are outside of your "approach cone" and the TOFS (tangential offset - in the top left) will show a reading higher than 1. The circle will also become red. To visualize this better, think of the circle as not only a circle but as a hollow cone looked at from the bottom, with the green circle representing your current level in the cone. As you descend into the cone (get closer to the target), the circle will shrink since the cone shrinks as you approach the point. If the green cross is not centered, then as you get closer, it will eventually fall out of cone, meaning your target fell out of the cone. TOFS value is a numerical value that represents whether your target is in the cone or not. Values less than 1 tell you it is inside the cone.

Next, the red cross is where you're docking port is pointing relative to where you're headed. After you align the green cross to the center, you should start aligning the red cross to the center by rotating your ship accordingly. There are degree readings (10 degrees and 20 degrees here) to describe at what angle your docking port is out of alignment with your approach path. If you are well aligned, the cross turns white (beware - as you get closer, any small misalignment becomes magnified, so adjust the whole way in).

Finally, the red arrow indicates rotational alignment with the two docking ports. We would use Q and E to try and rotate this to the top of the circle.

After you've successfully lined up these crosses and brought the red arrow to the top of the circle, you can go back to the easy-peasy DST and CVEL readings to make sure you approach at safe speeds.

See? Not so bad. And anything in KSP would probably be simpler. I think a version without the logarithmic scales and a purely numerical DST and CVEL reading would be perfect.

Edited August 22, 2013 by Prime flux

[Greys]

The multi-stage docking solution looks really nice, and would solve the issue of precision requirements that are impossible to resolve via the physics engine (if you make the limitations on a docking port too tight it can never reach a point where it's able to engage). But I foresee the model on such a system being potentially more complex than wheels, and we can all see how many addons have wheels that don't use custom wheel plugins.

[Captain Sierra]

I personally think you should be able to override the snap without having to use RCS. I think you should still be able to roll but the SAS will try to match rotations to the nearest permissable angle and only a significant manual input (more than just a tap) can override it.

I would also assume that the docking port magnetics (or collider fins or whatever) would try and snap you to a permissible angle as well. If not (or even if), it might be a good idea to add a tolerance factor so that the ports would tolerate misalignments by so many degrees. (something like 0-10)

That aside, I'd love to see this as soon as .22. It would be good for making a radial coupler part I have considered work on but until now, have no idea how to make snap at 0 ant 180* increments.

EDIT:

Just noticed the tolerance thing was already mentioned. Good. Consider me another supporter.

[Blue]

If such snap would be implemented, might'nt it savegame-break any spacecraft that had docking ports locked that already weren't locked from launch?

[Captain Sierra]

no. It simply adds a new feature to docking ports. Now, if they are using ports that are then told to lock at a specific angle (which would not be stock ports), then possibly. But since it is mostly limited to mod parts (very few of these are actually published yet), then I don't think it would be that bad. now, the THSS docking ports may actually be craft breaking since they would probably take advantage of this and that may do harm.

[sumghai]

If such snap would be implemented, might'nt it savegame-break any spacecraft that had docking ports locked that already weren't locked from launch?

For most people, it shouldn't break any saves, since the stock docking ports will probably omit these optional parameters.

My request was for SQUAD to extend the ModuleDockingNode capabilities to provide options for modders.

I'll also add that with these options, a player does not toggle orientation lock in-game - the orientation limits are configured internally in the CFGs.

Edited August 23, 2013 by sumghai