/*====================================================================*

 -  Copyright (C) 2001 Leptonica.  All rights reserved.

 -

 -  Redistribution and use in source and binary forms, with or without

 -  modification, are permitted provided that the following conditions

 -  are met:

 -  1. Redistributions of source code must retain the above copyright

 -     notice, this list of conditions and the following disclaimer.

 -  2. Redistributions in binary form must reproduce the above

 -     copyright notice, this list of conditions and the following

 -     disclaimer in the documentation and/or other materials

 -     provided with the distribution.

 -

 -  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

 -  ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

 -  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

 -  A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL ANY

 -  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

 -  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

 -  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

 -  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY

 -  OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

 -  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

 -  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 *====================================================================*/

/*!

 * \file morphseq.c

 * <pre>

 *

 *      Run a sequence of binary rasterop morphological operations

 *            PIX     *pixMorphSequence()

 *

 *      Run a sequence of binary composite rasterop morphological operations

 *            PIX     *pixMorphCompSequence()

 *

 *      Run a sequence of binary dwa morphological operations

 *            PIX     *pixMorphSequenceDwa()

 *

 *      Run a sequence of binary composite dwa morphological operations

 *            PIX     *pixMorphCompSequenceDwa()

 *

 *      Parser verifier for binary morphological operations

 *            l_int32  morphSequenceVerify()

 *

 *      Run a sequence of grayscale morphological operations

 *            PIX     *pixGrayMorphSequence()

 *

 *      Run a sequence of color morphological operations

 *            PIX     *pixColorMorphSequence()

 * </pre>

 */

#ifdef HAVE_CONFIG_H

#include <config_auto.h>

#endif  /* HAVE_CONFIG_H */

#include <string.h>

#include "allheaders.h"

/*-------------------------------------------------------------------------*

 *         Run a sequence of binary rasterop morphological operations      *

 *-------------------------------------------------------------------------*/

/*!

 * \brief   pixMorphSequence()

 *

 * \param[in]    pixs

 * \param[in]    sequence   string specifying sequence

 * \param[in]    dispsep    controls debug display results in the sequence:

 *                          0: no output

 *                          > 0: gives horizontal separation in pixels between

 *                               successive displays

 *                          < 0: pdf output; abs(dispsep) is used for naming

 * \return  pixd, or NULL on error

 *

 * <pre>

 * Notes:

 *      (1) This does rasterop morphology on binary images.

 *      (2) This runs a pipeline of operations; no branching is allowed.

 *      (3) This only uses brick Sels, which are created on the fly.

 *          In the future this will be generalized to extract Sels from

 *          a Sela by name.

 *      (4) A new image is always produced; the input image is not changed.

 *      (5) This contains an interpreter, allowing sequences to be

 *          generated and run.

 *      (6) The format of the sequence string is defined below.

 *      (7) In addition to morphological operations, rank order reduction

 *          and replicated expansion allow operations to take place

 *          downscaled by a power of 2.

 *      (8) Intermediate results can optionally be displayed.

 *      (9) Thanks to Dar-Shyang Lee, who had the idea for this and

 *          built the first implementation.

 *      (10) The sequence string is formatted as follows:

 *            ~ An arbitrary number of operations,  each separated

 *              by a '+' character.  White space is ignored.

 *            ~ Each operation begins with a case-independent character

 *              specifying the operation:

 *                 d or D  (dilation)

 *                 e or E  (erosion)

 *                 o or O  (opening)

 *                 c or C  (closing)

 *                 r or R  (rank binary reduction)

 *                 x or X  (replicative binary expansion)

 *                 b or B  (add a border of 0 pixels of this size)

 *            ~ The args to the morphological operations are bricks of hits,

 *              and are formatted as a.b, where a and b are horizontal and

 *              vertical dimensions, rsp.

 *            ~ The args to the reduction are a sequence of up to 4 integers,

 *              each from 1 to 4.

 *            ~ The arg to the expansion is a power of two, in the set

 *              {2, 4, 8, 16}.

 *      (11) An example valid sequence is:

 *               "b32 + o1.3 + C3.1 + r23 + e2.2 + D3.2 + X4"

 *           In this example, the following operation sequence is carried out:

 *             * b32: Add a 32 pixel border around the input image

 *             * o1.3: Opening with vert sel of length 3 (e.g., 1 x 3)

 *             * C3.1: Closing with horiz sel of length 3  (e.g., 3 x 1)

 *             * r23: Two successive 2x2 reductions with rank 2 in the first

 *                    and rank 3 in the second.  The result is a 4x reduced pix.

 *             * e2.2: Erosion with a 2x2 sel (origin will be at x,y: 0,0)

 *             * d3.2: Dilation with a 3x2 sel (origin will be at x,y: 1,0)

 *             * X4: 4x replicative expansion, back to original resolution

 *      (12) The safe closing is used.  However, if you implement a

 *           closing as separable dilations followed by separable erosions,

 *           it will not be safe.  For that situation, you need to add

 *           a sufficiently large border as the first operation in

 *           the sequence.  This will be removed automatically at the

 *           end.  There are two cautions:

 *              ~ When computing what is sufficient, remember that if

 *                reductions are carried out, the border is also reduced.

 *              ~ The border is removed at the end, so if a border is

 *                added at the beginning, the result must be at the

 *                same resolution as the input!

 * </pre>

 */

