Application: gvSIG desktop

OVERVIEW

==========

This ANT script builds a gvSIG Debian package. 

PRECONDITIONS

==========

- operative system with a GLIBC compatible version for all platforms

Ex: If it's built on a Ubuntu 9.04 it won't run in a Debian etch 

- external commands cp, ln, dpck 

- external command make and cmake to build natives

- a workspace in built without errors and the directory _fwAndami/gvSIG contains

all the extensions

The directory binaries/deb-etch must have the symbolic links to the native libraries

The main dependencies are:

libgdal1.5.0 for raster support (conflicts with v1.6 in order to support grass format)

libstdc++5 for mrsid support

BUILD

==========

1.- Building JNI gdal

Edit libjni-gdal/CMakeModules/FindGDAL.cmake and put the path where 

gdal headers are placed.

The easy way is install from repository (sudo aptitude install libgdal1-1.5.0-grass) and

set the directory /usr/include/gdal

Define the enviroment JAVA_HOME

Finally, run the ant build script.

2.- Building JNI ECW (v3.3)

Edit libjni-ecw/CMakeModules/FindECW.cmake and put the path where 

ECW headers are placed (ie. /usr/local/include)

Define the enviroment JAVA_HOME 

Finally, run the ant build script.

3.- Building JNI MrSID  (v7.0.0)

Edit libjni-mrsid/CMakeModules/FindMRSID.cmake and put the path where 

MrSID headers are placed (ie /usr/local/Geo_DSDK-7.0.6.2167)

NOTE: each group of lines has a different include directory!!

Set gcc-3.4 as the default gcc compiler

Set g++-3.4 as the default g++ compiler

Change libstdc++ in the compiler ( /usr/lib/gcc/i486-linux-gnu/3.4.6). Its needed to point libstdc++.so.5

Define the enviroment JAVA_HOME

Finally, run the ant build script 

4.- Building JNI proj

Edit libjni-proj4/Makefile to set the directory where is placed the JNI headers

For example:

"default_PROJECT_INCS= -Iinclude -I/usr/lib/jvm/java-1.5.0-sun/include -I/usr/lib/jvm/java-1.5.0-sun/include/linux" 

In a shell execute make

5.- Building the package

Run the ant script and the binary will be placed in the directory "dist"

POSTCONDITIONS

==============

-gvSIG Files:

/opt/gvSIG/bin  --> script to run gvSIG and extensions

/opt/gvSIG/lib  --> java binaries (jars) 

/opt/gvSIG/libs --> native libraries (so)

-System files:

/usr/share/mime/packages/gvsig.xml --> gvSIG mime type definition 

/usr/share/applications/gvsig.desktop --> desktop shortcut definition

/usr/share/icons/ico-gvSIG.png --> shortcut icon

TODO

=====

check /usr/share/mime/packages/gvsig.xml

Version number automatic

KNOWN PROBLEMS

==============

In the build.xml copy task doesn't preserve permission. Use task exec (with command cp) instead.

HOWTO INSTALL

==============

aptitude install libgdal1-1.5.0-grass sun-java5-jre

aptitude remove libgdal1-1.6.0

dpkg -i *.deb

ANY DOUBT

==========

jvhigon@gvsig.org

<?xml version="1.0" encoding="UTF-8"?>

<project name="BuildDebian" basedir="." default="build-without-jre">

<property name="dist.dir" value="dist"/>

<property name="build.dir" value="build"/>

<property name="gvsig.version" value="1.10"/>

<property name="gvsig.dir" value="/opt/gvSIG-${gvsig.version}"/>

<property file="../../appgvSIG/build.number" prefix="gvsig"/>

<!--	

<property name="jni-gdal.dir" value="../../libjni-gdal/lib-dist"/>

<property name="jni-proj.dir" value="../../libjni-proj4/dist"/>

-->

<property name="libs.dir" value="../../binaries/linux"/>

<property name="jni-gdal.dir" value="../../binaries/deb-etch/gdal"/>

<property name="jni-proj.dir" value="../../binaries/deb-etch/proj"/>

<property name="jni-ecw.dir" value="../../binaries/deb-etch/ecw"/>

<property name="jni-mrsid.dir" value="../../binaries/deb-etch/mrsid"/>

<target name="prepare" description="Prepare directory build" depends="prepare-common,prepare-all-natives">

	<!--Copy debian structure and change permissions --> 

	<copy todir="${build.dir}"  overwrite="true" preservelastmodified="false">

	    <fileset dir="${resources.dir}">

	    	<exclude name="gvSIG.sh"/>

	    </fileset>

	</copy>

	<exec executable="chmod" dir="${build.dir}/DEBIAN">

			<arg value="775"/>

			<arg value="postinst"/>

			<arg value="postrm"/> 

			<arg value="preinst"/> 

	</exec>

	<!--Copy gvSIG.sh -->

	<copy file="${resources.dir}/gvSIG.sh" todir="${build.dir}${gvsig.dir}/bin"/>

</target>

<target name="prepare-common" description="Prepare common files in the build directory">

	<!--Copy gvSIG lib -->

		<copy todir="${build.dir}${gvsig.dir}/bin/lib">

		    <fileset dir="../../_fwAndami/lib/">

		      <exclude name=".svn"/>

		    </fileset>

		</copy>

		<!--Copy gvSIG bin directory -->

		<copy todir="${build.dir}${gvsig.dir}/bin/gvSIG">

			<fileset dir="../../_fwAndami/gvSIG/">

				<exclude name=".svn"/>

			</fileset>

		</copy>

		<!--Copy theme -->

		<copy todir="${build.dir}${gvsig.dir}/bin/theme">

			<fileset dir="../../_fwAndami/theme/">

				<exclude name=".svn"/>

			</fileset>

		</copy>

		<!--Copy andami.jar -->

		<copy file="../../_fwAndami/andami.jar" todir="${build.dir}${gvsig.dir}/bin"/>

		<!-- Copy /usr resources -->

		<copy todir="${build.dir}/usr">

			<fileset dir="resources/usr"></fileset>

		</copy>

</target>

