[WIP, Plugin, Parts] (2014-10-16) LaserDist 0.5 for KSP 0.9, Alpha

[Dunbaratu]

LaserDist

[WIP, Plugin, Parts] (2014-10-16) LaserDist 0.5 for KSP 0.9, Alpha

Releases:

* https://github.com/Dunbaratu/LaserDist/releases

ZIP Download (See release page above):

* https://github.com/Dunbaratu/LaserDist/releases/download/v0.4/LaserDist.zip

Source Code Hosting site:

* https://github.com/Dunbaratu/LaserDist

License:

* GPL v3

Copyright © 2014 Steven Mading (aka Dunbaratu on Github)

[email protected]

This is a very small plugin. It makes a KSP Part that

measures straight line distances by laser.

The "Beamer 100x Disto-o-meter" Part aims a laser in a line

and then measures the distance in meters to the first object

the laser hits. The result is displayed in the right-click

menu for the part.

The laser can work over long distances - here it's measuring the

distance from a Kerbin orbit vessel to the Mun:

And even at those very long distances, the lasers can measure

rather small differences in distace, within reason (it has

an accuracy of 2 meters at this extreme range, to keep the

game from bogging down too much). In the screenshot below,

notice how the two lasers are returning different numbers for

their distance to the terrain very far away:

The direction of the laser is whichever way the laser gun is

pointed when you mounted it on the craft, as demonstrated here:

The electric draw for the laser is substantial. Each laser consumes

1 electric charge every 3 seconds that it's on.

Why does this Mod exist?

The intended purpose of this part is to be used in conjunction with