PIX *

pixMorphSequence(PIX         *pixs,

                 const char  *sequence,

                 l_int32      dispsep)

{

char    *rawop, *op;

char     fname[256];

l_int32  nops, i, j, nred, fact, w, h, x, border, pdfout;

l_int32  level[4];

PIX     *pix1, *pix2;

PIXA    *pixa;

SARRAY  *sa;

    if (!pixs)

        return (PIX *)ERROR_PTR("pixs not defined", __func__, NULL);

    if (!sequence)

        return (PIX *)ERROR_PTR("sequence not defined", __func__, NULL);

        /* Split sequence into individual operations */

    sa = sarrayCreate(0);

    sarraySplitString(sa, sequence, "+");

    nops = sarrayGetCount(sa);

    pdfout = (dispsep < 0) ? 1 : 0;

    if (!morphSequenceVerify(sa)) {

        sarrayDestroy(&sa);

        return (PIX *)ERROR_PTR("sequence not valid", __func__, NULL);

    }

        /* Parse and operate */

    pixa = NULL;

    if (pdfout) {

        pixa = pixaCreate(0);

        pixaAddPix(pixa, pixs, L_CLONE);

    }

    border = 0;

    pix1 = pixCopy(NULL, pixs);

    pix2 = NULL;

    x = 0;

    for (i = 0; i < nops; i++) {

        rawop = sarrayGetString(sa, i, L_NOCOPY);

        op = stringRemoveChars(rawop, " \n\t");

        switch (op[0])

        {

        case 'd':

        case 'D':

            sscanf(&op[1], "%d.%d", &w, &h);

            pix2 = pixDilateBrick(NULL, pix1, w, h);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'e':

        case 'E':

            sscanf(&op[1], "%d.%d", &w, &h);

            pix2 = pixErodeBrick(NULL, pix1, w, h);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'o':

        case 'O':

            sscanf(&op[1], "%d.%d", &w, &h);

            pixOpenBrick(pix1, pix1, w, h);

            break;

        case 'c':

        case 'C':

            sscanf(&op[1], "%d.%d", &w, &h);

            pixCloseSafeBrick(pix1, pix1, w, h);

            break;

        case 'r':

        case 'R':

            nred = strlen(op) - 1;

            for (j = 0; j < nred; j++)

                level[j] = op[j + 1] - '0';

            for (j = nred; j < 4; j++)

                level[j] = 0;

            pix2 = pixReduceRankBinaryCascade(pix1, level[0], level[1],

                                               level[2], level[3]);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'x':

        case 'X':

            sscanf(&op[1], "%d", &fact);

            pix2 = pixExpandReplicate(pix1, fact);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'b':

        case 'B':

            sscanf(&op[1], "%d", &border);

            pix2 = pixAddBorder(pix1, border, 0);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        default:

            /* All invalid ops are caught in the first pass */

            break;

        }

        LEPT_FREE(op);

            /* Debug output */

        if (dispsep > 0) {

            pixDisplay(pix1, x, 0);

            x += dispsep;

        }

        if (pdfout)

            pixaAddPix(pixa, pix1, L_COPY);

    }

    if (border > 0) {

        pix2 = pixRemoveBorder(pix1, border);

        pixSwapAndDestroy(&pix1, &pix2);

    }

    if (pdfout) {

        snprintf(fname, sizeof(fname), "/tmp/lept/seq_output_%d.pdf",

                 L_ABS(dispsep));

        pixaConvertToPdf(pixa, 0, 1.0, L_FLATE_ENCODE, 0, fname, fname);

        pixaDestroy(&pixa);

    }

    sarrayDestroy(&sa);

    return pix1;

}