<target name="prepare-all-natives" description="Prepare directory build with gvSIG native libraries">

		<mkdir dir="${build.dir}${gvsig.dir}/libs"/>

		<!--Copy ALL natives --> 

		<copy todir="${build.dir}${gvsig.dir}/libs">

					<fileset dir="${libs.dir}">

						<include name="*so*"/>

					</fileset>

		</copy>	

</target>

<target name="build-without-jre" description="Creates a Debian Package" depends="clean,prepare-all-natives,copyJAI">

	<mkdir dir="${dist.dir}"/>

	<antcall target="prepare">

		<param name="resources.dir" value="resources/without-jre"/>

	</antcall>

	<antcall target="prepare-version"/>

	<exec executable="dpkg">

	    <arg value="--build"/>

		<arg value="${build.dir}"/>

		<arg value="${dist.dir}"/>

	</exec>

</target>

<target name="build-with-jre" description="Creates a Debian Package with JRE" depends="clean,prepare-all-natives,copyJRE,copyJAI">

		<mkdir dir="${dist.dir}"/>

		<antcall target="prepare">

			<param name="resources.dir" value="resources/with-jre"/>

		</antcall>

	<antcall target="prepare-version"/>

		<exec executable="dpkg">

		    <arg value="--build"/>

			<arg value="${build.dir}"/>

			<arg value="${dist.dir}"/>

		</exec>

</target>

<target name="build-with-jre-etch" description="Creates a Debian Package with JRE  and usinf etch libraries" depends="clean,prepare-all-natives,copyJRE,copyJAI">

			<mkdir dir="${dist.dir}"/>

			<antcall target="prepare">

				<param name="resources.dir" value="resources/with-jre"/>

			</antcall>

		<copy todir="${build.dir}${gvsig.dir}/libs" overwrite="true" preservelastmodified="false">

			<fileset dir="${jni-ecw.dir}"/>

			<fileset dir="${jni-gdal.dir}"/>

			<fileset dir="${jni-mrsid.dir}"/>

			<fileset dir="${jni-proj.dir}"/>

		</copy>

	<replace file="${build.dir}/DEBIAN/control" token="gvsig-jre" value="gvsig-jre-etch" />

		<antcall target="prepare-version"/>

			<exec executable="dpkg">

			    <arg value="--build"/>

				<arg value="${build.dir}"/>

				<arg value="${dist.dir}"/>

			</exec>

</target>

<target name="prepare-version" description="Debian control file">

	<replace file="${build.dir}/DEBIAN/control" token="#version#" value="${gvsig.version}" />

	<replace file="${build.dir}/DEBIAN/control" token="#build#" value="${gvsig.build.number}" />

	<replace file="${build.dir}/${gvsig.dir}/bin/gvSIG.sh" token="@version" value="${gvsig.version}" />

	<replace file="${build.dir}/usr/share/applications/gvsig.desktop" token="@version" value="${gvsig.version}" />

	<!--<replace file="${build.dir}/DEBIAN/postinst" token="@version" value="${gvsig.version}"/>

	<replace file="${build.dir}/DEBIAN/postrm" token="@version" value="${gvsig.version}" />

	-->

</target>

<target name="copyJRE" description="Adds JRE.">

	<copy file="../instalador-gvSIG-lin/jre/j2re-1_6_0_20-linux.tar.gz" todir="${build.dir}${gvsig.dir}"/>

</target>

<target name="copyJAI" description="Copy JAI libraries.">

	<copy todir="${build.dir}${gvsig.dir}/libs">

				<fileset dir="resources/jai/libs">

				</fileset>

	</copy>

	<copy todir="${build.dir}${gvsig.dir}/bin/lib">

					<fileset dir="resources/jai/lib">

					</fileset>

	</copy>

	<copy file="resources/jai/LICENSE-jai.txt" todir="${build.dir}${gvsig.dir}"/>

</target>	

<target name="clean" description="Cleans the build directory">

	<delete dir="${build.dir}" />	

</target>

</project>

#!/bin/sh

# gvSIG.sh

export GVSIG_LIBS="/opt/gvSIG-@version/libs"

export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$GVSIG_LIBS"

export PROJ_LIB="/opt/gvSIG-@version/bin/gvSIG/extensiones/org.gvsig.crs/data"

export GDAL_DATA="$GVSIG_LIBS/gdal_data"

cd "/opt/gvSIG-@version/bin"

#java -Djava.library.path=/usr/lib:"/opt/gvSIG-@version/libs" -cp andami.jar:./lib/gvsig-i18n.jar:./lib/beans.jar:./lib/log4j-1.2.8.jar:./lib/iver-utiles.jar:./lib/castor-0.9.5.3-xml.jar:./lib/crimson.jar:./lib/xerces_2_5_0.jar:./lib/javaws.jar:./lib/xml-apis.jar:./lib/looks-2.0.2.jar:./lib/JWizardComponent.jar -Xmx500M com.iver.andami.Launcher gvSIG gvSIG/extensiones $1