scripted autopilots like [kOS](https://github.com/KSP-KOS/KOS/releases), to

provide a way to for you to write scripted pilot software that can

see the distance to the ground (or anything else like a ship) along

the laser line. The reason this can be useful is so you can detect

things like terrain slope and mountains in the way. The default

radar altimiter in KSP only shows you the distance directly under

the craft.

In a nutshell, the purpose is to solve this problem shown in this picture:

This mod can let you read the distance along the blue line in the diagram.

Why isn't it inside kOS then?

There is more than one KSP mod project for the purpose of letting

users write scripted autopilots. Another such project currently under

development is Jebnix

My goal is to make this part script-engine-agnostic so it works with

any such mod. I've been working in kOS mostly, but I didn't want this

part to be kOS-specific because there's no particular reason it has

to be.

Information for other modders trying to use the part:

As long as the scripting autopilot is designed to be able to query

and/or set KSPFields on parts, it should be able to read the value of

the distance, and turn the laser on and off, as follows:

• KSPField: 'Distance' is a float - the number of meters being shown in the display. It's -1 if there is currently no hit.
  
• KSPField: 'HitName' is a string - the name of the object being hit.
  
• KSPField: 'Activated' is a bool - true if the measuring device is on.
  
• KSPField: 'DrawLaser' is a bool (called "Visible" in the GUI) - true if the laser should be drawn when it's activated or false if it should be (realistically) invisible because, hey, it's coherent light and it's not supposed to be seen from the side.
  
• KSPField: 'CPUGreedyPercent' is a float (called "CPU hog" in the GUI) ranging from 0.0 to 20.0. It's how much of a single physics tick of time this mod will allow itself to consume during a single Update. If it hasn't gotten a good enough answer within that much time, it will wait until the next update to continue the calculation.
  
• KSPField: 'UpdateAge' is an integer - It's how many Unity Updates (animation frames, basically) it's been since the value you are seeing was calculated. Becuase of the logic of CPUGreedyPercent (see above) sometimes the value being displayed is stale by a few update ticks and shouldn't be trusted until the next time that UpdateAge becomes zero again. If you're in a situation where this mod needs to spend more than 1 update of time to get to a good answer for the distance, you'll see this value spinning a bit, quickly going 0,1,2,3,0,1,2,3,0,1,2,3...etc. When you see that, only when it hit the zeros was the distance value perfectly correct at THAT moment.
  Note: The higher that CPUGreedyPercent ("CPU hog") is, the less likely it is that UpdateAge will ever be nonzero, but the bigger hit your framerate might take.

How to Mount it.

. The Beamer 100x Dist-o-Meter is located in the "Electronics" tech node of the career tech tree. It's a 300-point node on the tree so you might not have it yet in a new fresh career game.

The Laser can be mounted anywhere as a surface-mount item. Take care to

note the orientation of the laser emiiter. (KSP lets you fine-tune

the rotation of a part by using the SHIFT key while you hit the WASDQE

keys.)

The Laser will bounce back and give you a distance measurement when

it encounters ANY object, including parts of your own craft. So

take care to mount it somewhere where the laser beam will have a clear

line of sight without obstruction.

To ensure a good mounting point, you can use "tweakables" to enable the

laser and make it show up in the VAB to look and see if you have it aimed

well.

Lightspeed

Note that if you use it to measure the distance to a far away body (i.e.

like aiming it at Duna from Kerbin), the mod does take into account

lightspeed. You have to hold the laser on an object steady and unchanged

for the entire duration of time it takes for lightspeed delay to

bounce the signal back or you won't get a measurement, so using it at that

great distance will be very hard.

FUTURE EXPANSION PLANS (i.e. the reason this is a WIP)

• Max distance isn't enforced yet: It's part of a future plan
  to have different variants of the part that work better the
  higher up the tech tree you go. For now, despite what it says,
  the range is actually infinite.
  
• Other sorts of sensors?: Now that the numerical approximation behind
  making a "fake raycast" that finds intersections with the planet terrain
  from far away and from any angle is implemented, this opens up the
  chance that other sorts of long range beam sensors could be made.
  For example a "biome detector" that returns the name of the biome
  where the hit occurred is a possibility, as is a "density at a distance"
  measurement which might tell you the atmospheric pressure or density
  at the ground level where the hit occurred. (Maybe because of something
  that the laser detects about interference with the air? It's a bit
  hard to justify realistically how that would work, but it's definitely
  possible with the software. Just not sure if it's possible in the
  real world, or whether real-world sanity is really the intent
  of this mod or not.
  

How do I use it from my script then?

Very Soon Now the dev team of kOS (of which I'm part) plans to

have a release that lets you read the fields of any part's KSPFields

(The stuff you see in the rightclick popup user interface panels), and

manipulate any part's widgets on the rightclick menus (the buttons,

the sliders, etc).

The plan from the beginning was to make LaserDist be a good test case

of this feature that may actually be useful in its own right.

But that's not released just yet. So at the moment this is only

usable as a manual piloting aid where you leave the part menu open

and look at it by eye as you fly.

Part modeling help?

I am aware that the artwork on the model isn't pretty. I'm a

programmer, not a graphic artist, and I don't have experience

with things like Maya and Blender. In fact I just made the model

by slapping together some stretched Cube and Cylnder objects in

Unity itself, without the aid of a modeling program. The model

is good enough to work with, but I'd be happy to have someone

better at art redesign the model. I included the model in

the github directory if you want to have a look.

Edited April 20, 2015 by Steven Mading
forgot to mention it works in 0.9 ages ago.

[Teoman2]

Wow um, That looks AMAZING. I cant help though, I'm not a programmer. Here, have a scary pic though...

Makes you think twice about jeb

[Pondafarr]

The part looks TOO good, it should be swapped out to look like a 1950's style steel flashlight...and duct tape

[Dunbaratu]

Updated for KSP 0.24.

https://github.com/Dunbaratu/LaserDist/releases/tag/v0.1p5

There is literally no difference in how it behaves and the source code wasn't changed. It was just recompiled.

It seems to "work" as well as it did before.

[Pondafarr]

Have you had any preliminary success with integrating it into KoS? the obvious thing is to include it in a spaceplane terrain following code, and to avoid that damn mountain on reentry landing...

[Dunbaratu]

The roadmap for how to integrate this into kOS is this:

- It's wrong for kOS to explicitly support this LaserDist with customized code just for LaserDist.

- It's wrong for LaserDist to explicitly support kOS with customized code just for kOS.

- Instead, kOS should implement a generic way to query/adjust the KSPfields of any part. If it can do this, then it can support LaserDist and a bunch of other things.

(A KSPField is a single row of the popup box that appears when you rightclick a part).

I was talking with erendrake and he agrees that this is the best approach. But as to when? I don't know.

[Drew Kerman]

well now, I can see this being useful for advanced terrain auto-guidance with my rover driver software. Egggcellent look forward to when it gets proper kOS integration

[Boamere]

Snip

What on Eart-kerbin?

[AndreyATGB]

This looks pretty nice, reading the OP I figure this isn't within the scope of this mod but I'd really like a mod that can measure lengths in the VAB. The best way to do this right now is to use procedural parts and hover them over stuff.

[Tyrador]

Maybe it would be possible to use this laser for docking alignment? Or even combine/wield stock docking port with these lasers?

[Dunbaratu]

This is the algorithm I'm planning on using to solve the PQS terrain hit problem (the fact that Squad appears to have never implemented an API function to find a ray intersect with the PQS terrain - They did create several API methods that seem by their name to do this, but upon using them I've discovered that despite their name they actually just find the intersect with the sea-level sphere of the planet, ignoring the PQS terrain entirely.)

Given a point in space, I can query KSP and ask it to tell me the PQS terrain below that spot in space. But the math being used to generate that answer is proprietary and hidden, so I can't solve for the intersect of a ray with the terrain surface function analytically (the math would probably be too ugly to do that anyway even if I could see it). I have to solve for it using a numerical algorithm that approximates the answer.

This is how I'm going to try doing it:

If I really wanted to be clever about it and reduce computational expense, I could try to take advantage of the fact that I know that from one animation frame to the next, the correct answer must necessarily be very close to the previous animation frame's correct answer, and therefore start the outermost recursion level with an 'i' just one step away from the previous 'i' that hit. (i.e. if on the previous animation frame, I found the hit in slice i=7, then on the next animation frame, don't start with slice i=0, start with slice i=6, on the assumption that in one animation frame its possible for the correct hit to move across the boundary from one slice to the next, but not possible to move as far as two whole slices in a mere tenth of a second or less.)