/*-------------------------------------------------------------------------*

 *   Run a sequence of binary composite rasterop morphological operations  *

 *-------------------------------------------------------------------------*/

/*!

 * \brief   pixMorphCompSequence()

 *

 * \param[in]    pixs

 * \param[in]    sequence   string specifying sequence

 * \param[in]    dispsep    controls debug display of results in the sequence:

 *                          0: no output

 *                          > 0: gives horizontal separation in pixels between

 *                               successive displays

 *                          < 0: pdf output; abs(dispsep) is used for naming

 * \return  pixd, or NULL on error

 *

 * <pre>

 * Notes:

 *      (1) This does rasterop morphology on binary images, using composite

 *          operations for extra speed on large Sels.

 *      (2) Safe closing is used atomically.  However, if you implement a

 *          closing as a sequence with a dilation followed by an

 *          erosion, it will not be safe, and to ensure that you have

 *          no boundary effects you must add a border in advance and

 *          remove it at the end.

 *      (3) For other usage details, see the notes for pixMorphSequence().

 *      (4) The sequence string is formatted as follows:

 *            ~ An arbitrary number of operations,  each separated

 *              by a '+' character.  White space is ignored.

 *            ~ Each operation begins with a case-independent character

 *              specifying the operation:

 *                 d or D  (dilation)

 *                 e or E  (erosion)

 *                 o or O  (opening)

 *                 c or C  (closing)

 *                 r or R  (rank binary reduction)

 *                 x or X  (replicative binary expansion)

 *                 b or B  (add a border of 0 pixels of this size)

 *            ~ The args to the morphological operations are bricks of hits,

 *              and are formatted as a.b, where a and b are horizontal and

 *              vertical dimensions, rsp.

 *            ~ The args to the reduction are a sequence of up to 4 integers,

 *              each from 1 to 4.

 *            ~ The arg to the expansion is a power of two, in the set

 *              {2, 4, 8, 16}.

 * </pre>

 */

PIX *

pixMorphCompSequence(PIX         *pixs,

                     const char  *sequence,

                     l_int32      dispsep)