for i in ./lib/*.jar ; do

  LIBRARIES=$LIBRARIES:"$i"

done

for i in ./lib/*.zip ; do

  LIBRARIES=$LIBRARIES:"$i"

done

/usr/lib/jvm/java-6-sun/bin/java -Djava.library.path=/usr/lib:"/opt/gvSIG-@version/libs" -cp andami.jar$LIBRARIES -Xmx500M com.iver.andami.Launcher gvSIG gvSIG/extensiones "$@"

Package: gvsig

Version: #version#-#build#

Priority: optional

Section: science

Architecture: i386

Depends: sun-java6-jre 

Maintainer: Jose Vicente Higon <jvhigon@gvsig.org>

Description: An open source GIS Desktop client 

 More information at http://www.gvsig.gva.es

#! /bin/sh

if [ "$1" = "configure" ]; then

	if [ -x /usr/bin/update-desktop-database ] ; then

        	/usr/bin/update-desktop-database

	fi

	if [ -x /usr/bin/update-mime-database ] ; then

        	/usr/bin/update-mime-database /usr/share/mime

	fi

fi

if [ -d /opt/gvSIG-1.10 ]

then

	cd /opt/gvSIG-1.10

else

	echo "Directory /opt/gvSIG-1.10 doesn't exist" 

	exit -1

fi 

#change permissions

chmod 775 bin/gvSIG.sh

chmod 777 bin

chmod -R 777 bin/gvSIG/extensiones

#check license agreement

more LICENSE-jai.txt

while (true)

do

	echo ""

    echo "Do you agree? [y/n]"

    read ok

    if [ $ok = "y" ]

    then

    	exit 0

    else

    	if [ $ok = "n" ]

   		then

                exit 1

    	fi

	fi

done

#! /bin/sh

# postun script for openproj

if [ "$1" = "configure" ]; then

	if [ -x /usr/bin/update-desktop-database ] ; then

        	/usr/bin/update-desktop-database

	fi

	if [ -x /usr/bin/update-mime-database ] ; then

        	/usr/bin/update-mime-database /usr/share/mime

	fi

fi

#remove directory

cd /opt

rm -rf gvSIG-1.10

#!/bin/sh

exit 0

2.0

                           Sun Microsystems, Inc.

                        Binary Code License Agreement

                  JAVA ADVANCED IMAGING API, VERSION 1.1.2

READ THE TERMS OF THIS AGREEMENT AND ANY PROVIDED SUPPLEMENTAL LICENSE TERMS

(COLLECTIVELY "AGREEMENT") CAREFULLY BEFORE OPENING THE SOFTWARE MEDIA

PACKAGE.  BY OPENING THE SOFTWARE MEDIA PACKAGE, YOU AGREE TO THE TERMS OF

THIS AGREEMENT.  IF YOU ARE ACCESSING THE SOFTWARE ELECTRONICALLY, INDICATE

YOUR ACCEPTANCE OF THESE TERMS BY SELECTING THE "ACCEPT" BUTTON AT THE END

OF THIS AGREEMENT.  IF YOU DO NOT AGREE TO ALL THESE TERMS, PROMPTLY RETURN

THE UNUSED SOFTWARE TO YOUR PLACE OF PURCHASE FOR A REFUND OR, IF THE

SOFTWARE IS ACCESSED ELECTRONICALLY, SELECT THE "DECLINE" BUTTON AT THE END

OF THIS AGREEMENT.

1.  LICENSE TO USE.  Sun grants you a non-exclusive and non-transferable

license for the internal use only of the accompanying software and

documentation and any error corrections provided by Sun (collectively

"Software"), by the number of users and the class of computer hardware for

which the corresponding fee has been paid.

2.  RESTRICTIONS.  Software is confidential and copyrighted. Title to

Software and all associated intellectual property rights is retained by Sun

and/or its licensors.  Except as specifically authorized in any Supplemental

License Terms, you may not make copies of Software, other than a single copy

of Software for archival purposes.  Unless enforcement is prohibited by

applicable law, you may not modify, decompile, or reverse engineer

Software.  You acknowledge that Software is not designed, licensed or

intended for use in the design, construction, operation or maintenance of

any nuclear facility.  Sun disclaims any express or implied warranty of

fitness for such uses.  No right, title or interest in or to any trademark,

service mark, logo or trade name of Sun or its licensors is granted under

this Agreement.

3. LIMITED WARRANTY.  Sun warrants to you that for a period of ninety (90)

days from the date of purchase, as evidenced by a copy of the receipt, the

media on which Software is furnished (if any) will be free of defects in

materials and workmanship under normal use.  Except for the foregoing,

Software is provided "AS IS".  Your exclusive remedy and Sun's entire

liability under this limited warranty will be at Sun's option to replace

Software media or refund the fee paid for Software.

4.  DISCLAIMER OF WARRANTY.  UNLESS SPECIFIED IN THIS AGREEMENT, ALL EXPRESS

OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED

WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR

NON-INFRINGEMENT ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT THESE DISCLAIMERS

ARE HELD TO BE LEGALLY INVALID.

5.  LIMITATION OF LIABILITY.  TO THE EXTENT NOT PROHIBITED BY LAW, IN NO

EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR

DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE

DAMAGES, HOWEVER CAUSED REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT

OF OR RELATED TO THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS

BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.  In no event will Sun's

liability to you, whether in contract, tort (including negligence), or

otherwise, exceed the amount paid by you for Software under this Agreement.

The foregoing limitations will apply even if the above stated warranty fails

of its essential purpose.

6.  Termination.  This Agreement is effective until terminated.  You may

terminate this Agreement at any time by destroying all copies of Software.

This Agreement will terminate immediately without notice from Sun if you

fail to comply with any provision of this Agreement.  Upon Termination, you

must destroy all copies of Software.

7. Export Regulations. All Software and technical data delivered under this

Agreement are subject to US export control laws and may be subject to export

or import regulations in other countries.  You agree to comply strictly with

all such laws and regulations and acknowledge that you have the

responsibility to obtain such licenses to export, re-export, or import as

may be required after delivery to you.

8.   U.S. Government Restricted Rights.  If Software is being acquired by or

on behalf of the U.S. Government or by a U.S. Government prime contractor or

subcontractor (at any tier), then the Government's rights in Software and

accompanying documentation will be only as set forth in this Agreement; this

is in accordance with 48 CFR 227.7201 through 227.7202-4 (for Department of

Defense (DOD) acquisitions) and with 48 CFR 2.101 and 12.212 (for non-DOD

acquisitions).

9.  Governing Law.  Any action related to this Agreement will be governed by

California law and controlling U.S. federal law.  No choice of law rules of

any jurisdiction will apply.

10.  Severability. If any provision of this Agreement is held to be

unenforceable, this Agreement will remain in effect with the provision

omitted, unless omission would frustrate the intent of the parties, in which

case this Agreement will immediately terminate.

11.  Integration.  This Agreement is the entire agreement between you and

Sun relating to its subject matter.  It supersedes all prior or

contemporaneous oral or written communications, proposals, representations

and warranties and prevails over any conflicting or additional terms of any

quote, order, acknowledgment, or other communication between the parties

relating to its subject matter during the term of this Agreement.  No

modification of this Agreement will be binding, unless in writing and signed

by an authorized representative of each party.

                             DEVELOPMENT TOOLS

                    JAVA ADVANCED IMAGING, VERSION 1.1.2

                         SUPPLEMENTAL LICENSE TERMS

These supplemental license terms ("Supplemental Terms") add to or modify the

terms of the Binary Code License Agreement (collectively, the "Agreement").

Capitalized terms not defined in these Supplemental Terms shall have the

same meanings ascribed to them in the Agreement. These Supplemental Terms

shall supersede any inconsistent or conflicting terms in the Agreement, or

in any license contained within the Software.

1. Software Internal Use and Development License Grant. Subject to the terms

and conditions of this Agreement, including, but not limited to Section 3

(Java(TM) Technology Restrictions) of these Supplemental Terms, Sun grants

you a non-exclusive, non-transferable, limited license to reproduce

internally and use internally the binary form of the Software complete and

unmodified for the sole purpose of designing, developing and testing your

Java applets and applications intended to run on the Java platform

("Programs").

2. License to Distribute Software.  In addition to the license granted in

Section 1 (Software Internal Use and Development License Grant) of these

Supplemental Terms, subject to the terms and conditions of this Agreement,

including but not limited to Section 3 (Java Technology Restrictions) of

these Supplemental Terms, Sun grants you a non-exclusive, non-transferable,

limited license to reproduce and distribute the Software in binary code form

only, provided that you (i) distribute the Software complete and unmodified

and only bundled as part of your Programs, (ii) do not distribute additional

software intended to replace any component(s) of the Software, (iii) do not

remove or alter any proprietary legends or notices contained in the

Software, (iv) only distribute the Software subject to a license agreement

that protects Sun's interests consistent with the terms contained in this

Agreement, and (v) agree to defend and indemnify Sun and its licensors from

and against any damages, costs, liabilities, settlement amounts and/or

expenses (including attorneys' fees) incurred in connection with any claim,

lawsuit or action by any third party that arises or results from the use or

distribution of any and all Programs and/or Software.

3. Java Technology Restrictions. You may not modify the Java Platform

Interface ("JPI", identified as classes contained within the "java" package

or any subpackages of the "java" package), by creating additional classes

within the JPI or otherwise causing the addition to or modification of the

classes in the JPI.  In the event that you create an additional class and

associated API(s) which (i) extends the functionality of the Java platform,

and (ii) is exposed to third party software developers for the purpose of

developing additional software which invokes such additional API, you must

promptly publish broadly an accurate specification for such API for free use

by all developers. You may not create, or authorize your licensees to

create, additional classes, interfaces, or subpackages that are in any way

identified as "java", "javax", "sun" or similar convention as specified by

Sun in any naming convention designation.

4.  Java Runtime Availability.  Refer to the appropriate version of the Java

Runtime Environment binary code license (currently located at

http://www.java.sun.com/jdk/index.html) for the availability of runtime code

which may be distributed with Java applets and applications.

5. Trademarks and Logos. You acknowledge and agree as between you and Sun

that Sun owns the SUN, SOLARIS, JAVA, JINI, FORTE, STAROFFICE, STARPORTAL

and iPLANET trademarks and all SUN, SOLARIS, JAVA, JINI, FORTE, STAROFFICE,

STARPORTAL and iPLANET-related trademarks, service marks, logos and other

brand designations ("Sun Marks"), and you agree to comply with the Sun

Trademark and Logo Usage Requirements currently located at

http://www.sun.com/policies/trademarks. Any use you make of the Sun Marks

inures to Sun's benefit.

6. Source Code. Software may contain source code that is provided solely for

reference purposes pursuant to the terms of this Agreement.  Source code may

not be redistributed unless expressly provided for in this Agreement.

7.  Termination for Infringement.  Either party may terminate this Agreement

immediately should any Software become, or in either party's opinion be

likely to become, the subject of a claim of infringement of any intellectual

property right.

For inquiries please contact: Sun Microsystems, Inc.,.   4150 Network

Circle, Santa Clara, California 95054, U.S.A

(Form ID#011801)

Copyright 2002 Sun Microsystems, Inc., 4150

Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved.

Sun Microsystems, Inc. has intellectual property rights relating to

technology embodied in this product. In particular, and without

limitation, these intellectual property rights may include one or more

of the U.S. patents listed at http://www.sun.com/patents and one or more

additional patents or pending patent applications in the U.S. and other

countries.

This product is distributed under licenses restricting its use, copying

distribution, and decompilation. No part of this product may be

reproduced in any form by any means without prior written authorization

of Sun and its licensors, if any.

Third-party software, including font technology, is copyrighted and

licensed from Sun suppliers.

Parts of the product may be derived from Berkeley BSD systems, licensed

from the University of California. UNIX is a registered trademark in the

U.S. and in other countries, exclusively licensed through X/Open

Company, Ltd.

Sun, Sun Microsystems, the Sun logo, Java, and Solaris, the 100% Pure

Java logo, the Java Coffee Cup logo and the Solaris logo are trademarks

or registered trademarks of Sun Microsystems, Inc. in the U.S. and other

countries.

The OPEN LOOK and Sun(TM) Graphical User Interface was developed by Sun

Microsystems, Inc. for its users and licensees. Sun acknowledges the

pioneering efforts of Xerox in researching and developing the concept of

visual or graphical user interfaces for the computer industry. Sun holds

a non-exclusive license from Xerox to the Xerox Graphical User

Interface, which license also covers Sun's licensees who implement OPEN

LOOK GUIs and otherwise comply with Sun's written license agreements.

Federal Acquisitions: Commercial Software - Government Users Subject to

Standard License Terms and Conditions.

DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED

CONDITIONS. REPRESENTATIONS AND WARRANTIES, INCLUDING ANY

IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A

PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED,

EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE

LEGALLY INVALID.

Copyright 2002 Sun Microsystems, Inc., 4150

Network Circle, Santa Clara, California 95054, Etats-Unis. Tous droits

r?serv?s.

Sun Microsystems, Inc. a les droits de propri?t? intellectuels relatants

? la technologie incorpor?e dans ce produit. En particulier, et sans la

limitation, ces droits de propri?t? intellectuels peuvent inclure un ou

plus des brevets am?ricains ?num?r?s ? http://www.sun.com/patents et un

ou les brevets plus suppl?mentaires ou les applications de brevet en

attente dans les Etats - Unis et les autres pays.

Ce produit ou document est prot?g? par un copyright et distribu? avec

des licences qui en restreignent l'utilisation, la copie, la

distribution, et la d?compilation. Aucune partie de ce produit ou

document ne peut ?tre reproduite sous aucune forme, par quelque moyen

que ce soit, sans l'autorisation pr?alable et ?crite de Sun et de ses

bailleurs de licence, s'il y ena.

Le logiciel d?tenu par des tiers, et qui comprend la technologie

relative aux polices de caract?res, est prot?g? par un copyright et

licenci? par des fournisseurs de Sun.

Des parties de ce produit pourront ?tre d?riv?es des syst?mes Berkeley

BSD licenci?s par l'Universit? de Californie. UNIX est une marque

d?pos?e aux Etats-Unis et dans d'autres pays et licenci?e exclusivement

par X/Open Company, Ltd.

Sun, Sun Microsystems, le logo Sun, Java, Solaris, le logo 100% Pure

Java, le logo Java Coffee Cup et le logo Solaris sont des marques de

fabrique ou des marques d?pos?es de Sun Microsystems, Inc. aux

Etats-Unis et dans d'autres pays.

L'interface d'utilisation graphique OPEN LOOK et Sun(TM) a ?t?

d?velopp?e par Sun Microsystems, Inc. pour ses utilisateurs et

licenci?s. Sun reconna?t les efforts de pionniers de Xerox pour la

recherche et le d?veloppment du concept des interfaces d'utilisation

visuelle ou graphique pour l'industrie de l'informatique. Sun d?tient

une license non exclusive do Xerox sur l'interface d'utilisation

graphique Xerox, cette licence couvrant ?galement les licenci?es de Sun

qui mettent en place l'interface d 'utilisation graphique OPEN LOOK et

qui en outre se conforment aux licences ?crites de Sun.

DOCUMENTATION EST FOURNIE "EN L'?TAT" ET TOUTES AUTRES CONDITIONS,

DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT

EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS

NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A

L'APTITUDE A UNE UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFA?ON.

JavaTM Advanced Imaging API v1.1.2 Readme

Contents

   * Introduction

        o Installation and System Requirements

        o Documentation

        o Bugs

   * Overview of JAI Functionality

        o Core Functionality

        o Operators

             + Native Acceleration

        o How to Run the JAI 1.1 version of Remote Imaging

        o How to Run the JAI 1.0.2 version of Remote Imaging

   * What's New

        o Core Classes

        o Operations

        o Network Imaging

        o Widget Package

        o Fixed Bugs

   * Changes From JAI 1.1.2-beta to JAI 1.1.2-RC

        o Bugs Fixed in JAI 1.1.2-RC

        o Enhancements Added in JAI 1.1.2-RC

   * Changes From JAI 1.1.2-RC to JAI 1.1.2

        o Bugs Fixed in JAI 1.1.2

        o Enhancements Added in JAI 1.1.2

   * Feedback

Introduction

The Maintenance Review release of the 1.1 version of the Java TM Advanced

Imaging (JAI) specification contains some changes since the JAI 1.1

specification Final Release. The present reference implementation, called

Java Advanced Imaging 1.1.2, implements the Maintenance Review version of

the JAI 1.1 specification and also contains bug fixes and performance

enhancements with respect to the most recent implementation of the JAI 1.1

specification Final Release which was called JAI 1.1.1_01. It represents

development pursuant to maintenance of the Java Advanced Imaging 1.1 JSR.

The changes since JAI 1.1.1_01 are described in the "What's New" section of

this document.

The Java Advanced Imaging API home page is located at

http://java.sun.com/products/java-media/jai/. There you will find binaries,

documentation, answers to frequently asked questions, and other information.

Installation and System Requirements

For general installation instructions please refer to the INSTALL page. For

system requirements please refer to the system requirements section of the

INSTALL page.

Documentation

Links to Java Advanced Imaging documentation are available at

http://java.sun.com/products/java-media/jai/docs/

Bugs

Some bugs are known to exist - see the BUGS page for details.

Overview of JAI Functionality

Core Functionality

All areas of the JAI specification have been implemented for this release.

The com.sun.media.jai.codec package continues to be an uncommitted part of

JAI. For mode information on image reading and writing images on the Java 2

platform and in JAI please refer to the page Image I/O in Java Advanced

Imaging.

All operators outlined in the Java Advanced Imaging API specification are

implemented.

The major areas of JAI functionality are described below:

  1. Tiling

     Images are made up of tiles. Different images may have different tile

     sizes. Each tile can be processed and stored in memory separately.

     Tiles may be stored in a centrally-maintained cache for performance.

     The use of tiling also facilitates the use of multiple threads for

     computation. Previously allocated tiles may also be re-used to save

     memory.

  2. Deferred execution

     Image operations performed on an image do not take place immediately

     when they are defined. Calculation of pixels happens only when a

     portion of the resultant image is requested, and only tiles that are

     needed are processed. However, operations always appear semantically to

     be completed immediately.

  3. Threaded Computation

     Requests for tiles are given to several running threads, allowing

     potential speedups on multi-processor systems or when requesting data

     over the network.

  4. Object-Oriented Extensibility

     Users can add their own image operators or override existing operators

     by registering the new operators with the operation registry. Please

     see the "The Java Advanced Imaging API White Paper," the API

     documentation, the JAI tutorial, the sample code, and the jai-interest

     archives for more information (in the archives search for subjects

     beginning with "sample code").

     Additionally, users may extend a number of non-image classes in order

     to add functionality to JAI:

        o Border Extension

          Operators may obtain an extended view of their sources using an

          extensible mechanism for generating pixel values outside of the

          source image bounds. New subclasses of BorderExtender may be used

          to obtain customized functionality.

        o Image Warping

          Subclasses of Warp may be written to perform customized image

          warping.

        o Pixel Interpolation

          Subclasses of Interpolation may be written to perform customized

          pixel interpolation.

        o Color Spaces

          Subclasses of ColorSpaceJAI may be written to implement

          mathematically defined color space transformations without the

          need for ICC profiles.

  5. Graphics2D-Style Drawing

     Graphics2D-style drawing may be performed on a TiledImage in a manner

     analogous to that available for java.awt.image.BufferedImage.

     The RenderableGraphics class provides a way to store a sequence of

     drawing commands and to "replay" them at an arbitrary output

     resolution.

  6. Regions of interest (ROIs)

     Non-rectangular portions of an image may be specified using a ROI or

     ROIShape object. These ROIs may be used as parameters to the Extrema,

     Mean, Histogram or Mosaic operations and the TiledImage.set() and

     TiledImage.setData() methods. Operations produce an appropriate ROI

     property on their output when one exists on their input.

  7. Image file handling

     This release of Java Advanced Imaging supports BMP, FlashPIX, GIF,

     JPEG, PNG, PNM, and TIFF images as defined in the TIFF 6.0

     specification, and WBMP type 0 B/W uncompressed bitmaps. TIFF G3 (1D

     and 2D), G4, PackBits, LZW, JPEG, and DEFLATE (Zip) compression types

     are understood.

     The classes dealing with image file handling (the

     com.sun.media.jai.codec package and private implementation packages

     that provide support for it) are provided in a separate jai file,

     jai_codec.jar. This jar file may be used separately from the

     jai_core.jar file containing the various javax.media.jai packages and

     their supporting classes.

     As described in the Core Functionality section of this document, the

     image codec classes should be considered as temporary helper functions.

     They will be replaced by a new API for image I/O that has been defined

     under the Java Community Process.

        o BMP File Handling:

               The BMP reader can read Version 2.x, 3.x and some 4.x BMP

               images. BMP images with 1, 4, 8, 24 bits can be read with

               this reader. Support for 16 and 32 bit images has also been

               implemented, although such images are not very common.

               Reading of compressed BMPs is supported. BI_RGB, BI_RLE8,

               BI_RLE4 and BI_BITFIELDS compressions are handled.

               The BMP reader emits properties such as type of compression,

               bits per pixel etc. Use the getPropertyNames() method to get

               the names of all the properties emitted.

               BMP Limitations:

                  + Only the default RGB color space is supported.

                  + Alpha channels are not supported.

               BMP Writer:

                  + The BMP writer is capable of writing images in the

                    Version 3 format. Images which make use of a

                    IndexColorModel with 2, 16, or 256 palette entries will

                    be written in palette form.

                  + RLE4 and RLE8 compression is supported when compatible

                    with the image data.

        o FlashPIX file handling:

               A limited FlashPIX reader is provided that is capable of

               extracting a single resolution from a FlashPIX image file.

               Only simple FlashPix files are decoded properly.

               The image view object is ignored, and image property

               information is not exported.

               There is no FlashPIX writer.

        o GIF file handling:

               There is no GIF writer due to the patent on the LZW

               compression algorithm.

        o JPEG file handling:

             + JPEG files are read and written using the classes found in

               the com.sun.image.codec.jpeg package of the JDK. A set of

               simple JAI wrapper classes around these classes is provided.

             + The JPEG decoder cannot read abbreviated streams, either

               tables-only or image-only.

        o PNG file handling:

               All files in the PNGSuite test suite have been read and

               written successfully. See the documentation in

               com.sun.media.jai.codec.PNGDecodeParam and PNGEncodeParam for

               more information.

        o PNM file handling:

               PNM files may be read and written in both ASCII and raw

               formats. The encoder automatically selects between PBM

               (bitmap), PGM (grayscale) and PPM (RGB) files according to

               the number of bands and bit depth of the source image.

               Due to the limitations of the format, only images with 1 or 3

               bands may be written.

        o TIFF file handling:

          TIFF support has the following limitations:

             + The TIFF encoder does not support LZW compression due to the

               patent on the algorithm.

             + Planar format (PlanarConfiguration field has value 2) is not

               supported for decoding or encoding.

        o WBMP file handling:

               The WBMP codec reads and writes images in the Wireless Bitmap

               format described in chapter 6 and Appendix A of the Wireless

               Application Protocol (WAP) Wireless Application Environment

               Specification, Version 1.3, 29 March 2000. The WBMP type

               supported is WBMP Type 0: B/W, Uncompressed Bitmap. There are

               no limitations on the image dimensions.

  8. Image Layouts

     Images with arbitrary pixel layouts may be processed in a uniform

     manner using the PixelAccessor and RasterAccessor classes.

     Source images with ComponentColorModels and IndexColorModels are

     supported. DirectColorModel images are not supported.

     PixelAccessor and RasterAccessor provide the most efficient support for

     the ComponentSampleModel/ComponentColorModel combination.

  9. Image Collections

     The output of a standard image operator on an instance of

     java.util.Collection is a collection of the same type. Nested

     collections are supported. Operators may also emit collections of their

     choice, or take collections as sources and emit a single image.

 10. Remote Imaging

     JAI allows operations to be performed remotely to be created in a

     manner similar to local operations. RemoteJAI.create() and

     RemoteJAI.createRenderable() can be used to create operations that are

     performed on remote hosts. Operation chains are created on the client

     and can contain a mix of local and remote operations by using

     JAI.create() and RemoteJAI.create(), respectively to create the

     operations.

     The "fileload" and "filestore" operations can allow files that reside

     only on remote filesystems to be loaded and stored remotely. This can

     be accomplished by setting the checkFileLocally argument to the

     operation to be false, in which case the presence of the file to be

     loaded or stored is not checked on the local file system when the

     operation is first created.

     See sections below for instructions on how to use the JAI 1.0.2 and 1.1

     or later versions of remote imaging.

 11. Iterators

     Optimized Rect and Random iterators exist as well as a non-optimized

     version of the Rook iterator.

 12. Snapshotting of External Sources

     SnapshotImage provides an arbitrary number of synchronous views of a

     possibly changing WritableRenderedImage.

 13. Meta-data Handling

     Meta-data handling is provided via a name-value database of properties

     associated with each JAI image. Mechanisms are provided by which such

     properties may be generated and processed in the course of image

     manipulation. The ability to defer computation of such data is also

     provided in a manner conceptually equivalent to that available for

     image data. Please refer to the DeferredData and DeferredProperty

     classes for more information.

 14. Serialization Support

     SerializerFactory provides a framework is provided to assist in

     serializing instances of classes which do not implement

     java.io.Serializable. Such objects must be serialized by extracting a

     serializable version of their state from which the original object may

     be extracted after deserialization.

Operators

Java Advanced Imaging extends the imaging functionality provided in the Java

2D API by providing a more flexible and scalable architecture targeted for

complex, high performance imaging requirements. In this context a large

number of imaging operators are provided.

   * Native Acceleration

     Pure Java implementations are provided for all image operators and

     imaging performance is addressed for some of these by providing C-based

     native code. Native C-code based acceleration for a certain subset of

     operators under specific conditions (listed in the table below) is

     available for the Sun/Solaris, Win32 and Linux (x86 only) platforms. On

     Sun UltraSPARC-based platforms, additional performance is gained with

     hardware acceleration via the VIS instructions for most natively

     supported operators. On Win32 platforms which support MMX instructions,

     hardware acceleration is gained for a subset of the natively supported

     operators.

     If a native implementation is present it is, by default, the preferred

     implementation. But if the nature of the sources and parameters of the

     operation are incompatible with the native operation then processing

     will revert to Java code. In general the following minimum requirements

     must be adhered to for the mediaLib native implementation of an

     operation to be executed:

        o All sources must be RenderedImages.

        o All sources and destination must have

             + a SampleModel which is a ComponentSampleModel and

             + a ColorModel which is a ComponentColorModel or no ColorModel

               (i.e., it is null).

        o All sources and the destination must have at most 4 bands of pixel

          data.

        o If Interpolation type is one of the arguments to the operator,

          then native acceleration is available only for Nearest, Bilinear,

          Bicubic and Bicubic2 cases. Additionally for byte images

          InterpolationTable is also supported for native acceleration.

     Further restrictions may be imposed by individual operations but the

     above are the most common requirements.

   * Imaging Operators

     The following image operators are implemented in this release. Only a

     brief description of each operator is provided here. For detailed

     information on these operators, refer to the package

     javax.media.jai.operator in the full documentation available at

     http://java.sun.com/products/java-media/jai/docs/index.html.

     All operations are performed on a per-band basis, unless specified

     otherwise. C acceleration applies to all platforms whereas VIS is

     specific to Sun UltraSPARC and MMX to Windows.

       1. Point and Arithmetic Operators

                                                     Native Acceleration

              Operator Name       Description

                                                 C VIS MMX      Notes

                                Computes the

           absolute             absolute value   X  X   X

                                of the pixels of

                                an image.

                                Adds the pixel

           add                  values of two    X  X   X

                                source images.

                                Adds a

           addcollection        collection of

                                images to one

                                another.

                                Adds a set of

                                constant values

           addconst             to the pixel     X  X   X

                                values of a

                                source image.

                                Adds a set of

                                constant values

           addconsttocollection to the pixel     X  X   X

                                values of a

                                Collection of

                                source images.

                                And's the pixel

           and                  values of two    X  X   X

                                source images.

                                And's the pixel

                                values of a

           andconst             source image     X  X   X

                                with a set of

                                constants.

                                Computes a

                                linear

           bandcombine          combination of   X  X   X  3x4 matrix only.

                                the bands of an

                                image.

                                Creates an image

                                consisting of

                                all bands of all

           bandmerge            sources

                                concatenated in

                                the order

                                encountered.

                                Selects a subset

                                of the bands of            Only if the band

           bandselect           an image,        X  X   X  selection is

                                possibly                   monotonically

                                reordering them.           increasing.

                                Thresholds a

                                single-band

           binarize             image to two     X  X

                                levels to

                                generate a

                                bilevel output.

                                Set all pixel

                                values below the

                                low value to

                                that low value,

           clamp                set all the      X  X   X

                                pixel values

                                above the high

                                value to that

                                high value.

                                Converts an

           colorconvert         image to a given

                                ColorSpace.

                                Generates an

                                optimal LUT by

           colorquantizer       executing a

                                color

                                quantization

                                algorithm

                                Combines two

                                images based on

           composite            their alpha      X  X   X

                                values at each

                                pixel.

                                Creates an image

           constant             with constant

                                pixel values.

                                Divides the

                                pixel values of

                                the first source

           divide               image by the     X

                                pixel values of

                                the second

                                source image.

                                Divides the

                                pixel values of

           dividebyconst        a source image   X

                                by a set of

                                constants.

                                Divides a set of

           divideintoconst      constants by the X

                                pixel values of

                                a source image.

                                Computes the

           exp                  exponential of   X

                                the pixel values

                                of an image.

                                Performs

                                reformatting on

                                an image,

                                including data

           format               type casting,

                                replacing the

                                SampleModel and

                                ColorModel, and

                                restructuring

                                the tile grid.

                                Inverts the

           invert               pixel values of  X  X   X

                                an image.

                                Computes the

                                natural

           log                  logarithm of the X

                                pixel values of

                                an image.

                                Performs general           Only if table

           lookup               table lookup on  X  X   X  has less than or

                                an image.                  equal to 4

                                                           bands.

                                Performs a

                                piecewise linear

                                remapping of

           matchcdf             pixel values to

                                match a given

                                cumulative

                                distribution

                                function.

                                Chooses the

           max                  maximum pixel    X  X   X

                                values between

                                two images.

                                Chooses the

           min                  minimum pixel    X  X   X

                                values between

                                two images.

                                Multiplies the

           multiply             pixel values of  X  X

                                two source

                                images.

                                Multiplies the

                                pixel values of

           multiplyconst        a source image   X  X

                                by a set of

                                constants.

                                Inverts the

           not                  pixel values of  X  X   X

                                a source image.

                                Or's the pixel

           or                   values of two    X  X   X

                                source images.

                                Or's the pixel

                                values of a

           orconst              source image     X  X   X

                                with a set of

                                constants.

                                Overlays one

           overlay              image on top of

                                another image.

                                Performs

                                piecewise linear

           piecewise            remapping of the

                                pixel values of

                                an image.

                                Performs a

                                linear remapping

           rescale              of the pixel     X  X

                                values of an

                                image.

                                Subtracts the

                                pixel values of

           subtract             one image from   X  X   X

                                those of

                                another.

                                Subtracts a set

                                of constant

           subtractconst        values from the  X  X   X

                                pixel values of

                                an image.

                                Subtracts a set

                                of constant

           subtractfromconst    values from the  X  X   X

                                pixel values of

                                an image.

                                Maps the pixel

                                values that fall

           threshold            between a low    X  X   X

                                and high value

                                to a set of

                                constants.

                                Xor's the pixel

           xor                  values of two    X  X   X

                                source images.

                                Xor's a source

           xorconst             image with a set X  X   X

                                of constants.

       2. Area and Geometric Operators

                                                      Native Acceleration

               Operator Name        Description

                                                  C VIS MMX       Notes

                                 Performs first             InterpolationTable

           affine                order geometric  X  X   X  is not MMX

                                 image warping.             accelerated for

                                                            even byte images.

           border                Adds a border

                                 around an image.

                                 Convolves an

           boxfilter             image using a

                                 two-dimensional

                                 box filter.

                                 Performs an MxN

           convolve              image            X  X   X  General and

                                 convolution.               separable cases.

                                 Extracts a

           crop                  subarea of an

                                 image.

                                 Performs

                                                            Only single band,

           dilate                morphological    X  X   X  3x3 kernels

                                 dilation on an

                                 image.                     centered at 1,1

                                 Performs

                                                            Only single band,

           erode                 morphological    X  X   X  3x3 kernels

                                 erosion on an

                                 image.                     centered at 1,1

                                 Performs a

                                 combined integral

           filteredsubsample     subsample and    X  X   X

                                 symmetric

                                 product-separable

                                 filter.

                                 Performs edge

           gradientmagnitude     detection using  X  X   X

                                 orthogonal

                                 gradient masks.

                                 Computes the               Only single band;

           maxfilter             maximum value of X  X   X  only for a SQUARE

                                 a pixel                    mask of size 3, 5,

                                 neighborhood.              or 7

                                 Computes the

           medianfilter          median value of aX  X   X

                                 pixel

                                 neighborhood.

                                 Computes the               Only single band;

           minfilter             minimum value of X  X   X  only for a SQUARE

                                 a pixel                    mask of size 3, 5,

                                 neighborhood.              or 7

                                 Creates a mosaic

           mosaic                of two or more   X  X   X

                                 rendered images.

                                 Rotates an image           InterpolationTable

           rotate                about an         X  X   X  is not MMX

                                 arbitrary point.           accelerated for

                                                            even byte images.

                                 Scales and                 InterpolationTable

           scale                 translates an    X  X   X  is not MMX

                                 image.                     accelerated for

                                                            even byte images.

                                                            InterpolationTable

           shear                 Shears an image. X  X   X  is not MMX

                                                            accelerated for

                                                            even byte images.

                                 Subsamples an

           subsampleaverage      image by         X  X

                                 averaging over a

                                 moving window.

                                 Subsamples a

           subsamplebinarytogray bilevel image to X  X

                                 a grayscale

                                 image.

                                 Translates an

                                 image by an                InterpolationTable

           translate             integral or      X  X   X  is not MMX

                                 fractional                 accelerated for

                                 amount.                    even byte images.

                                 Reflects an image

                                 in a specified

           transpose             direction or     X  X   X

                                 rotates an image

                                 in multiples of

                                 90 degrees.

                                 Sharpens an image

           unsharpmask           by suppressing   X  X   X  General and

                                 the low                    separable kernels.

                                 frequencies.

                                 Performs

           warp                  geometric warpingX  X   X  polynomial and

                                 on an image.               grid only.

       3. Frequency-domain, Transform, and Complex Operators

                                                               Native

            Operator Name           Description             Acceleration

                                                          C  VIS  MMX Notes

           conjugate        Computes the complex

                            conjugate of an image.

           dct              Computes the Discrete Cosine  X

                            Transform of an image.

                            Computes the Discrete

           dft              Fourier Transform of an       X

                            image, possibly resulting in

                            a complex image.

           dividecomplex    Computes the quotient of two

                            complex images.

                            Computes the inverse

           idct             Discrete Cosine Transform of  X

                            an image.

                            Computes the inverse

           idft             Discrete Fourier Transform    X

                            of an image.

           magnitude        Computes the magnitude of a

                            complex image.

                            Computes the squared

           magnitudesquared magnitude of a complex

                            image.

           multiplycomplex  Computes the product of two

                            complex images.

           periodicshift    Shifts an image

                            periodically.

           phase            Computes the phase angle of

                            a complex image.

                            Creates a complex image from

           polartocomplex   two images representing

                            magnitude and phase.

       4. Statistical Operators

                                              Native

            Operator                       Acceleration

              Name        Description

                                         C  VIS MMX  Notes

                      Computes the

                      maximum and                         Only if the ROI

           extrema    minimum pixel      X   X   X        is null or

                      values of an                        encloses the

                      image.                              entire image.

                      Computes the

           histogram  histogram of an    X   X   X

                      image.

                                                          Only if the ROI

                      Computes the mean                   is null or

           mean       pixel value of a   X   X   X        encloses the

                      region of an                        entire image and

                      image.                              the sampling

                                                          period is 1.

       5. Sourceless Operators

           Operator Name                    Description

           imagefunction Creates an image by evaluating a function.

           pattern       Creates an image consisting of a repeated pattern.