# A Tutorial for the Jenks-Caspall algorithm for optimal classification (oClass) of data software package.

# 

# 

Michael Williams

Michael Finn

USGS

Rolla, Missouri

USGS Icon by Robert Buehler

Any use of trade, product, or firm names is for descriptive purposes
only and does not imply endorsement by the U.S. Government

#### Data Preparation

The first thing you have to do in order to use the oClass classification
software is export all your image data from its proprietary format to
generic binary file in the BSQ (band sequential) format. For the
purposes of this tutorial we will assume you are using Imagine as your
GIS software (if you are using other software, please consult your
documentation for instructions on performing these steps).

> To begin, launch Imagine and click the "Import" button on the toolbar;
> (see figure 1). Note that the export radio button has been selected,
> type is set to "Generic Binary" and media is set to "File".
>
> ![](media/image1.png){width="5.992361111111111in"
> height="2.8243055555555556in"}

Figure 1. Imagine Export Screen

> Once you have chosen the input file (the image you wish to export),
> and the output file, click the OK button. You should now see a screen
> like figure 2.
>
> ![](media/image2.png){width="5.992361111111111in"
> height="2.8243055555555556in"}

Figure 2. Generic Binary Export Options

> Note that the "Swap Bytes" checkbox is checked. This is
> **[required]{.underline}** for Windows, if you do not check this box
> your classifications will all be wrong. Also notice that the data
> format is set to BSQ, this is the required file format for running
> oClass. Writing a header file for the image is not essential as long
> as you know the number of layers in the image, as well as its width
> and height. Once all of the proper options have been selected, click
> the "OK" button to export the file. Once it's finished you should see
> a screen like figure 3.

![](media/image3.png){width="5.997222222222222in" height="2.8125in"}

Figure 3. Finished Export

##### Running oClass

Now that you have exported all of your images to generic binary files,
it's time to load up oClass. Double click on "oclass.exe" and you should
be greeted with a screen like figure 4.

> ![](media/image4.png){width="4.634722222222222in"
> height="3.395138888888889in"}
>
> Figure 4. oClass Main Screen

The first thing that you need to do is select the image file you wish to
classify. To do this, click the "Browse" button next to the "Image File"
field. After you have selected your image file, you must fill in the
data type, the number of layers in the image, the width of the image (in
pixels), and the height of the image (in pixels); all of this
information can be obtained from the header file you generated while
exporting the original image. Now that all of the image-specific
information has been entered, you must choose what output formats you
would like to use, as well as the number of classes you would like to
generate for this file (note that you must choose at least one output
format in order to run the classification). What follows is a
description of each of these output formats:

-   CLA (short for classification) - If you plan on using the model
    generator (discussed later) to build an Imagine spatial modeler
    script to reclassify your original image, you MUST select CLA
    output. When you click the CLA output checkbox, the CLA output file
    field becomes active for you to choose your file.

-   HTML - A summary of the low/high values for every class in every
    image layer formatted using HTML.

-   Text - A summary of the low/high values for every class in every
    image layer in a plain text file.

> Now that you have filled in all of the required fields, you should
> have a screen similar to figure 5, assuming you chose all three output
> options.
>
> ![](media/image5.png){width="4.603472222222222in"
> height="3.3743055555555554in"}

Figure 5. Image File Loaded

With classification finished (figure 6), you can now either view the
HTML or text results, or click "Generate Model" to begin the process of
generating an Imagine spatial modeler script. If you choose to click
"Generate Model" you should see a screen like that of figure 7.

> ![](media/image6.png){width="4.665972222222222in"
> height="3.4368055555555554in"}

Figure 6. Finished Classification

> ![](media/image7.png){width="4.645138888888889in"
> height="3.4055555555555554in"}
>
> Figure 7. Model Generation Main Screen
>
> As can be seen from figure 7, four input parameters are required to
> generate the Imagine Spatial Modeler script: the CLA file you
> generated in the previous step; the path to the original Imagine file
> used to create the individual generic binary images; the name and path
> of the output file you wish the script to generate; and the filename
> of the script that we are generating.
>
> The first thing we need to do here is select the classification file
> we want to use, so we have to click browse and navigate to where we
> saved our CLA file (figure 8).

![](media/image8.png){width="5.905555555555556in"
height="3.645138888888889in"}

Figure 8. Choosing the CLA File

Clicking "Open" with give you a screen similar to figure 9.

![](media/image9.png){width="4.676388888888889in"
height="3.4055555555555554in"}

> Figure 9. Model Generation Main Screen
>
> All three of the remaining parameters will be chosen the same way, and
> once you have them all filled in you should get a screen similar to
> figure 10, simply click "Generate" to make the script. When it is
> complete you should see a screen similar to figure 11.

![](media/image10.png){width="4.645138888888889in"
height="3.395138888888889in"}

Figure 10. Ready To Generate Model Script