{

char    *rawop, *op;

char     fname[256];

l_int32  nops, i, j, nred, fact, w, h, x, border, pdfout;

l_int32  level[4];

PIX     *pix1, *pix2;

PIXA    *pixa;

SARRAY  *sa;

    if (!pixs)

        return (PIX *)ERROR_PTR("pixs not defined", __func__, NULL);

    if (!sequence)

        return (PIX *)ERROR_PTR("sequence not defined", __func__, NULL);

        /* Split sequence into individual operations */

    sa = sarrayCreate(0);

    sarraySplitString(sa, sequence, "+");

    nops = sarrayGetCount(sa);

    pdfout = (dispsep < 0) ? 1 : 0;

    if (!morphSequenceVerify(sa)) {

        sarrayDestroy(&sa);

        return (PIX *)ERROR_PTR("sequence not valid", __func__, NULL);

    }

        /* Parse and operate */

    pixa = NULL;

    if (pdfout) {

        pixa = pixaCreate(0);

        pixaAddPix(pixa, pixs, L_CLONE);

    }

    border = 0;

    pix1 = pixCopy(NULL, pixs);

    pix2 = NULL;

    x = 0;

    for (i = 0; i < nops; i++) {

        rawop = sarrayGetString(sa, i, L_NOCOPY);

        op = stringRemoveChars(rawop, " \n\t");

        switch (op[0])

        {

        case 'd':

        case 'D':

            sscanf(&op[1], "%d.%d", &w, &h);

            pix2 = pixDilateCompBrick(NULL, pix1, w, h);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'e':

        case 'E':

            sscanf(&op[1], "%d.%d", &w, &h);

            pix2 = pixErodeCompBrick(NULL, pix1, w, h);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'o':

        case 'O':

            sscanf(&op[1], "%d.%d", &w, &h);

            pixOpenCompBrick(pix1, pix1, w, h);

            break;

        case 'c':

        case 'C':

            sscanf(&op[1], "%d.%d", &w, &h);

            pixCloseSafeCompBrick(pix1, pix1, w, h);

            break;

        case 'r':

        case 'R':

            nred = strlen(op) - 1;

            for (j = 0; j < nred; j++)

                level[j] = op[j + 1] - '0';

            for (j = nred; j < 4; j++)

                level[j] = 0;

            pix2 = pixReduceRankBinaryCascade(pix1, level[0], level[1],

                                               level[2], level[3]);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'x':

        case 'X':

            sscanf(&op[1], "%d", &fact);

            pix2 = pixExpandReplicate(pix1, fact);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'b':

        case 'B':

            sscanf(&op[1], "%d", &border);

            pix2 = pixAddBorder(pix1, border, 0);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        default:

            /* All invalid ops are caught in the first pass */

            break;

        }

        LEPT_FREE(op);

            /* Debug output */

        if (dispsep > 0) {

            pixDisplay(pix1, x, 0);

            x += dispsep;

        }

        if (pdfout)

            pixaAddPix(pixa, pix1, L_COPY);

    }

    if (border > 0) {

        pix2 = pixRemoveBorder(pix1, border);

        pixSwapAndDestroy(&pix1, &pix2);

    }

    if (pdfout) {

        snprintf(fname, sizeof(fname), "/tmp/lept/seq_output_%d.pdf",

                 L_ABS(dispsep));

        pixaConvertToPdf(pixa, 0, 1.0, L_FLATE_ENCODE, 0, fname, fname);

        pixaDestroy(&pixa);

    }

    sarrayDestroy(&sa);

    return pix1;

}

/*-------------------------------------------------------------------------*

 *           Run a sequence of binary dwa morphological operations         *

 *-------------------------------------------------------------------------*/

/*!

 * \brief   pixMorphSequenceDwa()

 *

 * \param[in]    pixs

 * \param[in]    sequence   string specifying sequence

 * \param[in]    dispsep    controls debug display of results in the sequence:

 *                          0: no output

 *                          > 0: gives horizontal separation in pixels between

 *                               successive displays

 *                          < 0: pdf output; abs(dispsep) is used for naming

 * \return  pixd, or NULL on error

 *

 * <pre>

 * Notes:

 *      (1) This does dwa morphology on binary images.

 *      (2) This runs a pipeline of operations; no branching is allowed.

 *      (3) This only uses brick Sels that have been pre-compiled with

 *          dwa code.

 *      (4) A new image is always produced; the input image is not changed.

 *      (5) This contains an interpreter, allowing sequences to be

 *          generated and run.

 *      (6) See pixMorphSequence() for further information about usage.

 * </pre>

 */

PIX *

pixMorphSequenceDwa(PIX         *pixs,

                    const char  *sequence,

                    l_int32      dispsep)

