kicad/Documentation/biu-plan.txt

Proposed Plan for adding Nano Meters into PCBNEW as the Board Internal Unit
===========================================================================

Author:  Dick Hollenbeck  November 25, 2011

Introduction:
============

This document sketches out a plan to move KiCad's PCBNEW program from deci-mil
internal units to nanometer internal units. The changes to the code are
significant enough to describe the basic process before the work is started.

Definitions:
===========

*) Board Internal Units (BIU). This is a pseudonym for the engineering units
used by a BOARD when it is in RAM, and only when it is in RAM. BIU is
essentially equal to nanometers in the future, and equal to deci-mils currently.
A BIU refers typically to a measurement or a position on an XY grid, and this is
because this grid is dimensioned in BIUs along both its X and Y axes. Both X and
Y can be either positive or negative on this grid. In the case of measurements
or scalars, there can be a radius, a diameter, a distance (length), and all of
these can and should be expressed in BIUs, so long we are in RAM and so long as
we are talking about the objects within the class BOARD instance. One special
feature of XY points within the BIU coordinate system is that they will always
be integers. In contrast, distances and other forms of measurements are not
subject to the same limitation by the very nature of physics. Coordinates are
always integers because we used signed whole numbers to represent these BIU
coordinates.

*) Snap grid. A snap grid is a subset of the full set of possible XY coordinates
in the BIU coordinate system. Points falling on the snap grid are evenly spaced
in X and Y directions and are some integer multiple apart in this 2D space,
greater than one BIU.

Assumptions:
===========

a) It is ok to modify the board file format in order to handle the BIU change.

b) Boards saved on disk in the new format will not be readable using old software.

c) Since we have no backwards compatibility obligation (see b) above), we can
make significant changes to the file format while we have this disruption
opportunity.

General:
=======

With nano meters as the Board Internal Unit (BIU), a 32 bit signed integer can
only hold about 2 meters of positive length and 2 meters of negative length.
Moreover, because most of the bits within a 32 bit integer can be "used up" to
hold a typical length within a board, it is very likely that if pure 32 bit
integer math is done, such as the multiplication of two integers in order to
calculate a hypotenuse, then there will be an overflow within the 32 bit
integer. (Another way to think of the BIU acronym is "Board Integer Unit" instead
of as Board Internal Unit, to pave the way for the BFU, discussed below.)

Therefore all intermediate products, quotients, trig, and exponential
calculations should be done using some larger floating point type. By larger,
bitness or number of bits is meant. Distances that do not have to be rounded
back to integer immediately can and should stay in the larger floating point
"value container" for as long as possible. The typedef name of this floating
point type is BFU (Board Float Unit). The engineering units on a BFU are the
same as on a BIU. A typedef is nice so that we can toggle between double and
"long double" for various compilations, and so that when performing casts, these
are brief textual expressions.

Format Strings:
==============

Because all our save to disk functions use printf() style format strings, we
discuss how to construct a format string in the most usable way. There should be
a printf() style format string like "%.6g" for the BFU (cast to a hard coded
double) enclosed within a #define and its name should be FMT_ENG. This format
string will be used at least for saving BOARD and MODULE files, and perhaps
more.

FMT_ENG stands for "format string for ENGineering units used out in the file". A
define is needed simply to provide consistency across many sites of usage. BIUs
will be scaled before being written to disk in most every case, and since
scaling is a multiplication, it means casting one of the factors to BFU, and
then this product is output with a printf() style function using the FMT_ENG
string segment.

That is, the FMT_ENG will be suitable for use with a BFU type. When BFU is set
to double, then FMT_ENG will be set to "%.6g". When BFU is set to long double
then FMT_ENG will be set to "%.6Lg". For example:

#if USE_DOUBLE_BFU
typedef double          BFU;
#define FMT_ENG         ".%10g"
#else
typedef long double     BFU;
#define FMT_ENG         ".%10Lg"
#endif

A format string can then be built up using compile time concatenation of
strings, like this:

fprintf( fp, "Value: " FMT_ENG " " FMT_ENG "\n", BFU( biu1 * scale), BFU( biu2 * scale ) );

The 3rd and 4th arguments are BFUs, and the casting is done after the multiply
since the scaling factor is already a double or perhaps even a long double. The
final argument needs to match the format string, so the final product is wrapped
in a BFU, which could actually be a truncation down to 64 bit float from 80 bit
float. The key points are: the calculation must be done in a float type at least
as bit-wide as BFU, and that the value actually passed to fprintf() must match
the format string.

Choosing BIU Units:
==================

BIUs are only used when a BOARD or MODULE is in RAM. A BIU is equivalent to
either a 1) deci-mil or 2) nanometer, depending on how the source code is
compiled. It is not a runtime decision. Form 1) is needed only during the
preparation phase of the source code transition to nanometers. After the
transition, only nanometers will be used in the compilation. No runtime
switching is needed or wanted. Again, BIUs can only be one or the other for a
given compilation, and this will swing based on a single #define.