Edited July 28, 2014 by Steven Mading

[Ralathon]

Would it be possible to get a vector displaying the orientation of the laser in addition to the distance?

One way I'd want to use this is to put the laser on a infernal robotics hinge and sweep it over the landscape to give KOS a rough heightmap to select landing sites. But it'll be rather difficult to calculate the lay of the terrain if I don't have a quick way to fetch the orientation of the laser.

[Dunbaratu]

I'd thought of how it would be nice to combine this with Infernal Robotics to dynamically aim the laser. I'm glad someone wants to pursue that and I'd love to see the results.

As to how to read the vector, what I'd rather do is instead of making an exception for LaserDist, make it so that kOS can read the orientation of *any* part. It's already possible in kOS to apply a Rotation to a Vector, so if you could read the orientation rotation of any generic part, then in principle it would be possible to get the rotation transform of the LaserDist part, then apply that rotation to the unit vector V(0,-1, 0) (negative Y is the default "down" orientation of the laser before it is rotated by the part's current transform).

erendrake and I were discussing this and it is a thing we want to do - be able to read position and orientation information of any part on a vessel.

[erendrake]

be able to read position and orientation information of any part on a vessel.

This is something i am already working on right now, that is of course once i get off my ass and start working on kOS again.

https://github.com/KSP-KOS/KOS/issues/169

[Dunbaratu]

New release: https://github.com/Dunbaratu/LaserDist/releases/tag/v0.2

This has a crudimentary PQS terrain solver. It's still not perfect and occasionally does not register hits. That's because the computation expense of getting it perfect is not something I'm willing to burden the game engine with (it would take about a thousand iterations to be sure it always worked perfectly) As it is, I only use 100 iterations, which can cause it to occasionally miss a mountain because it falls in-between sample points of the algorithm.

[Dunbaratu]

v0.3 Now ready for kOS when kOS Fields released?

A lot has been fixed up and redone about the low-level numeric approximation algorithm (the "PQS raycast solver"). That's the bit that deals with the fact that none of KSP's built-in APIs actually find raycast intersections with the terrain when the terrain is far away and thus not "fully" loaded. (Even though some are named as if they would, they don't. They only find intersection with the sea level sphere under the terrain.)

Changes to the homebrewed PQS raycasting algorightm:

• **tighter +/- error level**: When the terrain is far enough way not to be fully loaded, so that my PQS aproximater raycaster has to be used, the new "epsilon" is 2 meters. (This is the accuracy level for the numeric approximizer. When it gets a value within 2 meters of the right answer it quits and gives you that. It used to be 5 meters).
  
• **less hogging of the limited CPU time**: When it has to fallback to the PQS approximate raycaster, it now limits its CPU usage based on how LONG it's taking rather than on other guesses. It actually watches a stopwatch and limits itself to a thin slice of the total time one physics update is meant to take - so other mods and the main game can have their time too.
  
• **algorithm can now spread across updates**: To allow less hogging of the CPU time, it now can store its state in the algorithm and then come back to it in the next update tick. So when the time is exceeded and it doesn't have a good answer yet, it now waits for the next update to pick up where it left off. This means that getting an answer can sometimes now take a few updates to obtain. A manual player won't see the difference, but an autopilot script needs to know about this.
  

New fields on the rightclick panel:

• **CPU hog** - a number from 2 to 20 - editable - This lets you set the balance between getting answers fast versus being nice to the rest of the game and trying not to take too much time during an animation frame. If you want faster updates to the Distance readout, set this higher. If the mod is stealing your framerate and becoming a problem, set this lower. If you want to permanently change this value and not constantly adjust it, change the setting ```CPUGreedyPercent``` in the part.cfg file for the laser.
  
• **Update Age** - integer - readonly - How many animation frame updates has it been since the value in the Distance field was up to date? If this value is bigger than zero, then that means you are looking at slightly stale data. In normal operation it should be zero when near the terrain, and then when higher up it will spin from 0 to 1 to 2 to 3 to 4 or so and then back to 0 again - very fast. This lets you know how slow your updates are from the solver. If you want quicker updating, you have to set **CPU hog** higher.
  

[GeoPhizzix]

Looks useful, will have to try this out as soon as I am given the chance.

[erendrake]

This is looking better and better, good work Steven!

[hieywiey]

Can this also be used to get a small amount of science from, for example finding the distance between Kerbin and [insert Planet/Moon/Asteroid Name Here], being worth more science for bodies that are farther away?

[Camacha]

I totally missed this. Very cool. I am still very tempted to do a comprehensive suite of different sensors, but I cannot justify the investment in time that would take, as I am already short on time for my daily duties and plans.

Maybe I should write what I envision down so that other people can run with it.

[RoverDude]

Beautiful

Let me know if you still need a model, I'll donate one.

[SkyHook]

If this works in the VAB, it's gold.

[Dunbaratu]

Can this also be used to get a small amount of science from, for example finding the distance between Kerbin and [insert Planet/Moon/Asteroid Name Here], being worth more science for bodies that are farther away?

Maybe someday. At the moment it would be a bit of a break of game balance because right now the laser is infinite distance. Also, for the really far objects it will start running into the problem that Unity is doing everything in single-precision floats and not doubles. I suspect that it will get to the point where you just don't have enough finite control to keep the laser aimed on the tiny fraction of a degree arc where there's a hit.

[Dunbaratu]

Beautiful

Let me know if you still need a model, I'll donate one.

If you're interested, here is where I've got the model I do have, and the readme describes where the "hotspots" in it are (where it attaches, and where the code expects to draw the laserbeam from):

https://github.com/Dunbaratu/LaserDist/tree/master/UnityModel

[Dunbaratu]

Release 0.4:

Added support for KSP-AVC mod (version checker) and KSP 0.25

https://github.com/Dunbaratu/LaserDist/releases