MITAB Library overview
======================
Note: until there is good complete documentation for the MITAB library,
this README file is the only source of information for integrating the
MITAB library in your application.
Please also visit the following URLs:
- The library's web page:
http://pages.infinit.net/danmo/e00/index-mitab.html
- The OGR architecture documentation:
http://gdal.velocet.ca/projects/opengis/ogrhtml/ogr_arch.html
COPYRIGHT AND LICENSE TERMS:
----------------------------
The most part of the MITAB library is
Copyright (c) 1998-2000, Daniel Morissette (danmo@videotron.ca)
it also contains parts and uses support libraries that are
Copyright (c) 1998-2000, Frank Warmerdam (warmerda@home.com)
and
Copyright (c) 1999, 2000, Stephane Villeneuve (stephane.v@videotron.ca)
The MITAB library, and its supporting libraries (OGR and CPL) are freely
available under the following OpenSource license terms:
**********************************************************************
* Copyright (c) 1998-2000, Daniel Morissette
* Copyright (c) 1998-2000, Frank Warmerdam
* Copyright (c) 1999,2000, Stephane Villeneuve
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included
* in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
* DEALINGS IN THE SOFTWARE.
**********************************************************************
USING THE TAB2TAB CONVERSION PROGRAM:
-------------------------------------
MITAB comes with a conversion program called TAB2TAB that can do tab-to-mif
and mif-to-tab translations:
Usage: tab2tab
Converts TAB or MIF file to TAB or MIF format.
The extension of (.tab or .mif) defines the output format.
COMPILING THE LIBRARY:
----------------------
When you extract the ZIP (or .tar.gz) file, you will get 3 directories
and the makefiles to compile the library using VC++ 6 under Windows or
using GNU make and GCC on Unix.
The MITAB directory contains the core of the library and the TAB2TAB
conversion program.
The OGR and CPL directories are support libraries used by MITAB and probably
won't be of much interest to you at the beginning.
To compile the lib on Windows:
In a DOS prompt, setup the VC++ environment variables by executing
VCVARS32.BAT (somewhere in your VC++ install) and start the build
using:
nmake -f makefile.vc
This should automagically compile the 3 sub-directories and the test
program (tab2tab.exe, tabdump.exe, mitabc_test.exe) in the MITAB directory.
If you plan to use MITAB from Visual Basic or non-C environments, then
have a look at contrib/README_VB.TXT
To compile the library on Unix:
The main directory contains a GNUmakefile whose default target will
compile the contents of the 3 sub-directories and the test programs
in the mitab directory.
Note about byte ordering: by default, the library is built for systems
with LSB first (Intel) byte ordering. To build the library on systems
that use MSB first byte ordering (such as SUN systems), you should add
the "-DCPL_MSB" flag to the compile flags in the "GNUmake.opt" file.
USING THE LIBRARY IN YOUR PROGRAMS:
-----------------------------------
There are 2 interfaces to access the library:
1- The C API. The C API is a simplified interface which allows you to
build simple applications quickly but may not give you access to every
property of every object type.
See the C API documentation at:
http://pages.infinit.net/danmo/e00/mitab-docs/mitab_capi.cpp.html
There are also interface definition files for various environments
in the contrib directory (mainly VB, Pascal and MapBasic... thanks to
Bo Thomsen)
2- The C++ API will give you full access to every feature of the MapInfo
data model. Unfortunately there is no complete documentation for the
library's C++ classes yet, but tab2tab.cpp is a good example that
shows how to open TAB files for read and write. Also, the main
classes you will need to deal with live in the header MITAB.H.
The rest of this file covers mostly the C++ API features but may also apply
to the C API indirectly.
TO READ FILES:
--------------
To open a .TAB or .MIF file for read, you can use the static method:
IMapInfoFile *IMapInfoFile::SmartOpen(const char *pszFname,
GBool bTestOpenNoError);
This function returns NULL if the file cannot be opened. If the open
was succesful, then it returns a new object of the type corresponding
to the type of file that was opened:
class TABFile: Class to handle .TAB datasets for read/write access.
Note that you cannot use it to modify exsiting datasets
(not yet!).
class TABView: Class to handle views on pairs of .TAB files linked
through an indexed field of type integer.
class MIFFile: Class to handle MIF files for read/write.
The method IMapInfoFile::GetFileClass() can be used to establish the
type of object that has been returned by SmartOpen().
TO CREATE NEW FILES:
--------------------
For write access, you create an instance of TABFile or MIFFile and use
it to open the new file and write to it. Note that only sequential write is
supported.
FEATURE CLASSES:
----------------
On read access, GetFeatureRef() returns object of classes derived from
class TABFeature. You can tell the type of an object using the method
TABFeature::GetFeatureClass().
The following table lists the various feature types and the geometry
types that can be returned and that are accepted (for writing) by each
of them:
Feature Type Returns (read mode) Accepts (write mode)
------------ ------------------- --------------------
TABPoint OGRPoint OGRPoint
TABFontPoint OGRPoint OGRPoint
TABCustomPoint OGRPoint OGRPoint
TABPolyline OGRLineString or OGRLineString or
OGRMultilineString OGRMultilineString
TABRegion OGRPolygon (with a OGRPolygon (with 1 or more
single ring) or rings) or OGRMultiPolygon
OGRMultiPolygon (for
multiple rings)
TABRectangle OGRPolygon OGRPolygon
TABEllipse OGRPolygon OGRPolygon or
OGRPoint corresponding to the
ellipse center
TABArc OGRLineString OGRLineString or
OGRPoint corresponding to the
arc's defining ellipse center
TABText OGRPoint (the lower- OGRPoint
left corner of the
text)
NOTE ABOUT "\n" IN STRINGS ON TABText OBJECTS:
----------------------------------------------
The text strings on text object may contain embedded "\n" characters in
MapInfo.
In those cases, the library returns strings in which the "\n" character
is escaped on two characters: "\" + "n"
The library will also automatically convert any "\"+"n" sequence in
strings into a binary "\n" when it writes text objects to TAB files.
This also implies that a single "\" character also has to be converted
to "\"+"\".
Also note that this conversion does not apply to table fields of type
"Char" since there appears to be no special treatment in MapInfo for
the "\n" sequence in char attribute field values.
------------
$Id: mitab_readme.txt,v 1.1 2003/06/11 21:08:56 fwarnock Exp $
------------
|