{

char    *rawop, *op;

char     fname[256];

l_int32  nops, i, j, nred, fact, w, h, x, border, pdfout;

l_int32  level[4];

PIX     *pix1, *pix2;

PIXA    *pixa;

SARRAY  *sa;

    if (!pixs)

        return (PIX *)ERROR_PTR("pixs not defined", __func__, NULL);

    if (!sequence)

        return (PIX *)ERROR_PTR("sequence not defined", __func__, NULL);

        /* Split sequence into individual operations */

    sa = sarrayCreate(0);

    sarraySplitString(sa, sequence, "+");

    nops = sarrayGetCount(sa);

    pdfout = (dispsep < 0) ? 1 : 0;

    if (!morphSequenceVerify(sa)) {

        sarrayDestroy(&sa);

        return (PIX *)ERROR_PTR("sequence not valid", __func__, NULL);

    }

        /* Parse and operate */

    pixa = NULL;

    if (pdfout) {

        pixa = pixaCreate(0);

        pixaAddPix(pixa, pixs, L_CLONE);

    }

    border = 0;

    pix1 = pixCopy(NULL, pixs);

    pix2 = NULL;

    x = 0;

    for (i = 0; i < nops; i++) {

        rawop = sarrayGetString(sa, i, L_NOCOPY);

        op = stringRemoveChars(rawop, " \n\t");

        switch (op[0])

        {

        case 'd':

        case 'D':

            sscanf(&op[1], "%d.%d", &w, &h);

            pix2 = pixDilateBrickDwa(NULL, pix1, w, h);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'e':

        case 'E':

            sscanf(&op[1], "%d.%d", &w, &h);

            pix2 = pixErodeBrickDwa(NULL, pix1, w, h);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'o':

        case 'O':

            sscanf(&op[1], "%d.%d", &w, &h);

            pixOpenBrickDwa(pix1, pix1, w, h);

            break;

        case 'c':

        case 'C':

            sscanf(&op[1], "%d.%d", &w, &h);

            pixCloseBrickDwa(pix1, pix1, w, h);

            break;

        case 'r':

        case 'R':

            nred = strlen(op) - 1;

            for (j = 0; j < nred; j++)

                level[j] = op[j + 1] - '0';

            for (j = nred; j < 4; j++)

                level[j] = 0;

            pix2 = pixReduceRankBinaryCascade(pix1, level[0], level[1],

                                               level[2], level[3]);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'x':

        case 'X':

            sscanf(&op[1], "%d", &fact);

            pix2 = pixExpandReplicate(pix1, fact);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'b':

        case 'B':

            sscanf(&op[1], "%d", &border);

            pix2 = pixAddBorder(pix1, border, 0);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        default:

            /* All invalid ops are caught in the first pass */

            break;

        }

        LEPT_FREE(op);

            /* Debug output */

        if (dispsep > 0) {

            pixDisplay(pix1, x, 0);

            x += dispsep;

        }

        if (pdfout)

            pixaAddPix(pixa, pix1, L_COPY);

    }

    if (border > 0) {

        pix2 = pixRemoveBorder(pix1, border);

        pixSwapAndDestroy(&pix1, &pix2);

    }

    if (pdfout) {

        snprintf(fname, sizeof(fname), "/tmp/lept/seq_output_%d.pdf",

                 L_ABS(dispsep));

        pixaConvertToPdf(pixa, 0, 1.0, L_FLATE_ENCODE, 0, fname, fname);

        pixaDestroy(&pixa);

    }

    sarrayDestroy(&sa);

    return pix1;

}

/*-------------------------------------------------------------------------*

 *      Run a sequence of binary composite dwa morphological operations    *

 *-------------------------------------------------------------------------*/

