MapCal Utilities

Updated 02/06/2011

The mc2bsbh Utility:

mc2bsbh 0.0.9 Windows executable, source and GPL license (114k)

mc2bsbh - MapCal to BSBchart Header Utility

This is a utility to take an image of a chart that has been calibrated with MapCal, and convert it into a BSB chart that can be displayed in many marine navigation programs.

For a GUI interface (for Windows only), see the KAP file Utility

Usage:
mc2bsbh infile [-l] [-d] [-s singlechart] [-o outfile | -e extension]

infile	the output from MapCal - normally CHARTCAL.DIR
outfile	This will default to the name in the DIR file but substitute the new extension of ".hdr".
-s	If you have a CHARTCAL with multiple chart calibrations, this is how you convert only one particular one.
-l	List the maps found in the input file.
-d	This is debug mode. It prints out a bunch of garbage.
-o	If you want to specify the new output header file name.
-e	If you want to use the generated name, but specify your own extension. If you use -d, note that as part of the debug, it will print the switches. But since it does this on the fly, it will ONLY print the switches that occur after the -d.

Another Feature

In MapCal, on the Chart Information screen, there is a comment field. In this field, if you follow the format below, you can add BSB information to the BSB header that you'd otherwise have to enter by hand. This is the functionality that replaced the -ced switch that was present in earlier releases.

BSBHDR CED/SE=2005,RE=43,ED=2009
BSBHDR KNP/SD=MEAN LOW WATER SPRINGS,PP=-23

The first BSBHDR line will add a line to the BSB header equal to CED/SE=2005,RE=43,ED=2009
The second BSBHDR line will superseed the default values for KNP/SD and KNP/PP with the specified values.

Important - don't skip this part! Another utility - kapgen

There are more directives you can put in the comment field for another utility.
The kapgen utility has calibrations built in for a group of charts. Expect that set of charts to increase! It totally automates the entire process, including going out and downloading the map image for you! Typing "kapgen -h" will give you a list of the available charts. Then, kapgen uses mc2bsbh, convert and tif2bsb for you to create the chart.
Get the details at the kapgen website. Scroll down for the English description. Give it a try. Something else brought to you by Marco.

Requirements:

Windows	sorry, as far as I know MapCal is not available on any other platform. The other 3 items are, though.
ImageMagick	Free
MapCal II	This comes as part of the free navigation package - Seaclear II
mc2bsbh	Uh, that's the utility this page is about - download it at the top of this page
tif2bsb	Free (make sure you get the Windows download - it also includes libtiff)

Description:

This is a utility to convert the MapCal calibration text file to a BSB header file. It is definately a beta. It will create a chart that can be displayed in OpenCPN. So, what it produces may or may not display in another navigation package.

Steps for use:

Notes:
convert below means the command that is part of ImageMagick.
chart should be substituted with the name of the chart you are working on. All files involved with the exception of CHARTCAL.DIR is the name of your chart, but with different extensions.

