Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/misc/volume38/lic/part07

Text File | 1993-08-11 | 66KB | 2,151 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Casey Leedom)
Subject: v38i110:  lic - LLNL Line Integral Convolution, v1.2, Part07/10
Message-ID: <[e-mail]>
X-Md4-Signature: 299c0cda33ada3acac503228b6d2f091
Sender: [e-mail] (Kent Landfield)
Organization: Sterling Software
Date: Thu, 12 Aug 1993 01:39:26 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Casey Leedom)
Posting-number: Volume 38, Issue 110
Archive-name: lic/part07
Environment: UNIX

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then feed it
# into a shell via "sh file" or similar.  To overwrite existing files,
# type "sh file -c".
# Contents:  lic.1.2/doc/cover.me lic.1.2/liblic/Convolve2D.c
#   lic.1.2/liblic/Convolve3D.c lic.1.2/liblic/LIC.3
#   lic.1.2/liblic/LIC_Create.3 lic.1.2/lic/lic.1
# Wrapped by kent@sparky on Wed Aug 11 19:38:06 1993
PATH=/bin:/usr/bin:/usr/ucb:/usr/local/bin:/usr/lbin ; export PATH
echo If this archive is complete, you will see the following message:
echo '          "shar: End of archive 7 (of 10)."'
if test -f 'lic.1.2/doc/cover.me' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lic.1.2/doc/cover.me'\"
else
  echo shar: Extracting \"'lic.1.2/doc/cover.me'\" \(6455 characters\)
  sed "s/^X//" >'lic.1.2/doc/cover.me' <<'END_OF_FILE'