/*!

 * \brief   pixMorphCompSequenceDwa()

 *

 * \param[in]    pixs

 * \param[in]    sequence   string specifying sequence

 * \param[in]    dispsep    controls debug display of results in the sequence:

 *                          0: no output

 *                          > 0: gives horizontal separation in pixels between

 *                               successive displays

 *                          < 0: pdf output; abs(dispsep) is used for naming

 * \return  pixd, or NULL on error

 *

 * <pre>

 * Notes:

 *      (1) This does dwa morphology on binary images, using brick Sels.

 *      (2) This runs a pipeline of operations; no branching is allowed.

 *      (3) It implements all brick Sels that have dimensions up to 63

 *          on each side, using a composite (linear + comb) when useful.

 *      (4) A new image is always produced; the input image is not changed.

 *      (5) This contains an interpreter, allowing sequences to be

 *          generated and run.

 *      (6) See pixMorphSequence() for further information about usage.

 * </pre>

 */

PIX *

pixMorphCompSequenceDwa(PIX         *pixs,

                        const char  *sequence,

                        l_int32      dispsep)

{

char    *rawop, *op;

char     fname[256];

l_int32  nops, i, j, nred, fact, w, h, x, border, pdfout;

l_int32  level[4];

PIX     *pix1, *pix2;

PIXA    *pixa;

SARRAY  *sa;

    if (!pixs)

        return (PIX *)ERROR_PTR("pixs not defined", __func__, NULL);

    if (!sequence)

        return (PIX *)ERROR_PTR("sequence not defined", __func__, NULL);

        /* Split sequence into individual operations */

    sa = sarrayCreate(0);

    sarraySplitString(sa, sequence, "+");

    nops = sarrayGetCount(sa);

    pdfout = (dispsep < 0) ? 1 : 0;

    if (!morphSequenceVerify(sa)) {

        sarrayDestroy(&sa);

        return (PIX *)ERROR_PTR("sequence not valid", __func__, NULL);

    }

        /* Parse and operate */

    pixa = NULL;

    if (pdfout) {

        pixa = pixaCreate(0);

        pixaAddPix(pixa, pixs, L_CLONE);

    }

    border = 0;

    pix1 = pixCopy(NULL, pixs);

    pix2 = NULL;

    x = 0;

    for (i = 0; i < nops; i++) {

        rawop = sarrayGetString(sa, i, L_NOCOPY);

        op = stringRemoveChars(rawop, " \n\t");

        switch (op[0])

        {

        case 'd':

        case 'D':

            sscanf(&op[1], "%d.%d", &w, &h);

            pix2 = pixDilateCompBrickDwa(NULL, pix1, w, h);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'e':

        case 'E':

            sscanf(&op[1], "%d.%d", &w, &h);

            pix2 = pixErodeCompBrickDwa(NULL, pix1, w, h);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'o':

        case 'O':

            sscanf(&op[1], "%d.%d", &w, &h);

            pixOpenCompBrickDwa(pix1, pix1, w, h);

            break;

        case 'c':

        case 'C':

            sscanf(&op[1], "%d.%d", &w, &h);

            pixCloseCompBrickDwa(pix1, pix1, w, h);

            break;

        case 'r':

        case 'R':

            nred = strlen(op) - 1;

            for (j = 0; j < nred; j++)

                level[j] = op[j + 1] - '0';

            for (j = nred; j < 4; j++)

                level[j] = 0;

            pix2 = pixReduceRankBinaryCascade(pix1, level[0], level[1],

                                               level[2], level[3]);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'x':

        case 'X':

            sscanf(&op[1], "%d", &fact);

            pix2 = pixExpandReplicate(pix1, fact);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        case 'b':

        case 'B':

            sscanf(&op[1], "%d", &border);

            pix2 = pixAddBorder(pix1, border, 0);

            pixSwapAndDestroy(&pix1, &pix2);

            break;

        default:

            /* All invalid ops are caught in the first pass */

            break;

        }

        LEPT_FREE(op);

            /* Debug output */

        if (dispsep > 0) {

            pixDisplay(pix1, x, 0);

            x += dispsep;

        }

        if (pdfout)

            pixaAddPix(pixa, pix1, L_COPY);

    }

    if (border > 0) {

        pix2 = pixRemoveBorder(pix1, border);

        pixSwapAndDestroy(&pix1, &pix2);

    }

    if (pdfout) {

        snprintf(fname, sizeof(fname), "/tmp/lept/seq_output_%d.pdf",

                 L_ABS(dispsep));

        pixaConvertToPdf(pixa, 0, 1.0, L_FLATE_ENCODE, 0, fname, fname);

        pixaDestroy(&pixa);

    }

    sarrayDestroy(&sa);

    return pix1;

}