Eventually we may want to actually use "BIU" as our integer type in source code
for those lengths which pertain to the board coordinate space. This would give
us the ability to easily modify it, go to a larger bitness, make the source code
more readable, and keep the type information out of the variable name. This
would mean having a point and/or size class based on BIU as the contained
integer types. This is a nice to have, but not immediately mandatory.

There will be a number of places within the source code which will have to be
doctored up to use the BFU casting. It will take some time to find all these
sites. During this time it should be possible to continue using deci-mils as the
BIU for source compilation.

There are a quite a number of path ways in and out of BOARDs and MODULEs. Most
everyone of these pathways involve conversion or scaling of BIUs. An example of
a pathway in is a BOARD disk file loading function. An example of a pathway out
of a BOARD is a disk file saving function. Likewise for MODULEs. We can
characterize the load and save functions by their source and destination
representations of lengths.

BOARDs and MODULEs will soon have a new format, which is basically the existing
format expressed in um or nm (TBD) rather than in deci-mils. For discussion, we
will say this new format is in mm, even though it may end up being in um. In
another year or two we will switch to s-expressions, or sooner if there is a
volunteer.

Here are the required immediate need BOARD load functions:

1) Legacy to deci-mil loader. This loader uses a floating point scaling factor
of unity, since destination is a RAM BOARD using deci-mils as its BIU.

2) Legacy to nanometer loader. This loader uses a floating point scaling factor
of 2540, since destination is a RAM BOARD using nanometers as its BIU, and
the source format is using deci-mils.

3) mm to nanometer loader.  This loader uses a floating point scaling factor
of 1000000, since the destination is a RAM BOARD using nanometers as its BIU.

There is no need for a nm to deci-mil loader. (Once somebody saves a file in the
new format, that format is used going forward, or its backup in the old format.)

Now duplicate the above 3 loader types for MODULEs.

Here are the required immediate need BOARD save functions:

1) deci-mil to deci-mil, using a floating point scaling factor of unity. It
should be possible to use trailing zero suppression on the deci-mils to get a
BOARD that is identical to an old BOARD, and this can be used to test the new
save function, using "diff" with whitespace ignore.  This saver is only in play
when the BIU is compiled to be deci-mils.

2) nanometer to mm, using a floating point scaling factor of 1/1000000. This
saver is only in play when the BIU is compiled to be nanometers.

Now duplicate the above 3 saver types for MODULEs.

New BOARD and MODULE files will have a new field in them identifying the
engineering units used, say mm.

In actuality, the source code to all 3 loaders, and to all 3 savers can be the
same source code with a single variable in each case for scaling.

All 6 loaders and all 6 savers should be written in parallel with existing
loaders and savers, so that we can toggle usage back and forth between the two
for awhile. This means we do not gut existing savers and loaders until the new
ones are debugged and stable.

The new savers and loaders are to be done in the context of a plug-in
architecture, described elsewhere.

Angles and Rotations:
====================

Internally we are switching from using an int to hold 1/10 of degrees angle to a
typedef called DEGREES. The allowed values that DEGREES can hold will be
enforced by the user interface policy, decided elsewhere. The engineering units
in the DEGREES type is degrees, no longer tenths of degrees.

/// a value used to hold rotations or angles.
typedef double  DEGREES;


User Interface Changes:
======================

All these changes have to be done in a way where they hinge on one #ifdef.

*) The grid dimension choices will have to be changed.

*) The drawing routines will have to be changed to handle the case that BIU is
compiled to be nm. Work towards getting legacy drawing code capable of handling
a compile time #define to control a single scaling factor. Only the scaling
factor should need be changed in the final state. Up until then, the work
required is to inject the BFU casting where needed along with the scaling
factor(s).

*) Remove any funky imperial to metric conversion functions which tried to hide/mask
problems with lack of BIU precision.

*) There may be some fix ups pertaining to "near enough" type testing involving
the user's mouse position, other than bounding box hit testing which should take
care of itself (in BIUs). This has more to do with near-ness to a line type
tests, and these are thought to best be done in screen coordinates anyway, not
BIUs.

Work Tasks:
==========

*) Within PCBNEW, find math expressions involving BIUs and cast them to BFUs
early enough so that the compiler generates code in the BFU realm.

*) Find a way to consistently round values from BFUs back to BIUs, and put that
code in place.  This could be done using a set accessor on a BIU, or other way.

*) Fix the User Interface issues mentioned above, and more found later.

*) Write the 4 new load and save functions. Vladimir recently committed code
which can be a starting point for some of these functions, except that the new
ones should reside within a PLUGIN object where we can save the scaling factor
variable as a member field of the plugin.  In order to meet the requirements
of all 3 board loaders, we may have to dynamically change the scaling factor
depending on what we find in the *.brd file and how the plugin is compiled.