X.\" Copyright (c) 1993 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.po 1.0in
X.ll 6.5in
X.nr pi 0n
X.de Hd
X.ds Vr 1.2
X.ds Dt \\$4
X..
X.Hd $Header: /d/sisal/a/casey/tmp/lic/doc/RCS/cover.me,v 1.5 1993/07/27 01:24:18 casey Exp $
X.of '\*(Dt''LLNL LIC version \*(Vr'
X.ef '\*(Dt''LLNL LIC version \*(Vr'
X.(b C
X.sz +10
X.rs
X.sp 2.25in
XLLNL
X.sp .25in
XLine Integral Convolution
X.sp .5in
XDistribution
X.sp 2in
XVersion \*(Vr
X\*(Dt
X.sz -10
X.)b
X.\" We delay defining the footer so it won't show up on the first page ...
X.of 'LLNL LIC version \*(Vr''\*(Dt'
X.ef '\*(Dt''LLNL LIC version \*(Vr'
X.pa
X.rs
X.sp 3.75in
XCopyright (c) 1993 The Regents of the University of California.
XAll rights reserved.
X.pp
XRedistribution and use in source and binary forms, with or without
Xmodification, are permitted provided that the following conditions
Xare met:
X.ip 1.
XRedistributions of source code must retain the above copyright
Xnotice, this list of conditions and the following disclaimer.
X.ip 2.
XRedistributions in binary form must reproduce the above copyright
Xnotice, this list of conditions and the following disclaimer in the
Xdocumentation and/or other materials provided with the distribution.
X.ip 3.
XAll advertising materials mentioning features or use of this software
Xmust display the following acknowledgement:
X.(q
XThis product includes software developed by the University of
XCalifornia, Lawrence Livermore National Laboratory and its contributors.
X.)q
X.ip 4.
XNeither the name of the University nor the names of its contributors
Xmay be used to endorse or promote products derived from this software
Xwithout specific prior written permission.
X.pp
XTHIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
XANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
XIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
XARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
XFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
XDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
XOR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
XHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
XLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
XOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
XSUCH DAMAGE.
X.pa
X.(b C
X.sz +2
XContents
X.sz -2
X.)b
X.sp 3v
X.(x i
XIntroduction
X.)x 1
X.(x i
XREADME
X.)x 2
X.(x i
XABSTRACT
X.)x 3
X.(x i
XMEMO
X.)x 4
X.(x i
XTODO
X.)x 5
X.(x i
XImaging Vector Fields Using Line Integral Convolution
X.)x 6
X.(x i
XManual pages
X.)x 7
X.(x i
XInclude file sources
X.)x 8
X.(x i
Xlic command source
X.)x 9
X.(x i
XLIC AVS coroutine module source
X.)x 10
X.(x i
XLIC library sources
X.)x 11
X.xp i
X.pa
X.(b C
X.sz +2
X1
X.sp 1v
XIntroduction
X.sz -2
X.)b
X.sp 3v
X.pp
XThis document contains the documentation and source code to the LLNL
XLine Integral Convolution (LIC) software distribution version \*(Vr.
X.pp
XThe LLNL LIC software is an experimental implementation of a new
Xvector visualization algorithm.  It allows researchers to experiment
Xwith this algorithm and duplicate results presented in the paper
X.i "Imaging Vector Fields Using Line Integral Convolution"
Xby Brian Cabral and Casey Leedom in the 1993 SIGGRAPH conference.
X.pp
XThe software consists of an object-oriented library that implements
Xthe algorithm, a command line interface and an AVS interface and
Xdocumentation for all of the above.
X.pa
X.(b C
X.sz +2
X2
X.sp 1v
XREADME
X.sz -2
X.)b
X.pa
X.(b C
X.sz +2
X3
X.sp 1v
XABSTRACT
X.sz -2
X.)b
X.pa
X.(b C
X.sz +2
X4
X.sp 1v
XMEMO
X.sz -2
X.)b
X.pa
X.(b C
X.sz +2
X5
X.sp 1v
XTODO
X.sz -2
X.)b
X.pa
X.(b C
X.sz +2
X6
X.sp 1v
XImaging Vector Fields Using Line Integral Convolution
X.sz -2
X.)b
X.pa
X.(b C
X.sz +2
X7
X.sp 1v
XManual pages
X.sz -2
X.)b
X.sp 3v
X.pp
X.(x i
Xlic.1
X.)x 1
X.(x i
XLIC.txt (AVS coroutine on-line documentation)
X.)x 2
X.(x i
XLIC.3
X.)x 3
X.(x i
XLIC_ComputeImage.3
X.)x 4
X.(x i
XLIC_Convolve.3
X.)x 5
X.(x i
XLIC_Create.3
X.)x 6
X.(x i
XLIC_Destroy.3
X.)x 7
X.(x i
XLIC_Filters.3
X.)x 8
X.(x i
XLIC_Modify.3
X.)x 9
X.(x i
XLIC_Query.3
X.)x 10
X.xp i
X.pa
X.(b C
X.sz +2
X8
X.sp 1v
XInclude file sources
X.sz -2
X.)b
X.sp 3v
X.pp
X.(x i
Xinclude/lic.h
X.)x 1
X.xp i
X.pa
X.(b C
X.sz +2
X9
X.sp 1v
Xlic command source
X.sz -2
X.)b
X.sp 3v
X.(x i
Xlic/lic.c
X.)x 1
X.xp i
X.pa
X.(b C
X.sz +2
X10
X.sp 1v
XLIC AVS coroutine module source
X.sz -2
X.)b
X.sp 3v
X.pp
X.(x i
Xavs/LIC.c
X.)x 1
X.xp i
X.pa
X.(b C
X.sz +2
X11
X.sp 1v
XLIC library sources
X.sz -2
X.)b
X.sp 3v
X.pp
X.(x i
Xliblic.h
X.)x 1
X.(x i
XComputeImage.c
X.)x 2
X.(x i
XConvolve2D.c
X.)x 3
X.(x i
XConvolve3D.c
X.)x 4
X.(x i
XCreate.c
X.)x 5
X.(x i
XDestroy.c
X.)x 6
X.(x i
XFilters.c
X.)x 7
X.(x i
XModify.c
X.)x 8
X.(x i
XQuery.c
X.)x 9
X.xp i
END_OF_FILE
  if test 6455 -ne `wc -c <'lic.1.2/doc/cover.me'`; then
    echo shar: \"'lic.1.2/doc/cover.me'\" unpacked with wrong size!
  fi
  # end of 'lic.1.2/doc/cover.me'
fi
if test -f 'lic.1.2/liblic/Convolve2D.c' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lic.1.2/liblic/Convolve2D.c'\"
else
  echo shar: Extracting \"'lic.1.2/liblic/Convolve2D.c'\" \(9707 characters\)
  sed "s/^X//" >'lic.1.2/liblic/Convolve2D.c' <<'END_OF_FILE'
X/*
X * $Header: /d/sisal/a/casey/tmp/lic/liblic/RCS/Convolve2D.c,v 1.7 1993/08/10 23:35:32 casey Exp $
X */
X
X/*
X * Copyright (c) 1993 The Regents of the University of California.
X * All rights reserved.
X *
X * Redistribution and use in source and binary forms, with or without
X * modification, are permitted provided that the following conditions
X * are met:
X * 1. Redistributions of source code must retain the above copyright
X *    notice, this list of conditions and the following disclaimer.
X * 2. Redistributions in binary form must reproduce the above copyright
X *    notice, this list of conditions and the following disclaimer in the
X *    documentation and/or other materials provided with the distribution.
X * 3. All advertising materials mentioning features or use of this software
X *    must display the following acknowledgement:
X *    This product includes software developed by the University of
X *    California, Lawrence Livermore National Laboratory and its
X *    contributors.
X * 4. Neither the name of the University nor the names of its contributors
X *    may be used to endorse or promote products derived from this software
X *    without specific prior written permission.
X *
X * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X * SUCH DAMAGE.
X */
X
X#ifndef lint
X    static char rcsid[] = "$Header: /d/sisal/a/casey/tmp/lic/liblic/RCS/Convolve2D.c,v 1.7 1993/08/10 23:35:32 casey Exp $";
X    static char copyright[] =
X    "Copyright (c) 1993 The Regents of the University of California.\n"
X    "All rights reserved.\n";
X#endif
X
X
X#include "liblic.h"
X
X
X/*
X *    Two-dimensional Line Integral Convolution.
X *    ============================================
X */
X
X
X#ifdef DEBUG
Xextern FILE *ps;
X#endif
X
X
Xvoid
XLIC_Convolve2D(LIC      *This,
X           int       i,
X           int       j,
X           int       direction,
X           double   *rIntegral,
X           double   *gIntegral,
X           double   *bIntegral,
X           double   *aIntegral,
X           double   *KernelArea)
X    /*
X     * Perform Line Integral Convolution on a two-dimensional vector field.
X     */
X{
X    REGISTER double L;            /* pos/neg length of kernel */
X    REGISTER double s, sp;        /* parametric distance along kernel */
X    double          wp;            /* integral corresponding to sp */
X    double          rSum, gSum,        /* integrated pixel values */
X            bSum, aSum;
X    int             speed;        /* integral table speed index */
X    double         *itab, is;        /* integral table and index scale */
X    int             LoopCount;        /* main loop iteration count */
X
X    sp = 0.0;
X
X    rSum = 0.0;
X    gSum = 0.0;
X    bSum = 0.0;
X    aSum = 0.0;
X
X    /*
X     * Establish length, L, of convolution and which ``speed'' version of the
X     * filter kernel to use.  The default L is the value set by the user.
X     * For VariableLength convolutions, L is scaled by the magnitude of the
X     * vector.  The default speed is to use the maximum ``speed'' version of
X     * the filter kernel.  For VariableSpeed convolutions, speed is scaled
X     * by the magnitude of the vector.
X     */
X    L = LIC_Length(This);
X    speed = LIC_INTEGRAL_SPEEDS - 1;
X    if (This->VariableLength || This->VariableSpeed)
X    {
X    REGISTER double fx, fy, norm;
X
X    fx = INDEX_2D(This->InputField, i, j)[0];
X    fy = INDEX_2D(This->InputField, i, j)[1];
X    norm = sqrt(fx*fx + fy*fy) / This->MaxLength;
X
X    if (This->VariableLength)
X        L *= norm;
X    if (This->VariableSpeed)
X        speed *= norm;
X    }
X
X    /*
X     * Establish filter kernel integral table to use based on direction and
X     * speed.  Also determine index scaling for values of s, 0 <= s <= L,
X     * into the table.  Note that the scaling is performed relative to L,
X     * not LIC_Length(This).  Scaling relative to L means that the filter
X     * is effectively dilated to match the convolution length even when
X     * performing VariableLength convolution.
X     */
X    if (This->NeedIntegration)
X    LIC_BuildIntegralTables(This);
X    if (direction == LIC_FOREWARD)
X    itab = &This->PosIntegralTable[speed][0];
X    else
X    itab = &This->NegIntegralTable[speed][0];
X    is = (double)(LIC_INTEGRAL_LEN - 1) / L;
X
X    LoopCount = 0;
X
X#   ifdef DEBUG
X    if (ThisPixel)
X        fprintf(ps, "0.0 0.0 moveto\n");
X#   endif
X
X    /*
X     * Only perform LIC if L is greater than zero.  Zero lengths
X     * can result from bad user input or magnitude based lengths.
X     */
X    if (L > 0)
X    {
X    REGISTER int    fi, fj;        /* vector field index */
X    REGISTER double x, y;        /* current cartesian location in the */
X                    /*   vector field */
X
X    fi = i;
X    fj = j;
X
X    x =  i + 0.5;
X    y = This->NormalField.Yres - j - 0.5;
X
X    wp = 0.0;
X
X    /* Loop until we reach the end of the line integral */
X    do
X    {
X        REGISTER double t;        /* distance to nearest cell edge */
X        REGISTER double fx, fy;    /* vector field values */
X
X        /*
X         * Grab the current cell vector.
X         */
X
X        /* Get the field value for this cell */
X        fx = INDEX_2D(This->NormalField, fi, fj)[0];
X        fy = INDEX_2D(This->NormalField, fi, fj)[1];
X
X        /* Bail out if the vector field goes to zero */
X        if (fx == 0.0 && fy == 0.0)
X        break;
X
X        if (direction == LIC_BACKWARD)
X        {
X        fx = -fx;
X        fy = -fy;
X        }
X
X        /*
X         * Compute the intersection with the next cell along the line
X         * of the vector field.
X         */
X        {
X        REGISTER double tt;
X#        define TT(v) \
X        { \
X            tt = (v); \
X            if (tt < t) \
X            t = tt; \
X        }
X
X        if (fx < -SIN_PARALLEL)
X            t = (FLOOR(x) - x) / fx;        /* left edge */
X        else if (fx > SIN_PARALLEL)
X            t = (CEIL(x) - x) / fx;        /* right edge */
X        else
X            t = HUGE_VAL;
X
X        if (fy < -SIN_PARALLEL)
X            TT((FLOOR(y) - y) / fy)        /* bottom edge */
X        else if (fy > SIN_PARALLEL)
X            TT((CEIL(y) - y) / fy)        /* top edge */
X
X#        undef TT
X        }
X
X        /* s and sp represent a monotonically moving convolution window */
X        s  = sp;
X        sp = sp + t;
X        t += ROUND_OFF;
X
X        /* Make sure we don't exceed the kernel width */
X        if (sp > L)
X        {
X        sp = L;
X        t  =  sp - s;
X        }
X
X#        ifdef DEBUG
X        if (ThisPixel)
X            fprintf(ps, "%f %f rlineto\n", fx*t, fy*t);
X#        endif
X
X        /*
X         * Grab the input pixel corresponding to the current cell and
X         * integrate its value over the convolution kernel from s to sp.
X         */
X        {
X#        if (PixelSize >= 3)
X            double rV, gV, bV;
X#        endif
X#        if (PixelSize == 4 || PixelSize == 1)
X            double aV;
X#        endif
X        {
X            REGISTER int ii, ij;
X
X            /* toriodally wrap input image coordinates */
X            ii = fi;
X            ij = fj;
X            WRAP(ii, This->InputImage.Xres);
X            WRAP(ij, This->InputImage.Yres);
X
X            /* Get the input image value for this cell */
X#            if (PixelSize >= 3)
X            rV = RED  (INDEX_2D(This->InputImage, ii, ij));
X            gV = GREEN(INDEX_2D(This->InputImage, ii, ij));
X            bV = BLUE (INDEX_2D(This->InputImage, ii, ij));
X#            endif
X#            if (PixelSize == 4 || PixelSize == 1)
X            aV = ALPHA(INDEX_2D(This->InputImage, ii, ij));
X#            endif
X        }
X
X        /* integrate over the convolution kernel between s and sp */
X        {
X            double          wt;
X            REGISTER double dw;
X
X            wt = itab[(int)(sp * is)];
X            dw = wt - wp;
X            wp = wt;
X
X#            if (PixelSize >= 3)
X            rSum  += (rV * dw);
X            gSum  += (gV * dw);
X            bSum  += (bV * dw);
X#            endif
X#            if (PixelSize == 4 || PixelSize == 1)
X            aSum  += (aV * dw);
X#            endif
X        }
X        }
X
X        /*
X         * March to the next cell.
X         */
X
X        LoopCount++;
X
X        /* Compute the cell we just stepped into */
X        x = x + fx*t;
X        y = y + fy*t;
X
X        /* break out of the loop if we step out of the field */
X        if (x < 0.0 || y < 0.0)
X            break;
X
X        fi = IFLOOR(x);
X        fj = This->NormalField.Yres - ICEIL(y);
X
X        /* Break out of the loop if we step out of the field */
X        if (   fi >= This->NormalField.Xres
X        || fj < 0)
X        break;
X
X        /*
X         * Loop until we reach the end or we think we've fallen into
X         * a singularity.
X         */
X    } while (sp < L && LoopCount <= 3*L);
X    }
X
X    if (LoopCount > 0 && L > 0)
X    {
X    *rIntegral = rSum;
X    *gIntegral = gSum;
X    *bIntegral = bSum;
X    *aIntegral = aSum;
X
X    /* Compute an integration normalization factor as function of sp */
X    *KernelArea = (This->NormalizationType == LIC_VARIABLE)
X        ? wp
X        : itab[LIC_INTEGRAL_LEN - 1];
X    }
X    else
X    {
X#    if (PixelSize >= 3)
X        *rIntegral = (This->DefaultRed == -1)
X        ? RED  (INDEX_2D(This->InputImage, i, j))
X        : (double)This->DefaultRed;
X        *gIntegral = (This->DefaultGreen == -1)
X        ? GREEN(INDEX_2D(This->InputImage, i, j))
X        : (double)This->DefaultGreen;
X        *bIntegral = (This->DefaultBlue == -1)
X        ? BLUE (INDEX_2D(This->InputImage, i, j))
X        : (double)This->DefaultBlue;
X#    else
X        *rIntegral = 0.0;
X        *gIntegral = 0.0;
X        *bIntegral = 0.0;
X#    endif
X#    if (PixelSize == 4 || PixelSize == 1)
X        *aIntegral = (This->DefaultAlpha == -1)
X        ? ALPHA(INDEX_2D(This->InputImage, i, j))
X        : (double)This->DefaultAlpha;
X#    else
X        *aIntegral = 0.0;
X#    endif
X
X    *KernelArea = 1;
X    }
X
X    /*
X     * Random bookkeeping for performance monitoring.
X     */
X    This->TotalLoopCount += LoopCount;
X    This->TotalLength    += sp;
X}
END_OF_FILE
  if test 9707 -ne `wc -c <'lic.1.2/liblic/Convolve2D.c'`; then
    echo shar: \"'lic.1.2/liblic/Convolve2D.c'\" unpacked with wrong size!
  fi
  # end of 'lic.1.2/liblic/Convolve2D.c'
fi
if test -f 'lic.1.2/liblic/Convolve3D.c' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lic.1.2/liblic/Convolve3D.c'\"
else
  echo shar: Extracting \"'lic.1.2/liblic/Convolve3D.c'\" \(10020 characters\)
  sed "s/^X//" >'lic.1.2/liblic/Convolve3D.c' <<'END_OF_FILE'
X/*
X * $Header: /d/sisal/a/casey/tmp/lic/liblic/RCS/Convolve3D.c,v 1.6 1993/08/10 23:35:32 casey Exp $
X */
X
X/*
X * Copyright (c) 1993 The Regents of the University of California.
X * All rights reserved.
X *
X * Redistribution and use in source and binary forms, with or without
X * modification, are permitted provided that the following conditions
X * are met:
X * 1. Redistributions of source code must retain the above copyright
X *    notice, this list of conditions and the following disclaimer.
X * 2. Redistributions in binary form must reproduce the above copyright
X *    notice, this list of conditions and the following disclaimer in the
X *    documentation and/or other materials provided with the distribution.
X * 3. All advertising materials mentioning features or use of this software
X *    must display the following acknowledgement:
X *    This product includes software developed by the University of
X *    California, Lawrence Livermore National Laboratory and its
X *    contributors.
X * 4. Neither the name of the University nor the names of its contributors
X *    may be used to endorse or promote products derived from this software
X *    without specific prior written permission.
X *
X * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X * SUCH DAMAGE.
X */
X
X#ifndef lint
X    static char rcsid[] = "$Header: /d/sisal/a/casey/tmp/lic/liblic/RCS/Convolve3D.c,v 1.6 1993/08/10 23:35:32 casey Exp $";
X    static char copyright[] =
X    "Copyright (c) 1993 The Regents of the University of California.\n"
X    "All rights reserved.\n";
X#endif
X
X
X#include "liblic.h"
X
X
X/*
X *    Three-dimensional Line Integral Convolution.
X *    ============================================
X */
X
X
Xvoid
XLIC_Convolve3D(LIC      *This,
X           int       i,
X           int       j,
X           int       k,
X           int       direction,
X           double   *rIntegral,
X           double   *gIntegral,
X           double   *bIntegral,
X           double   *aIntegral,
X           double   *KernelArea)
X    /*
X     * Perform Line Integral Convolution on a three-dimensional vector field.
X     */
X{
X    REGISTER double L;            /* pos/neg length of kernel */
X    REGISTER double s, sp;        /* parametric distance along kernel */
X    double          wp;            /* integral corresponding to sp */
X    double          rSum, gSum,        /* integrated pixel values */
X            bSum, aSum;
X    int             speed;        /* integral table speed index */
X    double         *itab, is;        /* integral table and index scale */
X    int             LoopCount;        /* main loop iteration count */
X
X    sp = 0.0;
X
X    rSum = 0.0;
X    gSum = 0.0;
X    bSum = 0.0;
X    aSum = 0.0;
X
X    /*
X     * Establish length, L, of convolution and which ``speed'' version of the
X     * filter kernel to use.  The default L is the value set by the user.
X     * For VariableLength convolutions, L is scaled by the magnitude of the
X     * vector.  The default speed is to use the maximum ``speed'' version of
X     * the filter kernel.  For VariableSpeed convolutions, speed is scaled
X     * by the magnitude of the vector.
X     */
X    L = LIC_Length(This);
X    speed = LIC_INTEGRAL_SPEEDS - 1;
X    if (This->VariableLength || This->VariableSpeed)
X    {
X    REGISTER double fx, fy, fz, norm;
X
X    fx = INDEX_3D(This->InputField, i, j, k)[0];
X    fy = INDEX_3D(This->InputField, i, j, k)[1];
X    fz = INDEX_3D(This->InputField, i, j, k)[2];
X    norm = sqrt(fx*fx + fy*fy + fz*fz) / This->MaxLength;
X
X    if (This->VariableLength)
X        L *= norm;
X    if (This->VariableSpeed)
X        speed *= norm;
X    }
X
X    /*
X     * Establish filter kernel integral table to use based on direction and
X     * speed.  Also determine index scaling for values of s, 0 <= s <= L,
X     * into the table.  Note that the scaling is performed relative to L,
X     * not LIC_Length(This).  Scaling relative to L means that the filter
X     * is effectively dilated to match the convolution length even when
X     * performing VariableLength convolution.
X     */
X    if (This->NeedIntegration)
X    LIC_BuildIntegralTables(This);
X    if (direction == LIC_FOREWARD)
X    itab = &This->PosIntegralTable[speed][0];
X    else
X    itab = &This->NegIntegralTable[speed][0];
X    is = (double)(LIC_INTEGRAL_LEN - 1) / L;
X
X    LoopCount = 0;
X
X    /*
X     * Only perform LIC if L is greater than zero.  Zero lengths
X     * can result from bad user input or magnitude based lengths.
X     */
X    if (L > 0)
X    {
X    REGISTER int    fi, fj, fk;    /* vector field indices */
X    REGISTER double x, y, z;    /* current cartesian location in the */
X                    /*   vector field */
X
X    fi = i;
X    fj = j;
X    fk = k;
X
X    x = i + 0.5;
X    y = This->NormalField.Yres - j - 0.5;
X    z = k + 0.5;
X
X    wp = 0.0;
X
X    /* Loop until we reach the end of the line integral */
X    do
X    {
X        REGISTER double t;        /* distance to nearest cell face */
X        REGISTER double fx, fy, fz;    /* vector field values */
X
X        /*
X         * Grab the current cell vector.
X         */
X
X        /* Get the field value in This pixel */
X        fx = INDEX_3D(This->NormalField, fi, fj, fk)[0];
X        fy = INDEX_3D(This->NormalField, fi, fj, fk)[1];
X        fz = INDEX_3D(This->NormalField, fi, fj, fk)[2];
X
X        /* bail out if the vector field goes to zero */
X        if (fx == 0.0 && fy == 0.0 && fz == 0.0)
X        break;
X
X        if (direction == LIC_BACKWARD)
X        {
X        fx = -fx;
X        fy = -fy;
X        fz = -fz;
X        }
X
X        /*
X         * Compute the intersection with the next cell along the line
X         * of the vector field.
X         */
X        {
X        REGISTER double tt;
X#        define TT(v) \
X        { \
X            tt = (v); \
X            if (tt < t) \
X            t = tt; \
X        }
X
X        if (fx < -SIN_PARALLEL)
X            t = (FLOOR(x) - x) / fx;        /* left face */
X        else if (fx > SIN_PARALLEL)
X            t = (CEIL(x) - x) / fx;        /* right face */
X        else
X            t = HUGE_VAL;
X
X        if (fy < -SIN_PARALLEL)
X            TT((FLOOR(y) - y) / fy)        /* bottom face */
X        else if (fy > SIN_PARALLEL)
X            TT((CEIL(y) - y) / fy)        /* top face */
X
X        if (fz < -SIN_PARALLEL)
X            TT((FLOOR(z) - z) / fz)        /* front face */
X        else if (fz > SIN_PARALLEL)
X            TT((CEIL(z) - z) / fz)        /* back face */
X
X#        undef TT
X        }
X
X        /* s and sp represent a monotonically moving convolution window */
X        s  = sp;
X        sp = sp + t;
X        t += ROUND_OFF;
X
X        /* Make sure we don't exceed the kernel width */
X        if (sp > L)
X        {
X        sp = L;
X        t  =  sp - s;
X        }
X
X        /*
X         * Grab the input pixel corresponding to the current cell and
X         * integrate its value over the convolution kernel from s to sp.
X         */
X        {
X#        if (PixelSize >= 3)
X            double rV, gV, bV;
X#        endif
X#        if (PixelSize == 4 || PixelSize == 1)
X            double aV;
X#        endif
X        {
X            REGISTER int ii, ij, ik;
X
X            /* toriodally wrap input image coordinates */
X            ii = fi;
X            ij = fj;
X            ik = fk;
X            WRAP(ii, This->InputImage.Xres);
X            WRAP(ij, This->InputImage.Yres);
X            WRAP(ik, This->InputImage.Zres);
X
X            /* Get the input image value for this cell */
X#            if (PixelSize >= 3)
X            rV = RED  (INDEX_3D(This->InputImage, ii, ij, ik));
X            gV = GREEN(INDEX_3D(This->InputImage, ii, ij, ik));
X            bV = BLUE (INDEX_3D(This->InputImage, ii, ij, ik));
X#            endif
X#            if (PixelSize == 4 || PixelSize == 1)
X            aV = ALPHA(INDEX_3D(This->InputImage, ii, ij, ik));
X#            endif
X        }
X
X        /* integrate over the convolution kernel between s and sp */
X        {
X            double          wt;
X            REGISTER double dw;
X
X            wt = itab[(int)(sp * is)];
X            dw = wt - wp;
X            wp = wt;
X
X#            if (PixelSize >= 3)
X            rSum  += (rV * dw);
X            gSum  += (gV * dw);
X            bSum  += (bV * dw);
X#            endif
X#            if (PixelSize == 4 || PixelSize == 1)
X            aSum  += (aV * dw);
X#            endif
X        }
X        }
X
X        /*
X         * March to the next cell.
X         */
X
X        LoopCount++;
X
X        /* Compute the cell we just stepped into */
X        x = x + fx*t;
X        y = y + fy*t;
X        z = z + fz*t;
X
X        /* break out of the loop if we step out of the field */
X        if (x < 0.0 || y < 0.0 || z < 0.0)
X            break;
X
X        fi = IFLOOR(x);
X        fj = This->NormalField.Yres - ICEIL(y);
X        fk = IFLOOR(z);
X
X        /* break out of the loop if we step out of the field */
X        if (   fi >= This->NormalField.Xres
X        || fj < 0
X        || fk >= This->NormalField.Zres)
X        break;
X
X        /*
X         * Loop until we reach the end or we think we've fallen into
X         * a singularity.
X         */
X    } while (sp < L && LoopCount <= 3*L);
X    }
X
X    if (LoopCount > 0 && L > 0)
X    {
X    *rIntegral = rSum;
X    *gIntegral = gSum;
X    *bIntegral = bSum;
X    *aIntegral = aSum;
X
X    /* Compute an integration normalization factor as function of sp */
X    *KernelArea = (This->NormalizationType == LIC_VARIABLE)
X        ? wp
X        : itab[LIC_INTEGRAL_LEN - 1];
X    }
X    else
X    {
X#    if (PixelSize >= 3)
X        *rIntegral = (This->DefaultRed == -1)
X        ? RED  (INDEX_3D(This->InputImage, i, j, k))
X        : (double)This->DefaultRed;
X        *gIntegral = (This->DefaultGreen == -1)
X        ? GREEN(INDEX_3D(This->InputImage, i, j, k))
X        : (double)This->DefaultGreen;
X        *bIntegral = (This->DefaultBlue == -1)
X        ? BLUE (INDEX_3D(This->InputImage, i, j, k))
X        : (double)This->DefaultBlue;
X#    else
X        *rIntegral = 0.0;
X        *gIntegral = 0.0;
X        *bIntegral = 0.0;
X#    endif
X#    if (PixelSize == 4 || PixelSize == 1)
X        *aIntegral = (This->DefaultAlpha == -1)
X        ? ALPHA(INDEX_3D(This->InputImage, i, j, k))
X        : (double)This->DefaultAlpha;
X#    else
X        *aIntegral = 0.0;
X#    endif
X
X    *KernelArea = 1;
X    }
X
X    /*
X     * Random bookkeeping for performance monitoring.
X     */
X    This->TotalLoopCount += LoopCount;
X    This->TotalLength    += sp;
X}
END_OF_FILE
  if test 10020 -ne `wc -c <'lic.1.2/liblic/Convolve3D.c'`; then
    echo shar: \"'lic.1.2/liblic/Convolve3D.c'\" unpacked with wrong size!
  fi
  # end of 'lic.1.2/liblic/Convolve3D.c'
fi
if test -f 'lic.1.2/liblic/LIC.3' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lic.1.2/liblic/LIC.3'\"
else
  echo shar: Extracting \"'lic.1.2/liblic/LIC.3'\" \(11842 characters\)
  sed "s/^X//" >'lic.1.2/liblic/LIC.3' <<'END_OF_FILE'
X.\" Copyright (c) 1993 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /d/sisal/a/casey/tmp/lic/liblic/RCS/LIC.3,v 1.5 1993/07/30 21:01:03 casey Exp $
X.TH LIC 3 \*(Dt
X.SH NAME
Xlic \- Line Integral Convolution library
X.SH SYNOPSIS
X.nf
X#include <lic.h>
X
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX('u
XLIC *\fBLIC_Create\fP(unsigned char    *\fIInputImage\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX(*'u
X    int        \fIiiXres\fP,
X    int        \fIiiYres\fP,
X    int        \fIiiZres\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX('u
X    float    *\fIInputField\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX(*'u
X    int        \fIifXres\fP,
X    int        \fIifYres\fP,
X    int        \fIifZres\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX('u
X    unsigned char    *\fIOutputImage\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX(*'u
X    LIC_Filter    \fIFilter\fP,
X    int        \fINormalizationType\fP,
X    int        \fINormalized\fP,
X    double    \fILength\fP,
X    double    \fIFrequency\fP,
X    int        \fIVariableLength\fP,
X    int        \fIVariableSpeed\fP,
X    int    \fIDefaultRed\fP,
X    int    \fIDefaultGreen\fP,
X    int    \fIDefaultBlue\fP,
X    int    \fIDefaultAlpha\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX'u
X    void        (*\fIUpdateUser\fP)(double),
X    void        (*\fIReportError\fP)(const char *))
X.DT
X
Xvoid \fBLIC_Destroy\fP(LIC *\fIThis\fP)
X
Xvoid \fBLIC_ChangeLength\fP(LIC *\fIThis\fP, double \fIlength\fP)
Xvoid \fBLIC_ChangeFrequency\fP(LIC *\fIThis\fP, double \fIfrequency\fP);
Xvoid \fBLIC_ChangePhase\fP(LIC *\fIThis\fP, double \fIphase\fP)
Xvoid \fBLIC_ChangeFilter\fP(LIC *\fIThis\fP, LIC_Filter \fIfilter\fP)
X
Xvoid \fBLIC_BuildIntegralTables\fP(LIC *\fIThis\fP)
Xdouble \fBLIC_Box\fP(LIC *\fIThis\fP, double \fIa\fP, double \fIb\fP, int \fIspeed\fP)
Xdouble \fBLIC_Ripple\fP(LIC *\fIThis\fP, double \fIa\fP, double \fIb\fP, int \fIspeed\fP)
Xdouble \fBLIC_Ramp\fP(LIC *\fIThis\fP, double \fIa\fP, double \fIb\fP, int \fIspeed\fP)
Xdouble \fBLIC_Select\fP(LIC *\fIThis\fP, double \fIa\fP, double \fIb\fP, int \fIspeed\fP)
X
Xvoid \fBLIC_ComputeImage\fP(LIC *\fIThis\fP)
X
X.ta \w'LIC *\fBLIC_Convolve2D\fP('u +\w'doubleXXX'u
Xvoid \fBLIC_Convolve2D\fP(LIC    *\fIThis\fP,
X.ta \w'LIC *\fBLIC_Convolve2D\fP('u +\w'doubleXXX*'u
X    int    \fIi\fP,
X    int    \fIj\fP,
X    int    \fIdirection\fP,
X.ta \w'LIC *\fBLIC_Convolve2D\fP('u +\w'doubleXXX'u
X    double    *\fIrIntegral\fP,
X    double    *\fIgIntegral\fP,
X    double    *\fIbIntegral\fP,
X    double    *\fIaIntegral\fP,
X    double    *\fIKernelArea\fP)
X.DT
X
X.ta \w'LIC *\fBLIC_Convolve3D\fP('u +\w'doubleXXX'u
Xvoid \fBLIC_Convolve3D\fP(LIC    *\fIThis\fP,
X.ta \w'LIC *\fBLIC_Convolve3D\fP('u +\w'doubleXXX*'u
X    int    \fIi\fP,
X    int    \fIj\fP,
X    int    \fIk\fP,
X    int    \fIdirection\fP,
X.ta \w'LIC *\fBLIC_Convolve3D\fP('u +\w'doubleXXX'u
X    double    *\fIrIntegral\fP,
X    double    *\fIgIntegral\fP,
X    double    *\fIbIntegral\fP,
X    double    *\fIaIntegral\fP,
X    double    *\fIKernelArea\fP)
X.DT
X
Xunsigned char *\fBLIC_InputImage\fP(LIC *\fIThis\fP)
Xfloat *\fBLIC_InputField\fP(LIC *\fIThis\fP)
Xunsigned char *\fBLIC_OutputImage\fP(LIC *\fIThis\fP)
X
Xdouble \fBLIC_Length\fP(LIC *\fIThis\fP)
Xdouble \fBLIC_Phase\fP(LIC *\fIThis\fP)
Xdouble \fBLIC_Frequency\fP(LIC *\fIThis\fP)
X
Xchar *\fBLIC_ConfiguredPixelType\fP(void)
Xint \fBLIC_ConfiguredPixelSize\fP(void)
X.fi
X.SH DESCRIPTION
X.B LIC
Xis the
X.I "Line Integral Convolution"
Xlibrary.  Line Integral Convolution is designed for vector field
Xvisualization but has applications in a number of other domains including
Ximage processing and special effects.
X.PP
XVectors are visualized by convolving an input image along vector
Xstream lines in an input vector field.  The result is an output image that
Xlooks like the input image, but blurred in the directions of the
Xvector field.
X.PP
XThe convolution is performed for each vector field element as
Xfollows: a parametric curve in the vector field is created by
Xlocally following the vector field forward and backward for some
Xdistance,
X.IR L .
XThe parametric curve is laid over the corresponding
Xinput image pixels.  This yields a pixel value function, \fIF\fP(\fIs\fP),
Xon the parametric curve.  \fIF\fP(\fIs\fP) is convolved with a filter kernel,
X\fIk\fP(\fIs\fP), to produce the Line Integral Convolution output:
X.PP
X.RS
Xintegral { \fIF\fP(\fIs\fP) * \fIk\fP(\fIs\fP) \fIds\fP }
X.RE
X.PP
XThe convolution sum is usually normalized by the area of the convolution
Xfilter in order to maintain the average brightness levels of the input
Ximage:
X.PP
X.RS
Xintegral { \fIF\fP(\fIs\fP) * \fIk\fP(\fIs\fP) \fIds\fP }
X/ integral { \fIk\fP(\fIs\fP) \fIds\fP }
X.RE
X.PP
XDepending on the shape of the filter kernel, the input image, the
Xinput vector field and several control parameters, a wide variety of
Xresults can be obtained.  These can range from the look of hair
Xfollowing vector field lines to melting surfaces to artificial motion
Xblur to periodic motion animations.
X.PP
XFor an in depth description of Line Integral Convolution see the paper
X.I "Imaging vector Fields Using Line Integral Convolution"
Xby Brian Cabral and Casey Leedom in the 1993 SIGGRAPH proceedings.
X.PP
XAll following information refers to the implementation of
XLine Integral Convolution in this software package.  This manual page
Xcorresponds to version 1.2 of the
X.B LIC
Xlibrary.
X.PP
XThe library software is object oriented in flavor (but is implemented
Xin ANSI C).  The general pattern of usage is to create a LIC object instance
Xvia
X.BR LIC_Create (3),
Xto modify various features of the instance via methods described in
X.BR LIC_Modify (3)
Xand then to call
X.BR LIC_ComputeImage (3)
Xto have the Line Integral Convolution performed.  When all is said and
Xdone, a call to
X.BR LIC_Destroy (3)
Xwill free up any resources used by the LIC instance.
X.PP
XFor more detailed information, see the manual pages for the individual
Xmethods.
X.SH COMPATIBILITY
XThis is experimental software.  In general, it is not compatible with
Xany other software system.  However, there is an AVS coroutine module
Xavailable which is compatible with other AVS modules.
X.PP
XSince the software is not part of the stock system software, some
Xeffort will probably be necessary to use it.  Typically this will
Xentail compiling your source with flags something like
X.RI -I/ usr / local / include
Xand linking your program with flags
X.RI -L/ usr / local / lib
Xand
X.RI -l lic .
XInstallations will differ from machine to machine and some installations
Xmay not require anything special to access the
X.B LIC
Xsoftware.
X.SH PORTABILITY
XThis software has been written to conform to ANSI C as
Xdefined in
X.I "ANSI X3.159-1989"
Xand
XPOSIX 1003.1 as defined in
X.IR "IEEE Std 1003.1-1990" .
XEvery effort has been made to make the software portable under those
Xguidelines.  There has been no effort whatsoever to make the software
Xusable under the obsolete K&R C definition.  C++ compatibility is
Xbelieved to be working, but has not been tested.
X.PP
XAs of this writing, the
X.B LIC
Xsoftware has been ported to DEC Alphas running OSF1, HP Snakes running
XHP-UX 8.07, IBM RS/6000s running AIX 3.2, SGI R3000/R4000s running
XIRIX 4.0.5 and Sun Sparcs running SunOS 4.1.1.
X.SH "RETURN VALUES"
XSee manual pages for individual functions and commands for details on
Xreturn values.
X.SH ERRORS
XSee manual pages for individual methods and commands for details on
Xerror handling.
X.SH "SEE ALSO"
X.BR lic (1),
X.BR LIC_ComputeImage (3),
X.BR LIC_Convolve (3),
X.BR LIC_Create (3),
X.BR LIC_Destroy (3),
X.BR LIC_Filters (3),
X.BR LIC_Modify (3),
X.BR LIC_Query (3),
XAVS coroutine module
X.B LIC
X.PP
X.I "Imaging Vector Fields Using Line Integral Convolution"
Xby Brian Cabral and Casey Leedom in the SIGGRAPH '93 proceedings.
X.SH BUGS
XPixel types and sizes are configured into the LIC software at compile time.
XOnly single precision vector field ordinate values are supported.  These should
Xboth be handled dynamically at run time.
X.PP
XThere are too many parameters to
X.BR LIC_Create .
XThere are also simultaneously too few and too many \fBLIC_Change\fP\fIFoo\fP
Xroutines.  There are too few because we really want to expose all the LIC
Xknobs to the user, but there are too many because they're proliferating like
Xrabbits.  Probably something more along the lines of
X.B XtVaSetArgs
Xis what we really want.
X.SH STANDARDS
XThis is unsupported, non-standard software.  It is not the subject of any
Xstandards effort.
X.SH COPYRIGHT
XCopyright (c) 1993 The Regents of the University of California.
XAll rights reserved.
X.PP
XRedistribution and use in source and binary forms, with or without
Xmodification, are permitted provided that the following conditions
Xare met:
X.TP 4
X1.
XRedistributions of source code must retain the above copyright
Xnotice, this list of conditions and the following disclaimer.
X.TP 4
X2.
XRedistributions in binary form must reproduce the above copyright
Xnotice, this list of conditions and the following disclaimer in the
Xdocumentation and/or other materials provided with the distribution.
X.TP 4
X3.
XAll advertising materials mentioning features or use of this software
Xmust display the following acknowledgement:
X.PP
X.RS 8
XThis product includes software developed by the University of
XCalifornia, Lawrence Livermore National Laboratory and its
Xcontributors.
X.RE
X.TP 4
X4.
XNeither the name of the University nor the names of its contributors
Xmay be used to endorse or promote products derived from this software
Xwithout specific prior written permission.
X.PP
XTHIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
XANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
XIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
XARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
XFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
XDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
XOR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
XHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
XLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
XOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
XSUCH DAMAGE.
END_OF_FILE
  if test 11842 -ne `wc -c <'lic.1.2/liblic/LIC.3'`; then
    echo shar: \"'lic.1.2/liblic/LIC.3'\" unpacked with wrong size!
  fi
  # end of 'lic.1.2/liblic/LIC.3'
fi
if test -f 'lic.1.2/liblic/LIC_Create.3' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lic.1.2/liblic/LIC_Create.3'\"
else
  echo shar: Extracting \"'lic.1.2/liblic/LIC_Create.3'\" \(11049 characters\)
  sed "s/^X//" >'lic.1.2/liblic/LIC_Create.3' <<'END_OF_FILE'
X.\" Copyright (c) 1993 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /d/sisal/a/casey/tmp/lic/liblic/RCS/LIC_Create.3,v 1.6 1993/07/30 20:00:49 casey Exp $
X.TH LIC_CREATE 3 \*(Dt
X.SH NAME
XLIC_Create \- create Line Integral Convolution object instance
X.SH SYNOPSIS
X.nf
X#include <lic.h>
X
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX('u
XLIC *\fBLIC_Create\fP(unsigned char    *\fIInputImage\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX(*'u
X    int        \fIiiXres\fP,
X    int        \fIiiYres\fP,
X    int        \fIiiZres\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX('u
X    float    *\fIInputField\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX(*'u
X    int        \fIifXres\fP,
X    int        \fIifYres\fP,
X    int        \fIifZres\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX('u
X    unsigned char    *\fIOutputImage\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX(*'u
X    LIC_Filter    \fIFilter\fP,
X    int        \fINormalizationType\fP,
X    int        \fINormalized\fP,
X    double    \fILength\fP,
X    double    \fIFrequency\fP,
X    int        \fIVariableLength\fP,
X    int        \fIVariableSpeed\fP,
X    int    \fIDefaultRed\fP,
X    int    \fIDefaultGreen\fP,
X    int    \fIDefaultBlue\fP,
X    int    \fIDefaultAlpha\fP,
X.ta \w'LIC *\fBLIC_Create\fP('u +\w'unsigned charXXX'u
X    void        (*\fIUpdateUser\fP)(double \fIpercent-complete\fP),
X    void        (*\fIReportError\fP)(const char *\fImessage\fP))
X.DT
X.fi
X.SH DESCRIPTION
X.if t .ds pi \(*p
X.if n .ds pi Pi
X.B LIC_Create
Xconstructs an instance of a LIC object.
X.PP
X.I InputImage
Xis the input image to be convolved,
X.I InputField
Xis the input vector field which controls the directional convolution and
X.I OutputImage
Xis the output image where Line Integral Convolution results will be placed.
X.IR iiXres ,
X.I iiYres
Xand
X.I iiZres
Xare the X, Y and Z sizes of
X.IR InputImage .
X.IR ifXres ,
X.I ifYres
Xand
X.I ifZres
Xare the X, Y and Z sizes of
X.I InputField
Xand
X.IR OutputImage .
XIf
X.I InputImage
Xis smaller than
X.I InputField
Xin some dimension, references to
X.I InputImage
Xpixels corresponding to
X.I InputField
Xcells will be wrapped toriodally.
XIf
X.B NULL
Xis passed for
X.IR OutputImage ,
X.B LIC_Create
Xwill automatically allocate space for it.
X.PP
XThe input and output images and input vector field are stored as raw binary
Xrow major arrays.
X.PP
X.I InputImage
Xand
X.I OutputImage
Xare arrays of pixels.  Each pixel is 1 to 4 bytes and must match
Xthe pixel size configured into the LIC library when it was compiled (see
X.B LIC_ConfiguredPixelSize
Xin the
X.B LIC_Query
Xmanual page).
X.PP
X.I InputField
Xis an array of single precision floating point vectors. Each vector
Xis of rank equal to the dimension of the data, 2 for two-dimensional
Xfields and 3 for three-dimensional fields.  The vectors are stored as
Xtwo- and three-tuples, respectively, ordered as x-ordinate, y-ordinate
Xand, if applicable, z-ordinate.
X.PP
X.I OutputImage
Xis created by
X.BR lic .
XThe x-y-z size is equal to that of
X.IR InputField .
X.PP
X.I Filter
Xmust be a pointer to a LIC_Filter type function:
X.PP
X.RS
X.nf
Xdouble \fIFilter\fP(LIC *\fIThis\fP, double \fIa\fP, double \fIb\fP, int \fIspeed\fP)
X.fi
X.RE
X.PP
X.I Filter
Xshould return the integral of the filter kernel between
X.I a
Xand
X.IR b .
X.I speed
Xspecifies the speed with respect to phase shift animation that
X.I Filter
Xshould use for its filter kernel.
X.I speed
Xis used to implement the variable speed option (though many filters ignore
Xthis parameter).
X.PP
XThe following filters are supplied with the LIC library:
X.PP
X.RS
X.nf
Xdouble \fBLIC_Box\fP(LIC *\fIThis\fP, double \fIa\fP, double \fIb\fP, int \fIspeed\fP)
Xdouble \fBLIC_Ripple\fP(LIC *\fIThis\fP, double \fIa\fP, double \fIb\fP, int \fIspeed\fP)
Xdouble \fBLIC_Ramp\fP(LIC *\fIThis\fP, double \fIa\fP, double \fIb\fP, int \fIspeed\fP)
Xdouble \fBLIC_Select\fP(LIC *\fIThis\fP, double \fIa\fP, double \fIb\fP, int \fIspeed\fP)
X.fi
X.RE
X.PP
XThey implement a box filter, a Hanning windowed Hanning ripple filter,
Xa ramp filter and a pixel selection filter, respectively.  See
X.BR LIC_Filters (3)
Xfor more information on LIC filters and the integration process.
X.PP
X.I NormalizationType
Xspecifies the type of normalization to be used:
X.B LIC_FIXED
Xor
X.BR LIC_VARIABLE .
XWith fixed normalization, output image pixels will be attenuated near
Xinput vector field singularities and edges of the input field where
Xvectors are not parallel to the edges.  With variable normalization,
Xoutput image pixels will maintain an even brightness level (relative
Xto the input image pixels they are summed from).
X.PP
X.I Normalized
Xspecifies that the input vector field is normalized: all vectors have
Xmagnitude 1 or 0.  If the vector field is not normalized, a separate
Xnormalized copy will be constructed for use in the convolution
Xmethods.  This may affect the ability to handle large problems because
Xof memory constraints.  If this becomes a problem, you may want to
Xconsider pre-normalizing the vector field.  However, this isn't an
Xoption if you want to do variable length or variable speed convolution
Xsince the vector magnitudes are used to control the length and speed
Xvariations (see variable length and variable speed documentation
Xbelow).
X.PP
X.I Length
Xspecifies the length of the filter kernel.  The filter kernel will actually be
X.RI 2* Length ,
Xextending from
X.RI - Length
Xto
X.RI + Length .
XIt is an error to specify a
X.I length
Xless than
X.BR 0 .
X.PP
X.I Frequency
Xspecifies the frequency of the filter kernel.
X.I Frequency
Xis interpreted as the number of cycles of the filter kernel over the domain
X.RB - \*(pi
Xto
X.BR \*(pi .
X(See
X.B LIC_ChangePhase
Xin the
X.BR LIC_Modify (3)
Xmanual page for a description of how to change the phase of the filter
Xkernel.)
X.I Frequency
Xis scaled to the length of the filter kernel.  Thus, a
X.I Frequency
Xof 2 will cause two repetitions of the filter kernel across the domain
X.RI - Length
Xto
X.RI + Length .
X.I Frequency
Xmust be non-zero and positive.
XCurrently, the only filter supplied with the LIC library that uses this
Xoption is
X.BR LIC_Ripple .
X.PP
X.I VariableLength
Xis a boolean flag which, when TRUE, specifies that variable length filtering
Xshould be performed.  The LIC filter length for each vector \fIv\fP will
Xvary from 0 to
X.I Length
Xbased on the vector's magnitude.  This magnitude scaling is performed
Xby finding the maximum magnitude vector in the input vector field,
X\fImax_v\fP, and then using a filter length equal to
X\fILength\fP  * ||\fIv\fP|| / ||\fImax_v\fP||.
XThe filter will be dilated to match the length of the convolution.
XThis prevents any visual artifacts which might occur because of abrupt
Xfilter truncation if the filter were not dilated.
X.PP
X.I VariableSpeed
Xis a boolean flag which, when TRUE, specifies that variable
X.I speed
Xfiltering should be performed.
XHigh magnitude regions of the vector field will use high
X.I speed
Xversions of the filter.  These higher speeds variations are typically
Xphase multiplied versions of the base phase and are used in periodic
Xmotion animations to give the appearance of higher speed in higher magnitude
Xregions of the vector field.
XHowever, it is up to each filter to implement its own interpretation of
X.IR speed .
X.PP
XFor the ripple filter, the speed variations use a different phase for each
Xvector
X.I v
Xbased on its magnitude.  These phase variations vary from
X.I Phase
Xto 3 *
X.IR Phase .
X.PP
XVariable speed filtering is currently only implemented by the ripple
Xfilter (it doesn't have any effect on the box filter and is of dubious
Xvalue for the ramp filter.)
X.PP
X.IR DefaultRed ,
X.IR DefaultGreen ,
X.I DefaultBlue
Xand
X.I DefaultAlpha
Xdefine the default red, green, blue and alpha pixel values to use to represent
Xzero magnitude vectors.  A value of
X.B -1
Xspecifies that the underlaying input image pixel value should be used.
XFor
X.B MONOCHROME
Ximages,
X.I default-alpha
Xcontrols the default pixel value.
X.PP
X.I UpdateUser
Xshould be
X.B NULL
Xor a pointer to user supplied function.  If
X.RB non- NULL ,
Xit will be called by
X.B LIC_ComputeImage
Xfrom time to time to report computation progress with a
X.I percent-complete
Xvalue between 0.0 and 100.0.
X.PP
X.B ReportError
Xshould be
X.B NULL
Xor a pointer to user supplied function.  If
X.RB non- NULL ,
Xit will be called by the LIC library routines to report various errors.
XTypically these will be to report memory allocation failure or errors
Xin user supplied parameters.  A
X.B NULL
Xterminated character string value,
X.IR message ,
Xwill be passed to
X.BR ReportError .
X.I message
Xwill not contain a trailing newline.
X.SH "RETURN VALUES"
X.B NULL
Xwill be returned if
X.B LIC_Create
Xis unable to allocate memory for the new LIC instance, otherwise a pointer
Xto the new instance is returned.
X.SH ERRORS
XLIC_Create: Unable to allocate memory for LIC instance variable
X.PP
XLIC_Create: Unable to allocate memory for normalized input vector field
X.PP
XLIC_Create: Unable to allocate memory for output image
X.SH "SEE ALSO"
X.BR LIC (3),
X.BR LIC_Destroy (3),
X.BR LIC_Modify (3),
X.BR LIC_Query (3)
X.SH BUGS
XIf a negative
X.I Length
Xis specified, a length of 0 will be used instead.
XIf a negative or zero
X.I Frequency
Xis specified, a frequency of 1e-6 will be used instead.  In both cases error
Xmessages should probably be output.
X.SH STANDARDS
XThis is unsupported, non-standard software.  It is not the subject of any
Xstandards effort.
END_OF_FILE
  if test 11049 -ne `wc -c <'lic.1.2/liblic/LIC_Create.3'`; then
    echo shar: \"'lic.1.2/liblic/LIC_Create.3'\" unpacked with wrong size!
  fi
  # end of 'lic.1.2/liblic/LIC_Create.3'
fi
if test -f 'lic.1.2/lic/lic.1' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lic.1.2/lic/lic.1'\"
else
  echo shar: Extracting \"'lic.1.2/lic/lic.1'\" \(10950 characters\)
  sed "s/^X//" >'lic.1.2/lic/lic.1' <<'END_OF_FILE'
X.\" Copyright (c) 1993 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /d/sisal/a/casey/tmp/lic/lic/RCS/lic.1,v 1.10 1993/08/10 23:26:52 casey Exp $
X.TH LIC 1 \*(Dt
X.SH NAME
Xlic \- Line Integral Convolution processor
X.SH SYNOPSIS
X.nf
X\fBlic\fP [\fIoptions\fP] \fIinput-image\fP \fIinput-vector-field\fP \fIoutput-image\fP
X.fi
X.SH DESCRIPTION
X.if t .ds pi \(*p
X.if n .ds pi Pi
X.B lic
Xis a command line interface to the
X.I "Line Integral Convolution"
Xlibrary.  Line Integral Convolution was designed for vector field
Xvisualization but has applications in a number of other domains
Xincluding image processing, special effects and artistic rendering.
XFor an in depth description of Line Integral Convolution, see
X.BR LIC (3).
X.PP
XThe input and output files are stored as raw binary files without any
Xheaders.  The files are organized as sequential row major (C-style)
Xarrays.
X.PP
XThe
X.I input-image
Xand
X.I output-image
Xfiles are arrays of pixels.  Each pixel is 1 to 4 bytes and must match
Xthe pixel size configured into
X.B lic
Xwhen it was compiled (see
X.B LIC_ConfiguredPixelSize
Xin the
X.B LIC_Query
Xmanual page).
X.PP
XThe
X.I input-vector-field
Xfile is an array of single precision floating point vectors. Each vector
Xis of rank equal to the dimension of the data, 2 for two-dimensional
Xfields and 3 for three-dimensional fields.  The vectors are stored as
Xtwo- and three-tuples, respectively, ordered as x-coordinate, y-coordinate
Xand, if applicable, z-coordinate.
X.PP
XThe
X.I output-image
Xis created by
X.BR lic .
XThe x-y-z size of the file is equal to that of the
X.IR input-vector-field .
XAs a safety feature
X.B lic
Xwill never overwrite an existing file.
X.PP
XOptions available are:
X.PP
X\fB\-x\fP \fIx-extent\fP (required parameter, \fBno default\fP)
X.br
X\fB\-y\fP \fIy-extent\fP (required parameter, \fBno default\fP)
X.br
X\fB\-z\fP \fIz-extent\fP (default \fB1\fP)
X.RS 5
XSets the
X.IR x ,
X.I y
Xand
X.I z
Xsize of
X.IR input-vector-field .
XThe
X.B \-x
Xand
X.B \-y
Xoptions are not optional.  They must be provided.  The
X.B \-z
Xis optional and defaults to the value of
X.BR 1 .
X.RE
X.PP
X\fB\-i\fP \fIi-extent\fP (default \fIx-extent\fP)
X.br
X\fB\-j\fP \fIj-extent\fP (default \fIy-extent\fP)
X.br
X\fB\-k\fP \fIk-extent\fP (default \fIz-extent\fP)
X.RS 5
XSets the
X.IR x ,
X.I y
Xand
X.I z
Xsize of
X.IR input-image .
XIf not specified, they will default to the same values specified for
X.IR input-vector-field .
XThe sizes for
X.I input-image
Xand
X.I input-vector-field
Xneed not match in any way.  If
X.I input-image
Xis smaller than
X.I input-vector-field
Xin some dimension, references to
X.I input-image
Xpixels corresponding to
X.I input-vector-field
Xcells will be wrapped toriodally.
X.RE
X.TP 5
X\fB\-f\fP \fIfilter\fP (default \fBbox\fP)
XSpecifies the filter shape to use for the LIC.
XAvailable filters are:
X.PP
X.RS
X.TP 8
X.B box
XSpecifies a constant box shape filter: \fIk\fP(\fIs\fP) =  1.
XAll input image pixels along LIC paths will be given equal weight.
X.TP 8
X.B ripple
XSpecifies a phase shifted Hanning ripple function, windowed by a Hanning
Xfunction: \fIk\fP(\fIs\fP) = (cos(\fId\fP*\fIs\fP + \fIphase\fP) + 1)/2
X* (cos(\fIc\fP*\fIs\fP) + 1)/2.
XWhere
X.I d
Xand
X.I c
Xare the dilation constants for the ripple and window functions,
Xrespectively, and
X.I phase
Xis the phase shift of the ripple function.
X.I d
Xand
X.I c
Xcontrol the number of cycles of the Hanning functions over the filter kernel
Xfrom
X.RI - L
Xto
X.RI + L .
X.I d
Xis controlled by the
X.B \-d
Xoption and
X.I c
Xis always equal to
X.BR 1 .
X.I phase
Xis controlled by the
X.B \-p
Xoption.
X.TP 8
X.B ramp
XSpecifies a ramp shape filter whose value is
X.B 0
Xat
X.RI - L
Xand
X.B 1
Xat
X.RI + L :
X\fIk\fP(\fIs\fP) = (\fIs\fP + \fIL\fP) / 2\fIL\fP.
X.TP 8
X.B select
XSpecifies a filter which is used to select an approximately one pixel
Xwide window near the end of the advected streamline and place it at
Xthe advection starting pixel.  This is achieved using a narrow
XGaussian filter and placing this filter near the end of the advected
Xstreamline.  This can be used to produce a warp of the input image.
X.RE
X.TP 5
X\fB\-n\fP \fInormalization\fP (default \fBvariable\fP)
XSpecifies the type of normalization to be used:
X.B fixed
Xor
X.BR variable .
XWith
X.B fixed
Xnormalization, output image pixels will be attenuated near input vector
Xfield singularities and edges of the input vector field where vectors are not
Xparallel to the edges.
XWith
X.B variable
Xnormalization, output image pixels will maintain an even brightness level
X(relative to the input image pixels they are summed from).
X.TP 5
X\fB\-N\fP
XSpecifies that the input vector field is normalized: all vectors have
Xmagnitude 1 or 0.  If the vector field is not normalized, a separate
Xnormalized copy will be constructed for use in the convolution
Xmethods.  This may affect the ability to handle large problems because
Xof memory constraints.  If this becomes a problem, you may want to
Xconsider pre-normalizing the vector field.  However, this isn't an
Xoption if you want to do variable length or variable speed convolution
Xsince the vector magnitudes are used to control the length and speed
Xvariations (see variable length and variable speed documentation
Xbelow).
X.TP 5
X\fB\-l\fP \fIfilter-length\fP (default \fB10.0\fP)
XSpecifies the length,
X.IR L ,
Xof the filter kernel.  The length of the filter kernel will actually be
X.RI 2* L ,
Xextending from
X.RI - L
Xto
X.RI + L .
X.PP
X\fB\-d\fP \fIfilter-frequency\fP (default \fB3.0\fP)
X.br
X\fB\-p\fP \fIfilter-phase\fP (default \fB0.0\fP)
X.RS 5
XSpecifies the frequency and phase of the filter kernel.
X.I filter-frequency
Xis interpreted as the number of cycles of the filter kernel over the domain
X.RB - \*(pi
Xto
X.BR \*(pi .
X.I filter-phase
Xis interpreted as the phase offset of the filter kernel in the same domain.
XBoth
X.I filter-frequency
Xand
X.I filter-phase
Xare scaled to the length of the filter kernel.  Thus, a
X.I filter-frequency
Xof 2 will cause two repetitions of the filter kernel across the domain
X.RI - L
Xto
X.RI + L .
XCurrently, only the
X.B ripple
Xfilter uses these options.
X.RE
X.TP 5
X\fB\-L\fP
XSpecifies that variable length filtering should be performed.  The LIC
Xfilter length for each vector \fIv\fP will vary from 0 to
X.I L
Xbased on the vector's magnitude.  This magnitude scaling is performed
Xby finding the maximum magnitude vector in the input vector field,
X\fImax_v\fP, and then using a filter length equal to
X\fIL\fP  * ||\fIv\fP|| / ||\fImax_v\fP||.
XThe filter will be dilated to match the length of the convolution.
XThis prevents any visual artifacts which might occur because of abrupt
Xfilter truncation if the filter were not dilated.
X.TP 5
X\fB\-S\fP
XSpecifies that variable
X.I speed
Xfiltering should be performed.
XHigh magnitude regions of the vector field will use high
X.I speed
Xversions of the filter.  These higher speeds variations are typically
Xfrequency scaled versions of the base filter and are used in periodic
Xmotion animations to give the appearance of higher speed in higher magnitude
Xregions of the vector field.
XHowever, it is up to each filter to implement its own interpretation of
X.IR speed .
X.PP
XFor the
X.B ripple
Xfilter, the speed variations use a different frequency for each vector
X.I v
Xbased on its magnitude.  These frequency variations vary from 6 *
X.I filter-frequency
Xfor zero magnitude vectors to
X.I filter-frequency
Xfor maximum magnitude vectors.  Variable speed filtering is currently only
Ximplemented by the
X.B ripple
Xfilter (it doesn't have any effect on the
X.B box
Xfilter and is of dubious value for the
X.B ramp
Xfilter.)
X.PP
X\fB\-r\fP \fIdefault-red\fP (default \fB-1\fP)
X.br
X\fB\-g\fP \fIdefault-green\fP (default \fB-1\fP)
X.br
X\fB\-b\fP \fIdefault-blue\fP (default \fB-1\fP)
X.br
X\fB\-a\fP \fIdefault-alpha\fP (default \fB-1\fP)
X.RS 5
XDefine the default red, green, blue and alpha pixel values to use to represent
Xzero magnitude vectors.  A value of
X.B -1
Xspecifies that the underlaying input image pixel value should be used.
XFor
X.B MONOCHROME
Ximages,
X.I default-alpha
Xcontrols the default pixel value.
X.RE
X.TP 5
X\fB\-v\fP
XCauses verbose performance information to be output on standard output.
XDuring the execution of the convolution, a message will be printed
Xperiodically and after completion of the convolution, overall performance
Xstatistics figures will be printed.
X.TP 5
X\fB\-V\fP
XCauses configuration information about the LIC library version to be printed.
XCurrently the size of pixels and their types,
X.BR RGB ,
X.BR ABGR ,
X.BR MONOCHROME ,
Xetc. are controlled by library compile-time definitions.
X.SH ERRORS
XObjections to bad command line arguments, missing files, wrong size files,
Xoutput files already existing, etc.  Additionally, complaints about not
Xbeing able to map files into memory
X.RB ( mmap
Xversion) or inability to allocate memory
X.RB ( malloc
Xversion).
X.SH "SEE ALSO"
X.BR LIC (3),
X.BR LIC_Filters (3)
X.SH BUGS
XPixel types and sizes are configured into the LIC software at compile time.
XOnly single precision vector field ordinate values are supported.  These should
Xboth be handled dynamically at run time.
X.SH STANDARDS
XThis is unsupported, non-standard software.  It is not the subject of any
Xstandards effort.
END_OF_FILE
  if test 10950 -ne `wc -c <'lic.1.2/lic/lic.1'`; then
    echo shar: \"'lic.1.2/lic/lic.1'\" unpacked with wrong size!
  fi
  # end of 'lic.1.2/lic/lic.1'
fi
echo shar: End of archive 7 \(of 10\).
cp /dev/null ark7isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 10 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still must unpack the following archives:
    echo "        " ${MISSING}
fi
exit 0
exit 0 # Just in case...