/*-------------------------------------------------------------------------*

 *            Parser verifier for binary morphological operations          *

 *-------------------------------------------------------------------------*/

/*!

 * \brief   morphSequenceVerify()

 *

 * \param[in]    sa    string array of operation sequence

 * \return  TRUE if valid; FALSE otherwise or on error

 *

 * <pre>

 * Notes:

 *      (1) This does verification of valid binary morphological

 *          operation sequences.

 *      (2) See pixMorphSequence() for notes on valid operations

 *          in the sequence.

 * </pre>

 */

l_int32

morphSequenceVerify(SARRAY  *sa)

{

char    *rawop, *op = NULL;

l_int32  nops, i, j, nred, fact, valid, w, h, netred, border;

l_int32  level[4];

l_int32  intlogbase2[5] = {1, 2, 3, 0, 4};  /* of arg/4 */

    if (!sa)

        return ERROR_INT("sa not defined", __func__, FALSE);

    nops = sarrayGetCount(sa);

    valid = TRUE;

    netred = 0;

    border = 0;

    for (i = 0; i < nops; i++) {

        rawop = sarrayGetString(sa, i, L_NOCOPY);

        op = stringRemoveChars(rawop, " \n\t");

        switch (op[0])

        {

        case 'd':

        case 'D':

        case 'e':

        case 'E':

        case 'o':

        case 'O':

        case 'c':

        case 'C':

            if (sscanf(&op[1], "%d.%d", &w, &h) != 2) {

                lept_stderr("*** op: %s invalid\n", op);

                valid = FALSE;

                break;

            }

            if (w <= 0 || h <= 0) {

                lept_stderr("*** op: %s; w = %d, h = %d; must both be > 0\n",

                            op, w, h);

                valid = FALSE;

                break;

            }

/*            lept_stderr("op = %s; w = %d, h = %d\n", op, w, h); */

            break;

        case 'r':

        case 'R':

            nred = strlen(op) - 1;

            netred += nred;

            if (nred < 1 || nred > 4) {

                lept_stderr(

                        "*** op = %s; num reduct = %d; must be in {1,2,3,4}\n",

                        op, nred);

                valid = FALSE;

                break;

            }

            for (j = 0; j < nred; j++) {

                level[j] = op[j + 1] - '0';

                if (level[j] < 1 || level[j] > 4) {

                    lept_stderr("*** op = %s; level[%d] = %d is invalid\n",

                                op, j, level[j]);

                    valid = FALSE;

                    break;

                }

            }

            if (!valid)

                break;

/*            lept_stderr("op = %s", op); */

            for (j = 0; j < nred; j++) {

                level[j] = op[j + 1] - '0';

/*                lept_stderr(", level[%d] = %d", j, level[j]); */

            }

/*            lept_stderr("\n"); */

            break;

        case 'x':

        case 'X':

            if (sscanf(&op[1], "%d", &fact) != 1) {

                lept_stderr("*** op: %s; fact invalid\n", op);

                valid = FALSE;

                break;

            }

            if (fact != 2 && fact != 4 && fact != 8 && fact != 16) {

                lept_stderr("*** op = %s; invalid fact = %d\n", op, fact);

                valid = FALSE;

                break;

            }

            netred -= intlogbase2[fact / 4];

/*            lept_stderr("op = %s; fact = %d\n", op, fact); */

            break;

        case 'b':

        case 'B':

            if (sscanf(&op[1], "%d", &fact) != 1) {

                lept_stderr("*** op: %s; fact invalid\n", op);

                valid = FALSE;

                break;

            }

            if (i > 0) {

                lept_stderr("*** op = %s; must be first op\n", op);

                valid = FALSE;

                break;

            }

            if (fact < 1) {

                lept_stderr("*** op = %s; invalid fact = %d\n", op, fact);

                valid = FALSE;

                break;

            }

            border = fact;

/*            lept_stderr("op = %s; fact = %d\n", op, fact); */

            break;

        default:

            lept_stderr("*** nonexistent op = %s\n", op);

            valid = FALSE;

        }

        LEPT_FREE(op);

    }

    if (border != 0 && netred != 0) {

        lept_stderr("*** op = %s; border added but net reduction not 0\n", op);

        valid = FALSE;

    }

    return valid;

}

