001/*******************************************************************************
002 * This software is provided as a supplement to the authors' textbooks on digital
003 * image processing published by Springer-Verlag in various languages and editions.
004 * Permission to use and distribute this software is granted under the BSD 2-Clause
005 * "Simplified" License (see http://opensource.org/licenses/BSD-2-Clause).
006 * Copyright (c) 2006-2023 Wilhelm Burger, Mark J. Burge. All rights reserved.
007 * Visit https://imagingbook.com for additional details.
008 ******************************************************************************/
009package imagingbook.common.edges;
010
011import imagingbook.common.geometry.basic.Pnt2d.PntInt;
012import imagingbook.common.util.ArrayUtils;
013
014import java.util.Iterator;
015import java.util.List;
016
017/**
018 * Represents a chain of connected edge points (integer pixel coordinates). As is, this could have also be implemented
019 * as a generic {@link List} but additional properties may be added in a future version.
020 *
021 * @author WB
022 * @version 2022/09/07 made immutable, add() method removed
023 */
024public class EdgeTrace implements Iterable<PntInt> {
025        
026        private final PntInt[] edgePoints;
027
028        /**
029         * Constructor, creates a {@link EdgeTrace} from the specified points.
030         *
031         * @param points an array of {@link PntInt} elements
032         */
033        public EdgeTrace(PntInt[] points) {
034                if (points.length == 0) {
035                        throw new IllegalArgumentException("point array must not be empty");
036                }
037                this.edgePoints = points;
038        }
039
040        /**
041         * Constructor, creates a {@link EdgeTrace} from the specified points.
042         *
043         * @param points a list of {@link PntInt} elements
044         */
045        public EdgeTrace(List<PntInt> points) {
046                this(points.toArray(new PntInt[0]));
047        }
048        
049        /**
050         * Returns the size of (number of points in) this edge trace.
051         * @return the size
052         */
053        public int size() {
054                return edgePoints.length;
055        }
056
057        /**
058         * Returns an array of points contained in this edge trace.
059         *
060         * @return an array of edge points
061         */
062        public PntInt[] getPoints() {
063                return edgePoints.clone();
064        }
065
066        @Override
067        public Iterator<PntInt> iterator() {
068                return ArrayUtils.getIterator(edgePoints);
069        }
070        
071        @Override
072        public String toString() {
073                return String.format("%s: start=%s length=%d", 
074                                this.getClass().getSimpleName(), edgePoints[0].toString(), size());
075        }
076
077}