> ![](media/image11.png){width="4.645138888888889in"
> height="3.4055555555555554in"}
>
> Figure 11. Model Script Generation Complete

I.  **Running the Model Script.**

Now that we have completed our classification, and have generated our
spatial modeler script, it's time to launch Imagine and run it. Once
Imagine is loaded click the "Modeler" button on the toolbar and in the
dialog that comes up click "Model Librarian", you should see something
similar to figure 12.

![](media/image12.jpeg){width="5.709722222222222in" height="4.46875in"}

Figure 12. Imagine Model Librarian

> In figure 12 we have already selected a script file that we generated
> previously, and all we need to do to run it is click "Run Model"
> (figure 13).
>
> ![](media/image13.jpeg){width="5.709722222222222in"
> height="4.509722222222222in"}

Figure 13. Running The Model

> Now you have a newly classified image! You can open up each layer in
> pseudo-color in a viewer to see the results.

II. **Using the "Batch" feature.**

> Another important feature of oClass is that it allows you to queue up
> multiple classifications to run sequentially, and it also lets you
> save a list of classification tasks, also called "jobs", so that you
> can run them later.
>
> To access the batch feature of oClass, click the "Batch" button on the
> main screen. after doing so you should see something similar to figure
> 14.
>
> ![](media/image14.png){width="5.989583333333333in"
> height="2.7354166666666666in"}

Figure 14. The Batch Screen.

> As can be seen here, the job list is currently empty, so lets go ahead
> and add something to it. On the left, you can see the main oClass
> screen, with all of the details filled out to classify a particular
> image, but rather than clicking "Run Classification" as we did
> earlier, we need to click "Add Current" in the batch window on the
> right. After doing this, the batch screen should look similar to
> figure 15.
>
> ![](media/image15.png){width="5.989583333333333in"
> height="2.7354166666666666in"}
>
> Figure 15. A New Job Added.
>
> We repeat this process four more times so that we have a total of five
> classification jobs in the job queue, giving us a screen similar to
> figure 16.
>
> ![](media/image16.png){width="5.995138888888889in"
> height="2.7354166666666666in"}

Figure 16. More Jobs Added.

> Now that our list of jobs that we want to run is complete, we need
> only click the "Run" button. After all the jobs have finished, a
> screen similar to figure 17 should appear.
>
> ![](media/image17.png){width="5.995138888888889in"
> height="2.745833333333333in"}

Figure 17. All Jobs Run.

> As mentioned earlier, the most important feature of the job queue
> system is its ability to save the list of currently queued up jobs out
> to a file so that they can be run later. All we have to do in order to
> save our list is click the "Save Job List" button, which will bring up
> a screen similar to figure 18.
>
> ![](media/image18.png){width="5.989583333333333in"
> height="2.3756944444444446in"}

Figure 18. Saving The Job List.

> Next, we choose a name and location for our job list (Batch Queue
> File) and click "Save". Now we can load our job list again any time we
> want by clicking the "Load Job List" button and choosing the .bqf file
> we just created!
>
> Another feature of the job queue system that it allows you to edit
> currently queued up jobs. The most common reason for needing to edit
> the details of a job is if we load a job list that was generated
> previously and the image file locations have changed. If we load a job
> list and oClass can't find the image file, it will indicate that a bad
> file exists; this can be seen in figure 19.
>
> ![](media/image19.png){width="5.995138888888889in"
> height="2.7354166666666666in"}
>
> Figure 19. Mssing File Example.
>
> As can be seen in figure 19, the image file for the first job in a
> list that we have loaded is no longer there, so we see the
> "\*\*\*\*BAD FILE\*\*\*\*" marker next to the job details. We want to
> be able to run our data set, but we don't want to have to go back and
> redo the whole list, and luckily we don't have to! All we need to do
> is click the "Edit" checkbox, and then click the job entry with the
> bad file in the list, the details of the job now show back up in the
> main oClass screen for us to edit! Notice in figure 20, that when we
> click "Edit" the "Add Current" button changes to "Commit Changes",
> this is because any changes we make to the job details on the left
> screen will be saved for that particular job when we click "Commit
> Changes", rather than adding a new job to the list.
>
> ![](media/image20.png){width="5.995138888888889in"
> height="2.7354166666666666in"}

Figure 20. Editing A Job.

> Once we click select the right location of the image file and click
> "Commit Changes" the list is updated and the "\*\*\*\*BAD
> FILE\*\*\*\*" marker goes away.
>
> ![](media/image21.png){width="5.989583333333333in"
> height="2.740972222222222in"}

Figure 21. Editing A Job.

> The final two features that exist in the job-queue system are the
> clear, and remove features. If you want to remove a single job from
> the list, all you need do is click on it to select it, and then click
> the "Remove" button. Similarly if you want to remove all of the jobs
> in the list and start over from scratch just click the "Clear" button.