/*-----------------------------------------------------------------*

 *       Run a sequence of grayscale morphological operations      *

 *-----------------------------------------------------------------*/

/*!

 * \brief   pixGrayMorphSequence()

 *

 * \param[in]    pixs

 * \param[in]    sequence   string specifying sequence

 * \param[in]    dispsep    controls debug display of results in the sequence:

 *                          0: no output

 *                          > 0: gives horizontal separation in pixels between

 *                               successive displays

 *                          < 0: pdf output; abs(dispsep) is used for naming

 * \param[in]    dispy      if dispsep > 0, this gives the y-value of the

 *                          UL corner for display; otherwise it is ignored

 * \return  pixd, or NULL on error

 *

 * <pre>

 * Notes:

 *      (1) This works on 8 bpp grayscale images.

 *      (2) This runs a pipeline of operations; no branching is allowed.

 *      (3) This only uses brick SELs.

 *      (4) A new image is always produced; the input image is not changed.

 *      (5) This contains an interpreter, allowing sequences to be

 *          generated and run.

 *      (6) The format of the sequence string is defined below.

 *      (7) In addition to morphological operations, the composite

 *          morph/subtract tophat can be performed.

 *      (8) Sel sizes (width, height) must each be odd numbers.

 *      (9) Intermediate results can optionally be displayed

 *      (10) The sequence string is formatted as follows:

 *            ~ An arbitrary number of operations,  each separated

 *              by a '+' character.  White space is ignored.

 *            ~ Each operation begins with a case-independent character

 *              specifying the operation:

 *                 d or D  (dilation)

 *                 e or E  (erosion)

 *                 o or O  (opening)

 *                 c or C  (closing)

 *                 t or T  (tophat)

 *            ~ The args to the morphological operations are bricks of hits,

 *              and are formatted as a.b, where a and b are horizontal and

 *              vertical dimensions, rsp. (each must be an odd number)

 *            ~ The args to the tophat are w or W (for white tophat)

 *              or b or B (for black tophat), followed by a.b as for

 *              the dilation, erosion, opening and closing.

 *           Example valid sequences are:

 *             "c5.3 + o7.5"

 *             "c9.9 + tw9.9"

 * </pre>

 */

PIX *

pixGrayMorphSequence(PIX         *pixs,

                     const char  *sequence,

                     l_int32      dispsep,

                     l_int32      dispy)

{

char    *rawop, *op;

char     fname[256];

l_int32  nops, i, valid, w, h, x, pdfout;

PIX     *pix1, *pix2;

PIXA    *pixa;

SARRAY  *sa;

    if (!pixs)

        return (PIX *)ERROR_PTR("pixs not defined", __func__, NULL);

    if (!sequence)

        return (PIX *)ERROR_PTR("sequence not defined", __func__, NULL);

        /* Split sequence into individual operations */

    sa = sarrayCreate(0);

    sarraySplitString(sa, sequence, "+");

    nops = sarrayGetCount(sa);

    pdfout = (dispsep < 0) ? 1 : 0;

        /* Verify that the operation sequence is valid */

    valid = TRUE;

    for (i = 0; i < nops; i++) {

        rawop = sarrayGetString(sa, i, L_NOCOPY);

        op = stringRemoveChars(rawop, " \n\t");

        switch (op[0])

        {

        case 'd':

        case 'D':