Find an image of a chart online or scan one in yourself.
If it is anything other than .png or .bmp, convert it to that (but save the original - there are more conversions to come) - Example: convert chart.jpg chart.bmp - Yep, it's just that simple.
Open MapCal and calibrate the chart. Note: You MUST save the calibration. It will save it in a file called CHARTCAL.DIR in the same directory the image was in when you opened it. For instructions on how to calibrate your file, see the MapCal help or the SeaClear site.
Run mc2bsbh to create the BSB header. It will create a header for each chart in the CHARTCAL.DIR file. The file will be named chart.hdr. Example: mc2bsbh CHARTCAL.DIR
Run convert to get the chart into the correct format of .tif for tif2bsb to use. This is two stage. Easiest way to show is by example: Step 1: convert chart.jpg -colors 127 chart.gif Step 2: convert chart.gif -colors 127 chart.tif - (For an explanation, see TIF Conversion below.
Run tif2bsb to create your chart. Example: tif2bsb -c 127 chart.hdr chart.tif chart.kap

So, if you downloaded a chart called NA47-8.jpg, here's the steps in shorthand, in a little different order for convenience:
convert NA47-8.jpg NA47-8.bmp
convert NA47-8.jpg -colors 127 NA47-8.gif
convert NA47-8.gif -colors 127 NA47-8.tif
Open NA47-8.bmp in MapCal, calibrate it, and save it
mc2bsbh CHARTCAL.DIR
tif2bsbh -c 127 NA47-8.hdr NA47-8.tif NA47-8.kap

TIFF Conversion:

It was discovered that tif2bsb didn't seem to want to work on a tif that was converted from a jpg or bmp. Now, this was annoying. Someone told me from the error, that it was because the tif had been created in RGB format instead of palette format. They explained that a tiff can be either format. If a RGB format (bmp/jpg/etc) was converted to a tiff, evidentally ImageMagick made the tiff RGB as well. So, the suggestion was made to first convert it to a gif, which is ONLY palette format. Since no one yet to come up with a single step way to do it, that's what we do. Convert jpg-gif-tif.

For people that have requested it, here is a longer explanation.

Raster vs. Vector.

There are two basic types of graphics. Raster and vector. Raster images have information for each and every pixel in the image. Vector graphics has information on the objects to be displayed. Like, it may have a definition of a line type of so may pixels wide, and dashed with the solid parts twice as long as the blank parts. Then, it will say to draw that type of line from this x/y position to that x/y position. In other words, a raster graphics has the picture while vector graphics has instructions on how to draw the picture.

RGB vs. Palette images.

For raster graphics, there are two basic ways to store the color of the pixels. RGB (Red/Green/Blue) stores a separate number for each of the colors for the intensity of each. So, a pixel might have 255, 255, 255 which is black. Or 0,0,0 which is white. Or 255,0,0 which is red. So, it has this set of three numbers for each and every pixel for the image. Palette does it different. It has a table of all the colors used. So it may say color 1 is 255,255,255 and color 2 is 0,0,0 and color 3 is 255,0,0. Then, after that table, it just has the color number for each pixel. So, it only stores just one number for each pixel.

Now, I'm not going to go into the advantages and disadvantages of each type, but basically, if you only have a few colors, a palette style graphic will take much less memory. If you have very many colors, a RB image may be smaller.

jpg,bmp,gif,tif, png

All of these are raster image types. The jpg and bmp files are RGB type rasters. The gif is a palette style raster. Now, here's the interesting. A tif or png can be either RGB or palette!

So, now I'll just recap what I said at the very beginning. tif2bsb requires a palette type tif. But Imagemagick convert, when converting from a RGB type image to a tif, will create a RGB type tif. When converting from a palette type image, it will create a palette type tif. So, for it to work for us, we will have to create the tif from a palette type image. Well, when converting from any image to a gif, since gif is only a palette type image, convert will create a palette type gif.

So, now you know. From a jpg, we have to convert to gif first, and then convert that to a tif so we get a palette type tif.

Resources:

Cruisers Forum - mc2bsbh thread - this is where the debugging and feature discussion is going on.
Cruisers Forum - OpenCPN Forum - This has debugging on OpenCPN, along with ancilliary projects on creating charts for marine navigation.

Change History:

First, the contributers:

Henrik Jessen
GPS-Marco

Update 11/18/2009:
1) corrected DTM calculation from DS*60 to DS*3600

Update 11/13/2009:
1) corrected an old bug (try mc2bsbh -e) and a bug introduced in 05
2) added a memory check
3) added a new switch "-l" to list all the maps present in CHARTCAL.DIR
4) added the BSB parameter CPH/180.0 if the map crosses 180° longitude
5) ignore CHARTCAL.DIR lines beginning with ;
6) improved printout of Usage:
7) changed switch -h in -o (since -h is normally for help)

Update 11/13/2009:
1) header length now unlimited
2) changes to compile with gcc 4.3.2
3) some internal code changes for consistancy and maintainability

Update 11/10/2009:
1) corrected a bug with header longer than 40 lines - now 250
2) corrected a bug with empty parameters in CHARTCAL.DIR
3) added a preprocessor of the MapCal comment field
4) a new switch -s MAPNAME to generate a single header from multiple CHARTCAL.DIR
5) removed obsolete switch -ced (see point 3)

Update 11/09/2009:
1) now it compiles on BCC32 (check for g++)
2) scales > 1000000 is not translated in SC=1e6
3) if longitude > 180, it writes long-360
4) rouded DU value (dot per inch is an integer)
5) corrected bug: DTM is DS * 60 (not just DS)
6) lat and long are written with a right number of decimals (>=6).

Update 11/08/2009:

New version 0.0.2 - Rewritten by a real c++ programmer - Henrik Jessen. Totally new code. Less source and smaller executable. I will have to look at it to figure out how it works. It also now supports multiple calibrations in a single CHARTCAL.DIR file. None of the switches have changed from my last version. Please test and let me know how it works. The old source is still available below.

Update 01/09/2010:
1) Show mc2bsb version in "Usage" printouts

Update 01/27/2010:
1) PP=central meridian for Transverse Mercator Projections
2) added key OST/1
3) added CPH/0.0 if not 180.0
4) keep shorter rows (chart name in single line)

Previous Versions:
mc2bsbh 0.0.6 c++ source file
mc2bsbh 0.0.5 c++ source file
mc2bsbh 0.0.4 c++ source file
mc2bsbh 0.0.2 c++ source file
mc2bsbh 0.0.1 c++ source file

Some example files and further discussion and a utility to batch process the BSB creation:

Some of the info is useful, and some I was just too lazy to rewrite.